acceleration

acceleration(
    result,
    *,
    age_col='age',
    method='residual',
    group=None,
    clocks=None,
    adjust=None,
    reference=None,
    match=('age', 'sex'),
)

Age acceleration, in whichever convention you mean.

Parameters

Name	Type	Description	Default
adjust	str \| Sequence[str] \| None	Extra covariates to regress out alongside chronological age. `"cell_composition"` Use the deconvolution clocks scored in this same run. An acceleration adjusted this way answers “is this person’s blood aging faster”, where the unadjusted version answers “is this person’s blood aging faster or is its cell mix different”, and reports both as one number. a sequence of column names Columns of `result.obs`, for measured counts or anything else. Only available with `method="residual"`: the absolute convention has no regression to add terms to, and `within_group` fits per stratum where a composition term would usually be rank-deficient.	`None`
method	str	`"absolute"` `predicted - chronological`. Interpretable in years, and confounded by the clock’s own bias: a clock that over-predicts everyone by three years gives everyone three years of acceleration. `"residual"` The residual from regressing predicted on chronological age. Centred at zero by construction, which removes that bias and also removes any real cohort-wide effect. The field’s default. `"both"` Absolute and residual side by side, two columns per clock named `<clock>_absolute` and `<clock>_residual`. Suffixed rather than stacked, because the two disagree by several years and a reader who cannot tell which column is which is worse off than with one. `"within_group"` Residual from a regression fitted separately within each level of `group`. What the AA2 benchmark needs: it asks whether cases accelerate relative to their own controls, not relative to a line fitted through both. `"reference"` Residual from a line fitted in another population, `reference`, and applied unchanged to this one: `score - (a + b * age)` with `a` and `b` estimated on the reference only, separately within each level of the categorical `match` columns. It answers “how does this person compare with people of the same age and sex in the reference”, which the within-cohort residual cannot, because that residual is centred on this cohort and so absorbs any effect the whole cohort shares.	`'residual'`
reference		For `method="reference"`: a scored :class:`~falconage.score.FalconResult` for the reference population, scored with the same fitted model (for KDM, the same fitted :class:`~falconage.models.clinical.KDMReference` passed to :func:`~falconage.score.score` for both). It must carry every clock asked for and every `match` column in its `obs`.	`None`
match	Sequence[str]	For `method="reference"`: the `obs` columns the comparison is matched on. `age_col` must be one of them; it is the regressor. Every other entry (usually `"sex"`) is categorical, and the line is fitted separately within each of its levels. Levels are compared as text, ignoring case and a trailing `.0`, so `"F"` matches `"f"` but not `"female"` or `2`: recode one side first.	`('age', 'sex')`

Raises

Name	Type	Description
	IllegalOperationError	When a clock’s scale does not admit the convention asked for. `"absolute"`, `"both"` and `"reference"` need the scale to admit `acceleration`, because each compares this cohort’s scores with a zero point set somewhere else.
	AnalysisError	With `method="reference"`: no reference given, a clock or a `match` column absent from it, a level of a `match` column in this result that the reference lacks, fewer than three usable reference samples in a stratum, or a study age outside the ages the reference covers in that stratum (the range is reported; the line is never extrapolated).

Notes

Which one a paper used is often not stated, and they disagree by several years on the same data. The convention is recorded in the returned frame’s method attribute so a downstream reader does not have to guess.

WHY A REFERENCE POPULATION. A clock fitted by regression regresses toward the mean age of its training population: it over-predicts the young and under-predicts the old, and a KDM projected from a reference inherits the same pull. In an older cohort predicted - chronological is then negative for most people whatever their health, and the within-cohort residual removes that bias only by centring the cohort on itself. Brain-age work documents the same bias (Smith et al. 2019, NeuroImage 200:528-539, doi:10.1016/j.neuroimage.2019.06.017) and corrects it with a regression of the prediction on age whose parameters can be estimated in a training or reference sample and applied unchanged to new data (de Lange and Cole 2020, NeuroImage: Clinical 26:102229, doi:10.1016/j.nicl.2020.102229). "reference" is that regression, fitted in the reference and taken as a residual so that it is on the same footing as "residual" above.

With method="reference" the frame’s attrs["reference_fit"] lists, per clock and stratum, the reference sample size, its age range, the fitted intercept and slope and the residual SD, so the comparison can be audited without the reference in hand.