score

score

The scoring loop and its result object.

Classes

Name	Description
FalconResult	Scores plus everything needed to say where they came from.

FalconResult

score.FalconResult(
    scores,
    obs,
    manifest,
    registry,
    coverage=dict(),
    skipped=dict(),
    se=None,
)

Scores plus everything needed to say where they came from.

scores is samples x clocks. Everything else – coverage, warnings, weight digests, the resolved config – hangs off the manifest, so a result written to disk and read back is self-describing.

Methods

Name	Description
evidence	Published effect sizes for the clocks in this result.
interpretation	One row per clock: what the number is, and what may be done with it.
long	One row per sample per clock, with the scale and provenance attached.

evidence

score.FalconResult.evidence(clock=None)

Published effect sizes for the clocks in this result.

The step between a number and something a reader can act on. See :func:falconage.registry.evidence; every row carries its DOI.

interpretation

score.FalconResult.interpretation()

One row per clock: what the number is, and what may be done with it.

Everything needed to read a score, in the object holding the score. Scale and unit say what the quantity is; legal_operations says which arithmetic the package will perform on it; reliability says how much of a within-person change is likely to be the assay; caveats carries any documented disagreement between the clock’s paper and the coefficients that circulate for it.

long

score.FalconResult.long()

One row per sample per clock, with the scale and provenance attached.

The scale column is not decoration: it is what stops a reader averaging a mortality log-hazard with an age in years because both were numbers in a column called value.

Functions

Name	Description
combine	Stack per-dataset results into one, for a benchmark across studies.
score	Score a dataset against one or more clocks.

combine

score.combine(results, *, keys=None, dataset_col='dataset')

Stack per-dataset results into one, for a benchmark across studies.

Datasets are scored separately and combined afterwards, never merged before scoring. Two reasons, and the second is the one that bites:

• a 27K study and an EPIC study have different probe spaces, and the outer join of ten of them is a mostly-NaN matrix that no clock should see;
• feature coverage is a property of a dataset. Merged, a clock that covers 99% of one study and 40% of another reports a single meaningless average, and the AA2 test silently compares cases in the well-covered study against controls in the badly-covered one.

Per-clock coverage is kept per dataset in uns and the manifests are merged, so a combined result still says which study contributed what.

score

score.score(
    data,
    clocks='compatible',
    *,
    device='auto',
    dtype=None,
    imputation='reference',
    min_coverage=0.8,
    reference=None,
    registry=None,
    caller='python',
)

Score a dataset against one or more clocks.

Parameters

Name	Type	Description	Default
clocks	str | Sequence[str]	"compatible" scores everything this dataset can support and reports the rest as skipped with a reason. "all" attempts every clock of the right modality and fails loudly on the ones that cannot run. A list names them explicitly, and every name in it must work – an explicit request is never silently dropped.	'compatible'
imputation	str	Passed to the per-clock feature alignment. See :func:falconage.models.linear.align; the short version is that zero is never a fill value. The mitotic mean, percentile and transmission clocks ignore it: their published statistic is taken over the features present, so absent ones are left out and the coverage record reads "excluded".	'reference'
min_coverage	float	The fraction of a clock’s features that must be present. Below it, the clock is skipped (clocks="compatible") or raises (explicit list).	0.8
reference		A fitted :class:~falconage.models.clinical.KDMReference or :class:~falconage.models.clinical.HDReference, for the two clinical clocks that have no fixed coefficients.	None

Returns

Name	Type	Description
	FalconResult	Scores, per-clock coverage, and a manifest recording the device, the dtype, every coefficient digest and every warning.