Python reference

Reading data

Every reader returns the same container, so nothing downstream can tell which format the data arrived in.

read	Dispatch on the filename. Convenience, not magic – it says what it chose.
read_betas	Read a beta matrix from CSV, TSV or parquet.
read_series_matrix	Read a GEO *_series_matrix.txt.gz: metadata and betas in one file.
read_clinical	Read a clinical chemistry table.
read_rrbs_dir	Assemble several RRBS files into one matrix on their shared sites.
read_bedmethyl	One nanopore bedMethyl file as a per-site methylation fraction.
read_bedmethyl_dir	Several bedMethyl files as one matrix on their shared sites.
read_panel	A targeted assay: pyrosequencing, EpiTYPER, amplicon, ddPCR.
read_computage_bench	One ComputAgeBench study, ready to score.
list_computage_bench	What is in the benchmark: one row per study.
preprocess.read_olink	An Olink NPX matrix: samples x proteins, values already log2.
preprocess.read_somascan	A SomaScan RFU matrix.
preprocess.read_counts	A bulk RNA-seq count matrix.
read_nightingale	Read a Nightingale Health NMR export (CSV, TSV or Excel) for MetaboAge and
FalconData	A scoreable dataset.

Raw arrays

IDAT to scoreable betas, which at first meant leaving FALCONAge for sesame or minfi and coming back. The manifest is fetched from Illumina’s public bucket and cached; it is the one step here that is not offline. Detection is computed before background correction, because pOOBAH’s null is the uncorrected out-of-band signal.

idat_to_betas	One Grn/Red IDAT pair to a beta vector, through the full chain.
read_idat_dir	Every Grn/Red pair in a directory, as one scoreable matrix.
preprocess.poobah	Detection p-values against the out-of-band background (Zhou 2018).
preprocess.noob	Normal-exponential background correction using the out-of-band signal.
preprocess.dye_bias	Equalise the two colour channels. Off by default – see the warning.
preprocess.bmiq	BMIQ: put type II probes on the type I scale.
preprocess.RawSignal	One sample’s in-band and out-of-band intensities, probe by probe.
preprocess.load_manifest	Address-to-probe mapping for one platform, indexed by probe id.
preprocess.manifest_record	What the run manifest records about the mapping that produced a beta.
preprocess.load_mask	The published mask for one platform, indexed by probe.
preprocess.mask_report	What applying this mask would cost each clock.
preprocess.apply_mask	Set masked probes to NaN. Not called anywhere automatically.

Preprocessing

Getting a matrix into the shape every clock assumes: bare probe identifiers, values in the beta range, a known platform. The EPIC v2 step is mandatory rather than optional – without it a v2 dataset overlaps almost nothing and the clocks score imputed values.

prepare	The standard chain: harmonise ids, collapse v2 replicates, clip, identify.
prepare_clinical	Rename to canonical markers and convert to the units the models expect.
qc	Look at the data before scoring it.
probe_loss	What each clock has lost on this dataset, before scoring anything.
preprocess.aggregate_replicate_probes	Strip EPIC v2 probe suffixes and collapse the replicates.
preprocess.impute	Dataset-level imputation, applied before any clock sees the matrix.
fit_batch_reference	Fit the frozen global parameters on a reference cohort.
apply_batch_reference	Correct a dataset against frozen parameters, one batch at a time.
preprocess.BatchReference	Frozen global parameters. The artefact that makes results stable.
preprocess.prepare_proteomic	Put a proteomic matrix on the scale a clock’s coefficients expect.
preprocess.prepare_transcriptomic	Run the whole chain, in order, recording each step.
preprocess.rle_normalise	Median-of-ratios size factors (DESeq’s RLE).
preprocess.yugene	The YuGene cumulative-proportion transform, per sample.
preprocess.median_centre	Subtract each gene’s median across the samples given.
preprocess.horvath_normalise	Calibrate each sample to Horvath’s gold standard (opt-in).

Uncertainty

How much of a score is the assay, and how far it is likely to be from the truth. Two different questions with two different answers, kept apart on purpose: technical replicates of the same DNA differ by up to nine years on prominent clocks, and a point estimate says nothing about either.

technical_se	Standard error on each score attributable to assay measurement noise.
interval	Score, lower and upper bound, long form.
conformal_interval	How far the prediction is likely to be from chronological age.
icc_from_replicates	Per-probe ICC(1,1) computed from the user’s own technical replicates.
uncertainty.load_probe_icc	Per-probe test-retest ICC, indexed by feature id.
uncertainty.probe_icc_source	Provenance of the bundled table, for the run manifest.
uncertainty.load_conformal	Calibrated prediction-interval half-widths, one row per clock and level.

Study design

The commands that come before the first array and after the last one. How many samples an effect needs, given the clock’s own reliability; and whether a difference that turned up survives the multi-clock rule that a re-analysis of six intervention datasets says it must.

power	How many samples to see an effect of this size on this clock.
detectable_effect	The smallest effect a given n can see. The inverse of :func:power.
consensus	Does a group difference hold up across clocks, or is it one clock?
registry.evidence	What a score on this clock has been shown to predict, and how strongly.

Scoring

The predict loop, its result object, and the provenance it carries.

score	The scoring loop and its result object.
combine	Stack per-dataset results into one, for a benchmark across studies.
FalconResult	Scores plus everything needed to say where they came from.

The clock catalogue

178 clocks in three availability groups: 69 bundled, 52 untraced and 57 licensed scaffolds whose coefficients are research-use-only or have no public source FALCONAge may redistribute. The registry says which, why, and which bundled clocks answer the same question.

