Tier 0 Hydrology Screening Metrics
Purpose
P114.4 adds fast watershed/year screening metrics from the disturbance ledger. They describe harvest and road exposure for review and UI use.
Tier 0 is not a hydrologic response model. It does not estimate peak-flow frequency, flood probability, or damage. Those begin in P114.5.
Metrics
For each watershed and year:
gross harvest, retention, and effective harvest area;
harvest_fraction;an equivalent clear-cut area (ECA) diagnostic:
eca_area_haandeca_fraction;active and connected road length;
road_density_km_per_km2andconnected_road_density_km_per_km2;active road crossings and
crossing_density_per_km2;riparian_effective_harvest_ha,snow_transient_effective_harvest_ha, andhigh_elevation_effective_harvest_ha.
ECA Semantics
ECA is an explicitly diagnostic indicator:
it uses the most recent harvest per unit;
it can be undiscounted or discounted by a configurable linear recovery period;
it is not a frequency-based response;
it is not a substitute for the P114.5 stochastic analysis.
Without recovery_years, ECA is undiscounted and the report warns.
With recovery_years, each unit’s last effective harvest area declines
linearly to zero over that period.
Road Metrics
road_active_kmis the sum of active road length in the watershed.road_connected_kmis the active length flagged as connected to streams.road_density_km_per_km2is active km divided by watershed area.connected_road_density_km_per_km2is connected km divided by watershed area.road_connected_fractionis connected km divided by active km, or null when no road is active.crossing_density_per_km2is active crossings divided by watershed area.
Exposure Context
Riparian, snow-transient, and high-elevation exposure use reviewed per-unit fractions:
from femic.hydrology.screening import UnitExposureContext
contexts = (
UnitExposureContext(
"u1",
riparian_fraction=0.25,
snow_transient_fraction=0.5,
high_elevation_fraction=0.1,
),
)
These are context-weighted fractions, not geometry intersections. The reviewed spatial analysis that produces them belongs to P114.2 or a later spatial overlay.
Regimes
A watershed regime can be recorded as rain, rain_on_snow,
snowmelt, snow_transient, or unknown. Missing regimes default to
unknown with a warning; this is a metadata flag, not a model.
Example
from femic.hydrology.screening import (
WatershedRegime,
compute_tier0_screening,
write_tier0_screening_report,
)
report = compute_tier0_screening(
ledger,
domain,
regimes=(WatershedRegime("w1", "snow_transient"),),
unit_contexts=contexts,
recovery_years=60,
)
write_tier0_screening_report(
report,
Path("metadata/hydrology/tier0_screening.json"),
)
Outputs
The report uses schema femic.hydrology.screening.v1 and records:
screening and ledger/domain identities;
recovery configuration;
one row per watershed/year;
caveats and warnings;
deterministic
screening_id.
Limits
ECA is a screening diagnostic, not a response model.
Context fractions are supplied inputs, not computed geometry.
No instance-specific threshold or operational decision is applied.
Regime flags do not model climate or event frequency.
The report does not replace field or hydrologist review.