femic.hydrology.disturbance Module
The femic.hydrology.disturbance module converts harvest, road,
retention, and recovery schedules into a complete annual unit/year disturbance
ledger. It records active road state, source event lineage, and time since
disturbance for later hydrologic response work.
It is an accounting layer, not a hydrology model or a flood-risk product.
Start Here If…
Use this page first if you are trying to:
convert WS4/FHOPS schedules into annual unit/year rows;
reconcile harvest area, retention, and unit area;
track road build, use, maintenance, and decommissioning;
preserve source event lineage; or
hand a disturbance ledger to Tier 0 or response modelling.
Typical Usage
from pathlib import Path
from femic.hydrology.disturbance import (
DisturbanceUnit,
HarvestEvent,
RoadEvent,
build_disturbance_ledger,
write_disturbance_ledger,
write_disturbance_ledger_csv,
)
ledger = build_disturbance_ledger(
domain_id="example-domain",
units=(
DisturbanceUnit("u1", 10.0, "w1", "h1"),
),
harvest_events=(
HarvestEvent("h1", "u1", 2020, 4.0, 1.0),
),
road_events=(
RoadEvent("r1b", "r1", "u1", 2020, "build", 1000.0, True, 1),
),
years=(2020, 2021, 2022),
)
write_disturbance_ledger(ledger, Path("metadata/hydrology/disturbance.json"))
write_disturbance_ledger_csv(ledger, Path("metadata/hydrology/disturbance.csv"))
Key Entry Surfaces
build_disturbance_ledger()Build a complete annual unit/year ledger with conservation checks.validate_disturbance_ledger()Check row completeness, area, road state, and age consistency.load_disturbance_units_csv()load_harvest_events_csv()load_road_events_csv()Load the first WS4/FHOPS handoff surfaces.write_disturbance_ledger()write_disturbance_ledger_csv()Persist JSON and one-row-per-unit/year CSV.DisturbanceLedgerAnnual ledger with units, rows, caveats, and provenance.
Cross-References
Annual harvest/road/retention disturbance ledgers.
P114.3 converts spatial harvest and road schedules into a complete annual ledger by unit and year. It is an accounting layer, not a hydrologic response.
- class femic.hydrology.disturbance.DisturbanceLedger(ledger_id, generated_utc, domain_id, years, units, rows, caveats=(), provenance=<factory>, schema_version='femic.hydrology.disturbance.v1')[source]
Bases:
objectComplete annual disturbance ledger for a hydrology domain.
- Parameters:
ledger_id (str)
generated_utc (str)
domain_id (str)
years (tuple[int, ...])
units (tuple[DisturbanceUnit, ...])
rows (tuple[DisturbanceLedgerRow, ...])
caveats (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]
- property row_count: int
Return the number of unit/year rows.
- rows: tuple[DisturbanceLedgerRow, ...]
- schema_version: str = 'femic.hydrology.disturbance.v1'
- units: tuple[DisturbanceUnit, ...]
- years: tuple[int, ...]
- class femic.hydrology.disturbance.DisturbanceLedgerRow(year, unit_id, watershed_id, hru_id, unit_area_ha, harvest_area_ha, retention_area_ha, effective_harvest_area_ha, road_active_length_m, road_connected_length_m, road_built_length_m, road_decommissioned_length_m, road_crossing_count, years_since_harvest, years_since_road_build, source_event_ids=())[source]
Bases:
objectOne unit/year disturbance state.
- Parameters:
year (int)
unit_id (str)
watershed_id (str)
hru_id (str | None)
unit_area_ha (float)
harvest_area_ha (float)
retention_area_ha (float)
effective_harvest_area_ha (float)
road_active_length_m (float)
road_connected_length_m (float)
road_built_length_m (float)
road_decommissioned_length_m (float)
road_crossing_count (int)
years_since_harvest (int | None)
years_since_road_build (int | None)
source_event_ids (tuple[str, ...])
- effective_harvest_area_ha: float
- harvest_area_ha: float
- hru_id: str | None
- retention_area_ha: float
- road_active_length_m: float
- road_built_length_m: float
- road_connected_length_m: float
- road_crossing_count: int
- road_decommissioned_length_m: float
- source_event_ids: tuple[str, ...] = ()
- unit_area_ha: float
- unit_id: str
- watershed_id: str
- year: int
- years_since_harvest: int | None
- years_since_road_build: int | None
- class femic.hydrology.disturbance.DisturbanceLedgerValidation(is_valid, errors, warnings)[source]
Bases:
objectValidation outcome for a disturbance ledger.
- Parameters:
is_valid (bool)
errors (tuple[str, ...])
warnings (tuple[str, ...])
- errors: tuple[str, ...]
- is_valid: bool
- to_dict()[source]
Return the validation as a JSON-serializable mapping.
- Return type:
dict[str, object]
- warnings: tuple[str, ...]
- class femic.hydrology.disturbance.DisturbanceUnit(unit_id, area_ha, watershed_id, hru_id=None)[source]
Bases:
objectOne spatial unit in the disturbance ledger.
- Parameters:
unit_id (str)
area_ha (float)
watershed_id (str)
hru_id (str | None)
- area_ha: float
- hru_id: str | None = None
- unit_id: str
- watershed_id: str
- class femic.hydrology.disturbance.HarvestEvent(event_id, unit_id, year, area_ha, retention_area_ha=0.0, treatment='clearcut', source='')[source]
Bases:
objectOne harvest or retention event on a spatial unit.
- Parameters:
event_id (str)
unit_id (str)
year (int)
area_ha (float)
retention_area_ha (float)
treatment (str)
source (str)
- area_ha: float
- event_id: str
- retention_area_ha: float = 0.0
- source: str = ''
- treatment: str = 'clearcut'
- unit_id: str
- year: int
- exception femic.hydrology.disturbance.HydrologyDisturbanceError[source]
Bases:
RuntimeErrorRaised when a disturbance schedule or ledger is invalid.
- class femic.hydrology.disturbance.RoadEvent(event_id, road_id, unit_id, year, action, length_m=0.0, connected_to_stream=False, crossing_count=0, source='')[source]
Bases:
objectOne road build, use, maintenance, or decommission event.
- Parameters:
event_id (str)
road_id (str)
unit_id (str)
year (int)
action (str)
length_m (float)
connected_to_stream (bool)
crossing_count (int)
source (str)
- action: str
- connected_to_stream: bool = False
- crossing_count: int = 0
- event_id: str
- length_m: float = 0.0
- road_id: str
- source: str = ''
- unit_id: str
- year: int
- femic.hydrology.disturbance.build_disturbance_ledger(*, domain_id, units, harvest_events, road_events, years, generated_utc=None)[source]
Build a complete annual unit/year disturbance ledger.
Every unit receives one row for every year, even when no event occurs. Harvest area and retention are gross annual flows; road lengths are active state plus gross annual build/decommission flows.
- Parameters:
domain_id (str)
units (Sequence[DisturbanceUnit])
harvest_events (Sequence[HarvestEvent])
road_events (Sequence[RoadEvent])
years (Sequence[int])
generated_utc (str | None)
- Return type:
- femic.hydrology.disturbance.load_disturbance_ledger(path)[source]
Load a disturbance ledger from JSON.
- Parameters:
path (Path)
- Return type:
- femic.hydrology.disturbance.load_disturbance_units_csv(path)[source]
Load units from a CSV with unit_id, area_ha, watershed_id, hru_id.
- Parameters:
path (Path)
- Return type:
tuple[DisturbanceUnit, …]
- femic.hydrology.disturbance.load_harvest_events_csv(path)[source]
Load harvest events from a CSV schedule.
- Parameters:
path (Path)
- Return type:
tuple[HarvestEvent, …]
- femic.hydrology.disturbance.load_road_events_csv(path)[source]
Load road events from a CSV schedule.
- Parameters:
path (Path)
- Return type:
tuple[RoadEvent, …]
- femic.hydrology.disturbance.validate_disturbance_ledger(ledger)[source]
Validate ledger structure, completeness, and row conservation.
- Parameters:
ledger (DisturbanceLedger)
- Return type:
- femic.hydrology.disturbance.write_disturbance_ledger(ledger, path)[source]
Write a disturbance ledger as pretty-printed JSON.
- Parameters:
ledger (DisturbanceLedger)
path (Path)
- Return type:
Path
- femic.hydrology.disturbance.write_disturbance_ledger_csv(ledger, path)[source]
Write one CSV row per unit/year for review and downstream joins.
- Parameters:
ledger (DisturbanceLedger)
path (Path)
- Return type:
Path