Package 'SeaSondeR'

Description

This function converts power values expressed in decibels (dB) to linear self-spectra power values. The conversion is based on the given receiver gain, which accounts for the radar system's amplification effects.

Usage

dB_to_self_spectra(dB_values, receiver_gain)

Arguments

Details

The conversion from decibels to linear power follows the equation:

$P = 10^{(dB + G)/10}$

where:

• \( P \) is the self-spectra power in linear scale,

• \( dB \) represents the power values in decibels,

• \( G \) is the receiver gain in decibels.

Value

A numeric vector of self-spectra power values in linear scale.

See Also

self_spectra_to_dB for the inverse operation.

Description

This function constructs a new SeaSondeRCS object with the provided header and data information, initializing default values for various attributes including processing steps, FOR and MUSIC data, noise level, APM, and reference noise normalized limits estimation interval.

Usage

new_SeaSondeRCS(header, data, seasonder_apm_object = NULL)

Arguments

Details

The object is created with the following components:

• header: Initially set to an empty list, then populated by seasonder_setSeaSondeRCS_header.

• data: Initially set to an empty list, then populated by seasonder_setSeaSondeRCS_data.

• version: Set to 1.

• ProcessingSteps: A character vector to log processing steps.

• FOR_data and MUSIC_data: Initialized as empty lists.

• NoiseLevel: Set using seasonder_defaultCSNoiseLevel().

• APM: Set to seasonder_apm_object if provided.

• interpolated_doppler_cells_index: An integer vector initialized as empty.

• reference_noise_normalized_limits_estimation_interval: Set using seasonder_defaultCSReference_noise_normalized_limits_estimation_interval().

• The object's class is set to c("SeaSondeRCS", "list").

After constructing the base object, the function updates the header and data attributes, initializes FOR parameters, and sets up the FOR configuration by calling seasonder_initSeaSondeRCS_FOR. A processing step message is logged to indicate successful creation.

Value

A SeaSondeRCS object with version 1 containing the specified header, data, and default-initialized attributes.

See Also

seasonder_setSeaSondeRCS_header, seasonder_setSeaSondeRCS_data, seasonder_setFOR_parameters, seasonder_setSeaSondeRCS_FOR

Description

This function takes a single line from a SeaSonde APM file and parses it into a named attribute and its corresponding value.

Usage

parse_metadata_line(line)

Arguments

Value

A list containing the attribute name and its value.

Description

This function prints the details of a SeaSondeRAPM object, including the station code, original file name, site origin (latitude and longitude), and antenna bearing. It is primarily used for displaying the object's metadata in a human-readable format.

Usage

## S3 method for class 'SeaSondeRAPM'
print(x, ...)

Arguments

Value

The SeaSondeRAPM object itself, invisibly.

Examples

# Print metadata of a test SeaSondeRAPM object
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
obj <- seasonder_readSeaSondeRAPMFile(apm_file)
print(obj)

Description

This method provides a formatted printout of the SeaSondeRCS object, displaying the station code, date/time, number of Doppler cells, and number of range cells. It is designed for interactive use, allowing users to quickly inspect the object.

Usage

## S3 method for class 'SeaSondeRCS'
print(x, ...)

Arguments

Details

The function uses the whisker package to render a template string with the header information.

Value

Invisibly returns the original SeaSondeRCS object.

Examples

obj <- list(header = list(nSiteCodeName = "Station1",
                            nDateTime = Sys.time(),
                            nDopplerCells = 256,
                            nRangeCells = 100))
class(obj) <- "SeaSondeRCS"
print(obj)

Description

This function processes a specified version of the SeaSonde file header. It identifies the appropriate header function for the given version, processes the header, and then updates the accumulating pool of header data. Specifically:

Usage

process_version_header(
  pool,
  version,
  specs,
  connection,
  endian = "big",
  prev_data = NULL
)

Arguments

Details

1. For fields in the current header that overlap with the accumulated pool, the current header's values overwrite those in the pool.

2. Fields that are unique to the current header are appended to the pool.

Value

List. A combination of the initial pool and the processed header for the given version. Fields in the current header will overwrite or append to the pool as described above.

Assumptions

This function assumes that the desired version-specific ⁠seasonder_readSeaSondeCSFileHeaderV*⁠ functions are available in the global environment.

See Also

seasonder_readSeaSondeCSFileHeaderV2 seasonder_readSeaSondeCSFileHeaderV3 seasonder_readSeaSondeCSFileHeaderV4 seasonder_readSeaSondeCSFileHeaderV5 seasonder_readSeaSondeCSFileHeaderV6

Description

This function verifies if a given value lies within a specified range and matches the expected type, if provided.

Usage

qc_check_range(field_value, min, max, expected_type = NULL)

Arguments

Value

The original field_value if it's within range and matches the expected_type; otherwise, an error is raised.

Description

This function verifies if a given value is of the expected type.

Usage

qc_check_type(field_value, expected_type)

Arguments

Value

The original field_value if it matches the expected_type; otherwise, an error is raised.

Description

This function performs a quality control check to ensure that a given field value is an unsigned number (i.e., a non-negative number). Optionally, it can also check if the field value matches a specified data type before performing the unsigned check.

Usage

qc_check_unsigned(field_value, expected_type = NULL)

Arguments

Value

Returns the field_value if it passes the checks: it is of the expected type (if expected_type is not NULL) and is non-negative. If any of the checks fail, the function logs an error message and aborts execution.

Description

This auxiliary function reads a field from a binary file using a provided specification and applies a quality control function on the retrieved data. The expectations and functioning of the quality control functions are described in detail in the documentation for seasonder_readSeaSondeCSFileBlock.

Usage

read_and_qc_field(field_spec, connection, endian = "big")

Arguments

Value

The value of the field after applying quality control.

Condition Management

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

Condition Classes:

• seasonder_cs_field_skipped: Condition that indicates a CSField was skipped during reading.

• seasonder_cs_field_qc_fun_rerun: Condition that indicates a rerun of the quality control function was triggered.

• seasonder_cs_field_qc_fun_not_defined_error: Error raised when the quality control function specified is not found in the shared environment seasonder_the.

• seasonder_cs_field_qc_fun_error: Error raised when an issue occurs while applying the quality control function.

Condition Cases:

• If a CSField is skipped during reading, the condition seasonder_cs_field_skipped is used to skip QC and then is re-signaled.

• If an alternate QC is rerun using the seasonder_rerun_qc_with_fun restart, the condition seasonder_cs_field_qc_fun_rerun is signaled.

• If the quality control function specified is not found in the shared environment seasonder_the, the error seasonder_cs_field_qc_fun_not_defined_error is raised.

• If there's an issue applying the quality control function, the error seasonder_cs_field_qc_fun_error is raised.

Restart Options: The function provides structured mechanisms to recover from errors/conditions during its execution using withRestarts. The following restart options are available:

• seasonder_rerun_qc_with_fun: Allows for rerunning QC with an alternate function.

  • Usage: In a custom condition handler, you can call seasonder_rerun_qc_with_fun(cond, alternateQCfunction) to trigger this restart and run an alternate QC using alternateQCfunction. alternateQCfunction will be used as follows alternateQCfunction(x) being x the value. No extra parameters are passed.

  • Effect: If invoked, the function logs an info message detailing the reason of the rerun, and then returns the value returned by alternateQCfunction.

See Also

seasonder_rerun_qc_with_fun, seasonder_readCSField

It's also important to note that within read_and_qc_field, the function seasonder_readCSField is used. This function has its own error management and restart options, which are detailed in its documentation.

Description

This function reads a row of numbers from a matrix that is represented as an array of text lines. It is used to facilitate reading data from SeaSonde APM files.

Usage

read_matrix_row(lines, start, number_of_lines_to_read)

Arguments

Value

A numeric vector containing the row values.

Description

This function reads and processes regular and repeated blocks of data based on provided specifications. Regular blocks are read directly, while repeated blocks are processed recursively based on a set of loops provided in the specifications.

Usage

readV6BlockData(
  specs,
  connection,
  endian = "big",
  prev_data = NULL,
  remaining_loops = NULL
)

Arguments

Value

A list. Contains the read and processed data based on the provided specifications. Regular variables are returned at the top level. Repeated blocks are nested lists with 'loop' and 'data' keys detailing the loop variable and corresponding data.

See Also

readV6BlockData

Examples

# Example: read a single UInt8 value using internal helper
specs <- list(
  field1 = list(
    type = "UInt8",
    qc_fun = "qc_check_unsigned",
    qc_params = list()
  )
)
con <- rawConnection(as.raw(c(10)), "rb")
result <- readV6BlockData(specs, con, endian = "big")
print(result)
close(con)

Description

This function applies amplitude and phase corrections to each antenna channel of a SeaSonde RAPM object based on the correction factors stored within the object.

Usage

seasonder_applyAPMAmplitudeAndPhaseCorrections(seasonder_apm_object)

Arguments

Value

The SeaSonde RAPM object with amplitude and phase corrections applied to the data.

Examples

# Apply amplitude & phase corrections to a test SeaSondeRAPM object
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
obj <- seasonder_readSeaSondeRAPMFile(apm_file)
corrected_obj <- seasonder_applyAPMAmplitudeAndPhaseCorrections(obj)

Description

Applies sign corrections to both cross-spectra and auto-spectra fields within a list of CSSW data cells.

Usage

seasonder_applyCSSWSigns(cs_data)

Arguments

Value

The modified list of CSSW data cells with sign corrections applied.

Description

This function checks whether log recording is currently enabled in the SeaSondeR package.

Usage

seasonder_areLogsEnabled()

Value

Logical indicating whether logs are enabled or disabled.

Examples

seasonder_areLogsEnabled()

Description

This function checks whether message logging is currently enabled.

Usage

seasonder_areMessagesEnabled()

Value

Logical value indicating whether messages are enabled.

Examples

seasonder_areMessagesEnabled()

Description

This function extracts the data from a seasonder_cs_object, representing a SeaSondeRCS object, and converts it into a JSON format. Optionally, it can write this JSON data to a specified file path.

Usage

seasonder_asJSONSeaSondeRCSData(seasonder_cs_object, path = NULL)

Arguments

Value

A character string in JSON format representing the data of the provided SeaSondeRCS object. If a path is provided, the function also writes this data to the specified file.

Note

If a path is provided and there is an issue writing to the file, the function logs an error message using seasonder_logAndMessage and returns the JSON data as a string.

See Also

seasonder_createSeaSondeRCS, seasonder_getSeaSondeRCS_data

Examples

# Example: create a simple SeaSondeRCS object and convert its data to JSON
cs_obj <- structure(list(data = list(a = 1, b = 2)), class = "SeaSondeRCS")
json_output <- seasonder_asJSONSeaSondeRCSData(cs_obj)
print(json_output)

Description

This function extracts the header data from a seasonder_cs_object, representing a SeaSondeRCS object, and converts it into a JSON format. Optionally, it can write this JSON data to a specified file path.

Usage

seasonder_asJSONSeaSondeRCSHeader(seasonder_cs_object, path = NULL)

Arguments

Value

A character string in JSON format representing the header data of the provided SeaSondeRCS object. If a path is provided, the function also writes this data to the specified file.

Note

If a path is provided and there is an issue writing to the file, the function logs an error message using seasonder_logAndMessage and returns the JSON data as a string.

See Also

seasonder_createSeaSondeRCS, seasonder_getSeaSondeRCS_header

Examples

# Example: create a simple SeaSondeRCS object and convert its header to JSON
cs_obj <- structure(list(data = list(a = 1, b = 2)), class = "SeaSondeRCS")
attr(cs_obj, "header") <- list(
  nSiteCodeName = "Station1",
  nDateTime = Sys.time(),
  nDopplerCells = 2,
  nRangeCells = 3
)
json_header <- seasonder_asJSONSeaSondeRCSHeader(cs_obj)
print(json_header)

