Workflow

The one-call orchestrator. Start here — see Usage Guide: Start here, one call.

hydroseason.workflow

Public orchestrator: preview an AOI, resolve water input, then add rainfall.

run_hydroseason ties together the modules that were designed to stay decoupled from each other: it resolves whatever water source the caller supplied (:mod:hydroseason._workflow_input), runs :func:analyze_catchment exactly once -- the sole routing authority, rainfall-blind -- and only then looks at rainfall at all. Rainfall is a strictly separate, best-effort branch: loading a supplied CSV, fetching from SILO, and comparing against the already-computed regime can each fail independently without taking the water analysis or the report down with them. Every rainfall failure is recorded on the result and surfaced as a UserWarning; only water input, analysis, and report-writing failures are fatal and propagate as exceptions. A supplied AOI is loaded once before acquisition so its optional display context can be previewed and reused for rainfall; context and preview failures only warn, but an unloadable supplied AOI is fatal.

Rainfall is off by default (fetch_rainfall=False). A supplied rainfall_csv_path always takes precedence over fetch_rainfall=True: if both are given, SILO is never called.

A fetch_rainfall=True run whose environment cannot import the SILO dependencies warns before the water step rather than after it, giving the caller a chance to abort before spending hours on water acquisition. The warning does not make ancillary rainfall fatal and does not change the water analysis.

progress is off by default. progress=True writes five numbered step lines to standard error and switches on the per-calendar-year bar that load_wofs_monthly_extent already provides; passing a callable instead delivers :class:hydroseason._progress.ProgressEvent objects and leaves the nested bar off. Progress reporting never changes what a run computes.

HydroSeasonRunResult dataclass

Everything a single run_hydroseason call produced.

analysis is always rainfall-blind, regardless of whether rainfall was requested or how it fared: the invariant this dataclass exists to make checkable is that analysis is identical whether or not rainfall was supplied at all.

run_hydroseason

run_hydroseason(water_source=None, *, output_dir: str | Path, aoi=None, aoi_name: str | None = None, start_date: str | None = None, end_date: str | None = None, water_mask_variable: str | None = None, fetch_rainfall: bool = False, rainfall_csv_path: str | Path | None = None, stac_url: str = DEFAULT_STAC_URL, stac_collection: str = DEFAULT_STAC_COLLECTION, statistics_stac_url: str | None = None, cache_dir: str | Path | None = None, phase_scheme: PhaseScheme | UnsetPhaseScheme = PHASE_SCHEME_UNSET, phase_model: LegacyPhaseModel | None = None, analysis_options: Mapping[str, Any] | None = None, report_title: str | None = None, report_subtitle: str | None = None, progress: bool | Callable[[ProgressEvent], None] = False, show_map: Literal['auto'] | bool = 'auto') -> HydroSeasonRunResult

Resolve water input, analyze it once, then add rainfall as context.

water_source follows :func:hydroseason._workflow_input.resolve_water_input: None fetches from DEA (requires aoi, start_date, end_date), otherwise it may be a DataFrame, CSV path, NetCDF/Zarr path, or an xarray Dataset/DataArray of a canonical water mask.

stac_url configures BOTH DEA searches the fetch path performs: the monthly ga_ls_wo_3 search and the ga_ls_wo_fq_myear_3 historical- statistics search that fixes this run's spatial denominator. Pass statistics_stac_url only to point the statistics search at a different service from the monthly one.

Rainfall is entirely optional and never influences the water analysis: analyze_catchment runs exactly once, before any rainfall handling, on the resolved extent alone. If rainfall_csv_path is supplied it takes precedence over fetch_rainfall -- SILO is never called when a CSV is given. Any rainfall failure (missing/malformed CSV, SILO fetch failure, missing aoi for a fetch, or a comparison failure) is caught, recorded on the result (rainfall_status, rainfall_error/ rainfall_comparison_error), and warned via UserWarning -- it never raises.

