HydroSeason

HydroSeason turns a monthly surface-water record into a hydrological year report — from a satellite-derived water-mask time series (such as Digital Earth Australia Water Observations), it works out when a catchment floods and dries, where each hydrological year begins and ends, and whether the pattern is even seasonal at all.

[!NOTE] HydroSeason analyzes surface-water extent percentages. It does not estimate river discharge, channel depth, total water volume, or groundwater storage.

What you get

One function call gives you one self-contained HTML report, an interactive water-extent timeline with each hydrological year, its wet and dry phases, and the flood events and low spells found in the record. Plus four CSVs carrying the same numbers for your own analysis: _monthly, _hydro_years, _wet_event, and _low_spells.

Open a real one (no install needed):

• Fitzroy River (WA) — a strongly seasonal monsoonal catchment
• Lachlan River (NSW) — an aseasonal one, characterized by flood events and dry spells instead of forced hydrological years
• Fitzroy River, with rainfall context — the same water analysis, with rainfall added purely as annotation

Installation

pip install hydroseason              # Core: CSV detection & reports (pandas, numpy)
pip install "hydroseason[raster]"    # + xarray, rioxarray, rasterio, geopandas, dask, zarr
pip install "hydroseason[stac]"      # + pystac-client, odc-stac (DEA STAC acquisition)
pip install "hydroseason[all]"       # Complete raster + STAC dependencies

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}")

run_hydroseason is the one function most people need — see the four ways to run it below for rasters, DEA fetching, and optional rainfall context.

How it works

1. You give it monthly water-extent data — a CSV you already have, a raster/NetCDF/Zarr cube, or nothing at all (it fetches Digital Earth Australia satellite data for you).
2. It checks whether the catchment has a reliable annual cycle — a signal-to-noise ratio (SNR): how strong and repeatable the yearly wet/dry swing is compared to noise.
3. It picks the matching analysis automatically — a strong, repeatable cycle gets per-year hydrological boundaries; an irregular or dryland catchment gets discrete flood-event and dry-spell characterization instead, rather than forcing a yearly pattern that isn't really there.
4. Optional rainfall adds context, never changes the answer — rainfall can be fetched or supplied alongside the water data, but it only annotates the report; it can never alter the regime, route, boundaries, phases, events, or spells that were already decided from water alone.
5. It writes one self-contained HTML report and four CSVs — open the HTML anywhere, no server needed; the CSVs are ready for your own analysis.

CSV, raster, or DEA fetch  →  run_hydroseason  →  seasonal or aseasonal route  →  HTML report + 4 CSVs

The four ways to run it

Runnable examples for each: Usage Guide — The four ways to run it, or the notebooks — start with 01_quickstart.ipynb. Acquisition internals (the fixed historical water mask, planning footprints, cache integrity, composite bundles) are documented in Advanced: DEA acquisition internals.

Case Studies

Three fully reproducible offline case studies using 2005–2025 DEA 30 m whole-catchment extent data across five Australian catchments (Daly, Fitzroy, Gilbert, Lachlan, Moonie):

1. Main Catchment Workflow — Route-aware analysis across five catchments: three seasonal/marginal monsoonal basins, two aseasonal dryland basins.
2. Resolution and Acquisition Evidence — Why 30 m resolution is the release standard: 60/90/300 m coarsening fails pre-declared fidelity gates for low-SNR catchments.
3. Rainfall Context — Proves rainfall is strictly additive: every water-only column stays byte-identical with rainfall attached.

Scientific Limitations

• Extent is not Volume or Discharge: Surface area percentage (extent_pct) dilutes narrow river channels and misses sub-canopy water.
• Cloud Gaps: High cloud/shadow invalid coverage (invalid_pct) distorts extent statistics if unflagged.
• Resolution: Coarsening spatial resolution distorts peak/trough timing and event boundaries. 30 m resolution remains authoritative.

Entry Points

Full API reference, grouped by task: Workflow, Loading Data, Analysis, Reporting.

Citation

If you use HydroSeason in your research, please cite both the software release (see CITATION.cff) and the methodological paper:

@article{tayer2026mapping,
  author  = {Tayer, Thiaggo C. and Beesley, Leah S. and Stewart-Koster, Ben
             and Bond, Nick and Douglas, Michael M. and Rossi, Maria J.
             and McGregor, Glenn B. and Marshall, Jonathan C.},
  title   = {Mapping resilience: A framework for analysing surface-water
             dynamics and persistent pools in non-perennial rivers using
             remote sensing, rainfall and river discharge data},
  journal = {Journal of Hydrology},
  volume  = {666},
  pages   = {134750},
  year    = {2026},
  doi     = {10.1016/j.jhydrol.2025.134750}
}

Full citation guidance, including the software BibTeX entry and the Zenodo DOI policy, is in docs/citation.md.

License

MIT License — see LICENSE.