Description

This function retrieves the Doppler frequency values corresponding to the specified bin indices in a given SeaSondeR object.

Usage

seasonder_Bins2DopplerFreq(seasonder_cs_object, bins)

Arguments

Details

This function retrieves the full set of Doppler bin frequencies using seasonder_getDopplerBinsFrequency in non-normalized form. It then selects the Doppler frequencies corresponding to the specified bin indices.

Value

A numeric vector of Doppler frequencies (in Hz) corresponding to the specified bins.

See Also

seasonder_DopplerFreq2Bins for the reverse operation. seasonder_getDopplerBinsFrequency for retrieving the full set of Doppler frequencies.

Description

This function retrieves the normalized Doppler frequencies corresponding to the specified bins in a given SeaSondeR object.

Usage

seasonder_Bins2NormalizedDopplerFreq(seasonder_cs_object, bins)

Arguments

Details

This function first retrieves the Doppler bin frequencies in normalized form using seasonder_getDopplerBinsFrequency. It then selects the normalized Doppler frequencies corresponding to the specified bin indices.

Normalized Doppler Frequency Calculation: The normalized Doppler frequency is typically defined as:

$f_{norm} = \frac{f_{doppler}}{f_{bragg}}$

where:

• $f_{norm}$ is the normalized Doppler frequency,

• $f_{doppler}$ is the Doppler frequency of a given bin,

• $f_{bragg}$ is the Bragg frequency, computed based on radar wavelength.

Value

A numeric vector of normalized Doppler frequencies corresponding to the specified bins.

See Also

seasonder_getDopplerBinsFrequency for retrieving Doppler bin frequencies.

Description

This function checks if the provided specifications (specs) contain entries for all the required fields listed in fields.

Usage

seasonder_check_specs(specs, fields)

Arguments

Details

The function iterates over each field in the fields vector and checks if there is an associated entry in the specs list. If any field is missing, an error is thrown using seasonder_logAndAbort indicating the missing field specification.

Value

Invisibly returns NULL.

Condition Management

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

Condition Classes:

• spsr_field_specification_missing_error: This error is thrown when a required field specification is missing from the specs list.

Condition Cases:

• Required field specification is missing.

Description

This function computes the projection of the antenna pattern vector onto the noise subspace, a critical step in the Multiple Signal Classification (MUSIC) algorithm. It is used to estimate the direction of arrival (DOA) by identifying the bearing that minimizes this projection.

Usage

seasonder_compute_antenna_pattern_proyections(En, a, Conj_t_a)

Arguments

Details

The MUSIC algorithm leverages the property that the antenna manifold vector is orthogonal to the noise subspace eigenvectors in an ideal scenario. However, in practice, noise in the covariance matrix perturbs the noise subspace, resulting in a small but non-zero projection. This function calculates the magnitude of this projection using the formula:

$P = a^H (En E_n^H) a$

where:

• $a$ is the antenna manifold vector.

• $En$ is the noise subspace eigenvector matrix.

• $H$ denotes the Hermitian (conjugate transpose) operator.

The bearing that produces the smallest projection is considered the best estimate of the signal bearing, as it corresponds to the direction where the signal is strongest relative to the noise.

Value

A complex scalar representing the magnitude of the projection of the antenna manifold vector onto the noise subspace. This value indicates how close the antenna manifold vector is to being orthogonal to the noise subspace.

References

• Paolo, T. de, Cook, T., & Terrill, E. (2007). Properties of HF RADAR Compact Antenna Arrays and Their Effect on the MUSIC Algorithm. OCEANS 2007, 1–10. doi:10.1109/oceans.2007.4449265.

Description

This function calculates the radial velocities corresponding to the Doppler bins in a SeaSondeRCS object, based on the provided Doppler frequencies. The calculation uses the radar's wave number and Bragg angular frequencies.

Usage

seasonder_computeBinsRadialVelocity(seasonder_cs_object, freq)

Arguments

Details

The radial velocity $v$ for each Doppler bin is computed using the formula:

$v = \frac{\text{Freq} - \text{BraggFreq}}{2 \cdot k_0}$

where:

• $\text{Freq}$ is the Doppler frequency of the bin.

• $\text{BraggFreq}$ is the Bragg Doppler angular frequency for the bin.

• $k_0$ is the radar wave number divided by $2\pi$.

The Bragg frequency is negative for bins with frequencies below zero and positive for bins with frequencies above zero.

Value

A numeric vector containing the radial velocities (in meters per second, m/s) corresponding to the provided Doppler frequencies.

See Also

seasonder_getBraggDopplerAngularFrequency to retrieve the Bragg angular frequencies. seasonder_getRadarWaveNumber to obtain the radar wave number.

Description

This function calculates the center Doppler bin for a SeaSondeRCS object based on the total number of Doppler bins. The center bin corresponds to the bin representing zero Doppler frequency.

Usage

seasonder_computeCenterDopplerBin(seasonder_cs_object, nDoppler)

Arguments

Details

The center Doppler bin is computed as: $center\_bin = nDoppler/2$ where nDoppler is the total number of Doppler bins. This represents the bin at zero Doppler frequency in a zero-indexed system. Since R uses one-based indexing, users might observe an offset when comparing the output of this function to CODAR's Radia Suite programs.

Value

A numeric value representing the center Doppler bin. The calculation assumes zero-based indexing from CODAR data files, but note that R uses one-based indexing, which may result in differences compared to CODAR's Radia Suite outputs.

See Also

seasonder_getSeaSondeRCS_MUSIC_nDopplerCells to retrieve the number of Doppler cells from a SeaSondeRCS object.

Description

This function computes the Doppler frequencies associated with each Doppler bin in a SeaSondeRCS object. The output can be normalized by the positive Bragg frequency if specified.

Usage

seasonder_computeDopplerBinsFrequency(
  seasonder_cs_object,
  nDoppler,
  center_bin,
  spectra_res,
  normalized = FALSE
)

Arguments

Details

Doppler frequencies are calculated using the formula:

$\text{frequency}_i = (\text{bin index}_i - \text{center bin}) \times \text{resolution}$

For normalized frequencies:

$\text{frequency}_i = \frac{\text{frequency}_i}{\text{positive Bragg frequency}}$

The center bin is typically determined using seasonder_getCenterDopplerBin(), and the resolution is obtained from seasonder_getDopplerSpectrumResolution(). Normalization is based on the positive Bragg frequency calculated by seasonder_getBraggDopplerAngularFrequency().

Value

A numeric vector representing the Doppler frequencies for each bin. If normalized = TRUE, the values are dimensionless and relative to the positive Bragg frequency. Otherwise, they are in Hz.

See Also

seasonder_getCenterDopplerBin, seasonder_getDopplerSpectrumResolution, seasonder_getBraggDopplerAngularFrequency

Description

This function converts a set of Doppler frequency values into their corresponding Doppler bin indices using predefined Doppler frequency bins and frequency step size.

Usage

seasonder_computeDopplerFreq2Bins(
  seasonder_cs_object,
  doppler_values,
  doppler_freqs,
  delta_freq,
  nDoppler
)

Arguments

Details

The function constructs a set of bin boundaries using the Doppler frequencies. The leftmost boundary is adjusted by subtracting delta_freq from the first Doppler frequency to extend the range.

The function then applies findInterval to determine the corresponding bin index for each input Doppler frequency. The bin assignment process follows these rules:

• rightmost.closed = TRUE: The last bin interval includes its upper boundary.

• all.inside = FALSE: Values outside the defined frequency range are assigned indices below 1 or above nDoppler.

• left.open = TRUE: The left interval is open, meaning values exactly equal to a boundary are assigned to the higher bin.

After determining the bin indices, values that are out of range (bins < 1 or bins > nDoppler) are set to NA.

Value

An integer vector of Doppler bin indices corresponding to the input Doppler frequencies. Values that fall outside the valid bin range are assigned NA.

See Also

seasonder_Bins2NormalizedDopplerFreq for converting bins back to normalized Doppler frequencies. findInterval for details on interval-based bin selection.

Description

This function processes a SeaSondeRCS object to compute the First Order Regions (FOR) using the specified method. It allows the user to configure the processing method and parameters dynamically.

Usage

seasonder_computeFORs(seasonder_cs_object, method = NULL, FOR_control = NULL)

Arguments

Details

Steps:

1. Set Method:

   • If a method is provided, it updates the SeaSondeRCS object with the specified method.

2. Retrieve Method:

   • If no method is specified, the function retrieves the method stored in the object.

3. Set Parameters:

   • If FOR_control is provided, the function updates the object's FOR parameters.

4. Method Execution:

   • Based on the selected method, the corresponding processing function is called. Currently, the only supported method is "SeaSonde", which calls seasonder_computeFORsSeaSondeMethod.

Use Case: This function provides a flexible interface for computing FORs, allowing users to dynamically select methods and configure parameters without modifying the internal object structure.

Value

The updated SeaSondeRCS object with the computed First Order Regions (FOR).

See Also

• seasonder_computeFORsSeaSondeMethod for processing FORs using the SeaSonde method.

• seasonder_setSeaSondeRCS_FOR_method for setting the processing method.

• seasonder_setFOR_parameters for configuring FOR parameters.

Examples

# Set sample file paths
seasonder_disableMessages()
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
# Read the antenna pattern file to create a SeaSondeRAPM object
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
# Create a SeaSondeRCS object from a spectral file
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
cs_obj <- seasonder_computeFORs(cs_obj, method = "SeaSonde")
# Retrieve existing FOR control parameters from the object
FOR_control <- seasonder_getSeaSondeRCS_FORConfig(cs_obj)
cs_obj <- seasonder_computeFORs(cs_obj, FOR_control = FOR_control)

Description

This function processes a SeaSondeRCS object to compute the First Order Regions (FOR) using the SeaSonde method. The workflow includes detecting null points, filtering amplitudes, limiting currents to a maximum range, and rejecting peaks based on proximity to Bragg indices and noise/ionospheric contamination.

Usage

seasonder_computeFORsSeaSondeMethod(seasonder_cs_object)

Arguments

Details

Workflow Steps:

1. Initialize Processing Steps:

   • Marks the start of the SeaSonde method processing in the object's metadata.

2. Detect Null Points:

   • Locates the nulls defining the First Order Regions (FOR) using seasonder_findFORNulls.

3. Filter Amplitudes:

   • Removes regions with insufficient amplitudes using seasonder_filterFORAmplitudes.

4. Limit Currents to Maximum Range:

   • Ensures that currents exceed the configured maximum radial velocity using seasonder_limitFORCurrentRange.

5. Reject Distant Bragg Peaks:

   • If enabled, rejects peaks that are too far from Bragg indices using seasonder_rejectDistantBragg.

6. Reject Noise/Ionospheric Peaks:

   • If enabled, removes peaks where non-Bragg power significantly exceeds Bragg power using seasonder_rejectNoiseIonospheric.

7. Finalize Processing Steps:

   • Marks the end of the SeaSonde method processing in the object's metadata.

Use Case: This function is designed for processing SeaSonde radar data to accurately identify and validate the First Order Regions, ensuring reliable current and wave measurements.

Value

The updated SeaSondeRCS object with the computed First Order Regions (FOR).

See Also

• seasonder_findFORNulls for detecting nulls in the FOR.

• seasonder_filterFORAmplitudes for amplitude filtering.

• seasonder_limitFORCurrentRange for limiting radial velocity.

• seasonder_rejectDistantBragg for rejecting distant Bragg peaks.

• seasonder_rejectNoiseIonospheric for rejecting noise/ionospheric contamination.

Description

