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] [--clock_filter_iqd CLOCK_FILTER_IQD]
                    [--variance_dates VARIANCE_DATES] [--steps STEPS]
                    [--lr LR] [--convergence_rate_tol CONVERGENCE_RATE_TOL]
                    [--convergence_tol_days CONVERGENCE_TOL_DAYS]
                    [--convergence_check_every CONVERGENCE_CHECK_EVERY]
                    [--convergence_patience CONVERGENCE_PATIENCE]
                    [--disable_early_stopping] [--name_all_nodes]
                    [--expected_min_between_transmissions EXPECTED_MIN_BETWEEN_TRANSMISSIONS]
                    [--only_use_full_dates] [--output_unit {days,years}]
                    [--multiply_date_precision] [--variance_on_clock_rate]
                    [--root_date_prior_scale_days ROOT_DATE_PRIOR_SCALE_DAYS]
                    [--initialise {tip-dates,clock}]
                    [--initial_branch_floor {positive,mutations}]
                    [--floating_clock_rate] [--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. By default this value is held fixed; pass –floating_clock_rate to treat it as a starting point instead.

--clock_filter_iqd

Discard the date of any tip whose root-to-tip divergence sits more than this many interquartile ranges from the regression line, before fitting. Those tips keep their place in the tree and simply become undated. 0, the default, keeps every date. 4 is a reasonable value if you suspect swapped or mistyped metadata: on datasets with a tight clock it identifies genuinely wrong dates with high precision and recovers much of the damage they do, but it finds only the worst of them – two sequences of similar divergence can swap dates and leave almost no trace in this statistic – so it is a mitigation rather than a fix. On the Ebola test data 4 drops 20 of 362 tips and 2 drops 32, so values below 4 are aggressive.

Default: 0.0

--variance_dates

How uncertain the reported tip dates are taken to be, in days: the standard deviation of the date likelihood for a tip with a full date. For a tip dated only to a month or a year this is combined in quadrature with half the width of that interval, so an imprecise date is dominated by its own window and raising this value does not inflate it. The old default of 0.3 treated a full date as known to within about seven hours, which over-constrains the fit: the tip dates then pin each root-to-tip total so tightly that the mutation counts have almost no say in how that total is divided among the branches on the path.

Default: 3.0

--steps

Upper bound on the number of SVI steps. By default this is a ceiling, not a target: fitting stops earlier once the predicted dates stop changing by more than –convergence_tol_days, since extra steps beyond that point change the answer only in ways too small to matter. Pass –disable_early_stopping to always run exactly this many steps, e.g. for a reproducible step count.

Default: 20000

--lr

Adam learning rate

Default: 0.03

--convergence_rate_tol

Relative change in the fitted clock rate below which it counts as settled, for early stopping. Checked alongside –convergence_tol_days because node dates can look stable while the rate is still moving, and the dates are more sensitive to the rate than a test on the dates alone can detect.

Default: 0.002

--convergence_tol_days

Stop once the mean absolute change in predicted node dates between convergence checks falls below this many days. A looser 1 day stopped too early: the node dates had settled but the clock rate was still moving, and the rate is what the dates are most sensitive to. On one real dataset a 5% error in the fitted rate cost 3 days of median disagreement with treetime, and tightening this from 1 to 0.1 took that disagreement from 11.3 days to 8.1. Simulated benchmarks improve too, from 14.9 to 14.1 days mean absolute error, for about 11% more runtime.

Default: 0.1

--convergence_check_every

How often, in steps, to evaluate the early-stopping criterion.

Default: 50

--convergence_patience

Number of consecutive checks (each –convergence_check_every steps apart) that must satisfy both –convergence_tol_days and –convergence_rate_tol before stopping early.

Default: 3

--disable_early_stopping

Always run the full –steps, ignoring the convergence criterion. Use this if you need an exact, reproducible number of SVI steps.

Default: False

--name_all_nodes

Should we name all nodes in the output tree?

Default: False

--expected_min_between_transmissions

Floor, in days, under each branch’s starting duration when –initialise clock is used. It has no effect under the default tip-date initialisation.

Default: 3

--only_use_full_dates

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

Default: False

--output_unit

Possible choices: days, years

Unit for the output branch lengths on the time tree.

Default: 'days'

--multiply_date_precision

Restore the old date-likelihood scale, –variance_dates multiplied by each tip’s precision window, rather than the two combined in quadrature. Multiplying conflates the width of the reported interval with how far a reported date can be from the truth for other reasons, so raising one inflates the other: at the default it made a year-only date uncertain to within ten years.

Default: False

--variance_on_clock_rate

Will cause the clock rate to be drawn from a random distribution with a learnt variance. Requires –floating_clock_rate, since a fixed rate has no variance to learn.

Default: False

--root_date_prior_scale_days

Scale of the Cauchy prior on the root date, in days before the oldest tip. Heavy-tailed, so this mainly sets where the prior stops being flat rather than how far back the root may go; the default of 100 years is uninformative for almost any tree.

Default: 36500.0

--initialise

Possible choices: tip-dates, clock

Where the fit starts. ‘tip-dates’ puts every tip on its own reported date and gives each internal node the mean over its children of the child’s position less what that child’s mutations represent at the clock rate. ‘clock’ is the older behaviour, which ignores the tip dates: every branch starts at its own mutations over the clock rate and the root at one reference tip’s divergence over that rate. The root date barely moves during a fit, so this choice largely decides where it ends up.

Default: 'tip-dates'

--initial_branch_floor

Possible choices: positive, mutations

The floor the tip-date initialiser puts under each branch. ‘positive’ keeps only what is needed to keep durations positive and lets the tip-date estimate stand. ‘mutations’ additionally requires at least the time that branch’s own mutations represent at the clock rate, which pushes a child later wherever the tip dates put it earlier than the mutations allow, and so inflates the tree wherever the clock estimate is off.

Default: 'positive'

--floating_clock_rate

Fit the clock rate as a free parameter instead of holding it at the estimate. This was the behaviour before the rate was fixed by default. It lets the fit recover from a poor starting estimate, at the cost of a rate biased low: fitting one free duration per branch alongside a single shared rate is the classic incidental-parameters problem, and the free fit landed below the reference rate on 18 of 24 real datasets.

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

• Index

• Module Index

• Search Page