HydroSeason

HydroSeason reads a monthly surface-water extent record (for example, from Digital Earth Australia Water Observations) and tells you whether the 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.

Documentation: tayerthiaggo.github.io/hydroseason

What you get

One call writes a self-contained HTML report, four CSVs (_monthly, _hydro_years, _wet_event, _low_spells), and a run manifest that records the method version and input checksums.

Open a real report (no install needed):

• Fitzroy River (WA) — seasonal: per-year boundaries
• Lachlan River (NSW) — aseasonal: events and dry spells
• Fitzroy River + rainfall — rainfall shown as context only

Browse a complete output folder (no install needed): docs/examples/fitzroy-river-wa/ — the HTML report, the four CSVs (monthly, hydro years, wet events, low spells), and the run manifest.

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

Python 3.10–3.13. Run hydroseason doctor to check which inputs your environment supports.

Quickstart

From a monthly extent CSV (date, extent_pct, optional invalid_pct):

from hydroseason import run_hydroseason

result = run_hydroseason(
    "monthly_extent.csv",
    output_dir="output/report",
    aoi_name="My AOI",
)
print(result.analysis.regime.regime)  # "seasonal", "aseasonal", or "insufficient_record"
print(result.analysis.route)          # "per_year_detection", "event_characterisation", ...
print(result.artifacts.html)

Or fetch DEA data for a polygon, from the command line:

hydroseason run --aoi catchment.geojson --aoi-name "My catchment" \
  --start-date 2005-01-01 --end-date 2025-12-01 \
  --output-dir output/report --cache-dir cache

The same function also takes NetCDF/Zarr rasters, optional rainfall, and — through run_hydroseason_many — many AOIs at once. See the Usage Guide and the notebooks.

How it works

1. Screen — on a DEA fetch, one read of the all-time WOfS statistics checks the AOI holds recurrent water before any monthly data is downloaded.
2. Test seasonality — circular Kuiper tests ask whether annual peaks and troughs recur in the same calendar months (at least five detectable years required).
3. Route — a seasonal record with at least seven resolved cycles gets per-year boundaries, refined with a robust (Huber) profile fit. Anything else gets flood-event and low-spell analysis.
4. Report — rainfall, if added, annotates the report but never changes the answer, which is decided from water alone.

Every run uses one frozen method, hydroseason-v0.2.0, recorded in the run manifest. Details: Methods Reference.

Case studies

Three reproducible studies on five Australian catchments (DEA 30 m, 2005–2025): the main workflow, resolution sensitivity, and rainfall context.

Citation

Please cite the software release (CITATION.cff):

@software{tayer_hydroseason,
  author  = {Tayer, Thiaggo C.},
  title   = {HydroSeason: Remote-sensing-first hydrological year and season detection},
  year    = {2026},
  url     = {https://github.com/tayerthiaggo/hydroseason},
  doi     = {10.5281/zenodo.21866898}
}

See Citation for version-specific DOIs.

License

MIT — see LICENSE.