This function calculates the geographic coordinates (latitude and longitude) for a given distance and bearing from a specified origin.

Usage

seasonder_computeLonLatFromOriginDistBearing(
  origin_lon,
  origin_lat,
  dist,
  bearing
)

Arguments

Details

The function uses the geodetic formulas provided by the geosphere package to compute the destination point based on:

• Origin longitude and latitude

• Distance in meters (converted from kilometers)

• Bearing in degrees

The calculation employs the geosphere::destPoint function, which handles the spherical geometry of the Earth.

Value

A data frame with two columns:

• lon: The longitude of the computed geographic coordinates.

• lat: The latitude of the computed geographic coordinates.

See Also

destPoint

Examples

# Example with a point at 100 km to the north of the origin
result <- seasonder_computeLonLatFromOriginDistBearing(-123.3656, 48.4284, 100, 0)
print(result)

Description

This function estimates the noise level in the self-spectra of a SeaSondeR cross‐spectral object. The noise level is determined by averaging the spectral power over a predefined frequency range where no first-order Bragg signal is expected. This value is later used in setting signal-to-noise thresholds for FOR detection.

Usage

seasonder_computeNoiseLevel(seasonder_cs_object, antenna = 3, smoothed = FALSE)

Arguments

Details

The noise level is computed via the following steps:

1. Determine Noise Reference Limits:

   • Retrieves the normalized Doppler frequency limits for noise reference from the FOR parameters (using seasonder_getFOR_parameters).

   • Converts these normalized limits into Doppler bin indices using seasonder_SwapDopplerUnits.

   • If any of the resulting bin indices are missing, they are replaced with appropriate default boundaries (i.e., upper limit set to the total number of Doppler cells and lower limit set to 1).

2. Extract Spectral Data for Noise Estimation:

   • The function extracts the self-spectra from the specified antenna (using seasonder_getSeaSondeRCS_SelfSpectra), limiting the extraction to the Doppler bins within the computed noise reference range (both negative and positive regions).

3. Compute the Average Noise Level:

   • The spectral data from both the negative and positive Doppler regions are concatenated, and the row-wise mean is calculated to estimate the average noise level.

4. Store the Noise Level:

   • The computed average noise level is stored in the object's NoiseLevel attribute by calling seasonder_setSeaSondeRCS_NoiseLevel.

   • A processing step message is logged using SeaSondeRCS_computeNoiseLevel_step_text.

The resulting noise level is essential for setting accurate thresholds during FOR detection.

Value

The updated SeaSondeRCS object with the computed noise level stored in its attributes.

See Also

• seasonder_getFOR_parameters for retrieving noise reference limits.

• seasonder_SwapDopplerUnits for converting normalized Doppler frequencies into bin indices.

• seasonder_getSeaSondeRCS_SelfSpectra for extracting self-spectra.

• seasonder_setSeaSondeRCS_NoiseLevel for storing the computed noise level.

Description

This function calculates the power matrix based on the provided steering vector, eigenvalues, and eigenvectors. The computation differs depending on the number of columns in the steering vector matrix.

Usage

seasonder_computePowerMatrix(eig, a)

Arguments

Details

The function computes the power matrix using the following steps:

• If a has two columns:

  1. Select the first two eigenvalues and their corresponding eigenvectors.

  2. Compute the matrix $G = a^* \cdot \text{eigVector}$, where $a^*$ is the conjugate transpose of a.

  3. Calculate the inverse of G and its conjugate transpose.

  4. Compute the power matrix $P = G_{\text{inv}}^* \cdot \text{diag(eigValues)} \cdot G_{\text{inv}}$.

• If a has one column:

  1. Select the first eigenvalue and its corresponding eigenvector.

  2. Follow similar steps as above with single-column operations.

If a has no columns, the function returns NULL.

Value

A complex matrix representing the power matrix, calculated based on the provided eigenvalues, eigenvectors, and steering vectors. If the number of columns in a is zero, the function returns NULL.

Mathematical Formula

For a steering vector matrix $a$, eigenvectors $\text{eigVector}$, and eigenvalues $\text{eigValues}$, the power matrix is calculated as:

$P = G_{\text{inv}}^* \cdot \text{diag(eigValues)} \cdot G_{\text{inv}}$

where: $G = a^* \cdot \text{eigVector}$ and $G_{\text{inv}}$ is the inverse of $G$.

References

• Paolo, T. de, Cook, T., & Terrill, E. (2007). Properties of HF RADAR Compact Antenna Arrays and Their Effect on the MUSIC Algorithm. OCEANS 2007, 1–10. doi:10.1109/oceans.2007.4449265.

Description

This function creates a SeaSondeRAPM object to store antenna pattern calibration data.

Usage

seasonder_createSeaSondeRAPM(
  calibration_matrix = matrix(complex(real = NA_real_, imaginary = NA_real_), nrow = 3,
    ncol = 0),
  ...
)

Arguments

Details

The function performs the following operations:

1. Validates the calibration_matrix with seasonder_validateCalibrationMatrixSeaSondeRAPM.

2. Initializes all other attributes either with default or user-provided values.

3. Merges the initialized attributes into calibration_matrix.

4. Sets the object's class to 'SeaSondeRAPM'.

For more details on the attributes, see seasonder_initializeAttributesSeaSondeRAPM.

Value

A SeaSondeRAPM object containing a complex matrix with class attribute 'SeaSondeRAPM' and additional attributes for metadata. Row names are set "A13", "A23" and "A33" and column names are set to be the values in BEAR.

See Also

seasonder_validateCalibrationMatrixSeaSondeRAPM, seasonder_initializeAttributesSeaSondeRAPM

Examples

# Create a test SeaSondeRAPM object by reading sample file
  apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
  obj <- seasonder_readSeaSondeRAPMFile(apm_file)

Description

This generic function creates a SeaSondeRCS object either from a file path or directly from a list containing header and data. When x is a character string, the function determines the file type (either "CS", "CSSY" or "CSSW") by analyzing the spectra file and reads it using the appropriate reading function. If specs_path is not provided (or set to rlang::zap()), the default YAML specifications path corresponding to the detected file type is used.

Usage

seasonder_createSeaSondeRCS(x, specs_path = NULL, ...)

Arguments

Details

For character inputs, the function first checks if the specified file exists. It then determines the file type using seasonder_find_spectra_file_type. If the specs_path parameter is not provided or is set to rlang::zap(), the default specifications file path is obtained using seasonder_defaultSpecsFilePath based on the detected file type. The file is then read using the appropriate reading function:

• seasonder_readSeaSondeCSFile for CS files.

• seasonder_readSeaSondeRCSSYFile for CSSY files.

• seasonder_readSeaSondeRCSSWFile for CSSW files.

For list inputs, the SeaSondeRCS object is created directly from the provided header and data. Additionally, a processing step is appended to the object using seasonder_setSeaSondeRCS_ProcessingSteps with a creation step text that indicates the source.

Value

A SeaSondeRCS object.

See Also

new_SeaSondeRCS, seasonder_readSeaSondeCSFile, seasonder_readSeaSondeRCSSWFile, seasonder_setSeaSondeRCS_ProcessingSteps

Examples

# Creating a SeaSondeRCS object from a list
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
specs_path <- seasonder_defaultSpecsFilePath("CS")
temp_obj <- seasonder_readSeaSondeCSFile(cs_file, specs_path)
cs_list <- list(header = temp_obj$header, data = temp_obj$data)
rcs_object <- seasonder_createSeaSondeRCS(cs_list)

# Creating a SeaSondeRCS object from a file path using default YAML specifications
rcs_object <- seasonder_createSeaSondeRCS(system.file("css_data/CSS_TORA_24_04_04_0700.cs", 
package = "SeaSondeR"))

# Creating a SeaSondeRCS object from a file path with a specified YAML specifications file
rcs_object <- seasonder_createSeaSondeRCS(
  system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR"),
  specs_path = seasonder_defaultSpecsFilePath("CS")
)

Description

This method creates a SeaSondeRCS object by reading a file from the specified file path. It verifies the file's existence, determines the file type ("CS", "CSSY" or "CSSW") using seasonder_find_spectra_file_type, and then reads the file using the appropriate function. If specs_path is not provided (or is set to rlang::zap()), the default YAML specifications file path is retrieved using seasonder_defaultSpecsFilePath based on the detected file type.

Usage

## S3 method for class 'character'
seasonder_createSeaSondeRCS(x, specs_path = rlang::zap(), endian = "big", ...)

Arguments

Details

The function performs the following steps:

1. Checks if the file specified by x exists; if not, it aborts with an error.

2. Determines the file type using seasonder_find_spectra_file_type.

3. If specs_path is not provided or is set to rlang::zap(), retrieves the default YAML specifications path using seasonder_defaultSpecsFilePath based on the detected file type.

4. Reads the file using the appropriate function:

   • seasonder_readSeaSondeCSFile for CS files.

   • seasonder_readSeaSondeRCSSYFile for CSSY files.

   • seasonder_readSeaSondeRCSSWFile for CSSW files.

5. Creates a SeaSondeRCS object using new_SeaSondeRCS with the header and data obtained from the file.

6. Appends a processing step indicating the creation source via seasonder_setSeaSondeRCS_ProcessingSteps with a creation step text generated by SeaSondeRCS_creation_step_text(x).

Value

A SeaSondeRCS object.

See Also

new_SeaSondeRCS, seasonder_find_spectra_file_type, seasonder_defaultSpecsFilePath, seasonder_readSeaSondeCSFile, seasonder_readSeaSondeRCSSYFile, seasonder_readSeaSondeRCSSWFile, seasonder_setSeaSondeRCS_ProcessingSteps, SeaSondeRCS_creation_step_text

Examples

# Create a SeaSondeRCS object from a file using the default YAML specifications
rcs_object <- seasonder_createSeaSondeRCS(
  system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
)

# Create a SeaSondeRCS object from a file with a specified YAML specifications file
rcs_object <- seasonder_createSeaSondeRCS(
  system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR"),
  specs_path = seasonder_defaultSpecsFilePath("CS")
)

Description

This method creates a SeaSondeRCS object directly from a list containing the header and data.

Usage

## S3 method for class 'list'
seasonder_createSeaSondeRCS(x, specs_path = NULL, ...)

Arguments

Details

The function creates a new SeaSondeRCS object using new_SeaSondeRCS with the provided header and data. It then appends a processing step, generated by SeaSondeRCS_creation_step_text("list"), to the object via seasonder_setSeaSondeRCS_ProcessingSteps.

Value

A SeaSondeRCS object.

See Also

new_SeaSondeRCS, seasonder_setSeaSondeRCS_ProcessingSteps, SeaSondeRCS_creation_step_text

Examples

# Given a list with header and data, create a SeaSondeRCS object
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
specs_path <- seasonder_defaultSpecsFilePath("CS")
temp_obj <- seasonder_readSeaSondeCSFile(cs_file, specs_path)
cs_list <- list(header = temp_obj$header, data = temp_obj$data)
rcs_object <- seasonder_createSeaSondeRCS(cs_list)

Description

This function reads a raw binary stream from a provided connection, expecting a specific format that contains the sign bits for self spectra values. The data is divided into 3 groups corresponding to: cs1a, cs2a, and cs3a.

Usage

seasonder_CSSW_read_asign(connection, key)

Arguments

Details

The function performs the following steps:

• Reads key$size bytes from the specified connection.

• Verifies that the number of bytes read matches the expected size.

• Checks that the total number of bytes is divisible by 3, allowing equal distribution among the groups.

• Splits the raw byte vector into 3 groups based on the calculated number of bytes per group.

• Converts each byte into its 8-bit binary representation (using rawToBits) and flattens the results for each group.

Value

A named list of 3 vectors, each containing bits as integers (0 or 1) for self spectra sign data.

