Skip to contents

Export Radial Metrics from a SeaSondeRCS Object

Source: R/SeaSondeRCS_MUSIC.R
seasonder_exportRadialMetrics.Rd

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

seasonder_cs_object

A SeaSondeRCS object containing MUSIC detection data and related metadata.

AngSeg

An optional list of angular segments to be applied to the vector flag field (VFLG). Each element should be a numeric vector of length 3 defining a segment. Default is an empty list.

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.

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.

Examples

# \donttest{
# Prepare a SeaSondeRCS object with MUSIC data
apm_file <- system.file("css_data/MeasPattern.txt", package = "SeaSondeR")
apm_obj <- seasonder_readSeaSondeRAPMFile(apm_file)
#> seasonder_createSeaSondeRAPM:  APM object created successfully.
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)
#> new_SeaSondeRCS:  SeaSondeRCS object created successfully.
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)
#> seasonder_runMUSIC:  MUSIC algorithm started.
#> seasonder_runMUSIC:  MUSIC algorithm finished.
radial_metrics <- seasonder_exportRadialMetrics(cs_obj, AngSeg = list(c(5, 30, 60)))
head(radial_metrics)
#>        LOND     LATD        VELU        VELV VFLG      RNGE BEAR       VELO
#> 1 -8.803399 42.20252 -0.73150986   0.8124240    0 0.1870365  318 -1.0932243
#> 2 -8.803050 42.20271  0.08548836  -0.1422765    0 0.1870365  329  0.1659845
#> 3 -8.801221 42.20288 -0.04852919  -0.1587318    0 0.1870365   17  0.1659845
#> 4 -8.802199 42.20293  1.42508463 -10.1400040    0 0.1870365  352 10.2396556
#> 5 -8.804139 42.20112 10.20069064   0.8924448    0 0.1870365  265 10.2396556
#> 6 -8.801183 42.20287 -3.55334455 -10.9360700    0 0.1870365   18 11.4988645
#>   HEAD SPRC SPDC MSEL MSA1 MDA1 MDA2      MEGR     MPKR        MOFR       MP13
#> 1  138    1  332    1  318   16 1440 37.517644 0.000000 0.000000000   9.817918
#> 2  149    1  333    2  347  329   17 18.529681 1.281161 0.008196858 -10.360013
#> 3  197    1  333    3  347  329   17 18.529681 1.281161 0.008196858 -10.360013
#> 4  172    1  341    2   18  352  265 10.680977 1.255016 0.480175432  18.178391
#> 5   85    1  341    3   18  352  265 10.680977 1.255016 0.480175432  18.178391
#> 6  198    1  342    1   18  357   11  7.646877 1.087325 0.966261326   5.698105
#>        MP23      MSP1      MDP1      MDP2 MSW1 MDW1 MDW2      MSR1        MDR1
#> 1 -74.77181 -94.73992 -94.11004   0.00000   88    2    0  6.030989 10797.14624
#> 2 -52.03949 -93.92921 -96.44397 -97.52001   21    4   91 43.954436  3684.43241
#> 3 -52.03949 -93.92921 -96.44397 -97.52001   21    4   91 43.954436  3684.43241
#> 4 -77.73468 -93.13555 -94.14548 -93.15898   52    3  142  7.804122 10080.28745
#> 5 -77.73468 -93.13555 -94.14548 -93.15898   52    3  142  7.804122 10080.28745
#> 6 -83.72088 -93.22757 -81.36097 -80.99737   58   30   38  7.408590    98.57057
#>        MDR2     MA1S     MA2S     MA3S         MEI1         MEI2         MEI3
#> 1  0.000000 1.360982 9.018854 6.186278 5.473080e-10 1.458802e-11 5.887997e-12
#> 2 33.138962 3.853958 8.727675 7.514739 6.686443e-10 3.608504e-11 6.028202e-12
#> 3 33.138962 3.853958 8.727675 7.514739 6.686443e-10 3.608504e-11 6.028202e-12
#> 4  1.349332 5.822285 6.497650 8.659952 7.490601e-10 7.013029e-11 4.088580e-12
#> 5  1.349332 5.822285 6.497650 8.659952 7.490601e-10 7.013029e-11 4.088580e-12
#> 6 56.402574 5.526817 7.654325 8.519368 7.301015e-10 9.547708e-11 2.856018e-12
#>   MDRJ PPFG PWFG
#> 1   16    9    9
#> 2    0    9    9
#> 3    0    9    9
#> 4    0    9    9
#> 5    0    9    9
#> 6   12    9    9
# }