Disturbance events

Purpose

WS4 consumes the femic.disturbance.v1 event table as a read-only report. The loader accepts the flat consumer rows produced by FEMIC (or the full event records) and reports what happened, where, when, and how severe it was.

This page does not make disturbances part of the simulation. Applying events to growth, transitions, or the objective is a later phase.

Consumer row

The loader reads these fields:

Field

Type

Meaning

event_id

string

Stable event identifier, unique within the table.

event_type

string

fire, insect, disease, drought, wind, flood, partial_mortality, harvest, salvage, or other.

year

integer

Calendar year the event began, 1900-2300.

severity_class

string

low, moderate, high, very_high, or unknown.

confidence

number

Confidence in [0, 1].

source_id

string

Upstream source identifier.

severity_value

number or null

Optional continuous severity in [0, 1].

fragment_ids

array or null

FEMIC fragment ids.

block_ids

array or null

WS4 block ids.

area_ha

number or null

Event area in hectares.

A full femic.disturbance.v1 record is also accepted; fields WS4 does not need (geometry, attribution, notes, timestamps) are ignored. The file may be a JSON list, an object with an events list, or a single event object.

Command

ws4 disturbance --events data/disturbance/fire_2023.json
ws4 disturbance --events data/disturbance/fire_2023.json --json
ws4 disturbance --events data/disturbance/table.json --block-id 101

The text report lists each event’s id, year, type, severity, blocks, and area. --json emits a stable summary with:

  • event_count

  • event_types

  • severity_classes

  • year_min and year_max

  • total_area_ha

  • affected_blocks

  • affected_fragments

  • sources

  • confidence_min and confidence_max

Limits

  • The loader does not apply events to the compiled dataset or the model.

  • --block-id matches block_ids directly. Fragment-to-block resolution belongs to the caller.

  • Geometry is not validated; the FEMIC contract owns that shallow check.

  • The command does not write a run directory or modify a schedule.

Cross-references