HydroSeason¶

Hydrological-year detection and seasonal/aseasonal analysis from monthly satellite surface-water extent, such as Digital Earth Australia Water Observations.

HydroSeason tests whether a catchment floods and dries on a reliable annual cycle. If it does, you get per-year boundaries and wet/dry phases. If it doesn't, you get flood events and low-water spells instead of a forced calendar.

Scope

HydroSeason measures surface-water extent. It does not estimate discharge, depth, volume, or groundwater.

What you get¶

One call writes a self-contained HTML report, four CSVs, and a run manifest. Live examples: Fitzroy River (seasonal) · Lachlan River (aseasonal) · Fitzroy + rainfall context.

The complete Fitzroy output folder — HTML, four CSVs, and run manifest — is browsable on GitHub.

Install¶

pip install hydroseason              # CSV input (pandas + numpy only)
pip install "hydroseason[raster]"    # + NetCDF/Zarr/xarray input and SILO rainfall
pip install "hydroseason[stac]"      # + fetch DEA Water Observations directly
pip install "hydroseason[all]"       # everything: all inputs, DEA fetch, rainfall

Quickstart¶

from hydroseason import run_hydroseason

result = run_hydroseason(
    "monthly_extent.csv",
    output_dir="output/report",
    aoi_name="My AOI",
)

print(f"Regime: {result.analysis.regime.regime}")
print(f"Route: {result.analysis.route}")
print(f"HTML: {result.artifacts.html}")

Where next¶

Page	Contents
Usage Guide	The four ways to run `run_hydroseason`, batches, routing, data quality, DEA internals
Methods Reference	The frozen `hydroseason-v0.2.0` method and its validation
CLI Recipes	The same workflow from the command line: progress, logs, resuming, exit codes
Preflight	What an AOI's record can support, decided before acquisition
Dynamic Hydrological State	Per-year boundaries, trough diagnostics, and phases
Case Studies	Three reproducible studies across five Australian catchments
Export Columns	Column dictionary for the four CSVs
API Reference	Every public function and class
Citation	How to cite HydroSeason