32. epical

32.1. Overview

epical provides a unified command-line interface to DNA methylation epigenetic clocks and related methylation-based predictors distributed with CpGtools.

The command uses a subcommand-per-clock design. Each supported clock has its own help page and can be run as:

epical CLOCK Input_file [options]

For example:

epical Horvath13 beta.tsv -o sample

Display the top-level help with:

epical -h

Display help for a specific clock with:

epical Horvath13 -h

32.2. Supported Clocks

The current CLI exposes the following clocks and predictors.

32.2.1. Human and general clocks

Command	Notes
Horvath13	Standard epigenetic clock command.
Horvath13_shrunk	Shrunk version of the Horvath 2013 clock.
Horvath18	Horvath 2018 clock.
Levine	Levine methylation clock.
Hannum	Hannum methylation clock.
Zhang_EN	Zhang elastic-net clock.
Zhang_BLUP	Zhang BLUP clock.
AltumAge	AltumAge predictor.
Lu_DNAmTL	DNAm telomere-length predictor.
Weidner	Weidner clock.
Lin	Lin clock.
ENCen100	EN-Cen 100-CpG model.
ENCen40	EN-Cen 40-CpG model.
Ped_Wu	Pediatric Wu clock.
PedBE	Pediatric buccal epigenetic clock.
Cortical	Cortical methylation clock.
MEAT	Muscle epigenetic age test.
mammClock1	Mammalian clock using the general mammalian implementation.

32.2.2. Gestational-age clocks

The following gestational-age predictors are available:

• GA_Bohlin

• GA_Haftorn

• GA_Knight

• GA_Mayne

• GA_Lee_CPC

• GA_Lee_RPC

• GA_Lee_rRPC

32.2.3. DunedinPACE

DunedinPACE is available as a dedicated subcommand. Its CLI is similar to the standard clocks, except that it intentionally does not provide the --log option.

32.2.4. Mouse clocks

The following mouse clocks are available:

• WLMT

• YOMT

• mmLiver

• mmBlood

These commands add a genome-build option:

-g {mm10,mm39}
--genome {mm10,mm39}

The default is mm10.

32.2.5. Mammalian species-specific clocks

The following clocks accept an explicit mammalian species:

• mammClock2

• mammClock3

Use:

-s {human,mouse}
--species {human,mouse}

The default is human.

32.2.6. EPM

EPM uses a separate model-building interface and requires both a methylation matrix and a metadata file as positional arguments:

epical EPM Input_file meta_file [options]

See EPM Options below for its specific parameters.

32.3. Input

For most clock subcommands, the first positional argument is the methylation input file:

epical Horvath13 Input_file

The exact accepted matrix format and delimiter behavior are defined by the underlying CpGtools methylation-clock implementation. Use the command-specific help for details:

epical Horvath13 -h

32.4. Common Options

Most clock commands share the following options:

Option	Description
-o, --output	Output prefix.
-p, --percent	Missing-CpG threshold used by the clock implementation. Default: 0.2.
-d, --delimiter	Input delimiter. When omitted, the underlying reader determines the delimiter.
-f {pdf,png}, --format {pdf,png}	Figure output format. Default: pdf.
-m, --metadata	Optional metadata file.
-l, --log	Optional log-file path. This option is not available for DunedinPACE.
--impute	Imputation method code. Accepted values are integers from -1 through 11. Default: 11.
-r, --ref	Optional external reference file used by supported imputation methods.
--overwrite	Allow existing output files to be overwritten.
--debug	Enable debug logging.

32.5. Example

Run the Horvath 2013 clock:

epical Horvath13 beta.tsv \
    -o horvath13

Specify a metadata file and PNG output:

epical Horvath13 beta.tsv \
    -m metadata.tsv \
    -f png \
    -o horvath13

Use an external reference file for imputation:

epical Horvath13 beta.tsv \
    --impute 11 \
    -r reference.tsv \
    -o horvath13

32.6. Mouse-clock Example

Run a mouse clock using the mm39 genome build:

epical WLMT mouse_beta.tsv \
    --genome mm39 \
    -o mouse_age

32.7. Mammalian-clock Example

Run a mammalian clock for mouse samples:

epical mammClock2 beta.tsv \
    --species mouse \
    -o mammalian_age

32.8. EPM Options

EPM has its own interface:

epical EPM Input_file meta_file [options]

Its options are:

Option	Description
-o, --output	Output prefix.
-p, --pcc	Absolute Pearson correlation coefficient threshold between chronological age and Beta-values. Default: 0.85.
-n, --niter	Number of expectation-maximization iterations. Default: 100.
-k, --kfold	Number of cross-validation folds. Default: 10.
-e, --etol	Model-fitting error tolerance. Default: 1e-5.
-d, --delimiter	Input delimiter.
-f {pdf,png}, --format {pdf,png}	Figure output format. Default: pdf.
-l, --log	Optional log-file path.
--impute	Imputation method code from -1 through 11. Default: 11.
-r, --ref	Optional external reference file.
--debug	Enable debug logging.

Example:

epical EPM beta.tsv metadata.tsv \
    --pcc 0.85 \
    --niter 100 \
    --kfold 10 \
    -o epm_model

32.9. Version

Display the installed version with:

epical --version

32.10. Command-specific Help

Each clock has its own help text derived from the model metadata bundled with CpGtools. Because clock-specific assumptions and requirements may differ, check the relevant subcommand before running an analysis.

Examples:

epical Horvath13 -h
epical DunedinPACE -h
epical WLMT -h
epical mammClock2 -h
epical EPM -h