Package: phylostan
phylostan: phylogenetic inference using StanIntroductionphylostanis a tool written in python for inferring phylogenetic trees from nucleotide datasets.
It generates a variety of phylogenetic models using the Stan language.
Through the pystan library,phylostanhas access to Stan's variational inference and sampling (NUTS and HMC) engines.
The program has been described and its performance evaluated in anarticle. The data and scripts used to generate the results can be foundhere.FeaturesPhylogenetic model components:Nucleotide substitution models: JC69, HKY, GTRRate heterogeneity: discretized Weibull distribution and general discrete distributionTree without clock constraint with uniform prior on topologyTime tree:Homochronous sequences: same sampling dateHeterochronous sequences: sequences sampled at different time pointsMolecular clocks:StrictAutocorrelatedUncorrelated: log-normal hierarchical priorCoalescent models:Constant population sizeSkyrideSkygridAlgorithms provided by Stan:Variational inference:Mean-field distributionFull-rank distributionNo U-Turn Sampler (NUTS)Hamiltonian Monte Carlo (HMC)PrerequisitesProgram/LibraryVersionDescriptionpythonTested on python 3.6, 3.7, 3.9pystan>=2.19 <3API forStandendropyLibrary for manipulating trees and alignmentsnumpy>=1.7You can install phylostan using pippipinstallphylostanYou can also run it locallypython-mphylostan.phylostan<COMMAND>where<COMMAND>is either thebuildorruncommand.Command-line usagephylostanis decomposed into two sub-commands:build: creates a Stan file: a text file containing the model.run: runs a Stan file with the data.These two steps are separated so the user can edit the Stan model. The main reason would be to modify the priors.To get some help about thebuildorruncommands:phylostanbuild--help
phylostanrun--helpQuickstartWe are going to use thefluA.faalignment andfluA.treetree files. This dataset contains 69 influenza A virus haemagglutinin nucleotide sequences isolated between 1981 and 1998.First, a Stan script needs to be generated using thebuildcommand:cdexamples/fluA
phylostanbuild-sfluA-GTR-W4.stan-mHKY-C4\--heterochronous--estimate_rate--clockstrict--coalescentconstantThis command is going to create a Stan filefluA-GTR-W4.stanwith the following model:Hasegawa, Kishino and Yano (HKY) nucleotide substitution modelRate heterogeneity with 4 rate categories using the Weibull distributionAssumes that sequences were sampled are different time points (heterochronous)Constant effective population sizeThe substitution rate will be estimatedIn the second step we compile and run the script with our dataphylostanrun-sfluA-GTR-W4.stan-mHKY-C4\--heterochronous--estimate_rate--clockstrict--coalescentconstant\-ifluA.fa-tfluA.tree-ofluA-qmeanfieldTheruncommand requires the data (tree and alignment) and an output parameter.
It also needs the parameters that were provided to thebuildcommand.
The output will consists of 4 files:fluA: this file is the output file of Stan. It contains the samples drawn from the variational distribution (or MCMC samples).fluA.diag: this file is also generated by Stan and it contains some information such as the ELBO at each iteration.fluA.trees: this file is a nexus file containing trees. It can be opened with a program such asFigTreeor summarized usingtreeannotatorfromBEASTorBEAST2.fluA-GTR-W4.pkl: the Stan script is compiled into this binary file. This file can be reused automatically byphylostanunless it must be recompiled, then the option--compilecan be used.At the end of the run,phylostanwill print on the screen the mean and 95% credibility interval of the parameters of interest:Weibull (shape) mean: 0.488 95% CI: (0.383,0.616)
Strict clock (rate) mean: 0.00499 95% CI: (0.00432,0.00577)
Constant population size (theta) mean: 4.03 95% CI: (3.14,5.05)
HKY (kappa) mean: 5.58 95% CI: (4.37 7.039)
Root height mean: 18.96 95% CI: (18.36 19.74)In this example we have used a mean-field distribution (-q meanfield) to approximate the posterior using variational inference.
The Stan model is already compiled so we can run the NUTS algorithm without re-generating the script file, simply issue the command:phylostanrun-sfluA-GTR-W4.stan-mHKY-C4\--heterochronous--estimate_rate--clockstrict--coalescentconstant\-ifluA.fa-tfluA.tree-ofluA-anutsThe NUTS algorithm is much slower (and more accurate) than variational inference so it should be used on a small dataset.Citing phylostanMathieu Fourment and Aaron E. Darling. Evaluating Probabilistic Programming and Fast Variational Bayesian Inference in Phylogenetics. 2019PeerJ. doi:10.7717/peerj.8272.@article{fourment2019phylostan,
  title    = "Evaluating probabilistic programming and fast variational
              {B}ayesian inference in phylogenetics",
  author   = "Fourment, Mathieu and Darling, Aaron E",
  journal  = "PeerJ",
  volume   =  7,
  pages    = "e8272",
  month    =  dec,
  year     =  2019
}