mptp(1)

📦
version 0.2.5 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ mptp — single-locus species delimitation ✨

okay bestie, sit down, hydrate, because we're about to talk about mptp(1) — single-locus species delimitation — and honestly? it's giving main character energy in the phylogenetics world. 🌸

🎀 NAME 🎀

mptp — single-locus species delimitation 💅

That's it, that's the whole name section. Short. Iconic. No notes. ✨

🌈 SYNOPSIS 🌈

So there are two whole ways to run this thing, and the vibe check depends entirely on whether you want a plain maximum-likelihood answer or a fancy one with support values. 🦋

💖 Maximum-likelihood species delimitation

If you just want the ML answer, no extra drama:

mptp --ml (--single | --multi) --tree_file newickfile
--output_file outputfile [options]

💜 Species delimitation with support values

And if you want the support values too, you're doing the whole <code>--mcmc</code> situation, which means more flags, more commitment, more slay:

mptp --mcmc positive integer (--single | --multi)
(--mcmc_startnull | --mcmc_startrandom | --mcmc_startml)
--mcmc_log positive integer --tree_file newickfile --output_file
outputfile [options]
heads up, bestie: in that second one, positive integer is literally standing in for a number you gotta supply — twice, once for --mcmc and once for --mcmc_log. it's not a keyword, it's a placeholder. don't type the words. 😭

both of these take [options] at the end, and the ( ... | ... ) bits mean pick exactly one — like, --single OR --multi, no greedy energy, you cannot have both. same deal with the --mcmc_start* trio. pick your fighter. 🥊

more parts coming, so don't go anywhere — we're just getting started. 💖

💖 DESCRIPTION 💖

Okay bestie, real talk: species is one of the fundamental units of comparison in literally every subfield of biology — systematics, anatomy, development, ecology, evolution, genetics, molecular biology, all of it. So the whole point of mptp is to give you an open source tool that infers species boundaries on a phylogenetic tree you hand it, based on the Poisson Tree Process (PTP) and the Multiple Poisson Tree Process (mPTP) models. 💅

mptp gives you two ways to infer species delimitation:

  • A maximum-likelihood based method that uses a dynamic programming approach to infer an ML estimate. ✨
  • An mcmc approach that samples the space of possible delimitations and hands you support values on the tree clades. 🎲

Both of those come in two flavours: the PTP model and the mPTP model. You pick PTP with the --single switch, and mPTP with --multi. Easy. 🎀

🌱 Input 🌱

The input for mptp is a newick file containing one phylogenetic tree. Heads up: branches express the expected number of substitutions per alignment site. That's the vibe. 🦋

⚙️ Options ⚙️

