femic.contracts.disturbance Module
The femic.contracts.disturbance module owns the
femic.disturbance.v1 event contract. It validates event records, their
spatial references, their severity representation, and their provenance without
importing FEMIC’s modelling or runtime stack.
Use this page when you are producing, reading, or validating disturbance events for a FEMIC instance, a ws4 scenario, or an FHOPS salvage plan.
Start Here If…
Use this page first if you are trying to:
define a shared fire, insect, drought, wind, mortality, harvest, or salvage event;
check a detector’s output before a model consumes it;
debug a type, severity, confidence, spatial-reference, or timestamp failure;
produce a flat row for a ws4 consumer; or
report which source and attribution method produced an event.
Typical Usage
from pathlib import Path
from femic.contracts.disturbance import (
consumer_rows,
events_for_block,
read_disturbance_table,
summarize_disturbance_table,
write_disturbance_table,
)
events = read_disturbance_table(Path("data/disturbance/fire_2023.json"))
summary = summarize_disturbance_table(events)
block_events = events_for_block(events, 101)
rows = consumer_rows(events)
write_disturbance_table(Path("data/disturbance/table.json"), events)
Key Entry Surfaces
validate_disturbance_event()Validate one event and its cross-field rules.DisturbanceEventTyped event with canonicalto_dict,from_dict, andto_consumer_row.read_disturbance_table()Read and validate a JSON table, aneventsobject, or a single event.write_disturbance_table()Write a validated table with unique event ids.summarize_disturbance_table()Return counts, types, severity classes, year and area ranges, sources, attributions, and spatial-reference counts.consumer_rows()Return the flat ws4-facing rows.events_for_block()Select events that name a block directly.disturbance_schema()Return a defensive copy of the JSON Schema document.
Cross-References
Versioned disturbance-event contract for the FRESH modelling ecosystem.
This module owns the femic.disturbance.v1 event record: the shared language
for fire, insect, drought, wind, partial mortality, harvest, and salvage events.
It validates the event, its spatial reference, its severity representation, and
its provenance before a consumer can use it.
The contract does not detect or attribute disturbances. It consumes events from an existing detector, inventory, or expert record.
- femic.contracts.disturbance.DISTURBANCE_SCHEMA: dict[str, object] = {'$id': 'https://femic.ubc.ca/schemas/disturbance.v1.json', '$schema': 'https://json-schema.org/draft/2020-12/schema', 'additionalProperties': False, 'properties': {'area_ha': {'minimum': 0, 'type': ['number', 'null']}, 'attribution': {'minLength': 1, 'type': 'string'}, 'attribution_method': {'minLength': 1, 'type': ['string', 'null']}, 'block_ids': {'items': {'minimum': 1, 'type': 'integer'}, 'type': ['array', 'null'], 'uniqueItems': True}, 'confidence': {'maximum': 1, 'minimum': 0, 'type': 'number'}, 'event_id': {'minLength': 1, 'type': 'string'}, 'event_type': {'enum': ['disease', 'drought', 'fire', 'flood', 'harvest', 'insect', 'other', 'partial_mortality', 'salvage', 'wind'], 'type': 'string'}, 'fragment_ids': {'items': {'minimum': 1, 'type': 'integer'}, 'type': ['array', 'null'], 'uniqueItems': True}, 'geometry': {'type': ['object', 'null']}, 'notes': {'type': ['string', 'null']}, 'retrieved_utc': {'format': 'date-time', 'type': 'string'}, 'schema_version': {'const': 'femic.disturbance.v1'}, 'severity_basis': {'minLength': 1, 'type': ['string', 'null']}, 'severity_class': {'enum': ['high', 'low', 'moderate', 'unknown', 'very_high'], 'type': 'string'}, 'severity_value': {'maximum': 1, 'minimum': 0, 'type': ['number', 'null']}, 'source_id': {'minLength': 1, 'type': 'string'}, 'source_version': {'minLength': 1, 'type': 'string'}, 'year': {'maximum': 2300, 'minimum': 1900, 'type': 'integer'}}, 'required': ['schema_version', 'event_id', 'event_type', 'year', 'severity_class', 'confidence', 'attribution', 'source_id', 'source_version', 'retrieved_utc'], 'title': 'FEMIC disturbance.v1 event', 'type': 'object'}
JSON Schema for one
femic.disturbance.v1event. Calldisturbance_schema()for a defensive copy.
- exception femic.contracts.disturbance.DisturbanceContractError[source]
Bases:
ValueErrorRaised when an event or table violates
femic.disturbance.v1.
- class femic.contracts.disturbance.DisturbanceEvent(event_id, event_type, year, severity_class, confidence, attribution, source_id, source_version, retrieved_utc, severity_value=None, severity_basis=None, attribution_method=None, geometry=None, fragment_ids=(), block_ids=(), area_ha=None, notes=None, schema_version='femic.disturbance.v1')[source]
Bases:
objectOne validated
femic.disturbance.v1event.- Parameters:
event_id (str)
event_type (str)
year (int)
severity_class (str)
confidence (float)
attribution (str)
source_id (str)
source_version (str)
retrieved_utc (str)
severity_value (float | None)
severity_basis (str | None)
attribution_method (str | None)
geometry (dict[str, object] | None)
fragment_ids (tuple[int, ...])
block_ids (tuple[int, ...])
area_ha (float | None)
notes (str | None)
schema_version (str)
- event_id
Stable identifier, unique within a table.
- Type:
str
- event_type
One of
DISTURBANCE_TYPES.- Type:
str
- year
Calendar year the event began.
- Type:
int
- severity_class
One of
SEVERITY_CLASSES.- Type:
str
- confidence
Attribution or detection confidence in [0, 1].
- Type:
float
- attribution
Cause or attribution label (for example
wildfireordrought).- Type:
str
- source_id
Upstream source identifier.
- Type:
str
- source_version
Upstream source version.
- Type:
str
- retrieved_utc
Timezone-aware ISO-8601 retrieval timestamp.
- Type:
str
- severity_value
Optional continuous severity in [0, 1]. Requires
severity_basis.- Type:
float | None, optional
- severity_basis
What the continuous severity measures (for example
dNBR).- Type:
str | None, optional
- attribution_method
Method or product used for attribution.
- Type:
str | None, optional
- geometry
Shallow-validated GeoJSON geometry.
- Type:
dict[str, object] | None, optional
- fragment_ids
Positive fragment ids touched by the event.
- Type:
tuple[int, …], optional
- block_ids
Positive block ids touched by the event.
- Type:
tuple[int, …], optional
- area_ha
Event area in hectares.
- Type:
float | None, optional
- notes
Optional free-text note.
- Type:
str | None, optional
- schema_version
Contract version. Defaults to
DISTURBANCE_SCHEMA_VERSION.- Type:
str, optional
- classmethod from_dict(event)[source]
Validate and construct an event from a mapping.
- Parameters:
event (mapping[str, object]) – Candidate event.
- Returns:
The validated event.
- Return type:
- Raises:
DisturbanceContractError – If the event violates
femic.disturbance.v1.
- to_consumer_row()[source]
Return the minimal ws4-facing row for this event.
- Returns:
A flat row with the event identity, year, type, severity, confidence, spatial ids, area, and source. It is deliberately smaller than the full record so a consumer does not need the contract package to report an event.
- Return type:
dict[str, object]
- femic.contracts.disturbance.consumer_rows(events)[source]
Return ws4-facing rows for a sequence of events.
- Parameters:
events (sequence[DisturbanceEvent]) – Validated events.
- Returns:
Flat rows from
DisturbanceEvent.to_consumer_row(), in input order.- Return type:
list[dict[str, object]]
- femic.contracts.disturbance.disturbance_schema()[source]
Return a defensive copy of the
femic.disturbance.v1JSON Schema.- Returns:
A copy of the schema document, safe for a caller to mutate.
- Return type:
dict[str, object]
- femic.contracts.disturbance.events_for_block(events, block_id)[source]
Return events that name a block, optionally through fragment ids.
- Parameters:
events (sequence[DisturbanceEvent]) – Validated events.
block_id (int) – Block id to select.
- Returns:
Events whose
block_idscontainsblock_id. This is a direct selection only; fragment-to-block resolution belongs to the consumer.- Return type:
tuple[DisturbanceEvent, …]
- femic.contracts.disturbance.read_disturbance_table(path)[source]
Read and validate a disturbance table from JSON.
- Parameters:
path (pathlib.Path) –
.jsonfile containing a list of events or an object with aneventslist.- Returns:
The validated events in file order.
- Return type:
tuple[DisturbanceEvent, …]
- Raises:
DisturbanceContractError – If the suffix is unsupported, the file is empty, a record is invalid, or two events share an id.
- femic.contracts.disturbance.summarize_disturbance_table(events)[source]
Return a provenance-bearing summary of a disturbance table.
- Parameters:
events (sequence[DisturbanceEvent]) – Validated events.
- Returns:
Counts, event types, severity classes, year range, total area, sources, attribution labels, confidence range, and spatial-reference counts.
- Return type:
dict[str, object]
- Raises:
DisturbanceContractError – If the table is empty or an event is invalid.
- femic.contracts.disturbance.validate_disturbance_event(event)[source]
Validate one event against
femic.disturbance.v1.- Parameters:
event (mapping[str, object]) – Candidate event.
- Raises:
DisturbanceContractError – If the event is not a mapping, has unknown or missing fields, carries an unsupported type or severity class, has an out-of-range year or probability, has no spatial reference, or has an invalid geometry, timestamp, or id list.
- Return type:
None
- femic.contracts.disturbance.write_disturbance_table(path, events)[source]
Write a validated disturbance table to JSON.
- Parameters:
path (pathlib.Path) – Destination
.jsonpath.events (sequence[DisturbanceEvent]) – Events to write. Each is validated before writing.
- Raises:
DisturbanceContractError – If the suffix is unsupported, the table is empty, an event is invalid, or two events share an id.
- Return type:
None