Report CSV columns¶
generate_catchment_report writes four CSVs beside the HTML report. These
files are the default user interface: dates are named explicitly, the
monthly table contains the flags needed to filter a timeline, and the
hydrological-year table contains the three boundary markers and their quality
signals. Internal condition-model and detector diagnostics are deliberately
not repeated in every row of the default CSVs.
The complete diagnostic frames are available in Python as
result.analysis.monthly and result.analysis.hydro_years (see the
diagnostic sections below).
For monthly WOfS acquired through the default high-level workflow, the fixed
scientific footprint is (DEA Multi-Year count_wet > 0) AND user AOI.
n_aoi is that historical mask's constant pixel count,
invalid_pct = 100 * n_invalid / n_aoi, and pixels outside the mask do not
affect quality percentages. extent_pct = 100 * n_water / n_valid uses valid
observations inside the same mask. The separate planning superset affects only
remote reads. Date and event selection remains percentage-based, and no area,
pixel-area, or km2 columns are added.
Monthly timeline (<stem>_monthly.csv)¶
One row is retained for every input month. date is the first day of the
month; percentages are 0--100.
| Column | Meaning |
|---|---|
date |
Month represented by the row. |
extent_pct |
Observed surface-water extent percentage. |
invalid_pct |
Percentage of the fixed historical-mask pixels that were invalid in that month; invalid pixels outside the mask are excluded. |
max_invalid_pct |
User-configurable per-month invalid-pixel limit over the historical-mask denominator, used when determining usable_month. |
baseline_extent_pct |
Record baseline extent used by both wet-event and low-spell detection. |
usable_month |
Whether the month is admitted by the configured quality policy. In the review-oriented flag workflow, finite partial-invalid months remain usable and are flagged by quality_state. |
quality_state |
Quality label for the month (usable, low, missing, or unknown). |
hy_year |
Hydrological-year identifier, blank when the selected route does not define years. |
confidence |
Hydrological-year confidence level (high, medium, low), blank when outside a resolved hydrological year. |
phase |
Phase label according to the selected phase_scheme (two_phase [default]: rising/receding, split at the observed peak; none: unspecified). |
phase_status |
Phase provenance (ok, provisional, interval_boundary, unresolved_cycle, outside_cycle, unusable, or disabled). interval_boundary marks usable months of a year whose timing_status is interval or broad. |
is_hy_peak |
True for the detected annual maximum month. |
is_hy_mid_dry |
True for the temporal mid-dry marker. |
is_hy_trough |
True for each year's trough boundary month (trough_boundary_date), whatever its timing status. |
in_wet_event / wet_event_id |
Whether the month belongs to a wet event and its identifier. |
in_low_spell / low_spell_id |
Whether the month belongs to a low-extent spell and its identifier. |
regime / route |
The regime decision and analysis route applied to the record. |
rainfall_mm / rain_anomaly_mm |
Optional supplied-CSV or SILO rainfall context, written only when rainfall loads successfully. The anomaly is rainfall minus the median for the same calendar month. These fields never drive regime routing, boundaries, phases, events, or low spells. |
Hydrological years (<stem>_hydro_years.csv)¶
This file is header-only for event_characterisation and other routes that do
not define hydrological years. Date columns are month starts.
| Column | Meaning |
|---|---|
catchment |
User-supplied AOI name, or HydroSeason results when the name is blank. |
hy_year |
Hydrological-year identifier. |
start_date / end_date |
Closed interval used for that hydrological year. start_date is the month after the previous cycle's trough_boundary_date (except for the first year of the record and a year after a gap). See Dates around the dry-season low. |
peak_date / mid_dry_date / trough_date |
Wet maximum, mid-dry, and trough boundary markers. |
peak_extent_pct / mid_dry_extent_pct / trough_extent_pct |
Extent observed at each marker. |
peak_invalid_pct / mid_dry_invalid_pct / trough_invalid_pct |
Invalid-pixel percentage at each marker. High values make the marker provisional/low confidence. |
drawdown_pct |
Peak-to-trough extent range when available. |
annual_condition |
Combined recharge (peak) and refuge (trough) condition relative to the record's own confirmed cycles; insufficient_baseline when fewer than five confirmed cycles with dated timing (point, interval or broad) exist to form a baseline. |
confidence |
Deterministic quality grade (high, medium, low) assigned based on data completeness and observation flags. This is an empirical quality grade, not a probability. |
status / boundary_status |
Result status and whether boundaries are exact, provisional, or otherwise constrained. |
peak_quality |
The peak observation judged against its own month-of-year norm: normal or anomalous. Only anomalous downgrades the cycle. |
boundary_basis |
Whether the boundary was detected per year or imposed from a fixed window derived from mean monthly extent. |
regime / route |
Record-level routing metadata. |
timing_status |
Aggregate timing identifiability for the row (point, interval, broad or unresolved): the weaker of peak_timing_status and trough_timing_status. boundary_status describes selection/data admissibility; timing_status describes temporal identifiability -- the two are independent. |
peak_timing_status / trough_timing_status |
How many months are tied with the peak or trough, within the cycle's detectability floor. For the trough, only the months from the cycle's peak to the trough boundary are compared; months after the boundary are not. point means a single month stood out, and it is the trough boundary. Since hydroseason-v0.3.0 a dated trough label always covers trough_month: when the months compared single out another month (for example a cloudy month the boundary search skipped), the interval is widened to cover both and graded by its width, and the boundary does not move. The exception is a boundary at the end of a dry, zero-extent low (trough_label_basis = end_of_dry_run, below): its label runs from the boundary to the month before the next peak and is graded by that width, interval or broad, never point. interval means a span of up to 3 months. broad (troughs only) means up to 6 months. unresolved means no bounded span. These statuses describe how distinct the extremum is, not how close the reported month is to the true one; see Dates around the dry-season low. |
peak_date / trough_date |
Populated only when the corresponding *_timing_status is point; blank for interval, broad or unresolved so a broad plateau or diffuse peak is never presented as a fabricated exact date. |
trough_boundary_date |
The operational boundary used for cycle segmentation, populated whenever a trough was detected regardless of timing status (blank only for a blank cycle with no trough opportunity at all). This is always trough_month, the actual date used to define hy_start/hy_end -- it is not the same as trough_interval_end_date: a refined boundary can sit strictly inside its own support interval, so the two must not be assumed equal. Use trough_date for a strict point-only claim and trough_boundary_date for "what date this cycle actually uses". |
peak_interval_start_date / peak_interval_end_date / trough_interval_start_date / trough_interval_end_date |
Bounds of equivalent evidence for that extremum across the cycle window (or robust-loss profile support interval for refined troughs; for an end_of_dry_run trough label, the boundary to the month before the next peak). Populated for point, interval and broad; also populated for unresolved when candidate extrema exist to preserve complete equivalent evidence. These are deterministic non-parametric support bounds, not nominal confidence intervals or probability distributions. |
detectability_floor_pp |
The record's detectability floor for that cycle, in percentage points: max(measurement_tolerance_pct, robust_noise_pp, peak_resolution_pp, trough_resolution_pp, machine epsilon). |
amplitude_to_floor_ratio |
That cycle's amplitude divided by detectability_floor_pp; 0.0 when the amplitude is at or below the floor. |
dry_run_start_date / dry_run_end_date |
Start and end of the dry run of this cycle's trough boundary: the months around the boundary whose extent stays within the boundary's own tolerance, followed past the search window and over cloudy months. dry_run_end_date is the end of the dry season. It can lie months after trough_boundary_date on a flat-bottomed trough, and past the next boundary in a year with no wet season. See Dates around the dry-season low. |
rewetting_date |
The first observed month above the dry run: when water returns. Blank when the record ends dry. |
dry_run_months |
Months from dry_run_start_date to dry_run_end_date, inclusive. |
dry_end_status |
interval when a re-wetting month was observed (the dry season ends between dry_run_end_date and the month before rewetting_date), censored when the record ends dry, unavailable when the cycle has no boundary. Never point. |
status_reason |
Why status and boundary_status have their values; see Why a cycle is provisional. ok for a complete, confirmed cycle. |
trough_refinement_status / trough_refinement_reason |
The pass-2 refinement verdict for the trough that ends this cycle and the reason code behind it; see Trough refinement diagnostics. Blank when pass 2 did not run (for example the fixed-window route). |
baseline_eligible |
Whether this cycle anchors the annual condition baseline: status is complete, boundary_status is confirmed, timing_status is point, interval or broad (only point before hydroseason-v0.3.0), peak_quality is not anomalous, and, with a fixed reference period, the cycle ends inside it. |
baseline_n |
Number of cycles this row's annual_condition is ranked against. With the full-record or a fixed reference it is the eligible count, minus one when the row is itself eligible; with a rolling reference it is that row's window size. When the eligible count is below min_baseline_cycles (default 5), annual_condition is insufficient_baseline. |
result.analysis.hydro_years also carries trough_label_basis, which is not
in the CSV. It says how the trough timing label was set: lowest_month when
it comes from comparing the months from the peak to the boundary, and
end_of_dry_run when the boundary is the last month of a dry, zero-extent low
longer than a month, water was seen to return, and the label was broad or
unresolved because every dry month ties. The label then runs from the
boundary to the month before the next peak; when that span is too wide to
grade, the label is left as it was and the basis stays lowest_month. It is
blank when the cycle has no trough. The dry-run dates are there as
dry_run_start_month, dry_run_end_month and rewetting_month.
Trough search geometry diagnostics¶
These six columns are on result.analysis.hydro_years, not in the CSV.
They describe how a boundary was found and never take part in finding one.
| Column | Meaning |
|---|---|
trough_search_radius_used |
Radius in months actually used for this year's window. Equals the configured trough_search_radius_months unless the adaptive retry widened this year. |
boundary_at_search_edge |
The published boundary sits exactly at an edge month of its own window. A warning that a lower continuation may lie outside; not a defect. |
boundary_search_edge_side |
left, right, or none. |
outside_window_observed |
Every month of the outside-audit span was present in the prepared frame. The span reaches at most five months from the anchor — the radius the adaptive retry can already use — so it never names a month the detector could not have selected. |
outside_window_lower |
A strictly lower raw observed extent exists in that span. |
retry_outcome |
not_attempted, applied, or rolled_back. |
outside_window_lower is a challenge count, not a clipping rate. It states
that a lower raw value was observed outside the window. It does not state that
the outside month is the correct boundary: a wider search can select a
competing event or damage cycle geometry. Confirming a challenge needs
per-cycle truth, which no real record supplies.
The two derived rates have different denominators and must not be compared:
boundary_search_edge_rate is over published boundaries, and
outside_window_lower_rate is over boundaries with outside_window_observed.
Both publish numerator, denominator, and an interval. Within one catchment that
interval is Wilson and is labelled an understatement, because cycles inside one
catchment are serially dependent; across a cohort it is a catchment-level
bootstrap.
Trough refinement diagnostics¶
Seasonal boundaries are found in two passes: pass 1 picks a robust trough in
each year's search window, and pass 2 refines it with the direct-profile
Huber fit (introduced in hydroseason-v0.2.0, unchanged in hydroseason-v0.3.0). These columns record what pass 2 found.
They are on result.analysis.hydro_years. Of these, only
trough_refinement_status and trough_refinement_reason are also in the CSV.
| Column | Meaning |
|---|---|
pass1_trough_month / pass1_trough_interval_start / pass1_trough_interval_end / pass1_trough_timing_status |
The pass-1 boundary and its timing status, retained unchanged so any refinement can be audited against what it replaced. |
trough_challenger_month / trough_challenger_interval_start / trough_challenger_interval_end / trough_challenger_timing_status |
What pass 2 proposed. Populated even when the pass-1 boundary is kept, so the proposal stays auditable. |
trough_challenger_low_state_start / trough_challenger_low_state_end |
The fitted low-state occupancy span. Distinct from endpoint uncertainty: a long flat low is not the same claim as an imprecisely located one. |
recovery_start_month |
First month of sustained recovery out of the low state. |
trough_refinement_status |
confirmed, provisional, unresolved, unavailable, or awaiting_next_peak. |
trough_refinement_reason |
Why that status was reached, e.g. accepted, low_quality_peak, interval_peak, open_span, missing_or_unresolved_peak, recovery_crosses_gap, gap_overlaps_low_state, gap_before_low_state (a fully-observed post-gap month sits materially below the pre-gap fitted low level, so the low state is not confined to before the gap and the pre-gap segment cannot answer for it), unstable_peak_sensitivity, unstable_quality_sensitivity, boundary_deferred_to_reliable_month (the naive latest support-cluster/pre-gap month was too cloud-contaminated to publish, so the boundary moved to the latest reliable month instead), boundary_deferred_to_implausible_month (the naive latest pre-gap month was reliable-quality but its raw value sat outside the low state's own equivalence band -- a real spike immediately before a data gap -- so the boundary moved to the latest month that was both reliable and plausible), no_reliable_boundary_in_support (no month in the support cluster was reliable and plausible enough to publish at all), recovery_within_noise (the month after the boundary clears the equivalence margin, so the boundary stands, but it still falls inside the record's own noise scale -- the call is real but finer than the observation comfortably supports, so it is not reported as confirmed), span_not_evaluable (the span's geometry left nothing to fit -- more than one gap, or a gap against a span edge; a sensitivity-ensemble scenario carrying this is excluded from the stability vote rather than counted as dissent, since it reports nothing about where the boundary lies), essential_low_quality_recovery (a month between the boundary and the next peak, needed to show the recovery, is low or unknown quality), unknown_quality (some months in the span carry no invalid-pixel information), post_gap_return_to_low_state (after a data gap the record returns to the low level, so the low state may continue through the gap), no_defensible_low_state (the span is shorter than three months or its first or last month is unobserved), not_requested (pass 2 was not run for this record), and three rollback codes that keep the pass-1 boundary: atomic_rollback_ordering (the refined boundary would not sit strictly between the two flanking peaks or would break boundary order), atomic_rollback_barrier (the earlier cycle has no preceding boundary to rebuild from), and atomic_rollback_cycle (moving the boundary would make one of the two cycles that share it inadmissible: a missing or unresolved peak, too few usable months, or changed peak evidence). A rolled-back row keeps the pass-2 verdict in trough_refinement_status, which can read confirmed, with trough_refinement_applied false and boundary_status provisional. |
trough_refinement_applied |
Whether the pass-2 boundary was adopted. |
trough_pulse_months |
Months detected as rewetting pulses inside the span. |
trough_local_scale_pp / trough_profile_best_loss / trough_profile_cutoff / trough_effective_support |
Fit diagnostics: local noise scale, achieved loss, the frozen admissibility cutoff, and effective observation support. |
trough_refinement_policy_version |
The frozen policy version that produced these values. |
trough_loss_basis |
Which loss the fit actually used: standardized_huber when a positive scale (residual noise, pixel floor, or an explicit measurement tolerance) was available, or exact_l1 when no positive scale exists at all. exact_l1 reports a deterministic exact-minimum support set up to numerical tolerance -- it carries no claimed confidence level; it is not a calibrated interval and must not be read as one. unavailable when pass 2 did not run. |
unavailable and unresolved are different claims and are never
collapsed. unavailable means pass 2 could not run for this cycle (for
example missing_or_unresolved_peak); unresolved means it ran and the
observations did not support a refined boundary. Reading the first as the second would turn "not
attempted" into "attempted and found nothing".
Applying a refinement is atomic across the two cycles that share the moved boundary: either both are updated or neither is, so a boundary can never be adopted on one side and not the other.
Why a cycle is provisional¶
boundary_status is confirmed only when both passes agree. Pass 1 needs a
full search window, the raw minimum selected, and selection_support of at
least 0.80. Pass 2 then needs both flanking peaks timed to a single month with
normal quality, recovery after the boundary that clears the record's own noise
scale, and good-quality recovery months. On long monthly satellite records
pass 2 is usually the binding gate: a cycle with a clean pass-1 selection
often stays provisional because a flanking peak is only interval-timed, the
recovery is within noise, or a recovery month is cloudy.
trough_refinement_reason names the condition. Because only
baseline_eligible cycles anchor the condition baseline, a record with few
confirmed cycles has a thin baseline; baseline_n shows how thin.
status_reason |
Meaning |
|---|---|
ok |
Complete cycle with a confirmed boundary. |
boundary_provisional |
Pass 1 did not confirm the boundary, or pass 2 ran and did not confirm it. trough_refinement_reason says which pass-2 condition failed. |
trough_refinement_fallback |
Pass 2 could not produce or adopt a refined boundary (it was unresolved, unavailable, or rolled back), so the pass-1 boundary is kept and marked provisional. |
unresolved_timing |
The cycle's peak or trough timing is unresolved. |
peak_quality_anomalous |
The peak month was far more obscured than that calendar month usually is. |
record_start_boundary |
The cycle starts at the beginning of the record, not at a detected boundary. |
insufficient_trough_candidates |
Too few usable trough candidates to place a boundary that year. |
insufficient_cycle_coverage |
Too few usable months to assemble the cycle. |
no_previous_boundary |
No preceding boundary exists, so the cycle has no resolved start. |
Wet events (<stem>_wet_event.csv)¶
Wet events are contiguous runs above a robust, record-specific wet threshold.
The default detector uses a noise-based threshold with hysteresis: an event
opens above baseline + 3 × noise and remains open while above
baseline + 1 × noise. Unusable months close an event. The event table is
descriptive and is produced for every route, including aseasonal records.
| Column | Meaning |
|---|---|
event_id |
One-based event identifier. |
start_date / end_date |
First and last month in the event. |
duration_months |
Number of contiguous event months. |
baseline_extent_pct |
Record baseline extent used by the wet-event detector. |
peak_date / peak_extent_pct |
Month and extent of the event maximum. |
mean_extent_pct |
Mean extent during the event. |
magnitude_pp_months |
Sum of (extent_pct - event_exit_threshold) for event months, clipped at zero. It measures event size and persistence in percentage-points × months; it is not a volume or discharge estimate. |
Low-extent spells (<stem>_low_spells.csv)¶
Low spells are independent of wet events. They are contiguous runs at or below
baseline - 1 × noise (or the configured quantile fallback), with a default
minimum duration of two months. They describe unusually low extent in this
record; they are not automatically a drought declaration.
| Column | Meaning |
|---|---|
low_spell_id |
One-based low-spell identifier. |
start_date / end_date |
First and last month in the spell. |
duration_months |
Number of contiguous low-extent months. |
baseline_extent_pct |
Record baseline extent used by the low-spell detector. |
min_extent_pct |
Minimum extent observed during the spell. |
Summary information¶
The HTML report's internal one-row summary (also returned by
CatchmentAnalysis.summary_row()) includes the timing fields below. They are
not repeated in the compact four-CSV bundle, so downstream code that needs
them should use the analysis result or a full summary export.
| Field | Units / range | Null / zero semantics |
|---|---|---|
amplitude_snr |
Unitless, >=0 (possibly inf) |
0.0 for insufficient records. Descriptive only; does not set the regime. |
peak_timing_concentration, trough_timing_concentration |
Mean resultant length, 0–1 | null for insufficient records. |
peak_timing_concentration_ci_low, peak_timing_concentration_ci_high, trough_timing_concentration_ci_low, trough_timing_concentration_ci_high |
Unitless 0–1, 95% bootstrap bounds | null for insufficient records. |
peak_timing_uniformity_p, trough_timing_uniformity_p |
Kuiper probability 0–1 | null for insufficient records. |
peak_phase_iqr_months, trough_phase_iqr_months |
Circular months | null with fewer than four timing observations or an insufficient record; IQR is descriptive only. |
n_timing_years |
Non-negative integer years | 0 for insufficient records; it is not a count of months. Equals n_peak_timing_years -- it keeps its historical peak-derived meaning and is never silently redefined as a minimum. |
n_peak_timing_years, n_trough_timing_years |
Non-negative integer years | Count of calendar years whose peak/trough extremum is independently identifiable (not unresolved). The conservative min() of the two is used only in the route gate, and is not itself a published field. |
n_zero_months |
Non-negative integer months | Total months with exact-zero observed extent among usable months. Descriptive only; it never enters a route or timing decision. |
zero_month_fraction |
Unitless, 0–1 | Fraction of usable months that are exact zero. |
n_whole_zero_years |
Non-negative integer years | Count of years whose usable months are all exact zero. A whole-zero year still contributes to dry-duration and event summaries; it contributes no peak or trough timing observation. |
pixel_support_status |
"available" or "unavailable" |
Whether the record carries pixel counts (n_water/n_valid/n_invalid/n_aoi). Percentage-only inputs always report "unavailable", and their min_peak_water_pixels threshold is not consulted. |
timing_evidence |
"supported", "insufficient", or "unsupported" |
Record-level timing verdict: insufficient when min(n_peak_timing_years, n_trough_timing_years) < min_informative_years; unsupported when the established seasonality/uniformity evidence rejects an annual cycle (today this is reachable only when regime == "aseasonal"); otherwise supported. |
mean_monthly_peak_month, mean_monthly_trough_month |
Calendar month 1–12 | Month of the maximum/minimum of mean monthly extent over qualifying years. null unless the record is routed with identifiable annual timing. |
R and confidence intervals are rounded to three decimal places in the
summary; IQR is rounded to two decimal places. The report uses peak R for
regime evidence and trough R for per-year boundary support. It does not use
IQR as a hidden decision threshold.
max_invalid_pct is always a configurable per-month invalid-pixel threshold
over the historical-mask denominator, not a percentage of invalid months.
AOI naming¶
The name argument is optional. Use it for a catchment name, station name, or
any label that identifies a custom AOI. It does not have to be a whole
catchment. If it is omitted or blank, reports and metadata use
HydroSeason results, and files use the safe stem hydroseason-results.