pywrdrb.post

pywrdrb.post#

Post-processing functions for evaluating simulation results, including error metrics relative to observations and Hashimoto reliability / vulnerability metrics.

pywrdrb.post.metrics#

Streamflow and IBT shortfall performance metrics.

Overview#

This module includes functions to calculate flow reliability, vulnerability, and shortfall event metrics (duration, severity, intensity, etc.) for major streamflow and inter-basin transfer (IBT) nodes. These calculations are performed across multiple ensemble realizations and can optionally incorporate time lags and flow contributions (e.g., Blue Marsh to Trenton).

Key Steps#

  1. Define reliability and vulnerability using Hashimoto et al. (1982) metrics.

  2. Support lagged flow contributions through routing logic.

  3. Track shortfall events with duration and recovery conditions.

  4. Generate ensemble-wide statistics per model and node.

Technical Notes#

  • Assumes input data are organized in nested dictionaries by model and realization.

  • Blue Marsh flow contributions to Trenton must be accounted for via lag logic.

  • Uses subset_timeseries() to restrict the time period of analysis.

  • Requires consistent naming conventions for nodes and flow variables.

Change Log#

Marilyn Smith, 2025-05-07, Initial module documentation and docstring standardization.

pywrdrb.post.metrics.calculate_reliability

Calculate reliability as the fraction of time flow exceeds the target.

pywrdrb.post.metrics.calculate_vulnerability

Calculate vulnerability as the maximum magnitude of flow deficit below the target.

pywrdrb.post.metrics.get_shortfall_metrics

Compute shortfall metrics including reliability, resiliency, and event statistics.

pywrdrb.post.metrics.get_ensemble_hashimoto_metrics

Calculate ensemble reliability and vulnerability metrics.

pywrdrb.post.calculate_error_metrics#

Calculate error metrics for simulated and observed streamflow data.

Overview#

This module provides functions for evaluating the performance of reservoir and major flow simulations in the Pywr-DRB model framework. It computes a suite of error metrics comparing modeled data to observed data at daily, monthly, yearly, and full timescales using metrics from HydroEval, flow duration curve statistics, autocorrelation diagnostics, and roughness indicators.

Key Steps#

  1. Subset modeled and observed time series to the desired time window.

  2. Resample data to monthly or yearly resolution if needed.

  3. Calculate performance metrics including NSE, KGE, autocorrelation, and FDC-based diagnostics.

  4. Return a summary table of error metrics for all nodes, models, scenarios, and timescales.

Technical Notes#

  • Metrics include daily, monthly, yearly, and full-period variants.

  • Uses HydroEval (hydro-informatics/hydroeval) for core metrics.

  • Metrics include log-transformed variants for low flow sensitivity.

  • Designed for evaluating Pywr-DRB reservoir and major river node outputs.

  • Timeseries input assumed to be pandas Series indexed by datetime.

Change Log#

Marilyn Smith, 2025-05-07, Added documentation and implemented full docstring formatting.

pywrdrb.post.calculate_error_metrics.calculate_error_metrics

Compute error metrics for modeled vs.

pywrdrb.post.ensemble_metrics#

Functions for processing ensemble output data.

Overview#

This module provides basic utility functions to compute statistics (mean, median, standard deviation) from ensemble datasets structured as nested dictionaries, where each realization contains one or more pandas DataFrames.

The expected structure is:
ensemble = {

‘realization_0’: pd.DataFrame, ‘realization_1’: pd.DataFrame, …

}

These functions are commonly used for analyzing uncertainty across ensemble simulations, such as those generated in stochastic reservoir modeling or policy evaluations.

Key Steps#

  1. Loop through all realizations in the ensemble dictionary.

  2. Convert values to float and handle NaNs where appropriate.

  3. Aggregate across ensemble members using mean, standard deviation, or median.

Technical Notes#

  • Input data must be time-aligned across realizations (identical index).

  • Missing values (NaNs) are filled with zeros before computing the ensemble mean.

  • Assumes all realizations are formatted as pandas DataFrames of equal structure.

  • Median is computed row-wise across ensemble members.

Links#

Change Log#

Marilyn Smith, 2025-05-07, Initial module documentation and cleanup.

pywrdrb.post.ensemble_metrics.ensemble_mean

Calculate the mean across ensemble realizations.

pywrdrb.post.ensemble_metrics.ensemble_std

Calculate the standard deviation across ensemble realizations.

pywrdrb.post.ensemble_metrics.ensemble_median

Calculate the median across ensemble realizations.