Description

This function converts the body structure of a CSSW file into a list of matrices that conform to the data structure required for creating a SeaSondeRCS object. The conversion is performed by mapping specific fields:

SSA1, SSA2, SSA3

Matrices are built using the numeric vectors found in the cs1a, cs2a and cs3a fields respectively.

CS12, CS13, CS23

Each complex cross-spectra matrix is formed by combining the real parts from c12m, c13m and c23m with the corresponding imaginary parts from c12a, c13a and c23a.

QC

The quality control matrix is obtained directly from the csqf field.

Usage

seasonder_CSSW2CSData(body)

Arguments

Details

Each row in the output matrices corresponds to the index provided by cell$indx$index in the input list.

The function first determines the maximum index among the cells in the body, which defines the number of rows for the matrices. Then, it calculates the number of columns for each matrix based on the length of the corresponding vectors from the first cell where they appear. Finally, each cell's data is inserted into the appropriate row of the matrices as indicated by the cell's indx$index value.

Value

A list with the following components:

SSA1

A numeric matrix containing self-spectra from cs1a.

SSA2

A numeric matrix containing self-spectra from cs2a.

SSA3

A numeric matrix containing self-spectra from cs3a.

CS12

A complex matrix formed by pairing c12m (real) and c12a (imaginary).

CS13

A complex matrix formed by pairing c13m (real) and c13a (imaginary).

CS23

A complex matrix formed by pairing c23m (real) and c23a (imaginary).

QC

A numeric matrix containing the quality control data from csqf.

Examples

# Example with a single cell
  cell <- list(
    indx  = list(index = 1),
    cs1a  = c(1, 2, 3),
    cs2a  = c(4, 5, 6),
    cs3a  = c(7, 8, 9),
    c12m  = c(10, 11, 12),
    c12a  = c(13, 14, 15),
    c13m  = c(16, 17, 18),
    c13a  = c(19, 20, 21),
    c23m  = c(22, 23, 24),
    c23a  = c(25, 26, 27),
    csqf  = c(28, 29, 30)
  )
  body <- list(cell)
  transformed <- seasonder_CSSW2CSData(body)
  print(transformed)

Description

Extracts the 'cs4h' component from a CSSW header and reorganizes the remaining header information under 'header_csr'.

Usage

seasonder_CSSW2CSHeader(header)

Arguments

Value

A transformed list representing a valid SeaSonde CS header with embedded CSSW header information.

Description

This function reads a raw binary stream from a provided connection, expecting a specific format that contains the sign bits for self spectra values. The data is divided into 3 groups corresponding to: cs1a, cs2a, and cs3a.

Usage

seasonder_CSSY_read_asign(connection, key)

Arguments

Value

A named list of 3 vectors. Each vector represents one group (i.e., cs1a, cs2a, cs3a) and contains integers (0 or 1) corresponding to the bits (in little-endian order) extracted from the raw data.

Description

This function reads a raw binary stream from a provided connection, expecting a specific format that contains the sign bits for complex spectral values. The data is divided into 6 groups corresponding to: C13r, C13i, C23r, C23i, C12r, and C12i.

Usage

seasonder_CSSY_read_csign(connection, key)

Arguments

Details

The function performs the following steps:

• Reads key$size bytes from the specified connection.

• Checks if enough bytes were read.

• Ensures that the total number of bytes is divisible by 6, allowing equal distribution among the groups.

• Splits the raw byte vector into 6 groups based on the calculated number of bytes per group.

• Converts each byte into its 8-bit representation (using rawToBits) and flattens the result.

Value

A named list of 6 vectors. Each vector represents one group (e.g., C13r, C13i, etc.) and contains integers (0 or 1) corresponding to the bits (in little-endian order) extracted from the raw data.

Description

This function converts the body structure of a CSSY file into a list of matrices that conform to the data structure required for creating a SeaSondeRCS object. The conversion is performed by mapping specific fields:

SSA1, SSA2, SSA3

Matrices are built using the numeric vectors found in the cs1a, cs2a and cs3a fields respectively.

CS12, CS13, CS23

Each complex cross-spectra matrix is formed by combining the real parts from c12r, c13r and c23r with the corresponding imaginary parts from c12i, c13i and c23i.

QC

The quality control matrix is obtained directly from the csqf field.

Usage

seasonder_CSSY2CSData(body)

Arguments

Details

Each row in the output matrices corresponds to the index provided by cell$indx$index in the input list.

The function first determines the maximum index among the cells in the body, which defines the number of rows for the matrices. Then, it calculates the number of columns for each matrix based on the length of the corresponding vectors from the first cell where they appear. Finally, each cell's data is inserted into the appropriate row of the matrices as indicated by the cell's indx$index value.

Value

A list with the following components:

SSA1

A numeric matrix containing self-spectra from cs1a.

SSA2

A numeric matrix containing self-spectra from cs2a.

SSA3

A numeric matrix containing self-spectra from cs3a.

CS12

A complex matrix formed by pairing c12r (real) and c12i (imaginary).

CS13

A complex matrix formed by pairing c13r (real) and c13i (imaginary).

CS23

A complex matrix formed by pairing c23r (real) and c23i (imaginary).

QC

A numeric matrix containing the quality control data from csqf.

Examples

# Example with a single cell
  cell <- list(
    indx  = list(index = 1),
    cs1a  = c(1, 2, 3),
    cs2a  = c(4, 5, 6),
    cs3a  = c(7, 8, 9),
    c12r  = c(10, 11, 12),
    c12i  = c(13, 14, 15),
    c13r  = c(16, 17, 18),
    c13i  = c(19, 20, 21),
    c23r  = c(22, 23, 24),
    c23i  = c(25, 26, 27),
    csqf  = c(28, 29, 30)
  )
  body <- list(cell)
  transformed <- seasonder_CSSY2CSData(body)
  print(transformed)

Description

This helper function extracts the 'cs4h' component from a CSSY header, removes it from the original header, and embeds the remaining header information within the 'header_csr' field of the CS header.

Usage

seasonder_CSSY2CSHeader(header)

Arguments

Value

A transformed header where the primary CS header is taken from 'cs4h' and the remaining CSSY header fields are stored in the 'header_csr' element.

Description

This function returns a list of default parameters for first-order radial processing in CODAR's Radial Suite R7. Each parameter has an equivalent R8 version, where applicable, often expressed in decibels (dB).

Usage

seasonder_defaultFOR_parameters()

Details

Parameter Descriptions:

1. nsm (R8: Doppler Smoothing)

   • Default value: 2

   • Usage: Sets how many Doppler bins (points) are smoothed. Smoothing helps remove jagged edges in the sea echo spectrum, aiding in locating the null between the first and second order (or noise floor).

   • Recommended values: Typically 2 to 6. Default in Radial Suite R8 is 2

   • Effects of over-/under-smoothing:

     • Too high: May smear out the real null, causing the first order to appear wider.

     • Too low: Jagged minima may cause the null to be detected inside the first-order region, making it appear too narrow.

2. fdown (R8: Null Below Peak Power)

   • Default value (R7): 10

   • Equivalent in dB (R8): 10 dB

   • Usage: Defines how far below the peak power the algorithm must descend (in dB) before searching for the null that separates the first and second order. This helps avoid including second-order energy as part of the first-order.

   • Recommended range: 3.981072 to 31.62278 (6 to 15 dB in R8). Default in Radial Suite R8 is 10 dB

   • Effects of misconfiguration:

     • Too large: The null search may be bypassed entirely, causing second-order content to be included in the first order.

     • Too small: The null may be found inside the first-order region, excluding valid Bragg energy.

3. flim (R8: Peak Power Dropoff)

   • Default value (R7): 100

   • Equivalent in dB (R8): 20 dB

   • Usage: Once a peak is located, any spectral bins that are more than flim below the peak (in linear scale) or ⁠20 dB⁠ below the peak (in dB scale) are excluded from the first-order region.

   • Recommended range: 15.84893 to 316.2278 (12 to 25 dB in R8). Default in Radial Suite R8 is 20 dB.

   • Effects of misconfiguration:

     • Too high: May include non-Bragg signal and yield spurious high velocity estimates.

     • Too low: May cut out part of the actual Bragg signal, underestimating maximum velocities.

4. noisefact (R8: Signal to Noise)

   • Default value (R7): 3.981072

   • Equivalent in dB (R8): 6 dB

   • Usage: Sets the threshold above the noise floor that must be exceeded for the algorithm to accept Doppler bins as potential first-order.

   • Recommended range: 3.981072 to 7.943282 (6 to 9 dB in R8). Default in Radial Suite R8 is 6 dB

   • Effects of misconfiguration:

     • Too high: Useful Bragg data could be excluded.

     • Too low: Noise or spurious signals may be included as Bragg.

5. currmax (R8: Maximum Velocity)

   • Default value: 2 m/s

   • Usage: Sets a maximum radial velocity, preventing first-order limits from extending beyond realistic current speeds for the site.

   • Effects of misconfiguration:

     • Too high: May include non-Bragg data, producing overestimated velocities.

     • Too low: May exclude valid Bragg data, underestimating velocities.

6. reject_distant_bragg (Reject Distant Bragg)

   • Default value: TRUE

   • Usage: Rejects a first-order region if its limits are farther from the Bragg index (central Doppler bin for zero current) than the width of the region itself. Helps avoid misclassifying strong but isolated signals (e.g., ships) as Bragg.

   • Recommendation: Usually keep this enabled unless operating at a site where only strongly biased positive or negative currents are expected.

7. reject_noise_ionospheric (Reject Noise/Ionospheric)

   • Default value: TRUE

   • Usage: Rejects Bragg if the total non-Bragg power in a range cell exceeds the Bragg power by at least the threshold set in reject_noise_ionospheric_threshold. Recommended to set as FALSE for 42 MHz systems.

   • Recommendation: Enable if the site experiences significant noise.

8. reject_noise_ionospheric_threshold (Reject Noise/Ionospheric Threshold)

   • Default value: 0

   • Equivalent in dB: 0 dB

   • Usage: Difference threshold (in dB) for comparing non-Bragg power to Bragg power. If non-Bragg power is higher by this threshold, the Bragg is rejected.

   • Recommended setting: Typically 0 dB. Increase only if needed to be less sensitive to noise contamination.

Value

A named list containing the default parameter values.

References

COS. SeaSonde Radial Suite Release 7; CODAR Ocean Sensors (COS): Mountain View, CA, USA, 2013. COS. SeaSonde Radial Suite Release 8; CODAR Ocean Sensors (COS): Mountain View, CA, USA, 2016.

Examples

params <- seasonder_defaultFOR_parameters()
print(params)

Description

This function returns the default parameters for the MUSIC algorithm used in the SeaSondeR package.

Usage

seasonder_defaultMUSIC_parameters()

Details

The default parameters are:

• 40: Threshold used in seasonder_MUSICCheckEigenValueRatio.

• 20: Threshold used in seasonder_MUSICCheckSignalPowers.

• 2: Threshold used in seasonder_MUSICCheckSignalMatrix.

• 20: Threshold used in seasonder_MUSICCheckBearingDistance.

Value

A numeric vector containing the default parameters for the MUSIC algorithm: c(40, 20, 2, 20).

See Also

seasonder_MUSICTestDualSolutions to understand the parameters in context.

Examples

# Retrieve default parameters
params <- seasonder_defaultMUSIC_parameters()
print(params)

Description

This function returns a list of default options used in the MUSIC algorithm.

Usage

seasonder_defaultMUSICOptions()

Details

The returned list includes:

• PPMIN: Lower threshold value (default is NULL).

• PWMAX: Upper threshold value (default is NULL).

• smoothNoiseLevel: Logical flag indicating whether the noise level should be smoothed (FALSE by default).

