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.

  • DisturbanceEvent Typed event with canonical to_dict, from_dict, and to_consumer_row.

  • read_disturbance_table() Read and validate a JSON table, an events object, 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.v1 event. Call disturbance_schema() for a defensive copy.

exception femic.contracts.disturbance.DisturbanceContractError[source]

Bases: ValueError

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

One validated femic.disturbance.v1 event.

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 wildfire or drought).

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:

DisturbanceEvent

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]

to_dict()[source]

Return the canonical dict form, including null optional fields.

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.v1 JSON 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_ids contains block_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) – .json file containing a list of events or an object with an events list.

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 .json path.

  • 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