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.

  • WatershedRegime Regime metadata for one watershed.

  • UnitExposureContext Reviewed per-unit riparian, snow-transient, and high-elevation fractions.

  • Tier0ScreeningReport Versioned 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: RuntimeError

Raised 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: object

Tier 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: object

One 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
to_dict()[source]

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

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: object

Reviewed 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: object

Hydrologic regime metadata for one watershed.

Parameters:
  • watershed_id (str)

  • regime (str)

  • notes (str)

notes: str = ''
regime: str = 'unknown'
to_dict()[source]

Return the regime as a JSON-serializable mapping.

Return type:

dict[str, object]

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:

Tier0ScreeningReport

femic.hydrology.screening.write_tier0_screening_report(report, path)[source]

Write a Tier 0 screening report as pretty-printed JSON.

Parameters:
Return type:

Path