Skip to content

Latest commit

 

History

History
161 lines (115 loc) · 8.03 KB

gnssir.md

File metadata and controls

161 lines (115 loc) · 8.03 KB

gnssir

gnssir is the main driver for the GNSS-IR code.

You need a set of instructions which are made using make_json_input. The required inputs are:

  • station name
  • latitude (degrees)
  • longitude (degrees)
  • ellipsoidal height (meters).

The station location does not have to be cm-level for the reflections code. Within a few hundred meters is sufficient. For example:

make_json_input p101 41.692 -111.236 2016.1

If you happen to have the Cartesian coordinates (in meters), you can set -xyz True and input those instead of lat, long, and height.

If you are using a site that is in the UNR database, as of 2021/10/26 you can set the a priori values to zeros:

make_json_input p101 0 0 0

gnssir will use defaults for other parameters if you do not provide them. Those defaults tell the code an azimuth and elevation angle mask (i.e. which directions you want to allow reflections from), and which frequencies you want to use, and various quality control (QC) metrics. Right now the default frequencies are GPS only, e.g. L1, L2C and L5.

The json file of instructions will be put in $REFL_CODE/input/p101.json. You should look at it to get an idea of the kinds of inputs the code uses. The default azimuths can be changed. Some parameters can be set via the command line, as in:

make_json_input p101 41.692 -111.236 2016.1 -e1 5 -e2 10

This changes elevation angles to 5-10 degrees. The default is to only use GPS frequencies, specifically L1, L2C, and L5. If you want all GNSS frequencies (GPS, Glonass, Galileo, Beidou):

make_json_input p101 41.692 -111.236 2016.1 -e1 5 -e2 10 -allfreq True

To only use GPS L1:

make_json_input p101 41.692 -111.236 2016.1 -e1 5 -e2 10 -l1 True

See below to learn the setting for setting specific frequencies.

To only use GPS L2C and require a spectral amplitude of 10:

make_json_input p101 41.692 -111.236 2016.1 -e1 5 -e2 10 -l2c True -ampl 10

To use GPS L2C, require a spectral amplitude of 10, and spectral peak to noise ratio of 3:

make_json_input p101 41.692 -111.236 2016.1 -e1 5 -e2 10 -l2c True -ampl 10 -peak2noise 3

Azimuth regions should not be larger than ~100 degrees. If for example you want to use the region from 0 to 270 degrees, you should not set a region from 0 - 270, but instead a region from 0-90, 90-180, and the last from 180-270. I know this is a bit offputting for people, but having these smaller regions makes the code easier to maintain (i.e. you are less likely to have more than one rising and setting arc for a single satellite).

make_json_input p101 41.692 -111.236 2016.1 -e1 5 -e2 10 -l2c True -ampl 10 -peak2noise 3 -azlist 0 90 90 180 180 270

The default is to allow four regions, each of 90 degrees.

Other things that are helpful to know for the make_json_input inputs:

  • Some json settings can be set at the command line. run make_json_input -h to see these.
    Otherwise, you will need to edit the json file. Note that there are a few inconstencies between the command line names and the json file (for example, h1 and h2 on the command line become minH and maxH in the json file). I apologize for this.
  • e1 and e2 are the min and max elevation angle, in degrees
  • minH and maxH are the min and max allowed reflector height, in meters
  • ediff, in degrees: restricts arcs to be within this range of input elevation angles e1 and e2
  • desiredP, desired reflector height precision, in meters
  • PkNoise is the periodogram peak divided by the periodogram noise ratio.
  • reqAmp is the required periodogram amplitude value, in volts/volts
  • polyV is the polynomial order used for removing the direct signal
  • freqs are selected frequencies for analysis
  • delTmax is the maximum length of allowed satellite arc, in minutes
  • wantCompression, boolean, compress SNR files using xz
  • screenstats, boolean, whether minimal periodogram results come to screen
  • refraction, boolean, whether simple refraction model is applied.
  • plt_screen: boolean, whether SNR data and periodogram are plotted to the screen
  • NReg [min and max required] : define the RH region (in meters) where the "noise value" for the periodogram is computed. This is used to compute the peak to noise ratio used in QC.
  • (this option has been removed) seekRinex: boolean, whether code looks for RINEX at an archive
  • azlist : pairs of azimuth regions, degrees, as described earlier
  • frlist : allows direct input of frequencies, i.e. -frlist 1 2 or -frlist 1 20 101 102

Simple examples for my favorite GPS site p041

make_json_input p041 39.949 -105.194 1728.856 (use defaults and write out a json instruction file)

rinex2snr p041 2020 150 (pick up and translate RINEX file for day of year 150 and year 2020 from unavco )

gnssir p041 2020 150 (calculate the reflector heights)

gnssir p041 2020 150 -fr 5 -plt True (override defaults, only look at L5 SNR data, and periodogram plots come to the screen)

Where would the code store the files for this example?

  • json instructions are stored in $REFL_CODE/input/p041.json
  • SNR files are stored in $REFL_CODE/2020/snr/p041
  • Reflector Height (RH) results are stored in $REFL_CODE/2020/results/p041

This is a snippet of what the result file would look like

  • Amp is the amplitude of the most significant peak in the periodogram (i.e. the amplitude for the RH you estimated).
  • DelT is how long a given rising or setting satellite arc was, in minutes.
  • emin0 and emax0 are the min and max observed elevation angles in the arc.
  • rise/set tells you whether the satellite arc was rising (1) or setting (-1)
  • Azim is the average azimuth angle of the satellite arc
  • sat and freq are as defined in this document
  • MJD is modified julian date
  • PkNoise is the peak to noise ratio of the periodogram values
  • last column is currently set to tell you whether the refraction correction has been applied
  • EdotF is used in the RHdot correction needed for dynamic sea level sites. The units are hours/rad. When multiplied by RHdot (meters/hour), you will get a correction in units of meters. For further information, see subdaily.

If you want a multi-GNSS solution, you need to:

  • make sure your json file is set appropriately
  • use a RINEX file with multi-GNSS data in it (i.e. use multi-GNSS orbits and in some cases rerun rinex2snr).

In 2020 p041 had a multi-GNSS receiver operating, so we can look at some of the non-GPS signals. In this case, we will look at Galileo L1.

make_json_input p041 39.949 -105.194 1728.856 -allfreq True

rinex2snr p041 2020 151 -orb gnss -overwrite True

gnssir p041 2020 151 -fr 201 -plt True

Note that a failed satellite arc is shown as gray in the periodogram plots. And once you know what you are doing (have picked the azimuth and elevation angle mask), you won't be looking at plots anymore.

New:

Before you start interpreting the results (using daily_avg, subdaily, vwc), and you just want to "see" the reflector height results, I have added a new utility: rh_plot It allows you to visualize results for up to a single year. It concantenates the RH results in case you want to use another program (e.g. Matlab) to do more assessment. It creates a single txt file and a plot where the RH results are plotted with respect to time, color coded by signal frequency, azimuth, and periodogram amplitude. The azimuth plots in particular might help you see that you should change your azimuth mask.

The required inputs are station name and year. Beyond that you can request:

  -doy1    initial day of year
  -doy2    end day of year
  -ampl    new amplitude constraint
  -azim1   new min azimuth (deg)
  -azim2   new max azimuth (deg)
  -h1 H1   min RH (m)
  -h2 H2   max RH (m)
  -peak2noise new peak2noise constraint