AOI and map parameters

run_hydroseason accepts one AOI analysis. If its supplied AOI contains multiple rows, they are analysed together as one union footprint; use run_hydroseason_many when rows must remain separate. Its show_map parameter accepts "auto" (default: preview only in a notebook), True (request a preview), or False (no preview). HydroSeasonRunResult returns aoi_context: AOIContext | None: compact display geometry and bounds when an AOI was supplied, otherwise None. It is display metadata, not a replacement for the analysed footprint.

Row-preserving DEA/STAC batches

run_hydroseason_many(aois, *, output_dir, start_date, end_date, ...) has no water_source parameter: it is DEA/STAC-only. It loads the vector once, splits it into one single-row AOI per input row, and invokes the single-AOI workflow for each. A MultiPolygon in one row remains one AOI. The result tuple is always in source order, even when scheduling begins larger items first.

Parameter / result	Contract
id_col	Optional source identifier column. Values must be non-null, nonblank, and unique before and after safe filename conversion; defaults are aoi-0001, aoi-0002, ...
workers	"auto" or a positive integer. Auto uses min(2, logical CPU count); 1 is sequential; a larger integer is honoured subject to memory admission.
memory_budget_gb	Optional positive finite decimal-GB budget. None uses 80% of currently available RAM.
show_map	"auto", True, or False; batch preview is best-effort and never changes child analyses.
HydroSeasonAOIOutcome	Immutable id, zero-based source_position, successful result or complete error_type/error_message; exactly one form is populated.
HydroSeasonBatchResult	Immutable outcomes tuple plus source-ordered .succeeded, .failed, and .raise_for_failures().
HydroSeasonBatchError	Raised by .raise_for_failures() with every failed outcome in .failures.

Each row receives output_dir/<safe-id>/ and, when provided, cache_dir/<safe-id>/. Runtime exceptions are captured per row, while invalid input, identifiers, dates, worker counts, or budgets fail before any child run. The scheduler estimates a 30 m native-resolution peak from the AOI's bounding box, admitting concurrent jobs only while the summed estimate fits. An oversized AOI warns and runs alone. Threads provide I/O overlap only; this outer scheduler does not set Dask worker counts or promise linear throughput.

hydroseason.batch

Row-preserving contracts and execution for multi-AOI workflows.

Provides memory-bounded multi-AOI batch processing via :func:run_hydroseason_many. Optional geospatial dependencies stay inside :func:_prepare_batch_aois so importing the public batch API remains available on a core installation.

HydroSeasonAOIOutcome dataclass

The successful result or captured exception for one source AOI row.

succeeded property

succeeded: bool

Whether this AOI completed without an exception.

HydroSeasonBatchError

Bases: RuntimeError

Raised when a batch contains one or more failed AOI outcomes.

HydroSeasonBatchResult dataclass

Immutable, source-ordered outcomes from a future batch workflow.

succeeded property

succeeded: tuple[HydroSeasonAOIOutcome, ...]

Successful outcomes in their original source order.

failed property

failed: tuple[HydroSeasonAOIOutcome, ...]

Failed outcomes in their original source order.

raise_for_failures

raise_for_failures() -> None

Raise a single error covering every failed AOI, if any.

run_hydroseason_many

run_hydroseason_many(aois, *, output_dir: str | Path, start_date, end_date, id_col: str | None = None, workers: Literal['auto'] | int = 'auto', memory_budget_gb: float | None = None, show_map: Literal['auto'] | bool = 'auto', fetch_rainfall: bool = False, stac_url: str = DEFAULT_STAC_URL, stac_collection: str = DEFAULT_STAC_COLLECTION, cache_dir: str | Path | None = None, analysis_options: Mapping[str, Any] | None = None, report_title: str | None = None, report_subtitle: str | None = None, progress: bool | Callable[[ProgressEvent], None] = False) -> HydroSeasonBatchResult

Run the public single-AOI workflow once for every source AOI row.