• doppler_interpolation: Doppler interpolation factor (default is 2).

• MUSIC_parameters: A numeric vector of default parameters for the MUSIC algorithm, retrieved from seasonder_defaultMUSIC_parameters().

• discard_low_SNR: Logical flag to discard solutions with low signal-to-noise ratio (TRUE by default).

• discard_no_solution: Logical flag to discard cases with no solution (TRUE by default).

Value

A list containing the default options for the MUSIC algorithm.

Examples

# Retrieve the default options for the MUSIC algorithm
opts <- seasonder_defaultMUSICOptions()
print(opts)

Description

This function returns the default file path for the specifications YAML file corresponding to the provided type. The type must be one of the names defined in the default paths (i.e., "CS" or "CSSY").

Usage

seasonder_defaultSpecsFilePath(type = "CS")

Arguments

Value

A character string representing the full path to the YAML specifications file.

Examples

# Retrieve the default CS specifications file path
  cs_specs_path <- seasonder_defaultSpecsFilePath("CS")

  # Retrieve the default CSSY specifications file path
  cssy_specs_path <- seasonder_defaultSpecsFilePath("CSSY")

Description

This function returns the default YAML specifications file path corresponding to a given spectra file. It first determines the file type by analyzing the file content and then retrieves the associated default specifications path.

Usage

seasonder_defaultSpecsPathForFile(filepath, endian = "big")

Arguments

Details

The function leverages seasonder_find_spectra_file_type to determine whether the file is of type "CS" or "CSSY". It then uses seasonder_defaultSpecsFilePath to obtain the corresponding default specifications path.

Value

A character string representing the default YAML specifications file path for the detected file type.

See Also

seasonder_find_spectra_file_type, seasonder_defaultSpecsFilePath

Description

This function resets the debug points to the default state ("none").

Usage

seasonder_disable_all_debug_points()

Value

A character vector containing only the default debug point "none".

Examples

seasonder_disable_all_debug_points()

Description

This function disables log recording in the SeaSondeR package. Once disabled, various SeaSondeR functions will no longer output logs.

Usage

seasonder_disableLogs()

Value

Invisibly returns FALSE, indicating that log recording has been disabled.

Examples

seasonder_disableLogs()

Description

This function disables message logging in the SeaSondeR package. Once disabled, various SeaSondeR functions will no longer output informational messages.

Usage

seasonder_disableMessages()

Value

logical FALSE indicating that message logging was disabled.

Examples

seasonder_disableMessages()

Description

This function converts a set of Doppler frequency values into their corresponding Doppler bin indices within a SeaSondeR object.

Usage

seasonder_DopplerFreq2Bins(seasonder_cs_object, doppler_values)

Arguments

Details

This function first retrieves the Doppler frequency bins from the given SeaSondeR object using seasonder_getDopplerBinsFrequency in non-normalized form. The spectral resolution, which defines the frequency step size ($\Delta f$), is obtained using seasonder_getDopplerSpectrumResolution.

The number of Doppler bins is then determined using seasonder_getnDopplerCells.

With this information, the function calls seasonder_computeDopplerFreq2Bins to determine the corresponding bin indices for each input Doppler frequency.

Value

An integer vector of Doppler bin indices corresponding to the input Doppler frequencies. Values that fall outside the valid bin range are assigned NA.

See Also

seasonder_Bins2NormalizedDopplerFreq for the reverse operation. seasonder_computeDopplerFreq2Bins for the core computation logic.

Description

This function converts Doppler frequencies (in Hz) into their corresponding normalized Doppler frequencies within a SeaSondeR object.

Usage

seasonder_DopplerFreq2NormalizedDopplerFreq(
  seasonder_cs_object,
  doppler_values
)

Arguments

Details

The function follows these steps:

1. Calls seasonder_DopplerFreq2Bins to convert the input Doppler frequencies into Doppler bin indices.

2. Calls seasonder_Bins2NormalizedDopplerFreq to obtain the corresponding normalized Doppler frequencies.

The normalized Doppler frequency is computed as:

$f_{doppler} = f_{norm} \times f_{bragg}$

where:

• $f_{doppler}$ is the Doppler frequency in Hz,

• $f_{norm}$ is the normalized Doppler frequency,

• $f_{bragg}$ is the Bragg frequency, computed based on radar wavelength.

This function ensures consistency by mapping input frequencies to their closest bin representation before normalization.

Value

A numeric vector of normalized Doppler frequencies corresponding to the input Doppler values.

See Also

seasonder_DopplerFreq2Bins for converting Doppler frequencies to bin indices. seasonder_Bins2NormalizedDopplerFreq for converting bin indices to normalized frequencies.

Description

This function adds one or more debug points to the list of enabled debug points.

Usage

seasonder_enable_debug_points(debug_points)

Arguments

Value

Updated character vector of enabled debug points.

Examples

seasonder_enable_debug_points("example_debug")

Description

This function enables log recording in the SeaSondeR package. Once enabled, various SeaSondeR functions will output logs.

Usage

seasonder_enableLogs()

Value

Invisibly returns TRUE, indicating that log recording has been enabled.

Examples

seasonder_enableLogs()

Description

This function enables message logging in the SeaSondeR package. Once enabled, various SeaSondeR functions will output informational messages.

Usage

seasonder_enableMessages()

Value

logical TRUE indicating that message logging was enabled.

Examples

seasonder_enableMessages()

Description

This function estimates the reference noise limits for normalized Doppler frequencies in a SeaSondeR cross-spectral object. These limits define the frequency range over which the noise floor is assessed for first-order region (FOR) detection.

Usage

seasonder_estimateReferenceNoiseNormalizedLimits(
  seasonder_cs_object,
  low_limit = 0.95,
  high_limit = 1
)

Arguments

Details

The function operates as follows:

1. Retrieves the Doppler bin frequencies in normalized units (relative to the Bragg frequency) via seasonder_getDopplerBinsFrequency.

2. Computes the noise limits by scaling the maximum normalized Doppler frequency using the provided low_limit and high_limit factors:

   • The lower bound is given by max(freq) * low_limit.

   • The upper bound is given by max(freq) * high_limit.

3. The default empirical choice for the lower bound (56.5% in the original calibration process) is adjustable via the low_limit parameter. This parameter was determined through an iterative process where the initial lower bound was decreased in increments (e.g., 0.5%) until the computed noise floor closely matched the reference provided by the AnalyseSpectra Tool in Radial Suite R8.

This approach is crucial for setting the signal-to-noise ratio (SNR) thresholds used in FOR detection.

Value

A numeric vector of length two, representing the lower and upper reference noise limits in normalized Doppler frequency.

See Also

seasonder_getDopplerBinsFrequency for retrieving Doppler bin frequencies.

Description

This function exports the MUSIC detection table from a SeaSondeRCS object to a CSV file.

Usage

seasonder_exportCSVMUSICTable(seasonder_cs_object, filepath)

Arguments

Details

This function performs the following steps:

1. Generates a MUSIC table using seasonder_exportMUSICTable.

2. Converts the resulting table to a data frame.

3. Writes the data frame to the specified CSV file using data.table::fwrite.

Value

The function returns NULL invisibly. The output is saved to the specified file.

See Also

• seasonder_exportMUSICTable

• fwrite

Examples

# Prepare a SeaSondeRCS object for examples, including APM
  apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
  apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
  specs_path <- seasonder_defaultSpecsFilePath("CS")
  cs_obj <- seasonder_createSeaSondeRCS(
    system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR"),
    specs_path = specs_path,
    seasonder_apm_object = apm_obj
  )
cs_obj <- seasonder_initMUSICData(
 cs_obj,
 range_cells = c(rep(5,11), rep(4,11)),
 doppler_bins = c(c(669:679),c(674:684))
)
cs_obj <- seasonder_runMUSIC(cs_obj)
  # Export MUSIC table to a temporary CSV file
  tmpfile <- tempfile(fileext = ".csv")
  seasonder_exportCSVMUSICTable(cs_obj, tmpfile)
  print(tmpfile)

Description

This function writes the formatted CTF range information, generated from a SeaSondeRCS object, to a specified file.

Usage

seasonder_exportCTFRangeInfo(seasonder_cs_object, file, tableStart = "")

Arguments

Details

The function internally calls seasonder_exportCTFRangeInfo_string to obtain a formatted string of range information. It then writes this output string to the specified file. Additionally, it returns the extracted range information invisibly, allowing further processing if necessary.

Value

Invisibly returns a data frame containing the range information.

Examples

# Prepare a SeaSondeRCS object with valid data
  apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
  apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
  cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
  cs_obj <- seasonder_createSeaSondeRCS(
    cs_file,
    seasonder_apm_object = apm_obj
  )
  # Export CTF range information to a temporary text file
  range_info <- seasonder_exportCTFRangeInfo(cs_obj, tempfile(fileext = ".txt"))

Description

This function extracts radial metrics from a SeaSondeRCS object and formats them for export using defined mustache templates. The formatted output, which includes MUSIC parameters, antenna pattern corrections, noise thresholds, and other spectral metrics, is written to a specified file. Additionally, the function returns the computed radial metrics as a data frame.

Usage

seasonder_exportLLUVRadialMetrics(seasonder_cs_object, LLUV_path, ...)

Arguments

Details

The function performs the following steps:

1. Retrieves the radial metrics from the SeaSondeRCS object using seasonder_exportRadialMetrics.

2. Obtains MUSIC parameters and antenna pattern attributes from the object.

3. Formats numeric values using predefined formats for each column.

4. Renders a data template (from "LLUV_RDM1_data.mustache") with the formatted radial metrics.

5. Generates a deterministic UUID from the rendered data.

6. Renders an overall LLUV template (from "LLUV_RDM1.mustache") that incorporates the radial parameters, formatted data, header information, and the generated UUID.

7. Writes the rendered LLUV content to the file specified by LLUV_path.

Value

Invisibly returns a data frame containing the radial metrics used in the export.

Examples

# Prepare a SeaSondeRCS object with MUSIC data
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
FOR <- seasonder_getSeaSondeRCS_FOR(cs_obj)
cs_obj <- seasonder_setSeaSondeRCS_FOR(cs_obj,FOR[4:5])
# Optionally, run MUSIC in FOR context to populate MUSIC data
cs_obj <- seasonder_runMUSICInFOR(cs_obj)
radial_metrics <- seasonder_exportLLUVRadialMetrics(cs_obj, tempfile(fileext = ".ruv"))
head(radial_metrics)

Description

This function generates a table containing detailed MUSIC detection data from a SeaSondeRCS object. The output table includes geographic coordinates, signal parameters, and other metadata for each MUSIC detection.

Usage

seasonder_exportMUSICTable(seasonder_cs_object)

Arguments

Details

This function performs the following operations:

1. Retrieves the timestamp (nDateTime) from the header of the SeaSondeRCS object. Defaults to as.POSIXct(0) if unavailable.

2. Initializes an empty data frame with predefined columns.

3. Retrieves MUSIC detection data, processes the Direction of Arrival (DOA) and geographic coordinates (lonlat), and unnests these fields.

4. Converts MUSIC bearings to geographic bearings using the associated Antenna Pattern Matrix (APM) object.

5. Computes additional metrics such as signal power in dB, signal-to-noise ratio (SNR), and DOA peak response in dB.

6. Appends the timestamp to the table and reorders columns for clarity.

Value

A data frame with the following columns:

• datetime: Timestamp of the data.

• longitude: Geographic longitude of the detection.

• latitude: Geographic latitude of the detection.

• range_cell: Range cell number.

• range: Range in kilometers.

• doppler_bin: Doppler bin number.

• doppler_freq: Doppler frequency.

• radial_velocity: Radial velocity in m/s.

