gnssrefl.vwc_input module

gnssrefl.vwc_input.build_vwc_tracks(tracks, arcs_df, min_req_pts_track, fr_list, apriori_rh_ndays)

Build a vwc_tracks dict from a (comprehensive) tracks dict.

Works on a copy of tracks: drops tracks whose freq is not in fr_list via delete_track; deactivates (track_id, epoch_id) buckets with fewer than min_req_pts_track QC-passing arcs in arcs_df via deactivate_epoch; drops tracks left with no active epochs. Sets metadata[‘file_type’] = ‘vwc_tracks’ and metadata[‘apriori_rh_ndays’]. Per-epoch derived fields (apriori_RH, RH_std, n_arcs, n_qc_arcs) are populated by save_tracks.

The input tracks dict is not mutated.

gnssrefl.vwc_input.define_track_clusters(azimuths, gap_threshold=10)

Define satellite track clusters from observed azimuths.

Groups azimuths into distinct tracks by sorting them on the circle, finding the largest gap (natural break), then splitting at any gap exceeding the threshold. Handles 0/360 wrap.

Parameters:

  • azimuths (array-like) – Observed azimuth values in degrees for a single satellite

  • gap_threshold (float) – Minimum azimuth gap in degrees to split into separate tracks. Default 10.

Returns:

Each array contains the azimuths belonging to one track.

Return type:

list of numpy arrays

gnssrefl.vwc_input.main()
gnssrefl.vwc_input.parse_arguments()
gnssrefl.vwc_input.vwc_input(station: str, year: int, fr=None, min_req_pts_track: int | None = None, minvalperday: int | None = None, bin_hours: int | None = None, minvalperbin: int | None = None, bin_offset: int | None = None, extension: str = '', tmin: float | None = None, tmax: float | None = None, warning_value: float | None = None, year_end: int | None = None, apriori_rh_ndays: int | None = None, legacy: bool = False, vwc_tracks_builder=None)

Sets inputs for the estimation of VWC (volumetric water content).

Auto-builds tracks.json for the station if it doesn’t already exist, walks every day in [year, year_end] calling extract_arcs with that tracks.json so each arc is tagged with its (track_id, track_epoch) and gnssir QC result, aggregates per (track_id, track_epoch), and writes the VWC-eligible subset as vwc_tracks.json. That file has the same schema as tracks.json with two added per-epoch fields: apriori_RH (the mean RH across QC-passing arcs in the last apriori_rh_ndays days of the range, default 365) and RH_std (the standard deviation over the same sample, or null when fewer than 3 samples are available).

Downstream phase and vwc commands consume vwc_tracks.json directly to get each arc’s apriori RH and track-mean azimuth.

Pass -legacy T to fall back to the old GPS-only flow that produces apriori_rh_{fr}.txt from per-day gnssir result files. -year_end is not supported with -legacy T.

Parameters:

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

  • year (int) – full year

  • fr (int or list of int, optional) – Default path: frequency filter. Only tracks whose freq is in this list are written to vwc_tracks.json. When None (default), all frequencies present in tracks.json are kept. Legacy path: single frequency (1 L1, 20 L2C, 5 L5). Only L2C is officially supported; passing a list of length > 1 with legacy=True is an error.

  • min_req_pts_track (int, optional) – Minimum number of arcs per (track_id, track_epoch) bucket required to keep that epoch. When None, the station JSON value of vwc_min_req_pts_track is used if present, otherwise 30. The resolved value is persisted back to the station JSON.

  • minvalperday (int, optional) – how many unique tracks are needed to compute a valid VWC measurement for a given day

  • extension (str, optional) – strategy extension value (same as used in gnssir, subdaily etc)

  • tmin (float, optional) – minimum soil moisture value

  • tmax (float, optional) – maximum soil moisture value

  • warning_value (float, optional) – for removing low quality satellite tracks when running vwc phase units, degrees

  • year_end (int, optional) – End year (inclusive). Defaults to year. Not supported with legacy=True.

  • apriori_rh_ndays (int, optional) – Window size, in days, counted backwards from the end of the date range, over which apriori_RH and RH_std are averaged. Default 365.

  • legacy (bool, optional) – When True, use the legacy GPS-only apriori_RH flow (writes apriori_rh_{fr}.txt from gnssir result files). Default: False.

Returns:

  • Default path – Files/{station}/{extension}/vwc_tracks.json

  • Legacy path – $REFL_CODE/input/<station>/[<extension>/]<station>_phaseRH_<C>_<label>.txt (the per-freq apriori_rh_{fr}.txt consumed by legacy phase/vwc; <C> is the constellation char and <label> the signal label, e.g. _G_L2C)

  • Both paths also persist the VWC-specific parameters (vwc_minvalperday,

  • vwc_min_soil_texture, vwc_max_soil_texture, vwc_min_req_pts_track,

  • vwc_warning_value) into the gnssir analysis JSON.

gnssrefl.vwc_input.vwc_input_legacy(station, year, fr, min_req_pts_track, minvalperday, bin_hours, minvalperbin, bin_offset, extension, tmin, tmax, warning_value)

Legacy GPS-only VWC input pipeline.

Loads the per-day gnssir result files for year, clusters arcs into tracks by satellite + azimuth, and writes the selected tracks to apriori_rh_{fr}.txt (the file name depends on the single requested frequency). Downstream phase -legacy T / vwc -legacy T consume that file to get each arc’s apriori RH.