Welcome to Chronumental’s documentation!#

Installation#

To install Chronumental using pip, run:

pip install chronumental

Usage#

Convert a distance tree into time tree with distances in days.

usage: chronumental [-h] --tree TREE --dates DATES [--dates_out DATES_OUT]
                    [--tree_out TREE_OUT]
                    [--treat_mutation_units_as_normalised_to_genome_size TREAT_MUTATION_UNITS_AS_NORMALISED_TO_GENOME_SIZE]
                    [--clock CLOCK] [--variance_dates VARIANCE_DATES]
                    [--initial_tau INITIAL_TAU] [--hs_scale HS_SCALE]
                    [--steps STEPS] [--lr LR] [--name_all_nodes]
                    [--expected_min_between_transmissions EXPECTED_MIN_BETWEEN_TRANSMISSIONS]
                    [--only_use_full_dates] [--model MODEL]
                    [--output_unit {days,years}] [--variance_on_clock_rate]
                    [--enforce_exact_clock] [--use_gpu] [--use_wandb]
                    [--wandb_project_name WANDB_PROJECT_NAME] [--clipped_adam]
                    [--reference_node REFERENCE_NODE]
                    [--always_use_final_params]

Named Arguments#

--tree

an input newick tree, potentially gzipped, with branch lengths reflecting genetic distance in integer number of mutations

--dates

A metadata file with columns strain and date (in “2020-01-02” format, or less precisely, “2021-01”, “2021”)

--dates_out

Output for date tsv (otherwise will use default)

--tree_out

Output for tree (otherwise will use default)

--treat_mutation_units_as_normalised_to_genome_size

If your branch sizes, and mutation rate, are normalised to per-site values, then enter the genome size here.

--clock

Molecular clock rate. This should be in units of something per year, where the “something” is the units on the tree. If not given we will attempt to estimate this by RTT. This is only used as a starting point, unless you supply –enforce_exact_clock.

--variance_dates

Scale factor for date distribution. Essentially a measure of how uncertain we think the measured dates are.

Default: 0.3

--initial_tau

Initial value for the tau parameter in the model. Only applies to Horseshoe.

Default: 3.2

--hs_scale

hs scale parameter in the model. Only applies to Horseshoe.

Default: 86917549.587

--steps

Number of steps to use for the SVI. Increasing this number will make runtime increase, but yield more accurate results.

Default: 20000

--lr

Adam learning rate

Default: 0.03

--name_all_nodes

Should we name all nodes in the output tree?

Default: False

--expected_min_between_transmissions

For forming the prior, an expected minimum time between transmissions in days

Default: 3

--only_use_full_dates

Only use full dates, given to the precision of a day

Default: False

--model

Model type to use

Default: “DeltaGuideWithStrictLearntClock”

--output_unit

Possible choices: days, years

Unit for the output branch lengths on the time tree.

Default: “days”

--variance_on_clock_rate

Will cause the clock rate to be drawn from a random distribution with a learnt variance.

Default: False

--enforce_exact_clock

Will cause the clock rate to be exactly fixed at the value specified in clock, rather than learnt

Default: False

--use_gpu

Will attempt to use the GPU. You will need a version of CUDA installed to suit Numpyro.

Default: False

--use_wandb

This flag will trigger the use of Weights and Biases to log the fitting process. This must be installed with ‘pip install wandb’

Default: False

--wandb_project_name

Wandb project name

Default: “chronumental”

--clipped_adam

Will use the clipped version of Adam

Default: False

--reference_node

A reference node to use for computing dates. This should be early in the tree, and have a correct date. If not specified it will be picked as the oldest node, but often these can be metadata errors.

--always_use_final_params

Will force the model to always use the final parameters, rather than simply using those that gave the lowest loss

Default: False

Indices and tables#