consensus

consensus(
    result,
    group_col,
    *,
    reference=None,
    alpha=0.05,
    age_col='age',
    min_generations=2,
    clocks=None,
    design='independent',
    subject_col=None,
)

Does a group difference hold up across clocks, or is it one clock?

Implements the decision rule from When to Trust Epigenetic Clocks (PMC11526921). Re-analysing six intervention datasets, the authors found that in five of them exactly one clock reached significance – a first-generation clock every time – and four of those five lost it under multiple-testing correction. In no case did the principal-component version of the same clock corroborate the finding. Their conclusion, stated plainly: a single significant clock after an intervention is likely a false positive.

So this runs every scored clock, corrects across the whole set actually tested, and returns a verdict rather than a table of p-values to pick from:

supported Significant after Bonferroni, across at least min_generations generations, including at least one outcome-trained clock (second generation, pace, or causal). unsupported One clock, or first-generation clocks only, or nothing surviving correction. inconclusive Something in between – most often several clocks at BH but not at Bonferroni.

Each clock is tested on its acceleration residual where that is a legal operation for its scale, and on the raw score where it is not. A pace of aging has no residual to take, and taking one anyway is the units error LEGAL_OPS exists to prevent.

The corroboration column, and when it is empty. high_reliability_partner names each clock’s principal-component version and partner_corroborates says whether that version agreed, which is the paper’s sharpest single diagnostic. It is None when the partner was not scored, and on a default install that is every one of them: the PC clocks are licensed, since the authors’ data file carries no licence and is not ours to ship. why says so explicitly rather than omitting the clause, because a verdict that silently drops its strongest check reads like one that passed it. fa.registry.load().import_pc_clocks(path) registers five of them from the authors’ CalcAllPCClocks.RData and turns it on.

Repeated measures. design says how the samples relate:

"independent" Two groups of different people; Welch’s t-test. "paired" group_col holds two visits and subject_col the person; each person’s change is tested with a paired t-test. A person needs one sample at each visit. "mixed" group_col holds two or more visits: y ~ visit + (1 | person), fitted by REML as nlme’s lme does (:mod:falconage.analysis.mixed), with Wald t or F on nlme’s containment degrees of freedom. A person with a missed visit still contributes. With more than two visits the test is the joint one over every visit contrast, and each contrast is reported.

Both repeated designs add mdc95, the minimum detectable change, :math:1.96\sqrt{2}\,SEM with the SEM the within-person SD across these visits (Weir 2005, doi:10.1519/15184.1), and below_mdc: a group mean can move significantly by less than any one person can be shown to have moved, and why says how many significant clocks did. That SEM carries day-to-day biology and assay noise together; :func:technical_se gives the assay part alone, and :func:variance_components separates the two when the design has technical replicates.