seasonder_readSeaSondeCSFile {SeaSondeR} | R Documentation |
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 asSSA*
,CSxy
, andQC
.
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
andseasonder_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
anddata = 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)