Documents · Verb reference

local_synchrony_pairs

Measure bounded canonical cold/warm/Delta pair synchrony.

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

Usage

from cubedynamics import verbs as v
v.local_synchrony_pairs(*, lower_var=None, upper_var=None, output_mask=None, computation_mask=None, max_radius_km=100.0, window_days=90, window_end=None, min_t=10, split_quantile=0.5, time_dim='time', pair_batch_size=16384, distance_sampling=None, sampling_seed=0)

Arguments

Argument	Meaning	Default
lower_var	Variable used for lower-tail synchrony, normally daily TMIN.	None
upper_var	Variable used for upper-tail synchrony, normally daily TMAX.	None
output_mask	Spatial Boolean mask of focal cells that should receive output.	None
computation_mask	Spatial Boolean mask of cells eligible as either pair endpoint. It must contain every output cell and normally includes the full spatial halo.	None
max_radius_km	Maximum physical search/observation support. This is not an inferred characteristic synchrony distance.	100.0
window_days	Length of the bounded trailing analysis window in coordinate days.	90
window_end	Inclusive window end; defaults to the latest time coordinate.	None
min_t	Minimum jointly selected tail observations required for Spearman synchrony.	10
split_quantile	Per-series tail split. The current climate workflow uses 0.5.	0.5
time_dim	Name of the temporal dimension.	'time'
pair_batch_size	Number of canonical pairs evaluated per temporal-kernel batch.	16384
distance_sampling	Experimental distance-stratified pair-sampling plan. None retains all eligible pairs.	None
sampling_seed	Deterministic seed used only when distance sampling is requested.	0

Accepts

A daily latitude/longitude climate Dataset containing the selected lower- and upper-tail variables, an optional focal output mask, and an optional computation mask for eligible pair endpoints.

Returns

A bounded sparse relationship Dataset with one canonical undirected pair, cold and warm tail-Spearman values, pairwise Delta, signed displacement, distance, bearing, and joint-tail counts.

Order / grammar behavior

Measure pairs once, then branch to local_synchrony_surface, synchrony_signature, empirical_synchrony_range, empirical_synchrony_decay, or landscape_change_signature. Supply the output tile plus its full observation-radius climate halo. The output mask must be a subset of the computation mask; use the latter to exclude ocean or nodata cells without dropping eligible border neighbors.

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()
print(pairs[["cold_synchrony", "warm_synchrony", "delta_s"]])

Works with