AdjustQ Module

These class functions replicate the CHPS FEWS AdjustQ tool.

Used as a preprocessing step to create upstream streamflow timeseries for routing reaches where LAG-K is being optimized

AdjustQ adjusts observed mean daily discharges using observed instantaneous and simulated discharges. If both observed mean daily and instantaneous data are missing, simulated discharge is used (if available). The process combines two CHPS FEWS transformations:

  1. AdjustQUsingInstantaneousDischarge: Corrects simulated discharges based on instantaneous observations.

  2. AdjustQUsingMeanDailyDischarge: Applies additional corrections if mean daily discharges exceed the error tolerance.

Any resulting negative discharge values are set to zero.

class nwsrfs_py.adjustq.AdjustQ(daily_flow_path, inst_flow_path, ac_run_path=None, blend=10, interp_type='ratio', error_tol=0.01, max_iterations=15)[source]

Bases: _AdjustQPrep

Class to perform an equivalent CHPS FEWS AdjustQ calculation, inheriting from _AdjustQPrep.

Intended to be used within the NWRFC autocalibration folder/data structure. Uses two different procedures to determine if observed instantaneous or simulated data is used to shape daily average observed streamflow:

  • One to correct for small gaps in observed instantaneous data.

  • Another method for correcting large gaps in observed instantaneous data.

The blend input variable defines which procedure to use. If both observed mean daily and instantaneous data is missing, simulated discharge is used (if available).

Parameters:

  • daily_flow_path (str) – Path to daily average observed streamflow csv provided in a NWRFC autocalb directory.

  • inst_flow_path (str) – Path to instantaneous observed streamflow csv provided in a NWRFC autocalb directory.

  • ac_run_path (str | None) – Optional path to NWRFC autocalibration results directory.

  • blend (int) – Threshold for determining how many time steps of missing observed instantaneous data constitutes a “large gap”. Default: 10.

  • interp_type (str) –

    Correction procedure used to correct simulated discharges for missing gaps smaller than the blend threshold. Accepts 'ratio' or 'difference'. Default: 'ratio'.

    • ratio: Correction factor is based on the ratio between observed and simulated discharges.

    • difference: Correction value is based on the difference between observed and simulated discharges.

  • error_tol (float) – Percent tolerance that the instantaneous daily average must match the observed daily flow average. Default: 0.01.

  • max_iterations (int) – Maximum number of iterations to adjust the instantaneous daily average to match the observed daily flow. Default: 15

obs_daily

Daily observation streamflow timeseries. (units: cfs)

Type:

pd.Series

obs_inst

Instantaneous observation streamflow timeseries. (units: cfs)

Type:

pd.Series

sim

Simulation streamflow timeseries (if provided). (units: cfs)

Type:

pd.Series

property adjustq: Series

This function detects if a simulation timeseries is provided and uses the appropriate AdjustQ calculation

  1. AdjustQ.adjustq_calc() is used if NWRFC autocalibration simulation (sim) is provided.

  2. Otherwise AdjustQ.inst_mean_q_merge() is used.

Returns a pd.Series.

adjustq_calc()[source]

Primary AdjustQ calculation function when NWRFC autocalibration simulation (sim) is provided.

This method orchestrates the full adjustment process:

  1. Identifies gaps in observed data.

  2. Calls AdjustQ._adjustq_inst_smallgaps() for short missing periods.

  3. Calls AdjustQ._adjustq_inst_largegaps() for long missing periods.

  4. Calls AdjustQ._adjustq_daily() to match daily volumes.

  5. Clips any negative results to zero.

Returns:

A Series with a adjustq timeseries (units: cfs)

Return type:

pd.Series

inst_mean_q_merge()[source]

Merges instantaneous observed streamflow data with daily mean streamflow data when NWRFC autocalibration simulation (sim) is 'None'.

For locations like reservoir outflows.

Where available this method uses instantaneous data to shape daily mean flow using AdjustQ._adjustq_daily().

Returns:

A Series containing the merged and adjusted discharge timeseries (units: cfs).

Return type:

pd.Series

classmethod load_example(sim=True, **kwargs)[source]

Generates a AdjustQ for the package provided example data.

Example data are NWRFC auto calibration results for location:

  • NRKW1: Nooksack River at North Cedarville, WA (USGS-12210700). The simulated timeseries is utilizing the following models: SacSnow, GammaUh, Lagk.

Any optional arguments associated with AdjustQ, can be passed.

Parameters:

  • sim (bool) – Incorporate the model simulation results in the AdjustQ calculation. Default: True.

  • **kwargs –

    Optional keyword arguments passed to AdjustQ.

    Common options include:

    • blend (int): Threshold for determining how many time steps of missing observed instantaneous data constitutes a “large gap”. Default: 10.

    • interp_type (str): Correction procedure used to correct simulated discharges for missing gaps smaller than the blend threshold. Accepts 'ratio' or 'difference'. Default: 'ratio'.

    • error_tol (float): Percent tolerance that the instantaneous daily average must match the observed daily flow average. Default: 0.01.

    • max_iterations (int): Maximum number of iterations to adjust the instantaneous daily average to match the observed daily flow. Default: 15.