mptp parses a large number of command-line options (she's thorough, we love her for it). To make it not overwhelming, they're grouped by theme below. 👑

✨ General options ✨

  • --help — Display help text and exit. Your girl is helpful. 🙈
  • --version — Output version information and exit. 🏷️
  • --quiet — Suppress all output to stdout except for warnings and fatal error messages. So warnings and fatal errors still show up — she's quiet, not reckless. 💀
  • --tree_file filename — Input newick file that contains a phylogenetic tree. Can be rooted or unrooted. 🌳
  • --output_file filename — Specifies the prefix used for generating output files.
    • For maximum-likelihood species delimitation, two files get created: first, filename.txt, which contains the actual delimitation, and filename.svg, which contains an SVG figure of the computed delimitation. 🖼️
    • For mcmc analyses, a file filename.txt is created containing the newick tree with supports values. 🫶
  • --outgroup comma-separated list of taxa — All computations for species delimitation are carried out on rooted trees. This option is used only (and is required) in case an unrooted tree was specified with the --tree_file option. mptp roots the unrooted tree by splitting the branch leading to the most recent common ancestor (MRCA) of the comma-separated list of taxa into two branches of equal size, and introducing a new node (the root of the new rooted tree) that connects these two branches. 🌱
  • --outgroup_crop — Crops taxa specified with the --outgroup option from the tree. ✂️
  • --min_br real — Any branch lengths in the input tree smaller or equal to real are excluded (ignored) from the computations. On top of that, for mcmc analyses, subtrees that exclusively consist of branch lengths smaller or equal to real are completely ignored from the proposals — support values for those clades are set to 0. (default: 0.0001) 📏
  • --precision positive integer — Specifies the precision of the decimal part of floating point numbers on output. (default: 7) 🔢
  • --minbr_auto filename — Automatically detects the minimum branch length from the p-distances of the FASTA file filename. 🤖
  • --tree_show — Show an ASCII version of the processed input tree (i.e. after it is rooted by, potentially cropping, the outgroup). Tree but make it ASCII, iconic. 🎨

🔥 Maximum-likelihood estimations 🔥

Estimating the maximum-likelihood delimitation is triggered by the switch --ml followed by --single (the PTP model) or --ml --multi (the mPTP model). Heads up: these two methods affect how the option --output_file behaves, and they can be controlled using the --min_br switch. Both methods require a rooted phylogenetic tree — however, an unrooted tree may be specified in conjunction with the option --outgroup. In that case, mptp roots it at that outgroup (see General options, --outgroup for more info). And note that both methods output an SVG depiction of the ML delimitation — see Visualization for more information on adjusting and fine-tuning the SVG output. 🖼️✨

Both methods ignore/discard branch lengths of size smaller than the size specified using the --min_br option. The PTP model then attempts to find a connected subgraph of the rooted tree that:

  1. contains the root, and
  2. the sum of likelihoods of fitting the edges of that subgraph in one exponential distribution and the remaining edges in another (exponential distribution) is maximized.

By likelihood we mean the sums of the probability density function with the mean defined as the reciprocal of the average of edge lengths in the particular distribution. No cap. 🧮

  • --ml --single — Triggers the algorithm for computing an ML estimate of the delimitation using the PTP model. 🔥
  • --ml --multi — Triggers the algorithm for computing an ML estimate of the delimitation using the mPTP model. 🔥
  • --pvalue real — Only used with the PTP model (specified with --single). Sets the p-value for performing a likelihood ratio test. Note that there is no likelihood ratio test for the mPTP model, so this test is not done. (default: 0.001) 📊

🎲 MCMC method 🎲

The MCMC method is triggered with the --mcmc switch combined with either --single (the PTP model) or --multi (the mPTP model). 💃

Some more stuff to write

Not me reading the actual manpage and it literally says "Some more stuff to write" 😭 — that's a placeholder straight from the source, bestie, and I'm keeping it because the one rule is that nothing gets dropped. The author is gonna circle back, fr fr.

  • --mcmc positive integer --single — Triggers the algorithm for computing support values by taking the specified number of MCMC samples (delimitations) using the PTP model. 🎲
  • --mcmc positive integer --multi — Triggers the algorithm for computing support values by taking the specified number of MCMC samples (delimitations) using the mPTP model. 🎲
  • --mcmc_sample positive integer — Sample only every n-th MCMC step. ⏭️
  • --mcmc_log — Log the scores (log-likelihood) for each MCMC sample in a file and create an SVG plot. 📈
  • --mcmc_burnin positive integer — Ignore all MCMC samples generated before the specified step. (default: 1) 🔥
  • --mcmc_runs positive integer — Perform multiple MCMC runs. If more than 1 run is specified, mptp will generate one seed for each run based on the provided seed using the --seed switch. Output files will be generated for each run. (default: 1) 🔁
  • --mcmc_credible real — Specify the probability (0.0 to 1.0) for which to generate the credible interval, i.e., the probability the true number of species will fall within the credible interval given the observed data. (default: 0.95) 🫶
  • --mcmc_startnull — Start MCMC sampling from the null-model. 🕳️
  • --mcmc_startrandom — Start MCMC sampling from a random delimitation. 🎰
  • --mcmc_startrandom — Start MCMC sampling from the ML delimitation. 🤨
Yes, bestie, --mcmc_startrandom shows up twice in the original page, and the second one is described as starting from the ML delimitation. I'm not editing the source's truth, I'm just holding up a mirror. 🙈
  • --seed positive integer — Specifies the seed for the pseudo-random number generator. (default: randomly generated based on system time) 🌱

🎨 SVG Output 🎨

The ML method generates one SVG file that visualizes the processed input tree (i.e. after it is rooted by, potentially cropping, the outgroup) and marks the subtrees corresponding to coalescent processes (the detected species groups) with red color, while the speciation process is colored green. 🎀

The MCMC method generates one SVG file per run visualizing the processed tree, and indicates the support value for each node, i.e., the percentage of MCMC samples (delimitations) in which the particular node was part of the speciation process. A value of 1 means it was always in the speciation process, while a value of 0 means it was always in a coalescent process. The tree branches are colored according to the support values of descendant nodes; a support value of 0 is colored with red, 1 with black, and values in between are gradients of the two colors. Only support values above 0.5 are shown, to avoid packed numbers in dense branching events. In addition, if --mcmc_log is specified, an additional SVG image of log-likelihoods plots for each sampled delimitation is created. 📊🌈

  • --svg_width positive integer — Sets the total width (including margins) of the SVG in pixels. (default: 1920) 📐
  • --svg_fontsize positive integer — Size of font in SVG image. (default: 12) 🔤
  • --svg_tipspacing positive integer — Vertical space in pixels between taxa in SVG tree. (default: 20) 📏
  • --svg_legend_ratio real — Ratio (value between 0.0 and 1.0) of total tree length to be displayed as legend line. (default: 0.1) 📊
  • --svg_nolengend — Hide legend. 🙈
  • --svg_marginleft positive integer — Left margin in pixels. (default: 20) ⬅️
  • --svg_marginright positive integer — Right margin in pixels. (default: 20) ➡️
  • --svg_margintop positive integer — Top margin in pixels. (default: 20) ⬆️
  • --svg_marginbottom positive integer — Top margin in pixels. (default: 20) ⬇️
  • --svg_inner_radius positive integer — Radius of inner nodes in pixels. (default: 0) ⭕

🎀 EXAMPLES 🎀

ok bestie let's get you actually running this thing, because reading options is one thing and typing them is another 💅

1. compute the maximum likelihood estimate with the mPTP model, and just throw away every branch whose length is less than or equal to 0.0001

mptp --ml --multi --min_br 0.0001 --tree_file newick.txt
--output_file out

2. run an MCMC analysis of 100 million steps with the mPTP model 🦋 it logs every one-millionth step, ignores the first 2 million steps, and discards all branches with lengths smaller or equal to 0.0001. use 777 as the seed. heads up: the chain starts from the ML delimitation (that's the default, no extra flag needed, slay).

mptp --mcmc 100000000 --multi --min_br 0.0001 --tree_file
newick.txt --output_file out --mcmc_log 1000000 --mcmc_burnin
2000000 -seed 777

3. do an MCMC analysis of 5 runs, each one 100 million steps, with the mPTP model. log every one-millionth step, ignore the first 2 million steps, and let it detect the minimum branch length by handing it the FASTA file alignment.fa which holds the alignment 🌸 use 777 as the seed. and this time every run starts from a random delimitation.

mptp --mcmc 100000000 --multi ---mcmc_runs 5 --mcmc_log 1000000
--minbr_auto alignment.fa --tree_file newick.txt --output_file
out --mcmc_burnin 2000000 -seed 777 --mcmc_startrandom

👑 AUTHORS 👑

Implementation by Tomas Flouri, Sarah Lutteropp and Paschalia Kapli.

Additional PTP and mPTP model authors include Kassian Kobert, Jiajie Zhang, Pavlos Pavlidis, and Alexandros Stamatakis.

absolute legends, every single one of them 💜

🙈 REPORTING BUGS 🙈

found something cursed? submit suggestions and bug-reports at <https://github.com/Pas-Kapli/mptp/issues>, or e-mail Tomas Flouri <Tomas.Flouri@h-its.org>.

✨ AVAILABILITY ✨

Source code and binaries are available at <https://github.com/Pas-Kapli/mptp>.

Copyright (C) 2015-2017, Tomas Flouri, Sarah Lutteropp, Paschalia Kapli

All rights reserved.

Contact: Tomas Flouri <Tomas.Flouri@h-its.org>, Scientific Computing, Heidelberg Insititute for Theoretical Studies, 69118 Heidelberg, Germany

This software is licensed under the terms of the GNU Affero General Public License version 3.

GNU Affero General Public License version 3

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

🌈 VERSION HISTORY 🌈

new features and important modifications of mptp (heads up: short lived or minor bug releases may not be mentioned here, so don't come for me):

  • v0.1.0 released June 27th, 2016
    • First public release. the debut era 🎀
  • v0.1.1 released July 15th, 2016
    • Bug fix (now LRT test is not printed in output file when using --multi)
  • v.0.2.0 released September 27th, 2016
    • Fixed floating point exception error when constructing random trees, caused from dividing by zero. Changed allocation from malloc to calloc, as it caused unititialized variables when converting unrooted trees to rooted when using the MCMC method. Fixed sample size for the AIC with a correction for finite sample sizes.
  • v.0.2.1 released October 18th, 2016
    • Updated ASV to consider only coalescent roots of ML delimitation. Removed assertion stopping mptp when using random starting delimitations for the MCMC method.
  • v0.2.2 released January 31st, 2017
    • Fixed regular expressions to allow scientific notation for branch lengths when parsing trees. Improved the accuracy of ASV score by also taking into account tips forming coalescent roots. Fixed memory leaks that occur when parsing incorrectly formatted trees.
  • v0.2.3 released July 25th, 2017
    • Replaced hsearch() with custom hashtable. Fixed minor output error messages.
  • v0.2.4 released May 14th, 2018
    • If we do not manage to generate a random starting delimitation with the wanted number of species (randomly chosen), we use the currently generated delimitation instead.
  • v0.2.5 released Sep 9th, 2023
    • Added likelihood ratio test for the multi method. Added implementation for the incomplete gamma function, and removed dependency for GNU scientific library.

and that's the whole page bestie, you made it to the end 🫶 this was mptp version 0.2.5, dated Sep 11, 2023 — go forth and delimit some species, no cap ⭐🧚💜

📦 where this page comes from