Documents · Verb reference

event_metrics

Summarize local events or regional episodes by calendar period.

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

Usage

from cubedynamics import verbs as v
v.event_metrics(*, period='year', metrics=('event_count', 'mean_duration', 'max_duration'), date_field='start')

Arguments

Argument	Meaning	Default
period	See implementation docstring below; no parameter-specific description supplied.	'year'
metrics	See implementation docstring below; no parameter-specific description supplied.	('event_count', 'mean_duration', 'max_duration')
date_field	See implementation docstring below; no parameter-specific description supplied.	'start'

Accepts

A local-cell or regional-episode EventResult and a bounded metric list.

Returns

An ordinary xarray Dataset grouped by year, month, or all events, with scope-aware counts and metric-level units.

Order / grammar behavior

Choose event scope before interpreting counts. Local event-days accumulate across cells; regional episode-days do not.

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.event_metrics(period="all", metrics=("event_count", "mean_duration", "max_duration"))).unwrap()
result[["event_count", "max_duration"]].to_dataframe().plot.bar()
plt.show()

Works with