Documents · Verb reference

stack_structure_diagnostics

Describe distance, direction, modality, and spatial group coherence.

Callable type: Grammar verb / pipe stage · Browse: Synchrony and comparison

Usage

from cubedynamics import verbs as v
v.stack_structure_diagnostics(*, metric='delta_s', distance_bin_edges_km=None, minimum_group_size=20)

Arguments

Argument	Meaning	Default
metric	See implementation docstring below; no parameter-specific description supplied.	'delta_s'
distance_bin_edges_km	See implementation docstring below; no parameter-specific description supplied.	None
minimum_group_size	See implementation docstring below; no parameter-specific description supplied.	20

Accepts

A Dataset produced by v.local_synchrony_stack(...) and one selected stack metric: cold_synchrony, warm_synchrony, or delta_s.

Returns

Distance-bin, direction-bin, residual-spread, three-bandwidth KDE-mode, deterministic two-group, and center-geography coherence diagnostics.

Order / grammar behavior

Build the unreduced stack first. KDE modes and forced two-group fields are experimental candidate screens, not climate-regime classifications; always inspect group membership on center geography.

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"

small = cube.isel(y=slice(0, 4), x=slice(0, 4))
temperature = xr.Dataset({"tmin": small, "tmax": small})
stack = (pipe(temperature) | v.local_synchrony_stack(lower_var="tmin", upper_var="tmax", window_days=14, min_t=3, center_y_indices=range(4), center_x_indices=range(4))).unwrap()
result = (pipe(stack) | v.stack_structure_diagnostics(metric="delta_s", distance_bin_edges_km=(0, 20, 40, 80), minimum_group_size=3)).unwrap()
result["direction_eta_squared"].plot(cbar_kwargs={"label": "Directional eta squared"})
plt.show()

Works with