gnssrefl.vwc_cl module

gnssrefl.vwc_cl.get_vwc_tracks_freqs(station, extension='')

Return sorted list of unique freq codes in vwc_tracks.json, or None if missing.

gnssrefl.vwc_cl.iter_vwc_epochs(vwc_tracks)

Yield (track_id, track_epoch, epoch, track) for every active epoch in a vwc_tracks.json document.

gnssrefl.vwc_cl.load_vwc_tracks(vwc_tracks_path)

Read a vwc_tracks.json document from disk.

gnssrefl.vwc_cl.main()
gnssrefl.vwc_cl.parse_arguments()
gnssrefl.vwc_cl.process_vwc_from_tracks(station, year, year_end, fr, extension, tracks, vwc_tracks, plt, screenstats, min_req_pts_track, polyorder, minvalperday, bin_hours, minvalperbin, bin_offset, snow_filter, tmin, tmax, warning_value, auto_removal, hires_figs, advanced, veg_model, save_tracks, level_doys, skip_leveling, colors, bx, by, fs, snow_file)

Run the shared VWC pipeline on a prepared tracks array.

Both the default multi-GNSS flow (vwc) and the GPS-only legacy flow (vwc_legacy) build a tracks array their own way and delegate the identical downstream work (set_parameters, snow filter, per-track phase fit, vegetation correction, leveling, output writing) to this function.

Parameters:

  • tracks (np.ndarray) – Track array with shape (N, 7). Cols 0-4 carry, in both paths: idx, mean RH (m), sat, track avg azimuth (deg), nvalstrack. Cols 5-6 carry (az_min, az_max) for the legacy path and (track_id, track_epoch) for the default path; the choice is selected by vwc_tracks.

  • vwc_tracks (dict or None) – Loaded vwc_tracks.json document for the default path (triggers tag-based arc matching via (track_id, track_epoch)), or None for the legacy path (triggers sat + azimuth-proximity matching).

gnssrefl.vwc_cl.vwc(station: str, year: int, year_end: int | None = None, fr: int | None = None, plt: bool = True, screenstats: bool = False, min_req_pts_track: int | None = None, polyorder: int = -99, minvalperday: int | None = None, bin_hours: int | None = None, minvalperbin: int | None = None, bin_offset: int | None = None, snow_filter: bool = False, tmin: float | None = None, tmax: float | None = None, warning_value: float | None = None, auto_removal: bool = False, hires_figs: bool = False, advanced: bool = False, vegetation_model: int | None = None, save_tracks: bool = False, extension: str | None = None, level_doys: list = [], skip_leveling: bool = False, legacy: bool = False)

Compute volumetric water content (VWC) from GNSS-IR phase estimates across all constellations/frequencies selected during vwc_input.

Reads vwc_tracks.json to get each arc’s apriori RH and track-mean azimuth, then concatenates the daily phase files, plots phase by azimuth quadrant, bins by time, applies vegetation correction, and converts to VWC. Pass -legacy T to use the old GPS-only flow that matches arcs against apriori_rh_{fr}.txt by satellite + azimuth.

The code supports two vegetation correction models: Model 1 (simple, default) uses amplitude-based correction suitable for sites with bare soil or sparse vegetation. Model 2 (advanced) uses the Chew et al. (2016) GPS Solutions (DOI: 10.1007/s10291-015-0462-4) algorithm, and should be used for sites with dense or tall vegetation.

Code now allows inputs (minvalperday, tmin, and tmax) to be stored in the gnssir analysis json file. To avoid confusion, in the json they are called vwc_minvalperday, vwc_min_soil_texture, and vwc_max_soil_texture. These values can also be overwritten on the command line …

Code now allows doy values for level nodes to be set in the json (variable name vwc_level_doys) and it is a list, i.e. [170,230] would be the input for summer months in NOAM. This can be overriden by the command line -level_inputs 170 230. If no information is provided by the user, it has defaults based on the station being in the northern or southern hemisphere. However, this is a hack, and I have no idea if it works well for Australia, e.g. It worked well for PBO H2O in the semi-arid western U.S. Those values are defined in set_parameters in phase_functions.py if you want to take a look If you want a time period that crosses the year boundary (i.e. you want all of december and january), you can input level_doys of 335 and 31, and the code will process accordingly.

