Package index

Reading data

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

• read_betas()

  Read a beta matrix

• read_series_matrix()

  Read a GEO series matrix

• read_clinical()

  Read a clinical chemistry table

• read_rrbs_dir()

  Read RRBS coverage files

• falcon_data() print(<falcon_data>) summary(<falcon_data>) : Build a dataset from an R matrix or data frame
• obs() : Sample annotation
• write_h5ad() read_h5ad() : Write a dataset to the interchange format both languages read

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()

  Standard methylation preprocessing

• horvath_normalise()

  Horvath’s gold-standard normalisation

• qc() : Quality control before scoring

• probe_loss()

  What each clock has lost on this dataset, before scoring

• fit_batch_reference()

  Fit a frozen batch-correction reference

• apply_batch_reference()

  Apply a frozen batch-correction reference

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()

  Technical standard error on each score

• interval()

  Scores with their measurement interval

• conformal_interval()

  Distribution-free prediction intervals against chronological age

• icc_from_replicates()

  Per-probe reliability from your own technical replicates

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_n()

  How many samples to see an effect

• consensus()

  Does a group difference hold up across clocks?

Scoring

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

• score() print(<falcon_result>) summary(<falcon_result>) : Score a dataset against one or more clocks

• combine()

  Combine per-dataset results for a benchmark across studies

• coverage()

  Per-clock coverage and skip reasons

• manifest()

  The run manifest

• interpretation()

  How to read each score in a result

• write_results()

  Write the standard results layout

• as.data.frame(<falcon_result>)

  Scores as a data frame

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.

• list_clocks()

  List the clock catalogue

• clock_info()

  Everything the registry knows about one clock

• cite_clock()

  Cite a clock

• compatible_clocks()

  Which clocks this dataset can actually be scored on

• register_local_weights()

  Supply a coefficient file for a clock FALCONAge does not distribute

• import_pc_clocks()

  Register the PC clocks from the authors’ data file

• import_dunedinpace()

  Register DunedinPACE from the authors’ R package

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

• cell_composition()

  Cell-type proportions estimated in the same run

• associate()

  Associate clock scores with an outcome

• cox_hazard()

  Univariable Cox hazard ratio per clock

• agreement()

  Between-clock agreement

• icc() : Intraclass correlation, ICC(2,1)
• run_benchmark() print(<falcon_benchmark>) : The AA1 and AA2 benchmark

Clinical references

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

• fit_kdm()

  Fit a Klemera-Doubal reference

• fit_hd()

  Fit a homeostatic dysregulation reference

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

• plot_bland_altman()

  Bland-Altman agreement across the age range

• plot_calibration()

  Residual against chronological age

• plot_acceleration()

  Distribution of age acceleration

• plot_acceleration_by_group()

  Age acceleration by group

• plot_acceleration_heatmap()

  Age acceleration across clocks and samples

• plot_forest()

  Forest plot of benchmark effect sizes

• plot_agreement()

  Agreement between clocks

• plot_clock_radar()

  Multi-clock radar profile

• plot_clock_chord()

  Circos chord diagram of CpG sharing between clocks

• plot_clock_pca()

  Samples embedded in clock space

• plot_clock_atlas()

  Clock atlas: every algorithm across every pooled study

• plot_coverage()

  Per-clock feature coverage

• plot_by_platform() plot_by_study() : Score distribution by platform or by study

• plot_kaplan_meier()

  Survival by age acceleration

• plot_volcano()

  Volcano plot of association results

• plot_benchmark()

  AA2 and AA1 counts per clock

• plot_benchmark_error_bias()

  Error against bias on healthy controls

• plot_benchmark_heatmap()

  Effect size per clock and dataset

• falcon_palette()

  The shared categorical palette

• falcon_scheme()

  The shared visual specification

• falcon_theme()

  The shared ggplot2 theme

• report()

  Write a self-contained HTML report

• run_report()

  Run the whole analysis and write every deliverable to a directory

• quarto_report()

  Write the step-ordered Quarto report for an output directory

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()

  Download public data by accession

• cache_info() clear_cache() : Inspect or clear the download cache

Configuration and setup

What resolved, on this machine, in this environment.

• falconage_install()

  Install the Python core FALCONAge computes with

• falconage_config() print(<falcon_config>) : What this installation resolved to

• falconage_available()

  Is the Python core importable?