pywatershed.Output#

class pywatershed.Output(control, model, monthly_accum_var_list=None, noi_var_list=None, noi_ids=None, noi_stats=None, hoi_var_list=None, hoi_ids=None, hoi_stats=None, netcdf_output_action='error', chunked_var_list=None, chunked_output_file=None, chunk_sizes=None, chunk_size_auto_warn=True)[source]#

Output collection and statistical analysis for models.

Collects data during execution, computes statistics after finalization. Supports PRMS processes and FlowGraph.

Parameters:

control (Control) – Model control with timing information
model (Model) – Pywatershed model instance
monthly_accum_var_list (list[str], optional) – Variables to accumulate monthly (all spatial units)
noi_var_list (list[str], optional) – Variables to collect at nodes of interest. Required if noi_ids is a list. Must NOT be provided if dict (use dict keys).
noi_ids (list[int] or dict[str, list[int]] or list[tuple] or dict[str, list[tuple]], optional) –
Node IDs for NOIs. Supports two ID types and two modes.

ID types:
- Simple IDs: Integer nhm_seg values (e.g., [12345, 67890])
- FlowGraph tuples: (node_maker_name, node_maker_id) for FlowGraph nodes (e.g., [(“prms_channel”, 12345), (“starfit”, 0)])
Modes:
- List mode: Same IDs for all vars (requires noi_var_list)
- Dict mode: {var_name: [ids]} per-variable IDs (don’t provide noi_var_list)
noi_stats (dict[Callable, list[str]], optional) – Statistics for NOIs: {function: [var1, var2, …]}
hoi_var_list (list[str], optional) – Variables to collect for HRUs of interest. Required if hoi_ids is a list. Must NOT be provided if hoi_ids is dict (use dict keys).
hoi_ids (list[int] or dict[str, list[int]], optional) –
HRU IDs (nhm_id values). Two modes:
- List mode: Same IDs for all vars (requires hoi_var_list)
- Dict mode: {var_name: [ids]} per-variable IDs (don’t provide hoi_var_list)
hoi_stats (dict[Callable, list[str]], optional) – Statistics for HOIs: {function: [var1, var2, …]}
chunked_var_list (list[str], optional) – Variables to write in chunks to zarr format. These variables will be buffered in memory for chunk_sizes[‘time’] timesteps and written to zarr file when buffer is full.
chunked_output_file (str or pathlib.Path, optional) – Path to zarr output file. Required if chunked_var_list is provided.
chunk_sizes (dict[str, int], optional) – Chunk sizes for zarr output. Keys: ‘time’, ‘nhru’, ‘nsegment’, ‘nnode’. If not provided, sensible defaults will be used based on spatial dimensions. Defaults target ~10-100 MB chunks.
chunk_size_auto_warn (bool, optional) – If True (default), warn when chunk_sizes are auto-determined.

Variables:

time (np.ndarray) – Daily time coordinate
time_months (np.ndarray) – Monthly time coordinate
n_days_per_month (xr.DataArray) – Days per month (for converting accumulations to means)
monthly_accumulations (dict[str, xr.DataArray]) – Monthly values, available after finalization
noi_arrays (dict[str, xr.DataArray]) – NOI time series, available after finalization
hoi_arrays (dict[str, xr.DataArray]) – HOI time series, available after finalization
noi_stats (dict[str, dict[str, xr.DataArray]]) – NOI statistics: noi_stats[variable][statistic]
hoi_stats (dict[str, dict[str, xr.DataArray]]) – HOI statistics: hoi_stats[variable][statistic]

Examples

