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_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 = '', simple_level: bool = False, 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):

Runs vwc() for each offset (0, 1, 2, …, bin_hours-1) to create separate VWC files, then combines them chronologically.

NOTE: Each offset calculates its own vegetation correction baseline, which can introduce systematic biases between offsets. See issue #358: https://github.com/kristinemlarson/gnssrefl/issues/358

Vegetation Model 2 (advanced):

Runs vwc() once with -save_tracks to generate track files, then aggregates those saved tracks into different time bins. This avoids reprocessing the vegetation corrections for each offset and eliminates the bias issue present in Model 1.

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, recommended)

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

  • simple_level (bool, optional) – use simple leveling instead of polynomial (default: False)

  • 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