Agreement between detected rhythms

detection_agreement compares already established binary detections. It does not fit rhythms. Each observation supplies a unique id, its shared biological sample unit, and first/second values of true, false, or null. Null means an unavailable test and remains separate from a valid negative result. Several movies from one sample must share its unit identifier.

The result retains every joint/missing category, marginal test denominators and fractions, and fractions restricted to jointly valid tests. It reports pooled cell agreement descriptively and Cohen's chance-corrected kappa within each unit. Constant margins cannot establish association and have no reported kappa. Neither-significant observations are valid negative test results; they are not proof of biological absence. See the kappa definition and original paper.

Set independent_units=True only for confirmed independent biological samples whose detection decisions also remain independent between samples. A shared adaptive multiple-testing correction can couple otherwise independent samples; the caller must retain that dependency and cannot certify independence merely from different animal identifiers. The summary gives equal weight to each eligible sample's observed kappa. With at least three nonconstant samples, a conservative Hoeffding interval describes the expectation of that bounded sample statistic. The interval permits arbitrary dependence between cells within a sample; it does not estimate latent true kappa or the fraction of biological rhythms. Constant-margin samples stay in the unit table, excluded from this conditional estimand. Small sample counts appropriately produce wide intervals. confidence applies to one interval; callers requiring simultaneous coverage must supply the adjusted confidence.

The default sample_method="none" performs no sample-level test. Explicit sample_method="spearman_permutation" compares one pair of fractions per independent sample, both on exactly that sample's jointly-tested cells. SciPy permutes sample pairings, enumerating all pairings when feasible, and returns a two-sided p-value. This tests independent, exchangeable pairings of the quantities, not the weaker hypothesis of zero rank correlation under arbitrary dependence. It needs at least three usable samples and variable fractions. The caller must declare the comparison family before adjusting these p-values. The SciPy permutation documentation describes this pairing convention; its Spearman guidance recommends permutation inference for small samples.

All settings, observations, counts and exclusions remain in the completed result and its reproducible public run record. Unconfirmed samples still receive descriptive results, with biological uncertainty and sample inference unavailable.