femic.hydrology.screening Module
The femic.hydrology.screening module computes Tier 0 watershed/year
screening metrics from a disturbance ledger and hydrology domain. It reports
harvest, ECA, road density, crossing density, and context-weighted riparian,
snow-transient, and high-elevation exposure.
It is a screening diagnostic, not a hydrologic response model or flood-risk product.
Start Here If…
Use this page first if you are trying to:
summarize harvest and road exposure by watershed/year;
inspect an ECA diagnostic with or without a recovery period;
compare active, connected, and crossing road density;
attach reviewed riparian/snow/elevation context fractions; or
produce a reviewable Tier 0 report before P114.5.
Typical Usage
from pathlib import Path
from femic.hydrology.screening import (
UnitExposureContext,
WatershedRegime,
compute_tier0_screening,
write_tier0_screening_report,
)
report = compute_tier0_screening(
ledger,
domain,
regimes=(WatershedRegime("w1", "snow_transient"),),
unit_contexts=(
UnitExposureContext("u1", 0.25, 0.5, 0.1),
),
recovery_years=60,
)
write_tier0_screening_report(
report,
Path("metadata/hydrology/tier0_screening.json"),
)
Key Entry Surfaces
compute_tier0_screening()Compute watershed/year Tier 0 screening rows.write_tier0_screening_report()Persist the report as JSON.WatershedRegimeRegime metadata for one watershed.UnitExposureContextReviewed per-unit riparian, snow-transient, and high-elevation fractions.Tier0ScreeningReportVersioned report with rows, caveats, warnings, and deterministic identity.
Cross-References
Tier 0 hydrology screening metrics and caveats.
These metrics describe harvest and road exposure. They are diagnostics, not a hydrologic response model.
- exception femic.hydrology.screening.HydrologyScreeningError[source]
Bases:
RuntimeErrorRaised when Tier 0 screening inputs or outputs are invalid.
- class femic.hydrology.screening.Tier0ScreeningReport(screening_id, generated_utc, ledger_id, domain_id, recovery_years, rows, caveats=(), warnings=(), provenance=<factory>, schema_version='femic.hydrology.screening.v1')[source]
Bases:
objectTier 0 screening report for one disturbance ledger and domain.
- Parameters:
screening_id (str)
generated_utc (str)
ledger_id (str)
domain_id (str)
recovery_years (int | None)
rows (tuple[Tier0ScreeningRow, ...])
caveats (tuple[str, ...])
warnings (tuple[str, ...])
provenance (dict[str, object])
schema_version (str)
- caveats: tuple[str, ...] = ()
- domain_id: str
- generated_utc: str
- ledger_id: str
- provenance: dict[str, object]
- recovery_years: int | None
- rows: tuple[Tier0ScreeningRow, ...]
- schema_version: str = 'femic.hydrology.screening.v1'
- screening_id: str
- to_dict()[source]
Return the screening report as a JSON-serializable mapping.
- Return type:
dict[str, object]
- warnings: tuple[str, ...] = ()
- class femic.hydrology.screening.Tier0ScreeningRow(year, watershed_id, regime, watershed_area_ha, harvest_area_ha, retention_area_ha, effective_harvest_area_ha, harvest_fraction, eca_area_ha, eca_fraction, road_active_km, road_connected_km, road_density_km_per_km2, connected_road_density_km_per_km2, road_connected_fraction, crossing_count, crossing_density_per_km2, riparian_effective_harvest_ha, snow_transient_effective_harvest_ha, high_elevation_effective_harvest_ha)[source]
Bases:
objectOne watershed/year Tier 0 screening row.
- Parameters:
year (int)
watershed_id (str)
regime (str)
watershed_area_ha (float)
harvest_area_ha (float)
retention_area_ha (float)
effective_harvest_area_ha (float)
harvest_fraction (float)
eca_area_ha (float)
eca_fraction (float)
road_active_km (float)
road_connected_km (float)
road_density_km_per_km2 (float)
connected_road_density_km_per_km2 (float)
road_connected_fraction (float | None)
crossing_count (int)
crossing_density_per_km2 (float)
riparian_effective_harvest_ha (float)
snow_transient_effective_harvest_ha (float)
high_elevation_effective_harvest_ha (float)
- connected_road_density_km_per_km2: float
- crossing_count: int
- crossing_density_per_km2: float
- eca_area_ha: float
- eca_fraction: float
- effective_harvest_area_ha: float
- harvest_area_ha: float
- harvest_fraction: float
- high_elevation_effective_harvest_ha: float
- regime: str
- retention_area_ha: float
- riparian_effective_harvest_ha: float
- road_active_km: float
- road_connected_fraction: float | None
- road_connected_km: float
- road_density_km_per_km2: float
- snow_transient_effective_harvest_ha: float
- watershed_area_ha: float
- watershed_id: str
- year: int
- class femic.hydrology.screening.UnitExposureContext(unit_id, riparian_fraction=0.0, snow_transient_fraction=0.0, high_elevation_fraction=0.0)[source]
Bases:
objectReviewed per-unit fractions used for screening exposure metrics.
- Parameters:
unit_id (str)
riparian_fraction (float)
snow_transient_fraction (float)
high_elevation_fraction (float)
- high_elevation_fraction: float = 0.0
- riparian_fraction: float = 0.0
- snow_transient_fraction: float = 0.0
- to_dict()[source]
Return the context as a JSON-serializable mapping.
- Return type:
dict[str, object]
- unit_id: str
- class femic.hydrology.screening.WatershedRegime(watershed_id, regime='unknown', notes='')[source]
Bases:
objectHydrologic regime metadata for one watershed.
- Parameters:
watershed_id (str)
regime (str)
notes (str)
- notes: str = ''
- regime: str = 'unknown'
- watershed_id: str
- femic.hydrology.screening.compute_tier0_screening(ledger, domain, *, regimes=(), unit_contexts=(), recovery_years=None, generated_utc=None)[source]
Compute watershed/year Tier 0 screening metrics.
The metrics are: - gross/effective harvest and harvest fraction; - a configurable, optionally recovery-discounted ECA diagnostic; - road density, connected-road density, and crossing density; - context-weighted riparian, snow-transient, and high-elevation exposure.
The context fractions are supplied by a reviewed spatial analysis; this function does not intersect geometries or resample rasters.
- Parameters:
ledger (object)
domain (object)
regimes (Sequence[WatershedRegime])
unit_contexts (Sequence[UnitExposureContext])
recovery_years (int | None)
generated_utc (str | None)
- Return type:
- femic.hydrology.screening.write_tier0_screening_report(report, path)[source]
Write a Tier 0 screening report as pretty-printed JSON.
- Parameters:
report (Tier0ScreeningReport)
path (Path)
- Return type:
Path