Read SeaSonde Cross Spectra (CS) File

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".

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.

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.

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

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)
#> List of 2
#>  $ header:List of 36
#>   ..$ nCsFileVersion  : int 6
#>   ..$ nDateTime       : POSIXct[1:1], format: "2024-04-04 07:00:00"
#>   ..$ nV1Extent       : int 1319
#>   ..$ nCsKind         : int 2
#>   ..$ nV2Extent       : int 1313
#>   ..$ nSiteCodeName   : chr "TORA"
#>   ..$ nV3Extent       : int 1305
#>   ..$ nRangeCells     : int 63
#>   ..$ nDopplerCells   : int 1024
#>   ..$ nFirstRangeCell : int 1
#>   ..$ nCoverMinutes   : int 15
#>   ..$ bDeletedSource  : int 0
#>   ..$ bOverrideSrcInfo: int 0
#>   ..$ fStartFreqMHz   : num 46.9
#>   ..$ fRepFreqHz      : num 4
#>   ..$ fBandwidthKHz   : num 801
#>   ..$ bSweepUp        : int 0
#>   ..$ fRangeCellDistKm: num 0.187
#>   ..$ nV4Extent       : int 1257
#>   ..$ CenterFreq      : num 46.5
#>   ..$ CellsDistKm     : num [1:63] 0.187 0.374 0.561 0.748 0.935 ...
#>   ..$ nOutputInterval : int 4
#>   ..$ nCreateTypeCode : chr "SSAQ"
#>   ..$ nCreatorVersion : chr "11.9"
#>   ..$ nActiveChannels : int 3
#>   ..$ nSpectraChannels: int 3
#>   ..$ nActiveChanBits : num 7
#>   ..$ nV5Extent       : int 1229
#>   ..$ ActiveChannels  : int [1:3] 1 2 3
#>   ..$ nCS6ByteSize    : num 1225
#>   ..$ TIME            :List of 9
#>   .. ..$ nTimeMark       : Factor w/ 3 levels "start","center time",..: 1
#>   .. ..$ nYear           : int 2024
#>   .. ..$ nMonth          : int 4
#>   .. ..$ nDay            : int 4
#>   .. ..$ nHour           : int 7
#>   .. ..$ nMinute         : int 0
#>   .. ..$ fSeconds        : num 0
#>   .. ..$ fCoverageSeconds: num 3.51e-310
#>   .. ..$ fHoursFromUTC   : num 0
#>   ..$ ZONE            :List of 1
#>   .. ..$ szTimeZone: chr "Atlantic/Reykjavik"
#>   ..$ LOCA            :List of 3
#>   .. ..$ fLatitude      : num 42.2
#>   .. ..$ fLongitude     : num -8.8
#>   .. ..$ fAltitudeMeters: num 0
#>   ..$ RCVI            :List of 4
#>   .. ..$ nReceiverModel  : Factor w/ 6 levels "Unknown","Awg3/Rcvr2 Chassis AC",..: 1
#>   .. ..$ nRxAntennaModel : Factor w/ 6 levels "Unknown","Box Loops",..: 1
#>   .. ..$ fReferenceGainDB: num 34.2
#>   .. ..$ szFirmware      : chr ""
#>   ..$ GLRM            :List of 10
#>   .. ..$ nMethod             : int 2
#>   .. ..$ nVersion            : int 1
#>   .. ..$ nPointsRemoved      : num 0
#>   .. ..$ nTimesRemoved       : num 0
#>   .. ..$ nSegmentsRemoved    : num 0
#>   .. ..$ fPointPowerThreshold: num 15
#>   .. ..$ fRangePowerThreshold: num 10
#>   .. ..$ fRangeBinThreshold  : num 0.5
#>   .. ..$ bRemoveDC           : int 0
#>   .. ..$ nReceiverModel      : Factor w/ 5 levels "Off","Point",..: 
#>   ..$ FOLS            :List of 4
#>   .. ..$ nNegBraggLeftIndex :List of 2
#>   .. .. ..$ loop: chr "nRangeCells"
#>   .. .. ..$ data: int [1:63] 0 334 335 321 317 324 323 323 316 313 ...
#>   .. ..$ nNegBraggRightIndex:List of 2
#>   .. .. ..$ loop: chr "nRangeCells"
#>   .. .. ..$ data: int [1:63] 0 333 340 344 349 351 349 349 352 353 ...
#>   .. ..$ nPosBraggLeftIndex :List of 2
#>   .. .. ..$ loop: chr "nRangeCells"
#>   .. .. ..$ data: int [1:63] 0 689 689 673 668 669 664 664 666 666 ...
#>   .. ..$ nPosBraggRightIndex:List of 2
#>   .. .. ..$ loop: chr "nRangeCells"
#>   .. .. ..$ data: int [1:63] 0 688 688 684 698 706 704 707 684 681 ...
#>  $ data  :List of 7
#>   ..$ SSA1: 'SeaSondeRCS_SSMatrix' num [1:63, 1:1024] 4.54e-11 3.38e-11 3.05e-11 3.80e-11 3.00e-11 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "SSA1"
#>   ..$ SSA2: 'SeaSondeRCS_SSMatrix' num [1:63, 1:1024] 3.47e-11 5.49e-11 8.77e-11 1.05e-10 2.90e-11 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "SSA2"
#>   ..$ SSA3: 'SeaSondeRCS_SSMatrix' num [1:63, 1:1024] -1.18e-10 -1.91e-10 -3.21e-10 -3.15e-10 -1.56e-10 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "SSA3"
#>   ..$ CS12: 'SeaSondeRCS_CSMatrix' cplx [1:63, 1:1024] -3.08e-11+6.10e-12i -3.11e-11+1.74e-11i -3.10e-11+6.70e-12i ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "CS12"
#>   ..$ CS13: 'SeaSondeRCS_CSMatrix' cplx [1:63, 1:1024] 5.08e-11+3.34e-11i 5.99e-11+2.59e-11i 5.34e-11+4.68e-11i ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "CS13"
#>   ..$ CS23: 'SeaSondeRCS_CSMatrix' cplx [1:63, 1:1024] -3.79e-11-4.55e-11i -5.50e-11-8.05e-11i -9.27e-11-1.31e-10i ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "CS23"
#>   ..$ QC  : 'SeaSondeRCS_QCMatrix' num [1:63, 1:1024] 1 1 1 1 1 ...
#>   .. ..- attr(*, "dimnames")=List of 2
#>   .. .. ..$ : chr [1:63] "range_001" "range_002" "range_003" "range_004" ...
#>   .. .. ..$ : chr [1:1024] "doppler_000" "doppler_001" "doppler_002" "doppler_003" ...
#>   .. ..- attr(*, "name")= chr "QC"