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]
            [--method {inside_outside,maximization,variational_gamma}] [-p]
            [-v] [--rescaling-intervals RESCALING_INTERVALS]
            [--max-iterations MAX_ITERATIONS] [-n POPULATION_SIZE]
            [-t NUM_THREADS] [--probability-space PROBABILITY_SPACE]
            tree_sequence output [deprecated_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.

deprecated_population_size

Deprecated positional argument, left for backwards compatibility.

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-06

--method

Possible choices: inside_outside, maximization, variational_gamma

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

-p, --progress

Show progress bar.

-v, --verbosity

How much verbosity to output.

--rescaling-intervals

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

--max-iterations

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

-n, --population_size

Estimated effective (diploid) population size. Ignored for the ‘variational_gamma’ method, but required otherwise. Default: None

-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: None treated as ‘logarithmic’

preprocess

Remove regions without data from an input tree sequence.

tsdate preprocess [-h] [--minimum_gap MINIMUM_GAP]
                  [--trim-telomeres TRIM_TELOMERES]
                  [--split-disjoint SPLIT_DISJOINT] [-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

--split-disjoint

Should disjoint nodes, that disappear from the trees then reappear further along the genome, be split into separate nodes. Default: True

-v, --verbosity

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