Documents · Verb reference
empirical_synchrony_range
Diagnose whether finite empirical cold/warm ranges can be resolved.
Callable type: Grammar verb / pipe stage · Browse: Synchrony and comparison
Usage
from cubedynamics import verbs as v
v.empirical_synchrony_range(*, bin_width_km=20.0, min_annulus_count=30, background_shell_count=4, background_method='outer_annuli', persistence_bins=3, annular_abs_tolerance=0.03, cumulative_abs_tolerance=0.01, min_profile_range=0.04, censor_fraction=0.8, fixed_radius_km=100.0)
Arguments
| Argument | Meaning | Default |
|---|---|---|
| bin_width_km | Width of empirical physical-distance annuli. | 20.0 |
| min_annulus_count | Minimum finite pair relationships required to summarize an annulus. | 30 |
| background_shell_count | Number of outer supported annuli used by the robust background rules. | 4 |
| background_method | Selected empirical background: outer_annuli, smoothed_outer_annuli, or distant_pairs. | 'outer_annuli' |
| persistence_bins | Consecutive supported annuli required before declaring convergence. | 3 |
| annular_abs_tolerance | Minimum absolute tolerance around the empirical background. | 0.03 |
| cumulative_abs_tolerance | Maximum allowed change between successive cumulative medians. | 0.01 |
| min_profile_range | Smaller supported profile ranges are classified as flat/unidentified. | 0.04 |
| censor_fraction | Candidate ranges at or beyond this fraction of discovery support are reported as unresolved. | 0.8 |
| fixed_radius_km | Physical radius of the fixed-control reduction retained in the output. | 100.0 |
Accepts
A sparse pair Dataset produced by v.local_synchrony_pairs(...) with a discovery radius larger than the fixed control radius.
Returns
Annular and cumulative empirical responses, three distant-background candidates, cold/warm/common range estimates and statuses, the unchanged fixed-radius control, and same-neighbor range-based diagnostics.
Order / grammar behavior
Use this branch only to ask whether a finite convergence distance resolves. A discovery limit is not a range; unresolved or boundary-limited estimates remain missing, and R_common is not a generally validated adaptive radius.
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_range(bin_width_km=5, min_annulus_count=2, background_shell_count=2, persistence_bins=2, fixed_radius_km=20)).unwrap()
print(result[["cold_range_km", "warm_range_km", "common_range_km", "common_range_status"]])
Works with
A sparse pair Dataset produced by v.local_synchrony_pairs(...) with a discovery radius larger than the fixed control radius.
See also
Implementation notes
R_common is the maximum of cold and warm ranges only when both resolve.
The common-range Delta diagnostic uses the same neighbors for both tails.
Discovery support, range, and kernel weighting are distinct; this verb
applies no parametric kernel and no distance weights. An unresolved or
censored result is valid and must not be replaced by the discovery radius.
The verb does not establish a preferred adaptive-neighborhood rule.
Implementation source. Signatures and descriptions on this page are generated from this checkout, not hand-maintained copies.