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.

  • DisturbanceLedger Annual 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: object

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

Return the ledger as a JSON-serializable mapping.

Return type:

dict[str, object]

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

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

Return the row as a JSON-serializable mapping.

Return type:

dict[str, object]

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

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

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

Return the unit as a JSON-serializable mapping.

Return type:

dict[str, object]

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

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

Return the event as a JSON-serializable mapping.

Return type:

dict[str, object]

treatment: str = 'clearcut'
unit_id: str
year: int
exception femic.hydrology.disturbance.HydrologyDisturbanceError[source]

Bases: RuntimeError

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

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

Return the event as a JSON-serializable mapping.

Return type:

dict[str, object]

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:
Return type:

DisturbanceLedger

femic.hydrology.disturbance.load_disturbance_ledger(path)[source]

Load a disturbance ledger from JSON.

Parameters:

path (Path)

Return type:

DisturbanceLedger

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:

DisturbanceLedgerValidation

femic.hydrology.disturbance.write_disturbance_ledger(ledger, path)[source]

Write a disturbance ledger as pretty-printed JSON.

Parameters:
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:
Return type:

Path