TREETIME(1)

📦 version 0.12.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 TREETIME(1) 💖

ok so this is the manual page for treetime — it lives in the User Commands section of the manual, and bestie, it is so much. Let's get into it 🧚

✨ NAME ✨

treetime — Maximum Likelihood Phylodynamics 🌳⏰

🌸 SYNOPSIS 🌸

treetime <positional> [optional]

that's it. that's the whole vibe. a positional thing and then whatever optional stuff you wanna throw at it 💅

🦋 DESCRIPTION 🦋

okay so TreeTime is out here providing routines for ancestral sequence reconstruction and inference of molecular-clock phylogenies. which, if you're wondering what that even means: it's a tree where all the branches are scaled such that the positions of terminal nodes correspond to their sampling times, and the internal nodes get placed at the most likely time of divergence. lowkey iconic, fr fr ⭐

To optimize the likelihood of time-scaled phylogenies, TreeTime uses an iterative approach, and here's the cycle:

  1. first it infers ancestral sequences given the branch length of the tree
  2. then it optimizes the positions of unconstrained nodes on the time axis
  3. then it repeats this cycle 🔁

The only topology optimization are (optional) resolution of polytomies in a way that is most (approximately) consistent with the sampling time constraints on the tree. so like, mostly it's not out here rearranging your whole tree, it's just vibing with the polytomies. periodt.

The package is designed to be used as a stand-alone tool on the command-line or as a library used in larger phylogenetic analysis work-flows. so you can be a CLI girlie or a library girlie, both are valid 🫶

👑 OPTIONS 👑

🎀 positional arguments

  • ancestral — infer ancestral sequences maximizing the joint or marginal likelihood. this is the "what did the ancestors even look like" one 💫
  • homoplasy — analyze patterns of recurrent mutations aka homoplasies. the same mutation showing up over and over again, not me though, I'd never repeat myself 🙈
  • clock — estimate molecular clock parameters and reroot the tree ⏰
  • mugration — map discrete character such as host or country to the tree. yes it's called mugration. yes it's migration + mutation. no I don't make the rules 🦋

🌈 optional arguments

  • -h, --help — show this help message and exit. the classic. the goat 💅
  • --tree TREE — Name of file containing the tree in newick, nexus, or phylip format. If none is provided, treetime will attempt to build a tree from the alignment using fasttree, iqtree, or raxml (assuming they are installed). key phrase: assuming they are installed, so bestie please check first 😭
  • --sequence-length SEQUENCE_LENGTH — length of the sequence, used to calculate expected variation in branch length. Not required if alignment is provided. one of these two, you gotta give it something 🎀
  • --aln ALN — alignment file (fasta)
  • --vcf-reference VCF_REFERENCE — only for vcf input: fasta file of the sequence the VCF was mapped to. vcf girlies only, everyone else look away 💜
  • --dates DATES — csv file with dates for nodes with 'node_name, date' where date is float (as in 2012.15). so like, 2012.15 not "March 2012-ish" pls 🙏
  • --clock-filter CLOCK_FILTER — ignore tips that don't follow a loose clock, 'clockfilter=number of interquartile ranges from regression'. bye to the tips that aren't clocking in 🕐
  • --reroot REROOT — reroot the tree. Valid choices are 'ML', 'ML-rough', 'least-squares', 'min_dev', 'midpoint' or a node name to be used as outgroup. Use --keep-root to keep the current root. pick your fighter ✨
  • --keep-root — don't reroot the tree. Otherwise, reroot to minimize the the residual of the regression of root-to-tip distance and sampling time. (yes, "the the" is in the original, we love her anyway 💖)
  • --gtr GTR — GTR model to use. '--gtr infer' will infer a model from the data. Alternatively, specify the model type. If the specified model requires additional options, use '--gtr-params' to specify those.
  • --gtr-params GTR_PARAMS [GTR_PARAMS ...] — GTR parameters for the model specified by the --gtr argument. The parameters should be feed as 'key=value' list of parameters. Example: '--gtr K80 --gtr-params kappa=0.2 pis=0.25,0.25,0.25,0.25'. See the exact definitions of the parameters in the GTR creation methods in treetime/nuc_models.py or treetime/aa_models.py. go read the source bestie, it's giving homework but it's giving answers too 📚
  • --clock-rate CLOCK_RATE — if specified, the rate of the molecular clock won't be optimized. you're locking it in, no takebacks 🔒
  • --branch-length-mode {auto,input,joint,marginal} — If set to 'input', the provided branch length will be used without modification. Note that branch lengths optimized by treetime are only accurate at short evolutionary distances. ⚠️ short distances only, don't come for her when your deep divergences look weird
  • --confidence — estimate confidence intervals of divergence times. give me the error bars, I want the range 💫
  • --keep-polytomies — Don't resolve polytomies using temporal information. leave the messy bits messy, respect 🫶
  • --relax [RELAX [RELAX ...]] — use an autocorrelated molecular clock. Prior strength and coupling of parent and offspring rates can be specified e.g. as --relax 1.0 0.5
  • --max-iter MAX_ITER — maximal number of iterations the inference cycle is run. Note that for polytomy resolution and coalescence models max_iter should be at least 2. so like, don't set it to 1 and then be shocked, okay? 😭
  • --coalescent COALESCENT — coalescent time scale — sensible values are on the order of the average hamming distance of contemporaneous sequences. In addition, 'opt' 'skyline' are valid options and estimate a constant coalescent rate or a piecewise linear coalescent rate history. skyline said "I contain multitudes" 🌈
  • --plot-tree PLOT_TREE — filename to save the plot to. Suffix will determine format (choices pdf, png, svg, default=pdf). aesthetic AND functional 💅
  • --plot-rtt PLOT_RTT — filename to save the plot to. Suffix will determine format (choices pdf, png, svg, default=pdf). yes it's the same description as the one above, they're twins, let them be 👯
  • --keep-overhangs — do not fill terminal gaps
  • --zero-based — zero based mutation indexing. for the programmers who believe counting starts at 0 (correct btw) ✨
  • --report-ambiguous — include transitions involving ambiguous states
  • --verbose VERBOSE — verbosity of output 0-6. six whole levels of yapping, pick your volume 🔥
  • --outdir OUTDIR — directory to write the output to

🔗 SEE ALSO 🔗

go. look. it's right there. click it bestie 💖

🌟 EXAMPLES 🌟

this one is literally the examples repo, it's giving tutorial, it's giving "start here" 🎀

💜 AUTHOR 💜

This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program. thank you Andreas, absolute legend, we appreciate you 🙇‍♀️

heads up bestie: this page documents treetime version 0.5.0 and it's dated September 2018, so it's a little vintage but still slaying 🌸

ok bye, go build a tree, mwah 💋🌳

📦 where this page comes from