gnssrefl.vwc_hourly module

VWC Hourly Rolling Module

This module generates VWC estimates from n-hour windows that start at every hour throughout the day, creating a rolling/sliding time window dataset.

For example, with 6-hour windows (bin_hours=6), this creates VWC estimates from:

Window 00:00-06:00
Window 01:00-07:00
Window 02:00-08:00
… continuing through each hour of the day

gnssrefl.vwc_hourly.combine_and_level_vwc_data(all_vwc_data, tmin, level_doys, polyorder, station, extension, fr, bin_hours)

Combine unleveled VWC data from multiple offsets and apply unified leveling.

This solves the bias problem in Model 1 by ensuring all offsets share the same leveling baseline calculation. See GitHub issue #358.

Parameters:

all_vwc_data (list of dict) – List of vwc_data dicts from each offset (PERCENTAGE units, 0-60)
tmin (float) – Minimum soil texture value (e.g., 0.05)
level_doys (list) – [start_doy, end_doy] for dry season baseline window
polyorder (int) – Polynomial order for leveling (-99 = auto)
station (str) – Station name
extension (str) – File extension
fr (int) – Frequency code
bin_hours (int) – Time bin size in hours

Returns:

vwc_data – Combined and leveled data with keys: ‘mjd’, ‘vwc’ (DECIMAL units), ‘datetime’, ‘bin_starts’

Return type:

dict

gnssrefl.vwc_hourly.generate_rolling_vwc_from_tracks(station, fr, bin_hours, minvalperbin, extension='', year=None, year_end=None)

Generate complete hourly rolling VWC dataset from saved track files.

Loads all track data once and creates bins at every hour (0:00, 1:00, 2:00, etc.) for the entire dataset.

Parameters:

station (str) – 4-character station name
fr (int) – Frequency code (20 for L2C, etc.)
bin_hours (int) – Time bin size in hours (e.g., 6 for 6-hour windows)
minvalperbin (int) – Minimum tracks required per time bin
extension (str) – Extension for file paths (default: ‘’)
year (int, optional) – Start year for filtering track files
year_end (int, optional) – End year for filtering track files

Returns:

vwc_data – Dictionary with ‘mjd’, ‘vwc’, ‘datetime’, ‘bin_starts’ (NOT leveled yet) Returns None if no track data found

Return type:

dict or None

gnssrefl.vwc_hourly.main(): Alternative entry point (for compatibility)

gnssrefl.vwc_hourly.main_hourly(): CLI entry point for vwc_hourly command

gnssrefl.vwc_hourly.parse_arguments_hourly(): Parse command line arguments for vwc_hourly command

gnssrefl.vwc_hourly.plot_hourly_vs_daily_vwc(station, fr, bin_hours, extension='')

Plot hourly rolling VWC (gray dots) vs daily VWC (bold red) for comparison.

Requires both daily and hourly VWC files to exist.

gnssrefl.vwc_hourly.vwc_hourly(station: str, year: int, fr: int, year_end: int | None = None, plt: bool = True, bin_hours: int = 6, minvalperbin: int = 5, min_req_pts_track: int | None = None, polyorder: int = -99, 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, extension: str = '', level_doys: list = [])

Generate VWC estimates from n-hour windows that start at every hour throughout the day, creating a rolling/sliding time window dataset.

For example, with bin_hours=6, this creates VWC estimates from: - Window 00:00-06:00 - Window 01:00-07:00 - Window 02:00-08:00 - … continuing through the day

Warning

This function is EXPERIMENTAL. Only daily (24-hour) VWC measurements are officially supported. Subdaily/hourly results should be used with caution and are provided for research purposes only.

Vegetation Model 1 (simple):: Uses two-pass processing: first collects unleveled VWC from all offsets, then applies unified leveling to the combined dataset. This ensures all offsets share the same leveling baseline.
Vegetation Model 2 (advanced):: Runs vwc() once with -save_tracks to generate track files, then aggregates those saved tracks into different time bins with unified leveling.

Examples

vwc_hourly p038 2022: 6-hour rolling bins for station p038 (default, model 1)
vwc_hourly p038 2022 -bin_hours 12 -minvalperbin 5: 12-hour rolling bins with minimum 5 tracks per bin
vwc_hourly okl2 2012 -vegetation_model 2: 6-hour rolling bins using advanced vegetation model (model 2)

Parameters:

station (str) – 4 character ID of the station
year (int) – full Year
year_end (int, optional) – last year for analysis
fr (int) – GNSS frequency code (e.g. 20 for GPS L2C, 101 for GLONASS L1). Must be a single freq present in vwc_tracks.json. The CLI auto-loops over multiple freqs by calling this function once per freq.
bin_hours (int, optional) – time bin size in hours (1,2,3,4,6,8,12). Default is 6
minvalperbin (int, optional) – min number of satellite tracks needed per time bin. Default is 5
level_doys (list, optional) – pair of day of years for baseline leveling period
function) ((other parameters same as vwc) –

Return type:

Creates hourly rolling VWC file under $REFL_CODE/Files/<station>/vwc_outputs/<freq_label>/<station>_vwc_rolling<bin_hours>hr.txt