hydropattern

Evaluate hydrologic time series against configured flow-pattern components. Designed for hydrologists and environmental scientists, hydropattern provides a command-line application and a secondary Python API.

Documentation

Start with the user documentation, then follow:

• Installation
• First evaluation
• Interpreting first results
• Glossary
• Configuration and characteristic reference
• Upgrade guidance

The user documentation site provides searchable guides and references.

Inputs and results

Provide a CSV or Excel file with a time column and one or more observation columns. Each observation column is a scenario, evaluated independently. A TOML file specifies components, ordered characteristic conditions, and optional output settings.

For example, a small CSV can contain a date column and one flow scenario:

time,flow
2020-01-01,0
2020-01-02,2

Results include raw timestep outcomes and component summary workbooks. Scenario grids can also produce response-surface plots. Characteristics cover timing, magnitude, duration, frequency, and rate of change. See CLI usage for output choices and working folders.

Install v0.3.1

Install the CLI with uv and Python 3.12 or newer:

uv tool install --python 3.12 hydropattern==0.3.1
uv tool update-shell
hydropattern --help

The installation guide provides platform-specific steps, a pip/virtual-environment alternative, and separate Python API installation.

To install from a source checkout, follow the source-checkout instructions.

First evaluation

Save flow.csv and first-run.toml in one folder.

Open a terminal in that folder, then execute:

hydropattern run first-run.toml --no-excel

Relative input-data paths resolve from the terminal's working folder, not the TOML file's location. No repository clone is needed for the published downloads. The command creates first-run_output/flow_sustained_flow.csv and first-run_output/sustained_flow_summary.xlsx.

The example marks two of eight fully known timesteps as component success: its total portion is 0.25. It identifies flow above 1 for at least two consecutive timesteps; isolated threshold exceedances fail duration. Configured success does not establish ecological benefit. Read the results guide before interpreting other configurations or unknown outcomes.

Scientific foundations

Natural flow regimes describe hydrologic variation relevant to ecosystems; functional flows connect that variation to environmental processes. See Poff et al. (1997), The Natural Flow Regime and Yarnell et al. (2020), A functional flows approach. Illustrative thresholds are not universal ecological criteria.

License

hydropattern is available under the GNU General Public License v3 or later.