Read SeaSonde Cross Spectra (CS) File Data — seasonder

This function reads the SeaSonde CS file data based on the provided header information. The CS file data includes the antenna voltage squared self spectra (SSA*) and the antenna cross spectra (CSxy). Additionally, a quality matrix (QC) is read when the header's nCsKind is greater than or equal to 2.

Usage

seasonder_readSeaSondeCSFileData(connection, header, endian = "big")

Arguments

connection: A connection object to the CS file.
header: A list containing the header information. This is typically the output of the seasonder_readSeaSondeCSFileHeader function.
endian: Character string indicating the byte order. Options are "big" (default) or "little".

Value

A list containing the processed CS file data including matrices for SSA*, CSxy, and QC (if applicable).

Details

SSA*: Represents the Antenna * voltage squared self spectra. These are matrices where each row corresponds to a range and each column to a Doppler cell.
CSxy: Represents the cross spectra between two antennas x and y. These are complex matrices.
QC: Quality matrix with values ranging from zero to one. A value less than one indicates that the SpectraAverager skipped some data during averaging.

Condition Management

This function utilizes the rlang package to manage errors and conditions, providing detailed and structured messages:

Error Classes:

"seasonder_cs_data_reading_error": This error is thrown when there is a problem reading the CS file data. This could be due to issues with the connection object or the file itself.
"seasonder_cs_missing_header_info_error": Thrown if essential header information such as nRangeCells, nDopplerCells, or nCsKind is missing or invalid.

Error Cases:

Connection object is not properly opened or is invalid.
Header information is incomplete or improperly formatted.
File read operations fail due to incorrect data size, type, or unexpected end of file.
Non-numeric values encountered where numeric spectra data is expected.

Examples

con <- rawConnection(as.raw(rep(0, 300)))
header <- list(nRangeCells = 1, nDopplerCells = 5, nCsKind = 2)
data <- seasonder_readSeaSondeCSFileData(con, header, endian = "big")
print(data)
#> $SSA1
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001           0           0           0           0           0
#> attr(,"name")
#> [1] "SSA1"
#> attr(,"class")
#> [1] "SeaSondeRCS_SSMatrix" "matrix"               "array"               
#> 
#> $SSA2
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001           0           0           0           0           0
#> attr(,"name")
#> [1] "SSA2"
#> attr(,"class")
#> [1] "SeaSondeRCS_SSMatrix" "matrix"               "array"               
#> 
#> $SSA3
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001           0           0           0           0           0
#> attr(,"name")
#> [1] "SSA3"
#> attr(,"class")
#> [1] "SeaSondeRCS_SSMatrix" "matrix"               "array"               
#> 
#> $CS12
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001        0+0i        0+0i        0+0i        0+0i        0+0i
#> attr(,"name")
#> [1] "CS12"
#> attr(,"class")
#> [1] "SeaSondeRCS_CSMatrix" "matrix"               "array"               
#> 
#> $CS13
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001        0+0i        0+0i        0+0i        0+0i        0+0i
#> attr(,"name")
#> [1] "CS13"
#> attr(,"class")
#> [1] "SeaSondeRCS_CSMatrix" "matrix"               "array"               
#> 
#> $CS23
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001        0+0i        0+0i        0+0i        0+0i        0+0i
#> attr(,"name")
#> [1] "CS23"
#> attr(,"class")
#> [1] "SeaSondeRCS_CSMatrix" "matrix"               "array"               
#> 
#> $QC
#>           doppler_000 doppler_001 doppler_002 doppler_003 doppler_004
#> range_001           0           0           0           0           0
#> attr(,"name")
#> [1] "QC"
#> attr(,"class")
#> [1] "SeaSondeRCS_QCMatrix" "matrix"               "array"               
#> 
close(con)