• signal_power: Signal power.

• bearing: Geographic bearing in degrees.

• bearing_raw: Original MUSIC bearing in degrees.

• noise_level: Noise level in dB.

• signal_power_db: Signal power in dB.

• SNR: Signal-to-noise ratio in dB.

• DOA_peak_resp_db: DOA peak response in dB.

See Also

• seasonder_getSeaSondeRCS_MUSIC

• seasonder_MUSICBearing2GeographicalBearing

• seasonder_getSeaSondeRAPM_AntennaBearing

Examples

# Load sample CSS and APM files
  cs_file  <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
  apm_file <- system.file("css_data/MeasPattern.txt",       package = "SeaSondeR")
  apm_obj  <- seasonder_readSeaSondeRAPMFile(apm_file)
  # Create SeaSondeRCS object with APM
  cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
FOR <- seasonder_getSeaSondeRCS_FOR(cs_obj)
cs_obj <- seasonder_setSeaSondeRCS_FOR(cs_obj,FOR[4:5])

  # Run MUSIC algorithm (in FOR context) if MUSIC data is available:
  cs_obj <- seasonder_runMUSICInFOR(cs_obj)
  # Export MUSIC table
  music_table <- seasonder_exportMUSICTable(cs_obj)
  print(music_table)

Description

This function extracts and formats radial metrics from a SeaSondeRCS object for export. It processes the MUSIC table, computes various spectral metrics, applies antenna pattern corrections, and combines the results into a final data frame formatted according to predefined column specifications.

Usage

seasonder_exportRadialMetrics(seasonder_cs_object, AngSeg = list())

Arguments

Details

The function proceeds as follows:

1. Retrieves the MUSIC table using seasonder_getSeaSondeRCS_MUSIC and the associated APM object.

2. Defines a template row with 34 predefined columns, initializing most numeric values to NA, except for specific defaults such as MSA1, MDA1, and MDA2 (set to 1440L).

3. Copies basic numeric fields and computes additional fields from the MUSIC table, such as the radial velocity (scaled by 100), range, range cell, doppler cell (shifted by -1), eigenvalue ratio, signal power ratio, and offset power ratio.

4. Computes the metric MDRJ by applying the function seasonder_computeMDRJ on the MUSIC row.

5. Extracts eigen decomposition results from each MUSIC row to populate the eigenvalue fields (MEI1, MEI2, MEI3).

6. Processes the DOA solutions stored in each MUSIC row: - For solutions retained as "single", geographic bearing corrections are applied to populate MSA1. - For dual-bearing solutions, the first two elements of the DOA bearings populate MDA1 and MDA2, respectively.

7. Computes additional spectral metrics such as the self-spectra conversion to dB (fields MA1S, MA2S, and MA3S) after subtracting the noise level (obtained for each antenna).

8. Based on the retained solution type (either "single" or "dual"), assigns location data (if available), sets selection flags, and computes additional output metrics (e.g., PPFG and PWFG).

9. Finally, all rows are combined into a data frame. If angular segments are provided, additional modifications to the vector flag (VFLG) are applied.

Value

A data frame with 34 columns containing the computed radial metrics. The columns include geographic coordinates, velocity components, range, bearing information, signal power metrics, noise thresholds, and computed spectral parameters.

Examples

# Prepare a SeaSondeRCS object with MUSIC data
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
FOR <- seasonder_getSeaSondeRCS_FOR(cs_obj)
cs_obj <- seasonder_setSeaSondeRCS_FOR(cs_obj,FOR[4:5])
# Run MUSIC algorithm to populate MUSIC data
cs_obj <- seasonder_runMUSICInFOR(cs_obj)
radial_metrics <- seasonder_exportRadialMetrics(cs_obj, AngSeg = list(c(5, 30, 60)))
head(radial_metrics)

Description

This function computes and exports range-related information based on the MUSIC data stored in a SeaSondeRCS object. The output table includes range cell identifiers, range values, noise levels (for each antenna), first-order region (FOR) boundaries, and counts of detections classified as single or dual solutions.

Usage

seasonder_exportRangeInfo(seasonder_cs_object)

Arguments

Details

The function performs the following operations:

1. Extracts key fields from the MUSIC data: range cell, range, and the retained solution type.

2. Aggregates counts of detections classified as single versus dual solutions.

3. Retrieves noise levels (in dB) for each antenna.

4. Obtains FOR boundaries using a dedicated export function and adjusts them based on the Doppler interpolation factor.

5. Merges the aggregated detection counts, noise levels, and FOR boundaries by range cell.

6. Selects and reorders the output columns.

Value

A data frame with the following columns:

SPRC

Range cell identifier.

RNGC

Range (in appropriate units).

NF01

Noise level (in dB) for antenna 1.

NF02

Noise level (in dB) for antenna 2.

NF03

Noise level (in dB) for antenna 3.

ALM1

Lower FOR boundary (after Doppler interpolation).

ALM2

Upper FOR boundary (after Doppler interpolation) for the first boundary set.

ALM3

Lower FOR boundary (after Doppler interpolation) for the second boundary set.

ALM4

Upper FOR boundary (after Doppler interpolation) for the second boundary set.

NVSC

Count of detections classified as "single".

NVDC

Count of detections classified as "dual".

NVAC

Total adjusted count (NVSC plus twice NVDC).

Examples

# Prepare a SeaSondeRCS object with MUSIC data
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
FOR <- seasonder_getSeaSondeRCS_FOR(cs_obj)
cs_obj <- seasonder_setSeaSondeRCS_FOR(cs_obj,FOR[4:5])
# Run MUSIC algorithm to populate MUSIC data
cs_obj <- seasonder_runMUSICInFOR(cs_obj)
range_info <- seasonder_exportRangeInfo(cs_obj)
head(range_info)

Description

This function extracts the spectral power corresponding to the First Order Region (FOR) from a given self-spectra (SS) matrix. It retrieves the spectral values within the Doppler bins identified as part of the positive and negative Bragg regions.

Usage

seasonder_extractFOR(seasonder_cs_object, spectrum, FOR)

Arguments

Details

The function performs the following steps:

1. Initialize Empty Matrices: Creates empty matrices to store extracted spectral data.

2. Extract Negative FOR Data:

   • If the negative FOR bins exist, calls seasonder_extractSeaSondeRCS_dopplerRanges_from_SSdata to extract the corresponding spectral values.

3. Extract Positive FOR Data:

   • If the positive FOR bins exist, extracts the spectral values using the same function.

4. Return Extracted Spectral Data: Outputs a list containing the extracted negative and positive Bragg region spectral data.

This function is primarily used for filtering and validating the first-order Bragg region in SeaSonde radar processing.

Value

A list with two elements:

• negative_FOR: A matrix containing spectral power for the negative Bragg region.

• positive_FOR: A matrix containing spectral power for the positive Bragg region.

See Also

• seasonder_extractSeaSondeRCS_dopplerRanges_from_SSdata for extracting Doppler bin subsets.

• seasonder_filterFORAmplitudes for filtering weak FOR detections.

Description

This function slices a self-spectra data matrix by selecting the columns corresponding to the specified Doppler cells.

Usage

seasonder_extractSeaSondeRCS_dopplerRanges_from_SSdata(SSmatrix, doppler_cells)

Arguments

Details

The function extracts a subset of columns from the self-spectra matrix. No explicit validation is currently performed to verify that the provided Doppler cell indices fall within the range of the matrix columns.

Value

A matrix containing only the columns corresponding to the selected Doppler cells.

Description

This function performs linear extrapolation on the SeaSondeR APM measurement matrix. It adds n extrapolated columns to both the left and right sides of the matrix.

Usage

seasonder_extrapolateAPM(seasonder_apm_object, n = 1)

Arguments

Details

The function retrieves the original bearing vector from the APM object using seasonder_getSeaSondeRAPM_BEAR and obtains the bearing resolution (attribute "BearingResolution"). If n == 0, the original matrix is returned unchanged. For n > 0, new bearings are generated for both sides using the resolution. The left side is extrapolated using the slope computed from the first two columns of the matrix, and the right side is extrapolated using the slope from the last two columns. The new columns are then combined with the original matrix, and the column names and the "BEAR" attribute are updated to reflect the complete set of bearings.

Value

A modified matrix with n extrapolated columns added to both sides. The column names and the "BEAR" attribute are updated with the new bearings, while the "BearingResolution" attribute remains unchanged.

Examples

# Extrapolate loops for a test SeaSondeRAPM object
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
obj <- seasonder_readSeaSondeRAPMFile(apm_file)
result <- seasonder_extrapolateAPM(obj, n = 1)

Description

This function filters the First Order Region (FOR) Doppler bins based on amplitude thresholds. It applies a combination of noise-based and peak power-based criteria to remove low-amplitude bins that do not meet the required signal-to-noise ratio.

Usage

seasonder_filterFORAmplitudes(seasonder_cs_object)

Arguments

Details

Steps in FOR Amplitude Filtering:

1. Retrieve First Order Parameters:

   • The function extracts flim (Null Below Peak Power) and noisefact (Signal-to-Noise Factor) from seasonder_getFOR_parameters.

2. Compute Noise Levels:

   • Calls seasonder_computeNoiseLevel to estimate the average noise level across all range cells.

   • Converts the noise level into a filtering threshold by multiplying it by noisefact.

3. Extract Smoothed Self-Spectra Data:

   • Retrieves the smoothed self-spectra (SSA3) using seasonder_getSeaSondeRCS_FOR_SS_Smoothed.

   • Extracts the FOR spectral power for each range cell using seasonder_extractFOR.

4. Determine Filtering Thresholds:

   • Computes a power threshold for each FOR region by taking the maximum amplitude in the FOR region and dividing it by flim.

5. Apply Filtering Conditions:

   • A Doppler bin is retained if its power is greater than:

     • The noise threshold (computed from noisefact).

     • The power threshold computed from flim.

6. Store Filtered FOR in Object:

   • Updates the SeaSondeRCS object with the filtered FOR bins.

This filtering ensures that only strong, reliable first-order Bragg signals are retained, reducing the impact of noise and second-order contamination.

Value

The updated SeaSondeRCS object with the filtered FOR bins.

See Also

• seasonder_computeNoiseLevel for computing noise levels.

• seasonder_getSeaSondeRCS_FOR_SS_Smoothed for retrieving smoothed self-spectra.

• seasonder_extractFOR for extracting FOR spectral power.

• seasonder_setSeaSondeRCS_FOR for storing the filtered FOR data.

Description

This function identifies the type of a spectra file (either "CS" or "CSSY") by reading its header block based on YAML specifications. It first attempts to read a key size block using the CSSY specifications, and if that fails, it reopens the file and tries to read the CS header block.

Usage

seasonder_find_spectra_file_type(filepath, endian = "big")

Arguments

Details

The function sets up error handling parameters and uses YAML specifications retrieved via seasonder_readYAMLSpecs and seasonder_defaultSpecsFilePath. It opens the file in binary read mode and ensures the connection is closed upon exit. If reading the key size block fails, it reopens the file to try reading the CS header block. The final file type is determined by the key returned from the file block.

Value

A character string representing the spectra file type ("CS" or "CSSY").

Description

This function locates the null points in the First Order Region (FOR) of a SeaSondeR cross-spectral object. It smooths the self-spectra (SS) data, extracts the relevant Doppler bins, and determines the boundaries of the first-order Bragg region for each range cell.

Usage

seasonder_findFORNulls(seasonder_cs_object)

Arguments

Details

The function follows these steps:

1. Smooth the Self-Spectra Data: Calls seasonder_SmoothFORSS to apply a running mean filter.

2. Extract Smoothed Self-Spectra: Retrieves the processed SS matrix using seasonder_getSeaSondeRCS_FOR_SS_Smoothed.

