API Reference

Public symbols re-exported from hydroseason (and a handful of submodule-only helpers from hydroseason.io). Internals (hydroseason._* module contents not listed below) are not part of the stable public API surface.

Most users need exactly one entry point:

from hydroseason import run_hydroseason

Everything below is organized by task. Full signatures, parameters, and return types are on each linked page.

At a glance

Symbol	Purpose	Page
run_hydroseason	One-call orchestrator: resolve water input, analyze, optional rainfall, write report	Workflow
HydroSeasonRunResult	Everything a run_hydroseason call produced	Workflow
run_hydroseason_many	DEA/STAC-only, row-preserving batch orchestration	Workflow
HydroSeasonBatchResult	Ordered per-row outcomes, failures, and raise_for_failures()	Workflow
HydroSeasonAOIOutcome	One source row's result or captured exception	Workflow
HydroSeasonBatchError	Aggregated error raised for failed batch outcomes	Workflow
preflight	Report what an AOI's record can support, before analysing it	Preflight
FeasibilityResult	Whether an AOI holds recurrent surface water, and the counts behind that call	Preflight
PreflightResult	Candidate, monthly, and timing decisions with their reason codes	Preflight
PreflightThresholds	One named, versioned cut-off profile	Preflight
PreflightProfileUnavailable	Raised when the reviewed default profile is not installed	Preflight
HydroSeasonPreflightError	Raised when the regular DEA screen rejects an AOI	Preflight
load_extent_csv	Read a monthly extent CSV into date-indexed form	Loading Data
load_aoi	Load and validate an AOI (vector path or GeoDataFrame)	Loading Data
load_monthly_masks	Load AOI-clipped raster masks from a directory	Loading Data
load_monthly_masks_zarr	Open an already-canonical Zarr mask cube lazily	Loading Data
load_wofs_from_stac	Load DEA WOfS from STAC directly, compose monthly, clip to AOI	Loading Data
load_wofs_monthly_extent	High-level DEA WOfS fetch, resumable by calendar year	Loading Data
complete_monthly_axis	Reindex a mask cube to a complete monthly axis	Loading Data
open_wo_statistics	Load native DEA Water Observation Statistics for an AOI	Loading Data
HistoricalWaterMask	The exact, immutable (count_wet > 0) AND AOI raster and its provenance	Loading Data
build_historical_water_mask	Build the exact historical water mask	Loading Data
load_or_build_historical_water_mask	Resolve a verified historical water mask, cache-first	Loading Data
build_wet_planning_footprint	Build a conservative coarse pruning footprint	Loading Data
WetPlanningFootprint	A prepared planning footprint's identity/geometry	Loading Data
acquire_wofs_cache	Fill or reuse a local WOfS Zarr cache store	Loading Data
open_completed_mask_cache	Lazily open a completed cache store's water-mask cube	Loading Data
open_completed_dual_extent_counts	Read back dual max/median-water pixel counts (composite_bundle="dual_composite_v1")	Loading Data
verify_cache_footprints	Verify a cache's persisted AOI/analysis footprints	Loading Data
WOfSCacheHandle	Pointer to a (possibly complete) on-disk WOfS cache store	Loading Data
HistoricalMaskCoverageWarning	Requested window falls outside the historical mask's coverage	Loading Data
HistoricalMaskRefreshedWarning	A newer statistics vintage was adopted, shifting extent_pct	Loading Data
analyze_catchment	Assess regime, then run the analysis that regime supports (routing authority)	Analysis
CatchmentAnalysis	Everything the record supports, plus how that was decided	Analysis
assess_water_regime	Assess what the observed surface-water record supports	Analysis
WaterRegimeAssessment	What the record supports, and what it does not	Analysis
Regime	Regime classification (seasonal / aseasonal / insufficient_record)	Analysis
extract_water_events	Extract wet episodes and dry spells from a monthly record	Analysis
WaterEventResult	Wet episodes, dry spells, and record-level summaries	Analysis
detect_hydrological_years	Detect hydrological years from a quality-screened monthly series	Analysis
label_hydrological_months	Assign Wet/Dry and hydrological-year labels from detected boundaries	Analysis
monthly_water_extent	Summarise monthly canonical masks (invalid pixels never count as dry)	Analysis
suggest_hydro_year_config	Propose a HydroYearConfig from a monthly climatology	Analysis
HydroYearConfig	Wet/dry search windows, at any phase of the calendar year	Analysis
analyze_hydrological_state	Run the dynamic hydrological-year + phase pipeline	Analysis
detect_dynamic_hydrological_years	Robust-extrema trough/peak boundary detection	Analysis
classify_seasonal_pattern	Advisory seasonal-shape summary (does not set the route)	Analysis
suggest_dynamic_hydro_year_config	Propose a DynamicHydroYearConfig from the record	Analysis
DynamicHydroYearConfig	Search windows, quality policy, and phase scheme for dynamic years	Analysis
HydrologicalStateResult	Output of analyze_hydrological_state	Analysis
SeasonalPatternResult	Output of classify_seasonal_pattern	Analysis
classify_annual_surface_water_condition	Rank annual peaks/troughs against the record's own cycles	Analysis
compute_monthly_surface_water_condition	Monthly wet/dry extremeness relative to the record	Analysis
aggregate_basin_monthly_extent	Combine AOIs into a basin series by summed counts or area weights	Analysis
generate_catchment_report	Write the self-contained HTML report plus the 4-CSV bundle	Reporting
generate_html_report	Compatibility API: render HTML from a supplied hydro_years DataFrame	Reporting
CatchmentReportPaths	Paths written by generate_catchment_report	Reporting

Pages

• Workflow — run_hydroseason, the one-call orchestrator.
• Preflight — Recurrent-water screening and detection-support decisions, before acquisition.
• Loading Data — CSV/raster/Zarr loaders, DEA/STAC acquisition, historical water mask, planning footprints, cache surfaces.
• Analysis — Catchment routing, regime assessment, wet events, hydrological-year detection, dynamic hydrological state.
• Reporting — HTML report and CSV bundle generation.