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.combine_offset_files_to_vwc_data(station, fr, bin_hours, extension='')

Combine all offset VWC files into a unified vwc_data dictionary. Used for vegetation model 1 processing.

Reads all VWC offset files (e.g., p038_vwc_L2_6hr+0.txt, p038_vwc_L2_6hr+1.txt, etc.), sorts all measurements chronologically, and returns a vwc_data dict.

Returns:

vwc_data – Dictionary with ‘mjd’, ‘vwc’, ‘datetime’, ‘bin_starts’ Returns None if no data found

Return type:

dict or None

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, year_end: int = None, fr: str = None, plt: bool = True, bin_hours: int = 6, minvalperbin: int = 5, min_req_pts_track: int = None, polyorder: int = -99, snow_filter: bool = False, tmin: float = None, tmax: float = None, warning_value: float = None, auto_removal: bool = False, hires_figs: bool = False, advanced: bool = False, vegetation_model: int = 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 (str, optional) – GNSS frequency. Default is from JSON or 20 (L2C)

  • 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)

Returns:

Creates hourly rolling VWC file

Return type:

station_vwc_L2_rolling6hr.txt