Documents · Verb reference

consolidate_events

Consolidate local-cell events into explicit regional episodes.

Callable type: Grammar verb / pipe stage · Browse: State and events

Usage

from cubedynamics import verbs as v
v.consolidate_events(*, spatial_relation='neighbors', max_gap='0D', radius_km=None, min_participating_cells=1, min_local_events=1)

Arguments

Argument	Meaning	Default
spatial_relation	See implementation docstring below; no parameter-specific description supplied.	'neighbors'
max_gap	See implementation docstring below; no parameter-specific description supplied.	'0D'
radius_km	See implementation docstring below; no parameter-specific description supplied.	None
min_participating_cells	See implementation docstring below; no parameter-specific description supplied.	1
min_local_events	See implementation docstring below; no parameter-specific description supplied.	1

Accepts

A local-cell EventResult plus explicit temporal-gap and spatial-connectivity criteria.

Returns

An EventResult with event_scope='regional_episode', episode summaries, source event IDs, and the complete consolidation rule.

Order / grammar behavior

Detect local events before consolidation. Matching dates alone never merge spatially unrelated rows.

Minimal example

Run from the repository root after python -m pip install -e '.[vignettes]'. Uses the checked observational PRISM fixture; no network is required.

from pathlib import Path
import xarray as xr
import matplotlib.pyplot as plt
from cubedynamics import pipe, verbs as v

# Frozen, reviewed PRISM observations; run from the repository root.
path = Path("tests/fixtures/real_data/prism_boulder_january_2024.nc")
with xr.open_dataset(path, engine="scipy") as observed:
    cube = observed["tmax"].load()
assert cube.attrs["units"] == "degC"

local = (pipe(cube) | v.threshold_state(threshold=0, direction="below") | v.detect_events(min_duration=2)).unwrap()
result = (pipe(local) | v.consolidate_events(spatial_relation="neighbors", max_gap="1D")).unwrap()
print(result.explain())
result.catalog.plot.scatter(x="start", y="participating_cell_count")
plt.show()

Works with