Documents · Verb reference

adaptive_synchrony_experiment

Experimentally compare empirical first breaks with fixed synchrony.

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

Usage

from cubedynamics import verbs as v
v.adaptive_synchrony_experiment(*, discovery_radius_km=1000.0, fixed_radius_km=500.0, bin_width_km=25.0, min_annulus_count=30, smoothing_bins=3, common_rule='max', time_window_id=None)

Arguments

Argument	Meaning	Default
discovery_radius_km	See implementation docstring below; no parameter-specific description supplied.	1000.0
fixed_radius_km	See implementation docstring below; no parameter-specific description supplied.	500.0
bin_width_km	See implementation docstring below; no parameter-specific description supplied.	25.0
min_annulus_count	See implementation docstring below; no parameter-specific description supplied.	30
smoothing_bins	See implementation docstring below; no parameter-specific description supplied.	3
common_rule	See implementation docstring below; no parameter-specific description supplied.	'max'
time_window_id	See implementation docstring below; no parameter-specific description supplied.	None

Accepts

A sparse pair Dataset with physical-distance support larger than the fixed comparison radius; sampled tables must retain design inclusion probabilities.

Returns

Raw and smoothed annular evidence, independent cold/warm first-break estimates and statuses, a configurable common break, fixed/adaptive robust reductions, QC, direct differences, and Delta sign change.

Order / grammar behavior

Experimental only: the current real-data gate is HOLD. Validate the first-break estimator and far-field sampling on exhaustive focal pixels before any scale-up. The discovery domain is not R*, and unresolved or ambiguous breaks remain missing.

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.adaptive_synchrony_experiment(discovery_radius_km=30, fixed_radius_km=20, bin_width_km=5, min_annulus_count=2)).unwrap()
print(result[["cold_break_km", "warm_break_km", "common_break_km", "common_break_status"]])

Works with