Examples

vwc p038 2017

one year for station p038

vwc p038 2015 -year_end 2017

three years of analysis for station p038

vwc p038 2015 -year_end 2017 -warning_value 6

warns you about tracks with phase RMS greater than 6 degrees rms

vwc p038 2015 -year_end 2017 -warning_value 6 -auto_removal T

makes new list of tracks based on your new warning value

Parameters:

  • station (str) – 4 character ID of the station

  • year (int) – full Year

  • year_end (int, optional) – last year for analysis

  • fr (int, optional) – Single GNSS frequency to process. main() handles the CLI -fr list (one/multiple/omitted) and calls this function once per freq; callers using vwc() directly must pass a single value. Only GPS is officially supported; other constellations are available for research/testing only.

  • plt (bool, optional) – Whether to produce plots to the screen. Default is True

  • min_req_pts_track (int, optional) – how many points needed to keep a satellite track. Default is 30. Can be set in the gnssir_input json (vwc_min_req_pts_track).

  • polyorder (int) – polynomial order used for leveling. Usually the code picks it but this allows to users to override. Default is -99 which means let the code decide

  • minvalperday (integer) – how many phase measurements are needed for each daily measurement default is 10

  • snow_filter (bool) – whether you want to attempt to remove points contaminated by snow default is False

  • tmin (float) – minimum soil texture value, default 0.05. This can now be set in the gnssir_input json (with vwc_ added)

  • tmax (float) – maximum soil texture value, default 0.5. This can now be set in the gnssir_input json (with vwc_ added)

  • warning_value (float) – screen warning about bad tracks (phase rms, in degrees). default is 5.5

  • auto_removal (bool, optional) – whether to automatically remove tracks that hit your bad track threshold default value is false

  • hires_figs (bool, optional) – whether to make eps instead of png files default value is false

  • advanced (bool, optional) – shorthand for vegetation_model=2

  • vegetation_model (int, optional) – vegetation correction model: 1=simple (default), 2=advanced (Chew et al. 2016) can be set in gnssir analysis JSON as vwc_vegetation_model

  • save_tracks (bool, optional) – save individual track VWC data to files (advanced model only)

  • extension (str) – extension used when you made the json analysis file

  • level_doys (list) – pair of day of years that are used to define time period for “leveling” default is north american summer

  • skip_leveling (bool, optional) – internal use only - skip leveling and return percentage units for unified leveling in vwc_hourly. Default is False.

  • legacy (bool, optional) – Use the legacy GPS-only apriori_RH flow. Default is False. Deprecated; may be removed after 2027-01-01.

Returns:

  • Daily phase results in a file at – $REFL_CODE/Files/<station>/[<extension>/]<station>_phase_<C>_<label>_<bin_hours>hr+<bin_offset>.txt with columns: Year DOY Ph Phsig NormA MM DD (<C> is the constellation char G/R/E/C and <label> the signal label L1/L2C/L5/…)

  • VWC results in a file at – $REFL_CODE/Files/<station>/[<extension>/]<station>_vwc_<C>_<label>_<bin_hours>hr+<bin_offset>.txt with columns: FracYr Year DOY VWC Month Day

gnssrefl.vwc_cl.vwc_legacy(station, year, year_end, fr, plt, screenstats, min_req_pts_track, polyorder, minvalperday, bin_hours, minvalperbin, bin_offset, snow_filter, tmin, tmax, warning_value, auto_removal, hires_figs, advanced, veg_model, save_tracks, extension, level_doys, skip_leveling, colors, bx, by, fs, snow_file)

Legacy GPS-only VWC flow.

Reads apriori_rh_{fr}.txt (the legacy per-freq track list), then delegates the downstream pipeline to process_vwc_from_tracks, which matches each phase-file row to a track by (satellite, azimuth within 3 deg) when no vwc_tracks.json doc is supplied.