Timing agreement within and across samples

cw.rhythm_timing_summary(records, independent_units=False, settings={}) consumes the complete saved results of rhythm_pair_timing. Each record contains exactly id, unit, reference, target, and timing. The identifier names a unique cell; recordings from one biological sample share the same unit. One call compares one ordered measurement pair. Reversing only some references is an input error.

The operation preserves three distinct findings: temporal behaviour within each cell, agreement between comparable cells in a sample, and repetition across independent biological samples. Missing, ambiguous and segment-specific offsets stay in the exclusion ledger. The phase definition and signed convention must match the supported native operation. Original period/component intervals are checked again across the proposed population before any circular conversion. Incompatible groups have no pooled angle. This practical native-interval rule does not prove exactly equal biological periods or confer simultaneous coverage on a collection of marginal confidence intervals.

Within each unit, eligible cell angles contribute equally to a descriptive mean vector. Its length measures observed concentration. Supplied phase intervals propagate through sine/cosine coordinate ranges to a conservative rectangle for that observed vector. This deterministic propagation is not an independent-cell confidence interval and has no newly invented coverage level. A rectangle that contains the origin has no identified mean direction. Opposing cell offsets do not become a precise zero-hour mean. One cell retains its own summary but cannot certify between-cell agreement. Original temporal classifications are counted separately, including changing and unresolved cells.

Across units, each eligible biological sample contributes one equally weighted within-sample mean vector. The vector is not normalized to unit length: doing so would erase dispersion among its cells. Many movies or cells from one sample cannot increase that sample's weight. Unknown independence allows descriptive output but no independent-sample interval. With enough independent samples, the existing Hoeffding bounded-mean operation supplies separate uncertainty bounds for the two coordinates, with Bonferroni allocation. Rectangle geometry supplies conservative concentration and direction bounds. A region containing the origin leaves the mean direction unresolved.

Sampling uncertainty concerns the mean observed eligible sample vectors, conditional on the supplied population and period comparability. It does not estimate latent phase measurement error or correct for rhythm selection. Propagated input phase uncertainty is retained separately and is never relabelled as a population confidence interval. A shared adaptive screening correction can couple sample inclusion; callers must set independent_units=False in that situation.

Settings default to:

{
  "confidence": 0.95,
  "period_equivalence_fraction": 0.1,
  "min_samples": 3,
  "concentration_threshold": 0.7
}

The fractions are configurable practical criteria, not biological constants. supported-concentration requires the sampling region's lower concentration bound to reach the declared threshold. Otherwise repetition remains unresolved, with its continuous estimate and bounds retained. The conservative interval may be broad for small samples. No Rayleigh test over pooled cells or shared tissue clock is inferred. Callers making several pair/stratum summaries can allocate confidence across that complete declared family before calling.

members retain requested, timing-eligible, summary-eligible, within-unit comparable and across-unit comparable outcomes. units retain original sample sizes, contributors, circular values, input-interval regions and temporal counts. population keeps separate requested, available and comparable denominators, descriptive results, sampling assumptions, coordinate intervals and unavailable reasons. Complete native results and the public run record remain available.