probe_loss

probe_loss(data, clocks='all', *, registry=None, top=3)

What each clock has lost on this dataset, before scoring anything.

One row per clock: how many of its features are present, and – for the clocks whose coefficients are available – how much of the model’s total weight those present features carry, plus the heaviest probes that are missing.

WHY BOTH NUMBERS. A count treats every probe as interchangeable and an elastic-net’s weights are nothing like uniform, so “92% of probes present” covers both “the 8% missing are negligible” and “the 8% missing carry a third of the model”. EPIC v2 dropped probes that several first-generation clocks lean on, which is why those clocks shift on v2 arrays while the principal-component versions barely move (Life Science Alliance 2025;8:e202403155) – the same probe loss, very different consequences.

Run this before score, on an array you have not used before. It costs one alignment per clock and answers “will this dataset support these clocks” without producing a number anyone can quote.

Parameters

Name	Type	Description	Default
clocks	str | list[str]	"all", "scoreable" for the ones whose coefficients are available, or an explicit list.	'all'
top	int	How many of the heaviest absent features to name per clock.	3

Returns

Name	Type	Description
	One row per clock, worst mass coverage first. mass_coverage is NaN
	for a clock whose coefficients are not available – the weights are what
	the column is computed from, so there is no honest value without them.
	n_removed_by_qc and qc_removed_mass count the clock CpGs the array
	carries but this data lacks, which were removed after measurement; they
	need the platform's manifest in the cache (fetch_manifest(platform))
	and are empty without it.