Ctrl+K

Command line interface

Command line interface#

This page provides formal documentation for the command-line interface to tsdate.

Example#

For a mutation rate of 1e-8 and an effective diploid population size of 20,000, the following command-line command will create dated tree sequence named output.trees.

tsdate date -m 1e-8 input.trees output.trees 20000

Alternatively, the following is more reliable, especially if you have multiple versions of Python installed or if the tsdate executable is not installed on your path:

python3 -m tsdate date -m 1e-8 input.trees output.trees 20000

For long-running dating processes, the --progress option may also be useful. Additional tsdate commands, notably preprocess_ts() are also available, see below:

Argument details#

This is the command line interface for tsdate, a tool to date tree sequences.

usage: tsdate [-h] [-V] {date,preprocess} ...

Positional Arguments#

subcommand

Possible choices: date, preprocess

Named Arguments#

-V, --version

show program’s version number and exit

Sub-commands#

date#

Takes an inferred tree sequence topology and returns a dated tree sequence.

tsdate date [-h] [-m MUTATION_RATE] [-r RECOMBINATION_RATE] [-e EPSILON]
            [-t NUM_THREADS] [--probability-space PROBABILITY_SPACE]
            [--method {inside_outside,maximization,variational_gamma}]
            [--ignore-oldest] [-p] [-v] [--max-shape MAX_SHAPE]
            [--rescaling-intervals RESCALING_INTERVALS]
            [--max-iterations MAX_ITERATIONS]
            tree_sequence output [population_size]
Positional Arguments#
tree_sequence

The path and name of the input tree sequence for which node ages are estimated.

output

The path and name of output file where the dated tree sequence will saved.

population_size

Estimated effective (diploid) population size.

Named Arguments#
-m, --mutation-rate

The estimated mutation rate per unit of genome per generation. If provided, the dating algorithm will use a mutation rate clock to help estimate node dates. Default: None

-r, --recombination-rate

The estimated recombination rate per unit of genome per generation. If provided, the dating algorithm will use a recombination rate clock to help estimate node dates. Default: None

-e, --epsilon

Specify minimum distance separating time points. Also specifies the error factor in time difference calculations. Default: 1e-6

-t, --num-threads

The number of threads to use. A simpler unthreaded algorithm is used unless this is >= 1. Not relevant for the ‘variational_gamma’ method. Default: None

--probability-space

Should the internal algorithm save probabilities in ‘logarithmic’ (slower, less liable to to overflow) or ‘linear’ space (faster, may overflow). Not relevant for the ‘variational_gamma’ method. Default: ‘logarithmic’

--method

Possible choices: inside_outside, maximization, variational_gamma

Specify which estimation method to use: ‘inside_outside’ is empirically better, but theoretically problematic; ‘maximization’ is worse empirically, especially with a gamma prior, but theoretically robust; ‘variational_gamma’ is a fast experimental continuous-time approximation. Current default: ‘inside_outside’

--ignore-oldest

Ignore the oldest node in the tree sequence: in older tsinfer versions this could be of low quality when using empirical data.

-p, --progress

Show progress bar.

-v, --verbosity

How much verbosity to output.

--max-shape

The maximum value for the shape parameter in the variational posteriors for the “variational_gamma” algorithm. This is equivalent to the maximum precision (inverse variance) on a logarithmic scale. Default: 1000

--rescaling-intervals

The number of time intervals within which to estimate a time scaling parameter. Default: 1000

--max-iterations

The number of iterations used in the expectation propagation algorithm. Default: 10

preprocess#

Remove regions without data from an input tree sequence.

tsdate preprocess [-h] [--minimum_gap MINIMUM_GAP]
                  [--trim-telomeres TRIM_TELOMERES] [-v]
                  tree_sequence output
Positional Arguments#
tree_sequence

The tree sequence to preprocess.

output

The path and name of output file where the preprocessed tree sequence will saved.

Named Arguments#
--minimum_gap

The minimum gap between sites to trim from the tree sequence. Default: 1000000

--trim-telomeres

Should all material before the first site and after the last site be trimmed, regardless of the length of these regions. Default: True

-v, --verbosity

How much verbosity to output (max is -vv).

Contents