Documents · Verb reference

overlap

Return a verb that finds coincident truth in two aligned state cubes.

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

Usage

from cubedynamics import verbs as v
v.overlap(other, *, left_variable=None, right_variable=None, name='overlap', temporal_alignment=None)

Arguments

Argument	Meaning	Default
other	The second aligned boolean or state cube.	required
left_variable	Variables to select from Dataset inputs. If omitted, state is used when present; otherwise a single-variable Dataset is accepted.	None
right_variable	Variables to select from Dataset inputs. If omitted, state is used when present; otherwise a single-variable Dataset is accepted.	None
name	Name for the returned condition Dataset.	'overlap'
temporal_alignment	Explicit temporal-support policy. Known, different supports require a choice. "labels" pairs unchanged labels and records the caveat; "require_exact_support" rejects different or unknown support.	None

Accepts

Two already aligned condition DataArrays or Datasets. Coordinates must match exactly. Known different observation supports require temporal_alignment='labels' or 'require_exact_support'; no reprojection, resampling, shift, or scientific harmonization is inferred.

Returns

A condition Dataset containing only Boolean state. The state variable is true only where both inputs are true; operand identity and exact-alignment metadata remain inspectable. Overlap does not invent a magnitude or threshold.

Order / grammar behavior

Define and align both conditions before overlap. Reduce the returned state variable when the intended result is a frequency or prevalence summary.

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"

cold = (pipe(cube) | v.threshold_state(threshold=0, direction="below")).unwrap()
unusual = (pipe(cube) | v.quantile_state(quantile=0.2, direction="below")).unwrap()
result = (pipe(cold) | v.overlap(unusual) | v.mean(dim="time", keep_dim=False)).unwrap()
# overlap returns a state Dataset; mean turns state into a proportion summary.
result["state"].plot(cbar_kwargs={"label": "Fraction of observed days"})
plt.show()

Works with