3. Identify the Doppler Center Bin: Determines the central Doppler bin using seasonder_getCenterDopplerBin.

4. Segment the Spectrum: Splits the smoothed SS data into:

   • The negative Bragg region (left side of the Doppler spectrum).

   • The positive Bragg region (right side of the Doppler spectrum).

5. Find Nulls in Each Region: Uses seasonder_findFORNullsInSSMatrix to identify the null positions.

6. Store Results: Extracts:

   • The First Order Region (FOR).

   • The maximum power (MAXP).

   • The Doppler bin index of the maximum power (MAXP.bin).

7. Update the SeaSondeRCS Object: Saves the detected FOR boundaries and related metrics.

Value

The updated SeaSondeRCS object with the computed FOR nulls, maximum power, and bin indices.

See Also

• seasonder_findFORNullsInSpectrum for processing individual spectra.

• seasonder_findFORNullsInSSMatrix for batch processing spectra across multiple range cells.

• seasonder_getSeaSondeRCS_FOR_SS_Smoothed for retrieving smoothed SS data.

Description

This function locates the null point in the First Order Region (FOR) spectrum, which separates the first-order Bragg peak from second-order energy or the noise floor.

Usage

seasonder_findFORNullsInFOR(
  FOR,
  start_point_P,
  doppler_bins,
  left_region = FALSE
)

Arguments

Details

The function follows these steps to determine the null point:

1. If left_region is TRUE, the FOR spectrum and Doppler bins are reversed.

2. The power spectrum is transformed to facilitate peak identification:

   • The absolute values of the power are taken and multiplied by -1.

   • The start_point_P threshold is also inverted.

3. The function identifies the first local maximum in the transformed spectrum that exceeds start_point_P.

4. The corresponding Doppler bin at the detected peak is returned as the null position.

The function relies on pracma::findpeaks to identify the peak.

Value

A numeric value representing the Doppler bin at the detected null position.

See Also

• seasonder_findFORNullsInSpectrum for locating nulls in a full spectrum.

• findpeaks for peak detection.

Description

This function locates the null points in the First Order Region (FOR) of a Doppler spectrum. These nulls define the boundaries separating the first-order Bragg peak from the surrounding noise or second-order energy.

Usage

seasonder_findFORNullsInSpectrum(
  seasonder_cs_object,
  spectrum,
  doppler_bins,
  negative_Bragg_region = FALSE
)

Arguments

Details

The function executes the following steps:

1. Retrieve First Order Settings: The function extracts the fdown parameter, which defines the drop-off level relative to the maximum power.

2. Prepare the Spectrum:

   • Convert all values to negative absolute magnitudes to facilitate peak detection.

   • Reverse the spectrum and Doppler bins if analyzing the negative Bragg region.

3. Find the Main Spectral Peak:

   • The function identifies the first major peak using findpeaks with at least two consecutive increases and decreases.

   • The search is limited to the portion of the spectrum beyond this peak.

4. Determine the First Order Boundaries:

   • The maximum power (MAXP) is found along with its bin index (MAXP.bin).

   • A threshold value start_point_P is computed as MAXP / fdown to establish the cutoff point for the null search.

5. Search for Nulls: The spectrum is split into left and right sections:

   • The right-side spectrum is analyzed using seasonder_findFORNullsInFOR to find the right null.

   • The left-side spectrum undergoes the same process but reversed.

6. Output the Results: The function returns a list containing:

   • The sequence of Doppler bins defining the FOR region.

   • The maximum power detected (MAXP).

   • The Doppler bin index where MAXP occurred (MAXP.bin).

Value

A list with three elements:

• FOR: A sequence of Doppler bins defining the first order region.

• MAXP: The maximum power found in the spectrum.

• MAXP.bin: The Doppler bin index of the maximum power.

See Also

• seasonder_findFORNullsInFOR for detecting nulls within a selected region.

• findpeaks for peak identification.

• seasonder_getFOR_parameters for retrieving FOR settings.

Description

This function applies the null-finding algorithm to each row of a self-spectra (SS) matrix, determining the boundaries of the First Order Region (FOR) for each range cell.

Usage

seasonder_findFORNullsInSSMatrix(
  seasonder_cs_object,
  SS,
  doppler_bins,
  negative_Bragg_region = FALSE
)

Arguments

Details

This function processes each row of the self-spectra matrix, treating each row as an independent spectrum for which the FOR nulls are identified. The nulls define the boundaries of the first-order Bragg region.

Processing Steps:

1. Iterate through each row of the SS matrix.

2. Extract the power spectrum for the corresponding range cell.

3. Apply seasonder_findFORNullsInSpectrum to determine the null positions.

4. Store the results in a named list, where each entry corresponds to a range cell.

Value

A named list where each entry corresponds to a range cell, containing the detected FOR null positions.

See Also

• seasonder_findFORNullsInSpectrum for detecting nulls in a single spectrum.

• seasonder_findFORNulls for high-level null detection across all spectra.

Description

This function returns the currently enabled debug points.

Usage

seasonder_get_enabled_debug_points()

Value

A character vector of enabled debug points.

Examples

seasonder_get_enabled_debug_points()

Description

Computes the radial velocities for each Doppler bin interval's high boundary for a SeaSonde radar cross-section (CS) object, as typically visualized in SpectraPlotterMap. This function utilizes the Doppler shift frequency alongside the radar's wave number and Bragg frequency to transform frequency measurements into radial velocities. The calculation is based on the relationship between the Doppler shift frequency and the velocity of surface currents within the radar's field of view.

Usage

seasonder_getBinsRadialVelocity(seasonder_cs_object)

Arguments

Details

Specifically, the radial velocity $v = (Freq - BraggFreq)/(2 * k_0)$ is used, where $v$ is the radial velocity, $Freq$ is the Doppler shift frequency for the bin, $BraggFreq$ is the Bragg frequency (negative for frequencies below 0 and positive for frequencies equal or above 0), and $k_0$ is the radar wave number divided by 2$\pi$.

Value

A numeric vector containing the radial velocities (in m/s) for each Doppler bin, calculated for the high boundary of each Doppler bin interval. The velocities provide insight into the scatterers' radial movement within the radar's observation area.

See Also

seasonder_getDopplerBinsFrequency, seasonder_getBraggDopplerAngularFrequency, seasonder_getRadarWaveNumber

Description

This function computes the Bragg Doppler angular frequencies for a SeaSonde radar system. These frequencies represent the characteristic Doppler shifts due to wave resonance at the Bragg wavelength.

Usage

seasonder_getBraggDopplerAngularFrequency(seasonder_cs_object)

Arguments

Details

The Bragg Doppler angular frequency $\omega_B$ is calculated using the formula $\omega_B = \sqrt{2 \cdot g \cdot k}$ where:

• $g$ is the gravitational acceleration (approximately $9.8 \, m/s^2$),

• $k$ is the radar wave number in radians per meter.

The returned vector contains the negative ($-\omega_B$) and positive ($+\omega_B$) angular frequencies.

Value

A numeric vector of length two, containing the negative and positive Bragg Doppler angular frequencies (in radians per second).

See Also

seasonder_getRadarWaveNumber to compute the radar wave number.

Description

This function calculates the Doppler bin indices corresponding to the first-order Bragg frequencies (-1 and 1) for a SeaSonde Cross Spectra (CS) object.

Usage

seasonder_getBraggLineBins(seasonder_cs_object)

Arguments

Details

This function uses the normalized Doppler frequencies for the first-order Bragg peaks ($-1$ and $1$) and maps them to their corresponding Doppler bin indices. The mapping is performed using the helper function seasonder_NormalizedDopplerFreq2Bins(), which converts normalized frequencies to bin indices based on the spectral resolution and the Doppler range of the radar system.

The bins are critical for identifying the Doppler shifts associated with the first-order Bragg scattering in HF radar systems, which correspond to surface waves with wavelengths half that of the transmitted radar signal.

Value

A numeric vector of length 2, where:

• The first value is the Doppler bin corresponding to the -1 Bragg frequency.

• The second value is the Doppler bin corresponding to the 1 Bragg frequency.

See Also

seasonder_NormalizedDopplerFreq2Bins for the frequency-to-bin mapping logic.

Description

This function computes the Bragg wavelength $\lambda_B$ for a SeaSonde radar system. The Bragg wavelength is defined as half the radar wavelength and is used to identify the fundamental scattering mechanisms in oceanographic radar measurements.

Usage

seasonder_getBraggWaveLength(seasonder_cs_object)

Arguments

Details

The Bragg wavelength $\lambda_B$ is calculated as: $\lambda_B = \frac{\lambda}{2}$ where:

• $\lambda$ is the radar wavelength in meters, obtained using seasonder_getRadarWaveLength.

The Bragg wavelength is a critical parameter in interpreting the resonance scattering from the sea surface, which is fundamental to the operation of HF radar systems.

Value

A numeric value representing the Bragg wavelength (in meters).

See Also

seasonder_getRadarWaveLength to compute the radar wavelength.

Description

This function calculates the center Doppler bin index for a SeaSondeRCS object. It obtains the total number of Doppler cells from the object using seasonder_getnDopplerCells and computes the center bin with seasonder_computeCenterDopplerBin.

Usage

seasonder_getCenterDopplerBin(seasonder_cs_object)

Arguments

Details

The center Doppler bin is computed by retrieving the total number of Doppler cells (via seasonder_getnDopplerCells) and then processing that value with seasonder_computeCenterDopplerBin. Note that while CODAR data files might use zero-based indexing, R uses one-based indexing.

Value

A numeric value representing the center Doppler bin.

Description

This function extracts the center frequency (in MHz) from the header of a SeaSondeRCS object. It accesses the header field named "CenterFreq" using seasonder_getSeaSondeRCS_headerField.

Usage

seasonder_getCenterFreqMHz(seasonder_cs_object)

Arguments

Value

A numeric value representing the center frequency in MHz.

Description

This function retrieves a specific value from the SeaSondeRCS object's header based on the provided path. The path can be a single field name or a list of nested field names.

Usage

seasonder_getCSHeaderByPath(seasonder_obj, path, warn_missing = TRUE)

Arguments

Value

The value at the specified path in the header. If the path is not found, NULL is returned and a warning is thrown.

Condition Management

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

Condition Classes:

• seasonder_SeaSonderCS_field_not_found_in_header: Indicates that the specified path was not found in the header.

Condition Cases:

• Field or nested fields specified by the path are not found in the header.

Examples

# Minimal example for seasonder_getCSHeaderByPath
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
field_value <- seasonder_getCSHeaderByPath(cs_obj, c("nRangeCells"))
print(field_value)

Description

This function calculates the frequency limits for each Doppler bin within a SeaSonde Cross Spectrum (CS) object. It can return frequencies either in their original Hz values or normalized by the second Bragg frequency. The frequencies are calculated as the high limit of each Doppler bin interval, similar to what is displayed in SpectraPlotterMap.

Usage

seasonder_getDopplerBinsFrequency(seasonder_cs_object, normalized = FALSE)

Arguments

Details

The function internally utilizes several helper functions such as seasonder_getCenterDopplerBin(), seasonder_getnDopplerCells(), and seasonder_getDopplerSpectrumResolution() to calculate the Doppler bin frequencies. Furthermore, when normalization is requested, it uses seasonder_getBraggDopplerAngularFrequency() to obtain the second Bragg frequency for normalization purposes.

Value

A numeric vector of frequencies representing the high limit of each Doppler bin interval. If normalized is TRUE, these frequencies are dimensionless values relative to the second Bragg frequency; otherwise, they are in Hz.

Description

This function computes the Doppler spectrum resolution for a given SeaSondeRCS object. The resolution reflects the frequency difference between consecutive Doppler bins in the spectrum.

