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] [--always_use_final_params]
[--treat_mutation_units_as_normalised_to_genome_size TREAT_MUTATION_UNITS_AS_NORMALISED_TO_GENOME_SIZE]
[--clock CLOCK] [--variance_dates VARIANCE_DATES]
[--variance_branch_length VARIANCE_BRANCH_LENGTH]
[--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]
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)
- --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
- --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
- --variance_branch_length
Scale factor for branch length distribution. Essentially how close we want to match the expectation of the Poisson.
Default: 1
- --steps
Number of steps to use for the SVI
Default: 1000
- --lr
Adam learning rate
Default: 0.1
- --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.