Analysis¶
Regime assessment, catchment routing, hydrological-year detection, wet events, and dynamic hydrological state. See Which route did my catchment take? and Dynamic Hydrological State for narrative context.
Catchment Routing (start here)¶
hydroseason._catchment ¶
Regime-routed catchment analysis: one entry point, no operator decisions.
analyze_catchment assesses the regime first, then dispatches to the
analysis that regime actually supports, and records which route it took and
why. Nothing prompts and nothing raises on a difficult record: a catchment
with no detectable annual cycle returns event descriptors and an empty
hydrological-year table rather than an exception or -- worse -- a full set of
confidently-labelled boundaries fitted to noise.
CatchmentAnalysis
dataclass
¶
Everything the record supports, plus how that was decided.
summary_row ¶
summary_row(*, name: str) -> dict
Flat one-row-per-catchment record for a cross-catchment table.
analyze_catchment ¶
analyze_catchment(extent, *, value_col: str = 'extent_pct', date_col: str | None = None, min_months_per_year: int = 9, max_invalid_pct: float = 20.0, quality_policy: QualityPolicy = 'flag', measurement_tolerance_pct: float = 0.0, phase_scheme: PhaseScheme | UnsetPhaseScheme = PHASE_SCHEME_UNSET, n_bootstrap: int = 200, random_state: int = 0) -> CatchmentAnalysis
Assess regime, then run the analysis that regime supports.
Fully automatic: the recommended action for the detected regime is taken, not offered. Callers wanting a different route should call the underlying detectors directly, which makes the override explicit in their own code rather than hidden in a flag here.
Regime Assessment¶
Annual timing evidence¶
WaterRegimeAssessment and CatchmentAnalysis.summary_row() expose the
following peak and trough timing fields. They are calculated from one peak and
one trough month in each qualifying year (at least min_months_per_year,
default 9, usable months). n_timing_years is a count of years, not
months.
| Field | Units / range | None or zero when |
Meaning |
|---|---|---|---|
amplitude_snr |
Unitless, >=0 (possibly inf) |
0.0 for insufficient records |
Climatological amplitude divided by mean within-month interannual SD. Descriptive only; does not set the regime. |
peak_timing_concentration, trough_timing_concentration |
Unitless mean resultant length, 0–1 | None for insufficient records |
Concentration of annual peak/trough months. |
*_timing_concentration_ci_low, *_ci_high |
Unitless 0–1 | None for insufficient records |
Percentile 95% bootstrap bounds for the corresponding R. |
peak_timing_uniformity_p, trough_timing_uniformity_p |
p-value 0–1 | None for insufficient records |
Deterministic Monte Carlo Kuiper p-value for the discrete 12-month uniform null. |
peak_phase_iqr_months, trough_phase_iqr_months |
Months, 0–12 approximately | None when fewer than four timings or insufficient |
Circular IQR; descriptive only and never a regime decision. |
n_timing_years |
Integer >=0 years | 0 for insufficient records |
Number of qualifying annual timing observations. Equals n_peak_timing_years; kept as a separate published field from the conservative min() used in the route gate. |
n_peak_timing_years, n_trough_timing_years |
Integer >=0 years | -- | Count of calendar years whose peak/trough extremum is independently identifiable under the default timing-identifiability gates. |
n_zero_months |
Integer >=0 months | -- | Total usable months with exact-zero observed extent. Descriptive only; never a route or timing predicate. |
zero_month_fraction |
Unitless, 0–1 | -- | Fraction of usable months that are exact zero. |
n_whole_zero_years |
Integer >=0 years | -- | Count of years whose usable months are all exact zero. Contributes to dry-duration/event summaries but no timing observation. |
pixel_support_status |
"available" | "unavailable" |
-- | Whether pixel counts (n_water/n_valid/n_invalid/n_aoi) are present. Percentage-only inputs report "unavailable", and the min_peak_water_pixels threshold is not consulted for them. |
timing_evidence |
"supported" | "insufficient" | "unsupported" |
-- | insufficient when min(n_peak_timing_years, n_trough_timing_years) < min_informative_years; unsupported when established seasonality/uniformity evidence rejects an annual cycle; otherwise supported. |
mean_monthly_peak_month, mean_monthly_trough_month |
Calendar month 1–12 | None for aseasonal/insufficient records |
Extrema of mean monthly extent when the record supports reporting them. |
Public regime assessment and routing emit the runtime decision_policy value hydroseason_0_2_0 while using exact empirical monthly extrema, circular timing statistics, and the timing-identifiability gates. decision_policy names the regime and route decision; it is not the method policy id (hydroseason-v0.3.0), which the run manifest records with its fingerprint. Extent is observed surface-water availability, not rainfall, discharge, storage volume, a climate variable, or natural-condition hydrology. A record's route is per_year_detection only when its regime is seasonal and its timing evidence is supported; a seasonal record with insufficient identifiable timing keeps its regime label but routes to event_characterisation. See the Methods Reference for the method specification.
hydroseason._regime ¶
Surface-water regime assessment: what kind of signal is this, and what may be asked of it?
This module answers a question that must be settled before hydrological-year detection runs: does the catchment's observed surface-water record contain a reproducible annual cycle at all? Detectors downstream will return an answer whether or not one exists, so the gate belongs here.
Scope note, deliberately narrow: extent_pct measures observed surface
water, which is water availability as seen from above. It is not a climate
variable and must not be read as one. Regulation, diversion, extraction,
farm-dam storage and land-use change all move surface-water extent
independently of rainfall, so a flat or shifted signal is evidence about water
availability, never directly about climate.
WaterRegimeAssessment
dataclass
¶
What the record supports, and what it does not.
assess_water_regime ¶
assess_water_regime(extent, *, value_col: str = 'extent_pct', date_col: str | None = None, min_months_per_year: int = _DEFAULT_MIN_MONTHS_PER_YEAR, max_invalid_pct: float = 20.0, quality_policy: QualityPolicy = 'flag', measurement_tolerance_pct: float = 0.0, n_bootstrap: int = 200, random_state: int = 0) -> WaterRegimeAssessment
Assess what the observed surface-water record supports.
Wet Events and Low Spells¶
hydroseason._events ¶
Event-based characterisation of a surface-water record.
The annual-cycle view (peak, trough, hydrological year) presumes a reproducible yearly rhythm. Where a catchment has none -- episodic dryland rivers fill on rainfall events rather than on a calendar -- that view has nothing to attach to, and forcing it produces boundaries that describe noise.
This module supplies the alternative vocabulary such records do satisfy: discrete wet episodes, low-extent spells, and how often filling recurs. These are the terms in which an intermittent river is normally described, and unlike a hydrological year they make no stationarity or periodicity assumption.
Episode detection uses hysteresis: an event opens when extent rises above a high threshold and stays open until it falls below a lower one. A single entry threshold would split one flood into several whenever the recession wobbles across it, inflating the event count precisely on the noisy records this module exists to serve.
WaterEventResult
dataclass
¶
Wet episodes, low-extent spells, and record-level summaries.
extract_water_events ¶
extract_water_events(extent, *, value_col: str = 'extent_pct', date_col: str | None = None, threshold_mode: str = 'noise', enter_k: float = _DEFAULT_ENTER_K, exit_k: float = _DEFAULT_EXIT_K, low_k: float = _DEFAULT_LOW_K, start_quantile: float = _DEFAULT_START_QUANTILE, end_quantile: float = _DEFAULT_END_QUANTILE, low_quantile: float = _DEFAULT_LOW_QUANTILE, min_event_months: int = 1, min_separation_months: int = 1, min_low_months: int = 2, max_invalid_pct: float = 20.0, quality_policy: QualityPolicy = 'flag') -> WaterEventResult
Extract wet episodes and low-extent spells from a monthly extent record.
A wet event is a departure above the record's baseline exceeding
enter_k noise scales, persisting until it falls back below exit_k
noise scales (hysteresis), lasting at least min_event_months, and
separated from the next episode by at least min_separation_months.
A low-extent spell is a run of at least min_low_months below the
baseline minus low_k noise scales. It is defined independently of
events: a catchment that never floods still has low-extent spells, and
defining a spell as the gap between two events reports none for exactly
the records that stay low.
The name is deliberate. This measures below this record's own typical
extent, not dryness in the cease-to-flow sense -- roughly a third of all
months qualify on a normal catchment, and calling those "dry" implies an
absence of water that the data does not show. months_below_low_pct is
reported alongside so the base rate is always visible: a long spell on a
catchment where 38% of months sit below baseline describes a sustained
below-average period, not a river without water.
threshold_mode selects how those thresholds resolve:
"noise" (default)
Baseline median plus/minus multiples of the record's own AR(1)-corrected
month-to-month noise. Means the same thing across catchments -- "larger
than this record's own wobble" -- and presupposes nothing about what
fraction of months are wet.
"quantile"
Fixed quantiles of the usable distribution. Robust but arbitrary: p75
places a quarter of all months above the entry threshold even on a
record containing no events whatsoever.
Where the noise estimate is degenerate -- a synthetic or heavily-quantised
record with no month-to-month variation -- noise mode cannot produce a
scale, so thresholds fall back to quantiles and the resolved mode is
reported as "quantile_fallback" rather than silently claiming
"noise".
Months screened out by the quality policy break an episode rather than bridging it: an unobserved month is not evidence that water persisted.
Hydrological-Year Detection Core¶
hydroseason.hydro_year ¶
Source-agnostic hydrological-year detection from monthly water extent.
Adapted from WaterMask-TSFill. Raster masks, WOfS, and extent CSVs converge
on this module's monthly extent_pct input.
HydroYearConfig
dataclass
¶
Wet then dry search windows, at any phase of the calendar year.
Windows are cyclic month ranges, not calendar-anchored spans: each is
read by walking forward from its start month to its end month, wrapping
through December where needed. The cycle for the record labelled Y is
anchored so the wet window ends in year Y; the wet window's start and
the whole dry window then fall wherever that anchoring puts them, which may
be the previous or the following calendar year.
The default describes a tropical monsoon: wet Nov(Y-1)..Apr(Y), then dry Jul(Y)..Dec(Y).
Because the geometry is cyclic, any phase of the calendar year is valid --
notably southern-Australian winter-rainfall catchments, e.g. wet_start_month=6, wet_end_month=9,
dry_start_month=11, dry_end_month=2, whose dry window ends in Y+1.
The only ordering rule left is that the dry window must begin after the wet
window ends.
cycle_span_months
property
¶
cycle_span_months: int
Total months from wet-window start to dry-window end.
windows_for_year ¶
windows_for_year(year: int) -> tuple[pd.Timestamp, pd.Timestamp, pd.Timestamp, pd.Timestamp]
Absolute (wet_start, wet_end, dry_start, dry_end) for record year.
Anchored on the wet window ending in year, then walked outward by
the cyclic spans, so every other bound lands in whichever calendar year
the phase implies without the caller specifying offsets.
detect_hydrological_years ¶
detect_hydrological_years(extent: Series | DataFrame, *, value_col: str = 'extent_pct', date_col: str | None = None, config: HydroYearConfig | None = None, duplicate_month_policy: DuplicateMonthPolicy = 'raise', missing_month_policy: MissingMonthPolicy = 'raise', max_invalid_pct: float = 20.0, quality_policy: QualityPolicy = 'flag') -> pd.DataFrame
Detect hydrological years from a complete, quality-screened monthly series.
invalid_pct is honoured when supplied in a DataFrame. The conservative
default rejects months with more than 20% invalid coverage. Set
quality_policy="flag" to retain those observations and continue while
leaving quality interpretation to the caller.
label_hydrological_months ¶
label_hydrological_months(dates: Index | Series | DatetimeIndex, hy_df: DataFrame) -> pd.DataFrame
Assign Wet/Dry and hydrological-year labels from detected boundaries.
monthly_water_extent ¶
monthly_water_extent(water_mask: 'xr.DataArray', *, water_value: int = 1, dry_value: int = 0, outside_value: int = -2, invalid_value: int = -1, spatial_dims: tuple[str, str] = ('y', 'x'), time_block: int = 1, wet_aoi=None, read_workers: int | None = None) -> pd.DataFrame
Summarise monthly canonical masks without treating invalid pixels as dry.
n_valid counts only pixels explicitly equal to water_value or
dry_value; any other code (unknown values, NaN, out-of-domain codes
that bypassed a classifier) counts as invalid rather than silently
inflating the valid denominator. Raster dependencies are imported only at
this computation boundary. The four scalar summaries are computed in
streamed blocks of time_block steps along time rather than in one
all-at-once dask.compute call, so peak memory stays bounded by
time_block (times the spatial chunk footprint) instead of scaling
with the full length of time. Raising time_block trades scheduler
overhead (more, smaller dask.compute calls) for locality (fewer calls,
more spatial chunks held concurrently); lower it to bound memory more
tightly, raise it to reduce per-call scheduling overhead.
wet_aoi, if given, is a polygon or GeoDataFrame (in any CRS) describing
the historical wet-AOI extent. It is rasterised against water_mask's
spatial grid exactly once (the grid is time-invariant across the whole
cube), then used to compute n_wet_aoi -- the per-month count of pixels
inside the wet AOI that are also not outside_value -- and the derived
wet_fill_pct = 100 * n_water / n_wet_aoi wet-footprint fill ratio
(NaN when n_wet_aoi is 0). When wet_aoi is None (the default),
no rasterisation happens at all and n_wet_aoi is set equal to
n_valid, so the other columns are unaffected and wet_fill_pct is
still well defined, computed with the same 100 * n_water / n_wet_aoi formula used in the
wet_aoi-given case (this keeps wet_fill_pct an exact
sum-then-percentage tiled aggregation of n_water/n_wet_aoi,
matching how extent_pct and invalid_pct already aggregate).
wet_fill_pct therefore equals extent_pct exactly and
unconditionally when wet_aoi is None, regardless of whether
invalid pixels are present, because both ratios reduce to the same
100 * n_water / n_valid formula in that case (they can legitimately
differ only when a real wet_aoi is supplied).
read_workers, if given (and > 0), overrides dask's threaded-scheduler
worker count for the dask.compute reductions below, where the lazy
STAC/COG graph is actually materialised. Profiling on real WOfS data found
this workload is decode/warp-CPU-bound rather than I/O-latency-bound as
might be assumed for remote reads: dask's own default worker count
outperformed every explicit override tried (4 through 64), and forcing a
higher count made it monotonically worse. Leave this at None (the
default, which leaves dask's configuration untouched) unless you have
profiled your own workload and confirmed a specific value helps -- see
hydroseason._io_extent_cache.load_wofs_monthly_extent's read_workers
docstring for the measurements. The override, if used, is scoped via
dask.config.set and restored on exit.
suggest_hydro_year_config ¶
suggest_hydro_year_config(extent: Series | DataFrame, *, value_col: str = 'extent_pct', date_col: str | None = None, **overrides) -> HydroYearConfig
Propose a HydroYearConfig from a monthly-mean climatology of extent.
Averages extent by calendar month, then takes the contiguous
above-mean run around the climatological peak as the wet window and the
below-mean run around the trough as the dry window. Because
HydroYearConfig windows are cyclic, the suggestion keeps whatever phase
the climatology shows rather than reshaping it toward a cross-year wet
season -- a winter-rainfall catchment gets a mid-year wet window.
This remains a first guess for review, not a substitute for it: bimodal,
flat, or noisy climatologies can produce a split that doesn't match
physical wet/dry seasons. Screen the record with assess_water_regime
first; a catchment it calls aseasonal has no phase worth suggesting. Pass explicit HydroYearConfig fields as overrides (e.g.
min_wet_months=3) to keep the suggested months but override other
settings.
Dynamic Hydrological State¶
hydroseason.hydrological_state ¶
Dynamic hydrological state: data-driven years, phases, and conditions.
The public face of the dynamic route. Where
:mod:hydroseason.hydro_year fixes a calendar-anchored hydrological year,
this module derives each cycle's boundaries from the observed extent record
itself, then labels months by cycle-relative phase and classifies each year's
surface-water condition against the record's own history.
:func:analyze_hydrological_state is the one call that runs the whole chain
(seasonality classification, dynamic year detection, phase assignment,
condition classification); the individual steps are re-exported for callers
that need only one of them. See the
Dynamic Hydrological State guide <https://tayerthiaggo.github.io/hydroseason/hydrological-state/>_.
DynamicHydroYearConfig
dataclass
¶
Search settings for :func:detect_dynamic_hydrological_years.
expected_trough_month (1-12) centres each year's trough search; it is
not a fixed year boundary. trough_search_radius_months sets how far the
search reaches either side of it, widened up to
adaptive_trough_search_radius_months on an adaptive retry.
max_invalid_pct, allow_unknown_quality and quality_policy set
which months count as usable; min_baseline_cycles, low_percentile
and high_percentile set the annual condition baseline;
phase_scheme selects the monthly phase labels.
HydrologicalStateResult
dataclass
¶
Output of :func:analyze_hydrological_state.
Attributes:
| Name | Type | Description |
|---|---|---|
pattern |
SeasonalPatternResult
|
Advisory seasonal shape from :func: |
config |
DynamicHydroYearConfig
|
The configuration used: the caller's, or the one suggested from
|
hydro_years |
DataFrame
|
One row per dynamic trough-to-trough cycle: peak, temporal mid-dry, half-loss, trough, dry run and annual condition columns. |
monthly_condition |
DataFrame
|
Each month's extent ranked against the same calendar month in other years. |
monthly_phase |
DataFrame
|
Cycle-relative phase label per month (see |
data_quality |
dict
|
Number of months per |
SeasonalPatternResult
dataclass
¶
Output of :func:classify_seasonal_pattern: an advisory seasonal shape.
The labels describe the selected fitted harmonic curve, not the observed record, and do not set the analysis route.
Attributes:
| Name | Type | Description |
|---|---|---|
pattern |
str
|
|
expected_peak_month, expected_trough_month |
int or None
|
Main peak and trough months of the fitted curve (1-12). |
secondary_peak_month, secondary_trough_month |
int or None
|
Second-ranked peak and trough months, when the curve has them. |
seasonal_strength |
float
|
|
bootstrap_support |
float
|
1.0 when any peak mode was retained, else 0.0. Not a calibrated confidence measure. |
peak_phase_iqr_months, trough_phase_iqr_months |
float or None
|
Always |
n_complete_years |
int
|
Calendar years with all twelve months usable. |
seasonal_cv_skill |
float
|
Leave-one-year-out skill of the selected harmonic order. |
periodicity_p |
float
|
Periodicity test p-value; 1.0 when no test ran. |
selected_harmonic_order |
int
|
Harmonic order of the fitted curve (0 is a constant). |
seasonal_amplitude_pp |
float
|
Peak-to-trough range of the fitted curve, in percentage points. |
amplitude_noise_ratio |
float
|
|
peak_timing_n_modes, trough_timing_n_modes |
int
|
Number of retained peak and trough modes. |
n_evaluable_years |
int
|
Years with any weighted, usable month. |
analyze_hydrological_state ¶
analyze_hydrological_state(extent, *, config: DynamicHydroYearConfig | None = None, reference_start=None, reference_end=None, reference: str = 'full_record', rolling_window_cycles: int = 10, rolling_min_cycles: int = 5, n_bootstrap: int = 200, random_state: int = 0, quality_policy: QualityPolicy = 'flag') -> HydrologicalStateResult
Run the dynamic hydrological-state chain on one monthly extent record.
Classifies the seasonal pattern, detects dynamic hydrological years, ranks each cycle's peak and trough against the record's own baseline, ranks each month against the same calendar month, and labels monthly phases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
extent
|
DataFrame or Series
|
Monthly water extent: an |
required |
config
|
DynamicHydroYearConfig
|
Search settings. When omitted, they are suggested from the seasonal
pattern, which raises |
None
|
reference
|
str
|
Annual condition baseline: |
'full_record'
|
reference_start
|
optional
|
Restrict the annual and monthly baselines to this period. |
None
|
reference_end
|
optional
|
Restrict the annual and monthly baselines to this period. |
None
|
rolling_window_cycles
|
int
|
Window length and minimum cycle count for the |
10
|
rolling_min_cycles
|
int
|
Window length and minimum cycle count for the |
10
|
n_bootstrap
|
int
|
Passed to :func: |
200
|
random_state
|
int
|
Passed to :func: |
200
|
quality_policy
|
('flag', 'exclude')
|
How low-quality months are treated. Ignored when |
"flag"
|
Returns:
| Type | Description |
|---|---|
HydrologicalStateResult
|
|
detect_dynamic_hydrological_years ¶
detect_dynamic_hydrological_years(extent, *, config: DynamicHydroYearConfig, value_col: str = 'extent_pct', date_col: str | None = None, pattern: SeasonalPatternResult | None = None) -> pd.DataFrame
Detect data-driven trough-to-trough hydrological years.
Each year's boundary is the observed low found in a search window centred
on config.expected_trough_month; the boundaries are then made
consistent across years and refined. Short interior cycles, and interior
years whose window clipped a lower trough, are retried with a wider
window. Each cycle reports its peak, temporal mid-dry, half-loss and
trough extents, timing labels, quality and status columns, and the dry
run of its trough boundary.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
extent
|
DataFrame or Series
|
Monthly water extent ( |
required |
config
|
DynamicHydroYearConfig
|
Search settings. |
required |
value_col
|
str
|
Extent column name. |
'extent_pct'
|
date_col
|
str
|
Date column, when the dates are not the index. |
None
|
pattern
|
SeasonalPatternResult
|
Seasonal pattern of the record; secondary extrema of the fitted curve
are added only when it is |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
One row per hydrological year; see the report columns reference. |
suggest_dynamic_hydro_year_config ¶
suggest_dynamic_hydro_year_config(extent, *, pattern: SeasonalPatternResult | None = None, **overrides) -> DynamicHydroYearConfig
Build a :class:DynamicHydroYearConfig from the record's seasonal pattern.
Uses the pattern's expected trough and peak months (pattern is
computed with :func:classify_seasonal_pattern when omitted);
overrides are passed to the config as given. Raises ValueError
when the pattern is weak_or_irregular, low_variability or
insufficient_record and expected_trough_month is not supplied.
classify_seasonal_pattern ¶
classify_seasonal_pattern(extent, *, resolution_floor_pp: float | None = None, mode_min_frequency: float | None = None, mode_min_separation_months: int | None = None, n_bootstrap: int = 200, n_null: int = _DEFAULT_N_NULL, random_state: int = 0, measurement_tolerance_pct: float = 0.0, quality_policy: Literal['exclude', 'flag'] = 'flag') -> SeasonalPatternResult
Classify annual-cycle shape from weighted, partial-year-tolerant evidence.
Every month passing the observation policy contributes, weighted by its
observed fraction. Evaluable partial years count towards the minimum of
five evaluable years and inform the fit; n_complete_years is reported
for reference only.
classify_annual_surface_water_condition ¶
classify_annual_surface_water_condition(annual: DataFrame, *, reference: str = 'full_record', reference_start: str | Timestamp | None = None, reference_end: str | Timestamp | None = None, rolling_window_cycles: int = 10, rolling_min_cycles: int = 5, min_baseline_cycles: int = 5, low_percentile: float = 20.0, high_percentile: float = 80.0, low_variability: bool = False, allow_low_variability_labels: bool = False, noise_pp: float | None = None, timing_amplitude_k: float = 2.0) -> pd.DataFrame
Rank each cycle's peak and trough extent against the record's own baseline.
Anchoring cycles are complete, with a confirmed boundary and a peak
that is not anomalous (where those columns exist), and dated timing
(point, interval or broad). Each cycle's peak (recharge) and
trough (refuge) extent is ranked against them by empirical percentile:
low at or below low_percentile, high at or above
high_percentile. The two labels join into annual_condition.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
annual
|
DataFrame
|
Cycles from :func: |
required |
reference
|
str
|
|
'full_record'
|
reference_start
|
optional
|
Keep only anchoring cycles whose |
None
|
reference_end
|
optional
|
Keep only anchoring cycles whose |
None
|
min_baseline_cycles
|
int
|
With fewer anchoring cycles every label is |
5
|
low_percentile
|
float
|
Percentile cut-offs for |
20.0
|
high_percentile
|
float
|
Percentile cut-offs for |
20.0
|
low_variability
|
bool
|
When true, and |
False
|
noise_pp
|
float
|
Robust noise scale. In the |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
|
compute_monthly_surface_water_condition ¶
compute_monthly_surface_water_condition(extent, *, reference_start=None, reference_end=None, value_col: str = 'extent_pct', date_col: str | None = None, max_invalid_pct: float = 20.0, allow_unknown_quality: bool = False, quality_policy: QualityPolicy = 'flag') -> pd.DataFrame
Rank each month's extent against the same calendar month in other years.
Only usable months enter the reference, a month is left out of its own
reference, and reference_start and reference_end (given together)
restrict it to that period. Returns one row per month with
extent_pct, reference_median_pct, anomaly_pct,
condition_percentile (empirical percentile), reference_n and
quality_state; anomaly and percentile are NaN for unusable months.
aggregate_basin_monthly_extent ¶
aggregate_basin_monthly_extent(monthly: DataFrame, *, date_col: str = 'date', aoi_col: str = 'aoi_id', area_weight_col: str | None = None) -> pd.DataFrame
Combine per-AOI monthly extent rows into one basin record.
With pixel-count columns (n_water, n_valid, n_invalid,
n_aoi) the counts are summed and extent_pct and invalid_pct
are recomputed from the sums. Otherwise extent_pct is weighted by
area_weight_col, which is then required, and invalid_pct is NaN.
An AOI missing from a month counts as fully invalid in the count path and
carries no weight in the area path; a month no AOI reported stays NaN.
Each AOI may contribute one row per month. n_aoi_reporting,
n_aoi_expected and aoi_coverage_pct say how many AOIs reported
each month.