Usage

seasonder_getDopplerSpectrumResolution(seasonder_cs_object)

Arguments

Details

The Doppler spectrum resolution is calculated using the formula: $SpectralResolution = SweepRate / NumberOfDopplerCells$ where:

• SweepRate is the frequency repetition rate of the radar, obtained from the field fRepFreqHz in the object's header.

• NumberOfDopplerCells is the total number of Doppler bins in the spectrum.

This calculation is fundamental for understanding the frequency spacing between adjacent Doppler bins in the radar spectrum.

Value

A numeric value representing the Doppler spectrum resolution in Hertz (Hz).

See Also

seasonder_getnDopplerCells to retrieve the number of Doppler cells. seasonder_getSeaSondeRCS_headerField to access specific header fields.

Description

This function retrieves the maximum radial velocity ('currmax') parameter from the FOR parameters in a SeaSondeRCS object.

Usage

seasonder_getFOR_currmax(seasonder_cs_object)

Arguments

Value

The value of the 'currmax' parameter.

Examples

# Minimal example for seasonder_getFOR_currmax
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
currmax_value <- seasonder_getFOR_currmax(cs_obj)
print(currmax_value)

Description

This function retrieves the power dropoff threshold ('fdown') for First Order Region detection from a SeaSondeRCS object.

Usage

seasonder_getFOR_fdown(seasonder_cs_object)

Arguments

Value

The value of the 'fdown' parameter.

Examples

# Minimal example for seasonder_getFOR_fdown
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
fdown_value <- seasonder_getFOR_fdown(cs_obj)
print(fdown_value)

Description

This function retrieves the null limit ('flim') parameter for FIRST Order Region processing from a SeaSondeRCS object.

Usage

seasonder_getFOR_flim(seasonder_cs_object)

Arguments

Value

The value of the 'flim' parameter.

Examples

# Minimal example for seasonder_getFOR_flim
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
flim_value <- seasonder_getFOR_flim(cs_obj)
print(flim_value)

Description

This function retrieves the noise factor ('noisefact') used in FOR processing from a SeaSondeRCS object.

Usage

seasonder_getFOR_noisefact(seasonder_cs_object)

Arguments

Value

The value of the 'noisefact' parameter.

Examples

# Minimal example for seasonder_getFOR_noisefact
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
noise_factor <- seasonder_getFOR_noisefact(cs_obj)
print(noise_factor)

Description

This function retrieves the Doppler smoothing factor ('nsm') from the FOR parameters in a SeaSondeRCS object.

Usage

seasonder_getFOR_nsm(seasonder_cs_object)

Arguments

Value

The value of the 'nsm' parameter.

Examples

# Minimal example for seasonder_getFOR_nsm
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
smoothing_factor <- seasonder_getFOR_nsm(cs_obj)
print(smoothing_factor)

Description

This function retrieves the First Order Region (FOR) parameters associated with a SeaSondeR cross-spectral object. If no FOR parameters are found in the object's attributes, it initializes them using seasonder_validateFOR_parameters.

Usage

seasonder_getFOR_parameters(seasonder_cs_object)

Arguments

Details

The function extracts the FOR parameters stored within the object. If the parameters are missing, the function initializes them using seasonder_validateFOR_parameters and assigns default values where necessary.

FOR Parameters:

• nsm: Doppler smoothing factor.

• fdown: Peak power dropoff threshold.

• flim: Null below peak power threshold.

• noisefact: Signal-to-noise threshold.

• currmax: Maximum velocity allowed.

• reject_distant_bragg: Flag to reject distant Bragg signals.

• reject_noise_ionospheric: Flag to reject ionospheric noise contamination.

• reject_noise_ionospheric_threshold: Threshold (in dB) for rejecting noise-affected Bragg signals.

• reference_noise_normalized_limits: Estimated limits for reference noise in normalized Doppler frequency.

Value

A named list containing the validated FOR parameters.

See Also

seasonder_validateFOR_parameters for initializing and validating FOR parameters. seasonder_defaultFOR_parameters for retrieving default parameter values.

Description

This function extracts a specified First Order Region (FOR) parameter from a SeaSondeRCS object.

Usage

seasonder_getFORParameter(seasonder_cs_object, FOR_parameter)

Arguments

Details

The function retrieves the list of FOR parameters using seasonder_getFOR_parameters() and extracts the value associated with FOR_parameter. If the parameter is not found, an error is logged.

Value

The value of the specified FOR parameter if found; otherwise, an error message is logged.

Examples

# Minimal example for seasonder_getFORParameter
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
nsm_value <- seasonder_getFORParameter(cs_obj, "nsm")
print(nsm_value)

Description

This function fetches the most recent log entries from the global log variable seasonder_the$log.

Usage

seasonder_getLog(n = 100)

Arguments

Value

A character vector of the n most recent log entries from the global log.

Examples

head(seasonder_getLog())

Description

This function returns the key configuration parameters for the MUSIC algorithm from a SeaSondeRCS object.

Usage

seasonder_getMUSICConfig(seasonder_cs_object)

Arguments

Details

The configuration is aggregated from the MUSIC_data attribute of the object for easy access.

Value

A list containing:

• doppler_interpolation: The Doppler interpolation factor.

• MUSIC_parameters: The numeric vector of MUSIC parameters.

Examples

# Minimal example for seasonder_getMUSICConfig
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
config <- seasonder_getMUSICConfig(cs_obj)
print(config)

Description

This function obtains the Doppler interpolation factor used in the MUSIC algorithm from a SeaSondeRCS object.

Usage

seasonder_getMUSICDopplerInterpolation(seasonder_cs_object)

Arguments

Details

The function accesses the MUSIC_data attribute under MUSIC_options and retrieves the doppler_interpolation parameter. If absent, it defaults to 1L.

Value

An integer representing the Doppler interpolation factor.

Examples

# Assuming cs_object is a valid SeaSondeRCS object.
# Minimal example for seasonder_getMUSICDopplerInterpolation
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
interp_factor <- seasonder_getMUSICDopplerInterpolation(cs_obj)
print(interp_factor)

Description

This function extracts the proportion of dual solutions from the MUSIC data in a SeaSondeRCS object.

Usage

seasonder_getMUSICDualSolutionsProportion(seasonder_cs_object)

Arguments

Details

The function checks the MUSIC_data attribute for a dual_solutions_proportion value. If not available, it defaults to NA_real_.

Value

A numeric value representing the dual solutions proportion, or NA if not set.

Examples

# Minimal example for seasonder_getMUSICDualSolutionsProportion
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
dual_prop <- seasonder_getMUSICDualSolutionsProportion(cs_obj)
print(dual_prop)

Description

This function extracts the interpolated MUSIC cross-spectra data from a SeaSondeRCS object.

Usage

seasonder_getMUSICInterpolatedData(seasonder_cs_object)

Arguments

Details

The function first checks if the interpolated data is set in the MUSIC_data attribute. If absent, it initializes the data with seasonder_MUSICInitInterpolatedData().

Value

A list representing the interpolated cross-spectra data.

Examples

# Minimal example for seasonder_getMUSICInterpolatedData
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
interp_data <- seasonder_getMUSICInterpolatedData(cs_obj)
str(interp_data)

Description

This function extracts the index of interpolated Doppler cells, stored in the MUSIC_data attribute of a SeaSondeRCS object.

Usage

seasonder_getMUSICInterpolatedDopplerCellsIndex(seasonder_cs_object)

Arguments

Details

The interpolated doppler cells index is part of the MUSIC_data and is used to identify which Doppler bins were introduced during the interpolation process.

Value

A vector of indices corresponding to the interpolated Doppler cells.

Examples

# Minimal example for seasonder_getMUSICInterpolatedDopplerCellsIndex
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
doppler_index <- seasonder_getMUSICInterpolatedDopplerCellsIndex(cs_obj)
print(doppler_index)

Description

This function extracts the MUSIC options from a SeaSondeRCS object.

Usage

seasonder_getMUSICOptions(seasonder_cs_object)

Arguments

Details

The function retrieves the MUSIC options from the object's MUSIC_data attribute. In the absence of user-defined options, it returns the default options provided by seasonder_defaultMUSICOptions().

Value

A list of MUSIC options.

Examples

# Minimal example for seasonder_getMUSICOptions
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
opts <- seasonder_getMUSICOptions(cs_obj)
print(opts)

Description

Get the nDopplerCells value from a SeaSondeRCS object

Usage

seasonder_getnDopplerCells(seasonder_obj)

Arguments

Value

The nDopplerCells value.

Examples

# Minimal example for seasonder_getnDopplerCells
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
n_doppler_cells <- seasonder_getnDopplerCells(cs_obj)
print(n_doppler_cells)

Description

Get the nRangeCells value from a SeaSondeRCS object

Usage

seasonder_getnRangeCells(seasonder_obj)

Arguments

Value

The nRangeCells value.

Examples

# Minimal example for seasonder_getnRangeCells
cs_file <- system.file("css_data/CSS_TORA_24_04_04_0700.cs", package = "SeaSondeR")
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
n_range_cells <- seasonder_getnRangeCells(cs_obj)
print(n_range_cells)

Description

This function computes the radar wavelength based on the center frequency of the SeaSonde radar system. The wavelength is derived using the speed of light and the radar's center frequency.

Usage

seasonder_getRadarWaveLength(seasonder_cs_object)

Arguments

Details

The radar wavelength $\lambda$ is calculated using the formula: $\lambda = \frac{c}{f}$ where:

• $c$ is the speed of light (approximately $3 * 10^8$ m/s),

• $f$ is the radar's center frequency in Hz, retrieved from the SeaSondeRCS object.

The center frequency is initially stored in MHz and is converted to Hz by multiplying it by $10^6$.

Value

A numeric value representing the radar wavelength in meters (m).

See Also

seasonder_getCenterFreqMHz to retrieve the radar's center frequency.

Description

This function computes the radar wave number $k$ for a SeaSonde radar system based on its wavelength. The wave number represents the spatial frequency of the radar wave.

Usage

seasonder_getRadarWaveNumber(seasonder_cs_object)

Arguments

Details

The radar wave number $k$ is calculated using the formula: $k = \frac{2 \pi}{\lambda}$ where:

• $\lambda$ is the radar wavelength in meters, calculated using seasonder_getRadarWaveLength.

• $2 \pi$ represents the relationship between the wavelength and wave number.

The wave number is an essential parameter for analyzing radar signals and their interaction with the medium being measured.

Value

A numeric value representing the radar wave number $k$ in radians per meter.

See Also

seasonder_getRadarWaveLength to compute the radar wavelength.

Description

Computes the radial velocity resolution for a SeaSonde radar cross-section (CS) object. This measurement indicates the smallest change in velocity that the radar can discern between different targets or scatterers within its observation area. The calculation is based on the Doppler spectrum resolution and the radar wave number, providing a crucial parameter for analyzing the radar's capability to distinguish between velocities.

Usage

seasonder_getRadialVelocityResolution(seasonder_cs_object)

Arguments

Details

The radial velocity resolution $v_{res}$ is determined using the formula:

$v_{res} = \frac{\text{SpectraRes}}{2 \cdot k_0}$

where $v_{res}$ is the radial velocity resolution, $\text{SpectraRes}$ is the Doppler spectrum resolution, and $k_0$ is the radar wave number divided by $2\pi$. This formula reflects the relationship between the frequency resolution of the radar's Doppler spectrum and the corresponding velocity resolution, taking into account the wave number which is a fundamental characteristic of the radar system.

Value

A single numeric value representing the radial velocity resolution in meters per second (m/s), indicating the radar's ability to differentiate between closely spaced velocities.

See Also

seasonder_getDopplerSpectrumResolution, seasonder_getRadarWaveNumber