pywatershed.analysis.HRUComparisonPanel#

class pywatershed.analysis.HRUComparisonPanel(shapefile_path, variable_names, run_directories, input_directories=None, hru_id_column='nhru_v1_1', map_width=1200, map_height=650, timeseries_width=1500, timeseries_height=250, colormap='viridis', simplify_tolerance=300, time_aggregations=None, run_colors=None, title_max_length=80, verbose=True)[source]#

Interactive comparison tool for HRU-based model outputs.

This class provides an interactive Panel-based interface for comparing multiple model runs across different variables, with spatial visualization and timeseries plotting capabilities.

Parameters:

shapefile_path (str or Path) – Path to shapefile containing HRU polygons
variable_names (list of str) – List of variable names to compare (should match netcdf filenames without .nc)
run_directories (dict) – Dictionary mapping run names to directory paths containing netcdf files. Example: {“Run1”: “/path/to/run1/output”, “Run2”: “/path/to/run2/output”}
input_directories (dict, optional) – Dictionary mapping run names to input directory paths. If a variable is not found in run_directories, will check input_directories. Example: {“Run1”: “/path/to/run1/input”, “Run2”: “/path/to/run2/input”}
hru_id_column (str, optional) – Column name in shapefile containing HRU IDs. If None, will auto-detect.
map_width (int, optional) – Width of map plot in pixels (default: 1200)
map_height (int, optional) – Height of map plot in pixels (default: 650)
timeseries_width (int, optional) – Width of timeseries plots in pixels (default: 1400)
timeseries_height (int, optional) – Height of each timeseries plot in pixels (default: 250)
colormap (str, optional) – Default colormap to use for spatial plots (default: “viridis”). Can be changed interactively in the app.
simplify_tolerance (int, optional) – Tolerance in meters for geometry simplification (default: 300). Increase this (e.g., 500 or 1000) for faster rendering with large domains.
time_aggregations (dict, optional) – Dictionary mapping aggregation names to functions that take an xarray DataArray and return aggregated values. If None, uses built-in defaults: Mean, Sum, Max, Min, Std, Range, Trend.
run_colors (dict, optional) – Dictionary mapping run names to colors for timeseries plots. If None, uses built-in colorblind-friendly palette. Example: {“Run1”: “#0173B2”, “Run2”: “#DE8F05”}
title_max_length (int) – Maximum length of timeseries plot titles before wrapping to a new line (default: 80). Titles longer than this will be split intelligently, preferring to break between the variable name and description.

verbosebool, optional: Whether to print diagnostic information during initialization (default: True). Set to False to suppress output messages.

Examples

>>> comparer = HRUComparisonPanel(
...     shapefile_path="model_nhru.shp",
...     variable_names=["prcp", "tmean", "hru_ppt"],
...     run_directories={
...         "Republican": "/path/to/republican/output",
...         "NHM": "/path/to/nhm/output",
...     },
... )
>>> app = comparer.create_app()
>>> app.show()  # Display in notebook
>>> # or app.servable() for deployment

__init__(shapefile_path, variable_names, run_directories, input_directories=None, hru_id_column='nhru_v1_1', map_width=1200, map_height=650, timeseries_width=1500, timeseries_height=250, colormap='viridis', simplify_tolerance=300, time_aggregations=None, run_colors=None, title_max_length=80, verbose=True)[source]#: Initialize the HRU Comparison Panel.

Methods

`__init__`(shapefile_path, variable_names, ...)	Initialize the HRU Comparison Panel.
`compute_difference`(var_name, left_run, right_run)	Compute difference between two runs (left - right).
`compute_time_aggregation`(var_name, run_name, ...)	Compute time aggregation for a variable and run.
`create_app`()	Create and return the interactive Panel application.
`create_map_plot`(var_name, left_run, right_run)	Create map plot showing either single run mean or difference.
`create_timeseries_plot`(var_name, hru_id)	Create timeseries plot for all runs at a selected HRU.
`get_variable_metadata`(var_name)	Get metadata for a variable.
`hru_plot_together`(run_variables[, hru_id, ...])	Plot multiple variables from different runs together at a single HRU.
`load_variable_data`(var_name, run_name)	Load data for a specific variable and run.
`servable`()	Create and return servable app for deployment.
`show`()	Create and display the app in a notebook.

compute_difference(var_name, left_run, right_run)[source]#

Compute difference between two runs (left - right).

Parameters:

var_name (str) – Variable name
left_run (str) – Left run name
right_run (str) – Right run name

Return type:

Optional[ndarray]

Returns:

np.ndarray or None – Difference values for each HRU, or None if either run doesn’t have data

compute_time_aggregation(var_name, run_name, aggregation)[source]#

Compute time aggregation for a variable and run.

Parameters:

var_name (str) – Variable name
run_name (str) – Run name
aggregation (str) – Aggregation method name

Return type:

Optional[ndarray]

Returns:

np.ndarray or None – Aggregated values for each HRU, or None if data not available

create_app()[source]#

Create and return the interactive Panel application.

Returns:: pn.Column – Panel application layout

create_map_plot(var_name, left_run, right_run, cmap_name='viridis', diff_tolerance=0.0, aggregation='Mean')[source]#

Create map plot showing either single run mean or difference.

Parameters:

var_name (str) – Variable name to plot
left_run (str) – Left run name
right_run (str or None) – Right run name (if None, plots only left run)

Returns:

gv.Overlay – GeoViews overlay with tiles and polygons

create_timeseries_plot(var_name, hru_id)[source]#

Create timeseries plot for all runs at a selected HRU.

Parameters:

var_name (str) – Variable name
hru_id (int) – HRU ID to plot

Returns:

holoviews plot – Timeseries plot

get_variable_metadata(var_name)[source]#

Get metadata for a variable.

Parameters:: var_name (str) – Variable name
Return type:: dict
Returns:: dict – Dictionary with ‘desc’ and ‘units’ keys, or empty strings if not found

hru_plot_together(run_variables, hru_id=None, width=None, height=None, title=None, renamer=None, colors=None)[source]#

Plot multiple variables from different runs together at a single HRU.

Variables with the same units are plotted on the same subplot, while variables with different units get separate subplots.

Parameters:

run_variables (dict) – Dictionary mapping run names to lists of variable names. Example: {“Run1”: [“prcp”, “hru_ppt”], “Run2”: [“prcp”]}
hru_id (int, optional) – HRU ID to plot. If None, uses current selected HRU from widget.
width (int, optional) – Width of plot in pixels. If None, uses self.timeseries_width.
height (int, optional) – Height of each subplot in pixels. If None, uses self.timeseries_height.
title (str, optional) – Custom title to add after HRU ID. Replaces unit label in title. Example: “HRU 84966: Precipitation Analysis”
renamer (dict, optional) – Dictionary to rename series labels in the legend. Keys are “{run}: {variable}”, values are display names. Example: {“Run1: prcp”: “Precipitation (Run1)”}
colors (dict, optional) – Dictionary mapping series labels (after renaming) to colors. If None, uses run colors from self.run_colors. Example: {“Precipitation (Run1)”: “#0173B2”}

Returns:

hvplot object – Plot or layout of plots

Examples

>>> plot = comparer.hru_plot_together(
...     {"Run1": ["prcp", "hru_ppt"], "Run2": ["prcp", "hru_rain"]},
...     hru_id=85806,
...     width=1600,
...     height=300,
...     renamer={
...         "Run1: prcp": "Precip",
...         "Run1: hru_ppt": "HRU Precip",
...     },
...     colors={"Precip": "#0173B2", "HRU Precip": "#DE8F05"},
... )

load_variable_data(var_name, run_name)[source]#

Load data for a specific variable and run.

Parameters:

var_name (str) – Variable name
run_name (str) – Run name

Return type:

Optional[DataArray]

Returns:

xr.DataArray or None – Loaded data array, or None if file doesn’t exist

servable()[source]#: Create and return servable app for deployment.

show()[source]#

Create and display the app in a notebook.

In CI environments (detected via GITHUB_ACTIONS, CI, or CONTINUOUS_INTEGRATION environment variables), this method will create the app but skip displaying it, which would hang indefinitely in non-interactive environments.

pywatershed.analysis.HRUComparisonPanel

Contents

pywatershed.analysis.HRUComparisonPanel#