>>> from pywatershed.analysis.time_stats import mean
>>> def max_flow(da):
...     return da.max(dim="time")
...
>>>
>>> # List mode: same IDs for all variables
>>> output = pws.base.Output(
...     control=control,
...     model=model,
...     noi_var_list=["seg_outflow"],  # Required with list mode
...     noi_ids=[12345, 67890],
...     noi_stats={mean: ["seg_outflow"]},
...     hoi_var_list=["hru_actet"],  # Required with list mode
...     hoi_ids=[1, 2, 3],
...     hoi_stats={mean: ["hru_actet"]},
... )
>>>
>>> # Dict mode: per-variable IDs
>>> output = pws.base.Output(
...     control=control,
...     model=model,
...     noi_ids={  # Dict keys define variables
...         "seg_outflow": [12345, 67890],
...         "seg_upstream_inflow": [12345],
...     },
...     noi_stats={mean: ["seg_outflow"]},  # Not all vars need stats
...     hoi_ids={  # Dict keys define variables
...         "hru_actet": [1, 2],
...         "pkwater_equiv": [3, 4, 5],
...     },
...     hoi_stats={mean: ["hru_actet"]},
... )
>>>
>>> # FlowGraph mode: tuple IDs for nodes
>>> output = pws.base.Output(
...     control=control,
...     model=flowgraph_model,
...     noi_ids={
...         "node_outflows": [("prms_channel", 12345), ("starfit", 0)],
...         "node_storages": [("starfit", 0)],
...     },
...     noi_stats={mean: ["node_outflows"]},
... )
>>> model.run(finalize=True, output=output)
>>>
>>> # Access hierarchically
>>> output.noi_stats["seg_outflow"]["mean"]
>>> output.hoi_stats["hru_actet"]["mean"]

__init__(control, model, monthly_accum_var_list=None, noi_var_list=None, noi_ids=None, noi_stats=None, hoi_var_list=None, hoi_ids=None, hoi_stats=None, netcdf_output_action='error', chunked_var_list=None, chunked_output_file=None, chunk_sizes=None, chunk_size_auto_warn=True)[source]#: Initialize Output and set up data collection.

Methods

`__init__`(control, model[, ...])	Initialize Output and set up data collection.
`calculate`()	Collect data for current timestep (called by model.run()).
`finalize`()	Finalize and calculate statistics (called by model.run()).
`to_netcdf`(output_dir)	Write output to netCDF files (not yet implemented).

Attributes

`hoi_arrays`	HOI time series (available after finalization).
`hoi_stats`	hoi_stats[variable][statistic] (after finalization).
`monthly_accumulations`	Monthly accumulations (available after finalization).
`n_days_per_month`	Number of days in each month for stats.
`noi_arrays`	NOI time series (available after finalization).
`noi_stats`	noi_stats[variable][statistic] (after finalization).
`time`	Daily time coordinate for NOI/HOI data.
`time_months`	Monthly time coordinate for accumulations.

calculate()[source]#

Collect data for current timestep (called by model.run()).

Return type:: None

finalize()[source]#

Finalize and calculate statistics (called by model.run()).

Return type:: None

property hoi_arrays: dict[str, DataArray] | None#: HOI time series (available after finalization).

property hoi_stats: dict[str, dict[str, DataArray]] | None#

hoi_stats[variable][statistic] (after finalization).

Type:: HOI statistics

property monthly_accumulations: dict[str, DataArray] | None#: Monthly accumulations (available after finalization).

property n_days_per_month: DataArray | None#

Number of days in each month for stats.

Returns:: xr.DataArray or None – DataArray of day counts per month with month dimension, useful for converting accumulations to means. Only available after finalization.

property noi_arrays: dict[str, DataArray] | None#: NOI time series (available after finalization).

property noi_stats: dict[str, dict[str, DataArray]] | None#

noi_stats[variable][statistic] (after finalization).

Type:: NOI statistics

property time: ndarray | None#: Daily time coordinate for NOI/HOI data.

property time_months: ndarray | None#: Monthly time coordinate for accumulations.

to_netcdf(output_dir)[source]#

Write output to netCDF files (not yet implemented).

Return type:: None

pywatershed.Output

Contents

pywatershed.Output#