Documents · Verb reference

empirical_synchrony_decay

Characterize empirical cold and warm synchrony decay.

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

Usage

from cubedynamics import verbs as v
v.empirical_synchrony_decay(*, discovery_radius_km=None, bin_width_km=20.0, min_annulus_count=30, background_shell_count=4, background_method='outer_annuli', local_shell_count=2, crossing_persistence_bins=2, min_local_excess=0.04, initial_window_km=100.0)

Arguments

Argument	Meaning	Default
discovery_radius_km	Physical support to analyze; defaults to all support in the pair table.	None
bin_width_km	Width of empirical annuli.	20.0
min_annulus_count	Minimum valid relationships required to support an annulus.	30
background_shell_count	Number of outer supported annuli used by empirical background rules.	4
background_method	outer_annuli, smoothed_outer_annuli, or distant_pairs.	'outer_annuli'
local_shell_count	Number of nearest supported annuli defining local synchrony.	2
crossing_persistence_bins	Consecutive supported annuli required for a fractional crossing.	2
min_local_excess	Minimum local synchrony above background required for decay metrics.	0.04
initial_window_km	Distance window used for the reported robust initial slope.	100.0

Accepts

A sparse pair Dataset produced by v.local_synchrony_pairs(...); saved pair checkpoints can be reused directly.

Returns

Annular median/IQR/count and cumulative curves; d25/d50/d75 fractional-decay coordinates; effective synchrony length; initial, near, middle, and far slopes; loss by 100 km; and valid cold-minus-warm contrasts.

Order / grammar behavior

Use after pair construction to ask how synchrony changes continuously with distance, not to select an adaptive radius. Keep fractional decay, effective length, slopes, and pairwise Delta_S scientifically distinct.

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"

with xr.open_dataset(path, engine="scipy") as observed:
    temperature = observed[["tmin", "tmax"]].isel(y=slice(0, 12), x=slice(0, 12)).load()
pairs = (pipe(temperature) | v.local_synchrony_pairs(lower_var="tmin", upper_var="tmax", max_radius_km=30, window_days=30, min_t=3)).unwrap()
result = (pipe(pairs) | v.empirical_synchrony_decay(bin_width_km=5, min_annulus_count=2, background_shell_count=2, min_local_excess=0.01, initial_window_km=20)).unwrap()
print(result[["cold_d50_km", "warm_d50_km", "cold_effective_length_km", "warm_beta_initial_per_100km"]])

Works with