# GNATSS Config File The GNSS-Acoustic positioning performed by GNATSS is governed by a configuration file. This is a text file with a YAML format that defines the _a priori_ geometry of the GNSS-Acoustic array. The configuration file is divided into multiple sections, but not all of the sections are required depending on your processing needs. In general, GNATSS operates in two modes, a pre-processing mode that operates on wave glider data to generate input required for array positioning, and a solver mode that performs the array positioning using the data computed by the pre-processing. There are two styles of pre-processing. The default pre-processing is the [_posfilter_](gnssa_preprocessing.md) mode, short for "position filter", which infers Wave Glider positions using a spline interpolation in tandem with a Kalman filter. The alternative pre-processing mode is the [_parsed_](parsed_processing.md) mode, which is designed to operate in a reduced capacity on 2-minute subsampled (or "parsed") data sets telemetered to shore in real-time during a survey. The posfilter and parsed modes may be defined in the same configuration file, but only one may be called when invoking `gnatss run`. By default GNATSS assumes pre-processing is done with the posfilter, but the parsed pre-processing can be executed by adding the `--parsed` flag. These modes are defined separately in the config file. It is possible to run only one mode at a time or to run a pre-processing mode and the solver in sequence, so it is optional to include their information in the config file. At a high level, the sections of the configuration file are: - Metadata _(required)_: Information about the array - Posfilter configuration _(optional)_: Pre-processing configuration - Parsed configuration _(optional)_: Pre-processing configuration for real-time observations - Solver _(optional)_: Array positioning configuration - Output configuration _(required)_: Destination for output files Further information on the input data formats may be found on the [Required Input Data](./input.md) page. A template of the configuration file is: ``` # Metadata site_id: SITE #Site Identifier campaign: Region #Geographical region/Subduction Zone time_origin: YYYY-MM-DD 00:00:00 #Time of survey array_center: lat: xx.yyyy #decimal latitude lon: xxx.yyyy #decimal longitude transponders: # list out all transponder and info, each entry is a different transponder (default: 3 transponders) - lat: xx.yyyyyyyyyy #decimal latitude lon: xx.yyyyyyyyyy #decimal longitude height: -zzzz.zz #transponder depth (m, positive up) internal_delay: t.tttt #Transponder Turn-Around Time (s) sv_mean: vvvv.vvv #Estimate of mean sound velocity (m/s) - lat: xx.yyyyyyyyyy #decimal latitude lon: xx.yyyyyyyyyy #decimal longitude height: -zzzz.zz #transponder depth (m, positive up) internal_delay: t.tttt #Transponder Turn-Around Time (s) sv_mean: vvvv.vvv #Estimate of mean sound velocity (m/s) - lat: xx.yyyyyyyyyy #decimal latitude lon: xx.yyyyyyyyyy #decimal longitude height: -zzzz.zz #transponder depth (m, positive up) internal_delay: t.tttt #Transponder Turn-Around Time (s) sv_mean: vvvv.vvv #Estimate of mean sound velocity (m/s) travel_times_variance: 1e-10 #Default value travel_times_correction: 0.0 #Default value transducer_delay_time: 0.0 #Default value # Posfilter configuration posfilter: export: full: false #false for only required fields, true to include optional RPH value and uncertainties atd_offsets: forward: 0.0053 #Value for SV3 Wave Glider rightward: 0 #Value for SV3 Wave Glider downward: 0.92813 #Value for SV3 Wave Glider input_files: novatel: path: /path/to/file #File with INSPVAA strings novatel_std: path: /path/to/file #File with INSSTDEVA strings gps_positions: #By default assume Chadwell format, (j2000 seconds, "GPSPOS" string, ECEF XYZ coordinates (m), XYZ Standard Deviations) path: /path/to/GPS_POS_FREED #File path to antenna positions, use wildcards ** for day-separated data format: key #Optional designation for alternate GNSS Position file formats travel_times: #By Default assume Chadwell format, (Time at Ping send [DD-MON-YY HH:MM:SS.ss], TWTT1 (microseconds), TWTT2, TWTT3, TWTT4), TWTT=0 if no reply path: /path/to/file #File path to TWTT data, use wildcards ** for day-separated data format: key #Optional designation for alternate TWTT file formats # Parsed configuration parsed: export: full: false #false for only required fields, true to include optional RPH value and uncertainties atd_offsets: forward: 0.0053 #Value for SV3 Wave Glider rightward: 0 #Value for SV3 Wave Glider downward: 0.92813 #Value for SV3 Wave Glider input_files: gps_positions: #By default assume Chadwell format, (j2000 seconds, "GPSPOS" string, ECEF XYZ coordinates (m), XYZ Standard Deviations) path: /path/to/file #File path to antenna positions, use wildcards ** for day-separated data format: key #Optional designation for alternate GNSS Position file formats raw_data: #Assume Wave Glider model SV-3 zipped pin files (*.tar.gz) path: /path/to/file #File path to QC data, use wildcards ** for day-separated data # Solver configuration solver: reference_ellipsoid: #These values should be constant unless the Earth changes semi_major_axis: 6378137.000 reverse_flattening: 298.257222101 gps_sigma_limit: 0.05 #Uncertainty threshold for transducer positions, data with larger uncertainties ignored std_dev: true #true=standard deviation, false=covariance, probably deprecated geoid_undulation: xx.yy #Geoid height in m bisection_tolerance: 1e-10 #Do not change harmonic_mean_start_depth: -4.0 #Shallowest water depth for calculating mean sound velocity from CTD data input_files: sound_speed: #Assume 2-column text file with depth (m), sound velocity (m/s) path: /path/to/file # deletions: # Path to deletns.dat deletions file used by Chadwell code as well # path: /path/to/deletns.dat #gps_solution: /path/to/gps_solution.csv #Path to pre-processed input data in standard GNSS-A data format, this skips the Posfilter step # path: /path/to/gps_solution.csv #quality_control: # path: /path/to/quality_control.csv # Output configuration output: # Directory path to output directory path: /path/to/output/ ``` The information that should be defined in the config.yaml file is as follows: ### Metadata - **Site ID** This is the name of the array, generally denoted by a four-letter code - **Campaign** The geographical region where the array is located, generally a subduction zone - **Time Origin** The approximate date when the survey was conducted. Note that surveys may last multiple days, but only one date is required here since the data will be averaged into one final position. - **Array Center** The approximate center of the array. - **Transponders** A priori information for each transponder in the array. GNATSS is currently configured to operate on arrays of 3 transponders. GNATSS will assign names to the transponders based upon the order they are included in the configuration file. The first entry will be named "SITE-1", the second entry "SITE-2", etc. The following information must be provided: - lat: The latitude of the transponder in decimal degrees - lon: The longitude of the transponder in decimal degrees - height: The ellipsoidal height of the transponder in meters (negative down) - internal_delay: The user-defined transponder wait time in seconds. When the transponder receives an interrogation ping, it will wait for this amount of time before sending a reply ping in order to avoid interference between the replies from the array. - sv_mean: An initial estimate of the average sound velocity throughout the water column above the transponder in m/s - **Travel Time Variance** The assumed uncertainty of the acoustic two-way travel times, given as a variance. This value is treated as a constant and should not need to be modified. - **Travel Times Correction** This value is used to adjust the travel times and should not need to be changed. - **Transducer Delay Time** This is a time delay that is introduced by software on the wave glider separating when an interrogation ping is registered and when the acoustic pulse is sent by the transducer. By default, it is assumed that any transducer delay times are accounted for before or during the posfilter. Some surface platforms, notably the Sonardyne GNSS-A payload, also include this delay in the TWTT measurement despite the acoustic pulse not being in the water during the delay. In this case, the user must remove the delay from the TWTT measurements before running GNATSS or else the TWTT measurements will be systematically inflated by the delay. ### Posfilter configuration - **Export** The _full_ parameter determines whether to include roll, pitch, and heading values not required for the solver but useful for recalculating transducer positions. The default value of _false_ provides only the minimum data fields required for the solver, as defined by the [GNSS-Acoustic Standard Data Format](https://hal.science/hal-04319233/). - **ATD Offsets** The ATD offsets (also called the _lever arms_) are the static offsets between the GNSS antenna and acoustic transducer in the static body frame coordinates of the surface platform. The given values in the above template are the ATD offsets for the SV3 Wave Glider. - **Input Files** These are file paths to [input data](./input.md) required specifically for the posfilter mode, assumed to be collected by an SV3 wave glider using a Sonardyne GNSS-A payload. - The user may input a file path to a single input file or use the UNIX "\*\*" wildcard to point to multiple input files, such as day-separated data. - The novatel files contain raw NMEA strings describing the velocity, orientation, and standard deviations of the surface platform. - The GPS positions are assumed to be computed by the user with a GNSS processing software of their choice, such as PRIDE PPP-AR, GAMIT, or GipsyX. By default GNATSS assumes that the solution has been converted into a legacy Chadwell format, but other supported formats can be provided by designating an optional `format` key in the configuration file (See [_Required Input Data_](./input.md) for the list of supported file formats and keys). - The TWTT input file contains the ranges collected by the surface platform to every transponder in the array. These ranges should include the internal delay of the transponders but exclude the transducer delay time. By default GNATSS assumes this file is in the legacy Chadwell format, but other supported formats can be provided by designating an optional `format` key in the configuration file (See [_Required Input Data_](./input.md) for the list of supported file formats and keys). ### Parsed configuration - **Export** The _full_ parameter determines whether to include roll, pitch, and heading values not required for the solver but useful for recalculating transducer positions. The default value of _false_ provides only the minimum data fields required for the solver, as defined by the [GNSS-Acoustic Standard Data Format](https://hal.science/hal-04319233/). - **ATD Offsets** The ATD offsets (also called the _lever arms_) are the static offsets between the GNSS antenna and acoustic transducer in the static body frame coordinates of the surface platform. The given values in the above template are the ATD offsets for the SV3 Wave Glider. - **Input Files** These are file paths to [input data](./input.md) required specifically for the parsed mode, assumed to be collected by an SV3 wave glider using a Sonardyne GNSS-A payload. - The user may input a file path to a single input file or use the UNIX "\*\*" wildcard to point to multiple input files, such as day-separated data. - The GPS positions are assumed to be computed by the user with a GNSS processing software of their choice, such as PRIDE PPP-AR, GAMIT, or GipsyX. By default GNATSS assumes that the solution has been converted into a legacy Chadwell format, but other supported formats can be provided by designating an optional `format` key in the configuration file (See [_Required Input Data_](./input.md) for the list of supported file formats and keys). - The raw data files are zipped tarballs that contain data stored in a `.pin` format telemetered to shore by the LRI model SV-3 Wave Glider (See [_Required Input Data_](./input.md)). ### Solver configuration - **Reference Ellipsoid** Ellipsoidal parameters of the Earth. These should not have to change. - **GPS Sigma Limit** This is an uncertainty threshold in meters. If the uncertainty of the surface platform position crosses this threshold, the data will not be considered in the GNSS-A positioning due to poor positioning. - **Std_dev** Determines the uncertainty parameters of the surface platform positions. If _std_dev=true_, the position uncertainties are assumed to be standard deviations. If _std_dev=false_, the uncertainties are assumed to be variances. - **Geoid Undulation** The local geoid height at the center of the GNSS-Acoustic array in meters. - **Bisection Tolerance** Tolerance parameter for acoustic raytracing calculations. Should not need to be changed. - **Harmonic Mean Start Depth** GNATSS will automatically recalculate the harmonic mean sound velocity for each transponder in the array between the transponder depth and the starting depth defined here in meters. - **Input files** File paths to the input files required for the solver mode. These files include: - Sound speed file, as described in [_Required Input Data_](./input.md). - Deletions file, in legacy Chadwell format. A separate deletions file in GNATSS format is automatically generated and updated in the output file path. - GPS Solution file, containing the transducer positions and TWTTs in the [GNSS-Acoustic Standard Data Format](https://hal.science/hal-04319233/). Only required if not running the posfilter mode. If running end-to-end processing by calling the posfilter and solver module, the _gps_solution.csv_ file will be generated in the output path and can be automatically loaded by calling the _--from-cache_ flag when running GNATSS, in which case a file path does not need to be designated. - Quality Control file ### Output configuration - **Output Path** File path in which GNATSS will store posfilter and solver results.