seasonder_readSeaSondeCSFile: Read SeaSonde Cross Spectra (CS) File

In SeaSondeR: Radial Metrics from SeaSonde HF-Radar Data

Read SeaSonde Cross Spectra (CS) File

Description

This function reads and processes a SeaSonde CS file, extracting both its header and data.

Usage

seasonder_readSeaSondeCSFile(filepath, specs_path, endian = "big")

Arguments

filepath	A character string specifying the path to the SeaSonde CS file.
specs_path	A character string specifying the path to the YAML specifications for the CS file.
endian	Character string indicating the byte order. Options are "big" (default) or "little".

Details

The function starts by establishing a connection to the CS file specified by filepath. It then reads the necessary metadata and header specifications from the specs_path. Based on the CS file version determined from its header, it applies specific adjustments to the header data. After processing the header, the function validates the CS file data using seasonder_validateCSFileData and then reads the data itself via seasonder_readSeaSondeCSFileData.

Value

A list containing two components:

• header: A list containing the processed header information of the CS file.

• data: A list containing the processed data of the CS file. The structure of this list depends on the content of the CS file and can contain components such as ⁠SSA*⁠, CSxy, and QC.

Condition Management

This function utilizes the rlang package to manage conditions and provide detailed and structured condition messages:

Condition Classes:

• seasonder_read_cs_file_error: An error class that indicates a general problem when attempting to read the SeaSonde CS file.

• seasonder_cs_file_skipped: Condition indicating that the processing of a CS file was skipped due to an error.

Condition Cases:

• Failure to open a connection to the file.

• Unsupported version found in the specs file.

• Any other error that can arise from dependent functions such as seasonder_readSeaSondeCSFileHeader and seasonder_readSeaSondeCSFileData.

Restart Options: This function provides a structured mechanism to recover from errors during its execution using the rlang::withRestarts function. The following restart option is available:

seasonder_skip_cs_file(cond)

This allows for the graceful handling of file reading errors. If this restart is invoked, the function will log an error message indicating that the processing of a specific CS file was skipped and will return a list with header = NULL and data = NULL. The restart takes one argument: cond (the condition or error that occurred).

• Usage: In a custom condition handler, you can call seasonder_skip_cs_file(cond) to trigger this restart and skip the processing of the current CS file.

• Effect: If invoked, the function logs an error message detailing the reason for skipping the file and then returns a list with both the header and data set to NULL.

References

Cross Spectra File Format Version 6. CODAR. 2016

See Also

seasonder_skip_cs_file, seasonder_validateCSFileData, seasonder_readSeaSondeCSFileHeader, seasonder_readSeaSondeCSFileData, seasonder_readYAMLSpecs

Examples

spec_file <- seasonder_defaultSpecsFilePath("CS")
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
cs <- seasonder_readSeaSondeCSFile(cs_file, spec_file, endian = "big")
str(cs)

SeaSondeR documentation built on June 8, 2025, 10:50 a.m.