Package: gnssrefl0
gnssrefl0This package is a new version of my GNSS interferometric reflectometry (GNSS_IR) code.The main difference bewteen this version and previous versions is that I am
attempting to use proper python packaging rules, LOL. I have separated out the main
parts of the code and the command line inputs so that you can use the gnssrefl0 libraries
yourself or do it all from the command line. This should also - hopefully - make
it easier for the production of Jupyter notebooks. The latter are to be developed
by UNAVCO with NASA funding.For those of you who don't like reading documentationI recommend you use the web appI developed. It
can show you how the technique works without installing any code. It also picks up
the data for you and provides results in less than 10 seconds.Overview CommentsThe goal of this python repository is to help you compute (and evaluate) GNSS-based
reflectometry parameters using geodetic data. This method is often
called GNSS-IR, or GNSS Interferometric Reflectometry. There are three main codes:rinex2snrtranslates RINEX files into SNR files needed for analysis.gnssircomputes reflector heights (RH) from GNSS data.quickLookgives you a quick (visual) assessment of a file without dealing
with the details associated withgnssir.There is also a RINEX download scriptdownload_rinex, but it is not required.Environment VariablesYou should define three environment variables:EXE = where various RINEX executables will live.ORBITS = where the GPS/GNSS orbits will be stored. They will be listed under directories by
year and sp3 or nav depending on the orbit format.REFL_CODE = where the reflection code inputs (SNR files and instructions) and outputs (RH)
will be stored (see below). Both SNR files and results will be saved here in year subdirectories.However, if you do not do this, the code will assume your local working directory (where you installed
the code) is where you want everything to be. The orbits, SNR files, and periodogram results are stored in
directories in year, followed by type, i.e. snr, results, sp3, nav, and then by station name.PythonIf you are using the version from gitHub:make a directory, cd into that directory, set up a virtual environment, a la python3 -m venv env, activate itgit clonehttps://github.com/kristinemlarson/gnssrefl0pip install .If you use the PyPi version:make a directory, cd into that directory, set up a virtual environment, activate itpip install gnssrefl0Non-Python CodeAll executables should be stored in the EXE directory.  If you do not define EXE, it will look for them in your
local working directory.  The Fortran translators are much faster than using python. But if
you don't want to use them,
they are optional, that's fine. FYI, the python version is slow
not because of the RINEX - it is because you need to calculate
a crude model for satellite coordinates in this code. And that takes cpu time....Requiredtranslator for compressed RINEX files. CRX2RNX,http://terras.gsi.go.jp/ja/crx2rnx.htmlOptional Fortran RINEX Translator for GPS, the executable must be called gpsSNR.e,https://github.com/kristinemlarson/gpsonlySNROptional Fortran RINEX translator for multi-GNSS, the executable must be called gnssSNR.e,https://github.com/kristinemlarson/gnssSNROptional datatool, teqc, is highly recommended.  There is a list of static executables at the
bottom ofthis pageOptional datatool, gfzrnx is required if you plan to use the RINEX 3 option. Executables available from the GFZ,http://dx.doi.org/10.5880/GFZ.1.1.2016.002rinex2snr - making SNR files from RINEX filesI run a lowercase shop. Please name RINEX files accordingly and use lowercase station names. It also means
that the filename must be N characters long (ssssddd0.yyo), where ssss is station name, ddd is day of year, and yy is
two character year. If you have installed the CRX2RNX code, you can also provide a compressed RINEX format file,
which means your file must be called ssssddd0.yyd.  I think my code allows gz or Z as compression types.A RINEX file has extraneous information in it (the data used for positioning) - and does not provide some of the
information needed (elevation and azimuth angles) for reflectometry. The first task you
have is to translate a data file from RINEX into what I will call a SNR format - and to calculate those geometric angles.For the latter you will need an orbit file. If you tell it which kind of orbit file you want, the code will go get it for you.Secondly, you will need to decide how much of the data file you want to save. If you are new
to the systems, I would chooseoption 99, which is all data between elevation angles of 5 and 30 degrees.The command line driver isrinex2snr. You need to tell the program the name of the station,
the year and doy of year, your orbit file preference, and your SNR format type.
A sample call for a station called p041, restricted to GPS satellites, on day of year 132 and year 2020 would be:rinex2snr p041 2020 132 99 navIf the RINEX file for p041 is in your local directory, it will translate it.  If not,
it will check four archives (unavco, sopac, cddis, and sonel) to find it.
I will also search ga (geoscience Australia), nz (New Zealand), ngs, and bkg if you invoke -archive,
e.g.rinex2snr tgho 2020 132 99 nav -archive nzWhat if you want to run the code for all the data for a given year?rinex2snr tgho 2019 1 99 nav -archive nz -doy_end 365If your station name has 9 characters, the code assumes you are looking for a
RINEX 3 file. However, it will store the SNR data using the normal
4 character name. This requires you install the gfzrnx executable that translates RINEX 3 to 2.The snr options are always two digit numbers.  Choices are:99 is elevation angles of 5-30 degrees  (most applications)88 is elevation angles of 5-90 degrees66 is elevation angles less than 30 degrees50 is elevation angles less than 10 degrees (good for tall, high-rate applications)orbit file options:nav : GPS broadcast, perfectly adequate for reflectometryigs : IGS precise, GPS onlyigr : IGS rapid, GPS onlyjax : JAXA, GPS + Glonass, within a few daysgbm : GFZ Potsdam, multi-GNSS, not rapidgrg: French group, GPS, Galileo and Glonass, not rapidwum : Wuhan, multi-GNSS, not rapidWhat if you do not want to install the fortran translators?  Use -fortran True on the command line.quickLookBefore using thegnssircode, I recommend you tryquickLook. This allows you
to quickly test various options (elevation angles, frequencies, azimuths).
The required inputs are station name, year, doy of year, and SNR Format (start with 99).If the SNR file has not been previously stored, you can provide a properly named RINEX file
(lowercase only) in your working directory. If it doesn't find a file in either of these places, it
will try to pick up the RINEX data from various archives (unavco, sopac, sonel, and cddis) and translate it for
you into the correct SNR format. There are stored defaults for analyzing the
spectral characteristics of the SNR data.  If you want to override those, usequickLook -hquickLook p041 2020 150 99(this uses defaults)quickLook gls1 2011 271 99(this uses defaults)quickLook smm3 2018 271 99 -h1 8 -h2 20(smm3 is about 15 meters tall, so I am modifying from the defaults)Many archives make it difficult for you to access modern GNSS signals. This is really unfortunate,
as the L2C and L5 GPS signals are great, as are the signals from Galileo, Glonass, and Beidou.Many archives also make it difficult for you to use high-rate data. Especially for sea level studies, I recommend
going higher than typical geodetic sampling rates.gnssirThis is the main driver for the reflectometry code.  You need a set of instructions which can be made usingmake_json_input.  At a minimummake_json_inputneeds the station name (4 char), the latitude (degrees), longitude (degrees) and ellipsoidal height (meters). It 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 metrics.Things that are helpful to know for the json and commandline inputs:Names for the GNSS frequencies1,2,5 are GPS L1, L2, L520 is GPS L2C101,102 Glonass L1 and L2201, 205, 206, 207, 208: Galileo frequencies302, 306, 307 : Beidou frequenciesReflection parameters:e1 and e2 are the min and max elevation angle, in degreesminH and maxH are the min and max allowed reflector height, in metersdesiredP, desired reflector height precision, in metersPkNoise is the periodogram peak divided by the periodogram noise ratio.reqAmp is the required periodogram amplitude value, in volts/voltspolyV is the polynomial order used for removing the direct signalfreqs are selected frequencies for analysisdelTmax is the maximum length of allowed satellite arc, in minutesazval are the azimuth regions for study, in pairs (i.e. 0 90 270 360 means you want to evaluate 0 to 90 and 270 to 360).Other json inputs:wantCompression, boolean, compress SNR filesscreenstats, boolean, whether minimal periodogram results come to screenrefraction, boolean, whether simple refraction model is applied.plt_screen: boolean, whether SNR data and periodogram are plotted to the screenseekRinex: boolean, whether code looks for RINEX at an archiveSimple example for my favorite GPS sitep041make_json_input p041 39.949 -105.194 1728.856(use defaults and write out a json instruction file)rinex2snr p041 2020 150 99 nav(pick up and translate RINEX file from unavco)gnssir p041 2020 150 99(calculate the reflector heights)gnssir p041 2020 150 99 -fr 5 -plt True(override defaults, only look at L5, SNR data and periodogram plots come to the screen)Where are the files for this example?json is stored in REFL_CODE/input/p041.jsonSNR files are stored in REFL_CODE/2020/snr/p041Reflector Height (RH) results are stored in REFL_CODE/2020/results/p041I do not save RINEX files.If you want multi-GNSS, you need to use multi-GNSS orbits and edit the json file. And the RINEX you select
must have multi-GNSS SNR observations in it. p041 currently has multi-GNSS data in the RINEX file:rinex2snr p041 2020 151 99 gbm(use GFZ orbits so you can use GPS, Glonass, and Galileo)gnssir p041 2020 151 99 -fr 201 -plt True(look at the lovely Galileo L1 data)PublicationsThere are A LOT of publications about GPS and GNSS interferometric reflectometry.
If you want something with a how-to flavor, try this paper,
which isopen optionAlso look to the publications page on mypersonal websiteHow can I import the libraries in this package?