Relative timing of supported rhythms

cw.rhythm_pair_timing(reference, target, settings={}) reads two trace objects with hours, values, saved estimate and significance results, and explicit boolean detected and period_supported evidence flags. The caller must supply the original corrected detections; this action never runs or re-corrects a screen. It reports positive offsets when the target follows the reference.

Period uncertainty comes from the native 95% spectrum-resampling interval, or an asymptotic normal interval from FFT nonlinear least-squares component covariance. The latter remains conditional on the fitted model and its residual assumptions. Other estimators remain selectable for screening, but missing native uncertainty is an explicit timing refusal. A multi-component estimate additionally needs component_period_band: [lower, upper] to isolate one component. The selected significance peak's saved spectral bin must overlap the component's uncertainty interval. A significant peak elsewhere supplies no evidence for that component.

Both marginal uncertainty ranges must put the entire possible period difference inside the declared practical equivalence margin. Their joint coverage lower bound is recorded without assuming the traces independent. This is an explicit practical comparison rule, not proof of equal periods or a shared tissue clock. Only then is the mean of the comparable estimates used as the reporting period for a shared band-limited analytic phase. Neither trace is fitted at that period. The band must contain both uncertainty ranges and exclude other fitted components. Band phase zero refers to the isolated oscillation, not necessarily the maximum of a non-sinusoidal raw waveform.

Actual common timestamps are split into complete regular segments at missing values and gaps. No missing values are interpolated. Each sufficiently observed segment uses the existing public coupling core's analytic phase, edge trimming, cycle jackknife lag interval, and cycle-level drift model. Segments retain native diagnostics and original time coordinates. Multiple segments remain separate; no whole-record offset or continuity is inferred across a gap.

The default settings are:

{
  "phase_definition": "band_limited_analytic",
  "period_equivalence_fraction": 0.1,
  "phase_band_fraction": 0.25,
  "min_observations": 24,
  "min_cycles": 3,
  "edge_trim_cycles": 1.5,
  "confidence": 0.95,
  "stability_change_cycles": 0.1,
  "stability_scatter_cycles": 0.1,
  "label_tolerance_cycles": 0.08333333333333333
}

Fractions and temporal margins are configurable analysis choices. Their defaults are practical reporting tolerances, not biological constants. A segment is stable-within-margin only when the whole drift interval implies a total change inside the specified margin and its observed cycle residual scatter is small. An interval containing zero alone is insufficient. changing requires drift beyond the practical margin; intermediate evidence remains unresolved. These conditional cycle-jackknife approximations may retain dependence induced by filtering. The classification is descriptive interval containment, with no selection-adjusted p-value or test of mechanistic phase locking. Nonlinear timing variation remains visible in the complete timecourse and residual scatter.

Continuous offsets and intervals precede optional descriptive in-phase, half-cycle, and other-offset labels. These labels use the point estimate and recorded tolerance; their uncertainty remains visible and they are not hypothesis tests. Saved segments and timecourse tables accompany the full native result.

The analytic signal uses SciPy's Hilbert transform. Native spectrum resampling follows Costa et al.. The distinction between non-significance and containment within practical bounds is discussed by Lakens; the particular period and temporal rules above are documented Workbench choices.