registry.load	Load the packaged registry. Cached for the life of the process.
registry.ClockRegistry	Loaded catalogue. Immutable except for user-registered local weights.
registry.Clock	One registry entry.
registry.register_local_weights	Supply a coefficient file for a clock FALCONAge does not distribute.

Analysis

Age acceleration in its three conventions, association and survival models, reliability, and the AA1/AA2 benchmark. Each is gated on the clock’s scale type – acceleration on a pace-of-aging clock is a units error, not a conservative choice.

acceleration	Age acceleration, in whichever convention you mean.
cell_composition	Cell-type proportions estimated in this same run, as a covariate frame.
associate	Ordinary least squares of each clock on an outcome, adjusted for covariates.
cox_hazard	Univariable Cox hazard ratio per clock, by Breslow-tied partial likelihood.
agreement	Between-clock correlation.
icc	ICC(2,1): two-way random effects, absolute agreement, single measure.
run_benchmark	The AA1 and AA2 tests, and the score that combines them.
leave_one_marker_out	Recompute a clinical clock without each marker in turn, and say what moved.
fit_clock	Fit an elastic net to predict obs[target], judged out of fold.

Clinical references

KDM and homeostatic dysregulation have no fixed coefficients: both are defined relative to a reference cohort, and the manifest records which.

models.fit_kdm	Fit the KDM reference regressions, as BioAge’s kdm_calc does.
models.fit_hd	Estimate the healthy reference centre and covariance.
models.clinical.phenoage	Clinical Phenotypic Age in years.
blood_count_ratios	NLR, PLR, LMR and SII from a complete blood count.

Model architectures

Not every clock is a dot product. Six summarise a probe set with a mean or a percentile; the principal-component and neural families need a weight file no licence permits redistributing; scAge asks a different question entirely, one age per cell from a methylome that is 99% missing. All of these are implemented and tested against synthetic weights, and all of them work the day a user supplies a file.

models.AggregationClock	postprocess(statistic(X[features])).
models.NeuralClock	A feed-forward network over a fixed probe set.
models.read_neural_weights	Load layer weights from a .safetensors file.
models.PCLinearClock	postprocess(((x - centre) @ rotation) @ pc_coefficients).
models.read_rotation	Load a rotation from .npz.
models.ScAgeReference	Per-CpG linear models of bulk methylation on age.
models.fit_scage_reference	Fit the per-CpG age models on a bulk reference cohort.
models.scage	An age per cell, by profile likelihood over a grid of candidate ages.

Figures and reports

Every plot returns its data as well as its figure, which is how the two languages draw the same numbers with different engines. clock_atlas is the exception in scale rather than in kind: one figure covering every clock across every pooled study, for the case where a per-clock panel would need forty of them.

plot.ba_vs_ca	Predicted against chronological age, with the identity line.
plot.bland_altman	Difference against mean, with bias and 95% limits of agreement.
plot.calibration	Residual against chronological age.
plot.acceleration_density	Histogram of acceleration, optionally split by group.
plot.acceleration_by_group	Box and strip of acceleration by group – the case/control workhorse.
plot.acceleration_heatmap	Clocks by samples, z-scored within clock.
plot.forest	Effect size and 95% interval per clock/dataset comparison.
plot.kaplan_meier	Survival of the fastest-ageing tail against the slowest.
plot.volcano	Effect size against evidence, for a table from :func:~falconage.associate.
plot.clock_corr	Correlation heatmap, hierarchically ordered.
plot.clock_radar	Closed-polygon profile across clocks, one polygon per group.
plot.clock_chord	Circos-style chord diagram of CpG sharing between clocks.
plot.clock_pca	Samples embedded in clock space.
plot.clock_atlas	One figure comparing every clock across every pooled study.
plot.coverage_bar	Per-clock feature coverage. The plot to read before the scores.
plot.missingness	Distribution of per-sample missingness.
plot.beta_density	Per-sample beta distribution.
plot.platform_comparison	Score distribution split by array platform.
plot.study_comparison	Score distribution split by study.
plot.benchmark_bars	AA2 and AA1 counts per clock, ordered by the combined total.
plot.benchmark_error_bias	MedAE against MedE, sized by the benchmark total.
plot.benchmark_heatmap	Effect size per clock and dataset, with significant cells outlined.
plot.reliability_forest	Technical standard error per clock, with the ICC that cohort implies.
plot.score_interval	One clock’s scores with their intervals, sample by sample.
plot.platform_bias	What probe loss costs each clock, in years, on each platform.
plot.consensus_plot	The multi-clock verdict, drawn.
plot.palette
plot.save_all	Render every figure this result can support and write it as PNG.
report.write_report	Render one self-contained HTML file for a scoring run.
report.run_report	Write every deliverable of one run into outdir.
report.write_quarto_report	Write falconage_report.qmd into a run’s output directory; render it if asked.

Downloading public data

Accession in, files and a normalised sample table out. Credentialed archives are documented rather than automated – the access agreement is the user’s, not the tool’s.

download	Fetch public data from an accession.
download.cache_info
download.clear_cache	Delete the download cache. Returns the bytes freed.

Configuration and setup

What resolved, on this machine, in this environment.

config	What this installation resolved to: versions, devices, registry size.
configure	Set the console verbosity. None reads FALCONAGE_VERBOSE.
core.resolve	Pick a device and dtype, and say no clearly when the request is impossible.
core.describe	What this machine can actually do. Backs falconage config.
FalconConfig
RunManifest	Provenance for one scoring run.