# Exporting Radial Metrics

    library(SeaSondeR)

# Exporting Radial Metrics in SeaSondeR

This vignette demonstrates how to export radial metrics from HF-Radar spectra using the SeaSondeR package. The exported radial metrics table contains key parameters (e.g. DOAs, FOR limits, signal strengths) that can be used with tools such as Sea Display.

## Example

    # Set sample file paths
    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)
    #> seasonder_createSeaSondeRAPM: APM object created successfully.

    # Create a SeaSondeRCS object from a spectral file
    cs_obj <- seasonder_createSeaSondeRCS(cs_file, seasonder_apm_object = apm_obj)
    #> new_SeaSondeRCS: SeaSondeRCS object created successfully.

    # Compute first-order regions and run the MUSIC algorithm if needed:

    cs_obj <- seasonder_computeFORs(cs_obj, FOR_control = list(nsm = 2, fdown = 10^(10/10), flim = 10^(20/10),
                                                                noisefact = 10^(6/10), currmax = 2,
                                                                reject_distant_bragg = TRUE, reject_noise_ionospheric = FALSE,
                                                                reject_noise_ionospheric_threshold = 0))
    #> seasonder_rejectDistantBraggPeakTest: First Order Rejected at range 3, peak negative_FOR. Distance Bragg test failed.
    #> seasonder_rejectDistantBraggPeakTest: First Order Rejected at range 53, peak negative_FOR. Distance Bragg test failed.
    #> seasonder_rejectDistantBraggPeakTest: First Order Rejected at range 54, peak negative_FOR. Distance Bragg test failed.
     cs_obj <- seasonder_runMUSICInFOR(cs_obj)
    #> seasonder_runMUSIC:  MUSIC algorithm started.
    #> seasonder_runMUSIC:  MUSIC algorithm finished.

    # Define a land mask (AngSeg) to remove onshore data
    AngSeg <- purrr::list_c(lapply(45:61, function(i) list(c(i, 313, 360), c(i, 0, 31))))

    temp_file <- tempfile(fileext = ".ruv")

    # Export the radial metrics in LLUV format
    radial_metrics <- seasonder_exportLLUVRadialMetrics(cs_obj,
                                                        LLUV_path = temp_file,
                                                        AngSeg = AngSeg)

    # Display the first few rows of the exported radial metrics
    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.810673 42.20290 -10.83519089   2.7015165    0 0.7481461  284 -11.1668954
    #>   HEAD SPRC SPDC MSEL MSA1 MDA1 MDA2     MEGR     MPKR        MOFR       MP13
    #> 1  138    1  332    1  318   16 1440 37.51764 0.000000 0.000000000   9.817918
    #> 2  149    1  333    2  347  329   17 18.52968 1.281161 0.008196858 -10.360013
    #> 3  197    1  333    3  347  329   17 18.52968 1.281161 0.008196858 -10.360013
    #> 4  172    1  341    2   18  352  265 10.68098 1.255016 0.480175432  18.178391
    #> 5   85    1  341    3   18  352  265 10.68098 1.255016 0.480175432  18.178391
    #> 6  104    4  324    2  303  284   17 14.73077 1.888563 0.169387956  62.720131
    #>        MP23      MSP1      MDP1      MDP2 MSW1 MDW1 MDW2      MSR1      MDR1
    #> 1 -74.77181 -94.73992 -94.11004   0.00000   88    2    0  6.030989 10797.146
    #> 2 -52.03949 -93.92921 -96.44397 -97.52001   21    4   91 43.954436  3684.432
    #> 3 -52.03949 -93.92921 -96.44397 -97.52001   21    4   91 43.954436  3684.432
    #> 4 -77.73468 -93.13555 -94.14548 -93.15898   52    3  142  7.804122 10080.287
    #> 5 -77.73468 -93.13555 -94.14548 -93.15898   52    3  142  7.804122 10080.287
    #> 6 -42.53534 -93.15633 -95.86587 -98.62718   61    4  142  9.589858  3357.601
    #>        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  8.765369 2.744370 9.868149 8.270750 8.306654e-10 5.638981e-11 5.380048e-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    0    9    9

The example above exports the radial metrics into a file (LLUV format) that can later be reviewed using visualization applications such as Sea Display.

## Description of the Radial Metrics Table

Below are the columns of the exported Radial Metrics table in SeaSondeR.

Column | Description
--- | ---
LOND, LATD | Longitude and latitude (decimal degrees)
VELU, VELV | East and north components of velocity (cm/s)
VFLG | Vector validity (see below)
RNGE | Distance from the antenna (km)
BEAR | Bearing of the vector (counter-clockwise from true north)
VELO | Radial velocity (cm/s)
HEAD | Velocity direction (counter-clockwise from true north)
SPRC | Range cell
SPDC | Doppler bin
MSEL | Selected solution (1 = single, 2 = dual 1, 3 = dual 2)
MSA1 | Bearing of the single solution (1440 if invalid)
MDA1, MDA2 | Bearing of the first and second dual solutions (1440 if invalid)
MEGR | Ratio of the first and second eigenvalue
MPKR | Signal power ratio
MOFR | Off-diagonal ratio
MP13 | Phase between antennas 1 and 3
MP23 | Phase between antennas 2 and 3
MSP1 | Signal power of the single solution (dB)
MDP1, MDP2 | Signal power of the first and second dual solutions (dB)
MSW1 | 3-dB width of the DOA function below the peak for the single solution
MDW1, MDW2 | 3-dB width of the DOA function below the peak for the first and second dual solutions
MSR1 | Value of DOA function at the peak of the single solution
MDR1 | Value of DOA function at the peak of the first dual solution
MDR2 | Value of DOA function at the peak of the second dual solution
MA1S, MA2S, MA3S | SNR of the self-spectrum of antennas 1, 2, and 3 for this Doppler bin
MEI1, MEI2, MEI3 | First, second, and third eigenvalue of the covariance matrix
MDRJ | Reason for dual-solution rejection (see below)
PPFG, PWFG | Flags for QARTOD tests 103 and 104 (1 = pass, 4 = fail)

### VFLG

The value is composed as a sum of powers of 2, representing a binary number where each bit indicates a specific flag.

Value | Description
--- | ---
0 | Valid vector
+64 | Low SNR
+4096 | Either PPFG or PWFG is not equal to 1

### MDRJ

This value is also composed as a sum of powers of 2, where each bit represents a flag.

Value | Description
--- | ---
0 | Dual solution not rejected
+1 | P1 test failure
+2 | P2 test failure
+4 | P3 test failure
+8 | The angle difference between both solutions is less than 20 degrees
+16 | Only one peak was found in the dual solution