PAML tutorials

In this repository, you will find tutorials that you can use to further your understanding in phylogenetics and the usage of PAML programs.

Before going through the tutorials available in this repository, please make sure that you have correctly installed PAML as detailed in the section below. In addition, please take your time to go through the PAML Wiki to familiarise yourself with the control files that you will need to use to run PAML programs as well as specific notation and format that you will need to consider when preparing your input files.

Note

One of the main problems users face is data formatting. To this end, please make sure that you go through the section Data formatting in the PAML Wiki before running PAML programs and format your input data files and control files accordingly.

Important

• Problems with input data, control files, error/warning messages output by the PAML programs (which inform users about formatting issues in their input files or wrong settings in their control files), and general questions should be posted in the PAML discussion group. Before posting a message, please use the search tool in the PAML discussion group to check whether your question/s have already been asked by other PAML users. You should also refer to the FAQs document. If you still cannot find an answer to your question/s, please post them in the PAML discussion group.
• Please, do not paste the screen output and the error/warning that you get without any reference when you are requesting help. Instead, make sure that you attach the input data and the control files you are using, explain how you ran PAML, which PAML version you are using, etc. In that way, your issue will be much easier and faster to troubleshoot. You can find more information about how to report your warning/error message on this website.
• Please, only raise an issue on the PAML GitHub repository when you experience technical problems such as compiling issues, programs aborting or not running at all, etc.

Installing PAML programs

ANSI C source codes and executable files are distributed for UNIX, Linux, and Mac OS X (see the latest stable release available on the PAML GitHub repository). To download and install PAML software, please follow the next links included in the PAML wiki:

• Downloading and installing PAML
  • PAML for Linux
    • How to export paths in Linux
  • PAML for Mac OS X
    • How to export paths in Mac OS X
  • PAML for Windows 10 or later
    • How to export paths using the Windows Subsystem for Linux
  • Old compiled versions of PAML
    • PAML for Mac OS X
    • PAML for Windows 9x/NT/2000/XP/Vista 7
  • Graphical user interface: PAML-X

Documentation

We have created a PAML Wiki where the contents of the PAML documentation in PDF format have been migrated. We are continuously working and improving this Wiki to make the documentation more interactive and easy to follow!

At the time of writing, you can access the following sections, which are also detailed in the PAML Wiki home section:

• Overview
  • PAML documentation
  • What PAML programs can do
  • What PAML programs cannot do
• Data formatting
  • Sequence data file format
    • Sequential and interleaved formats
      • Species/sequence names
      • Option G
      • Option G for codon sequences (codeml with seqtype = 1)
    • Site pattern counts
  • Tree file format and representations of tree topology
    • Parenthesis notation
    • Tree files produced by PAUP and MacClade
    • Branch or node labels
    • Divergence date symbol @
    • Branch representation of tree topology
• Substitution models
  • Nucleotide substitution models
  • Codon substitution models
    • Branch models
    • Site models
      • Suzuki and Gojobori’s (1999) method for detecting sites under positive selection
    • Branch-site models
    • Clade models
    • Mutation-selection models
  • Amino acid substitution models
• PAML programs
  • BASEML
  • BASEMLG
  • CODEML
  • Evolver
  • Infinitesites
  • MCMCtree
  • yn00

Citing PAML

If you use PAML, please cite the following:

• Yang, Z (1997). PAML: a program package for phylogenetic analysis by maximum likelihood. Comput. Appl. Biosci. 13, 555-556.
• Yang, Z (2007). PAML 4: Phylogenetic Analysis by Maximum Likelihood. Mol. Biol. Evol. 24, 1586-1591.

In addition...

If you use the PAML program MCMCtree, please cite the following papers if you have used/run...

• ... the approximate likelihood calculation to speed up analyses with phylogenomic datasets (calculating branch lengths, Hessian, and gradient):
  • dos Reis M and Yang Z (2011). Approximate likelihood calculation for Bayesian estimation of divergence times. Mol. Biol. Evol. 28, 2161-2172.
• ... Bayesian model selection analyses:
  • dos Reis M, et al. (2018). Using phylogenomic data to explore the effects of relaxed clocks and calibration strategies on divergence time estimation: Primates as a test case. Syst. Biol. 67, 594–615. Also, please cite the mcmc3r R package if you use it (see tutorial via this link).
• ... the models for continuous morphological characters implemented in MCMCtree:
  • Álvarez-Carretero S, et al. (2019). Bayesian estimation of species divergence times using correlated quantitative characters. Syst. Biol. 68, 967–986. Also, please cite the mcmc3r R package if you use it (see tutorial via this link).
• ... the protocol Bayesian Molecular Clock Dating Using Genome-Scale Datasets:
  • dos Reis M and Yang, Z (2019). Bayesian Molecular Clock Dating Using Genome-Scale Datasets. In: Anisimova, M. (eds) Evolutionary Genomics. Methods in Molecular Biology, vol 1910. Humana, New York, NY. You can also access this chapter and the code used throughout the protocol on the divtime GitHub repository maintained by Mario dos Reis.
• ... the protocol Environmental Microbial Evolution: Methods and Protocols:
  • dos Reis M (2022) In: Haiwei Luo (ed.) Environmental Microbial Evolution: Methods and Protocols. Methods in Molecular Biology, vol 2569. Humana, New York, NY. You can access the code used throughout the protocol on the microdiv GitHub repository maintained by Mario dos Reis.
• ... the Bayesian sequential-subtree (BSS) approach and/or the scripts to fit skew-t distributions to fossil calibrations:
  • Álvarez-Carretero S, et al. (2022) A species-level timeline of mammal evolution integrating phylogenomic data. Nature 602, 263–267. You can find the tutorial to reproduce these analyses on the mammals_dating GitHub repository maintained by Sandra Álvarez-Carretero.

If you use the PAML program CODEML, please cite the following papers if you have used/run...

• ... the protocol A Beginners guide to estimating the non-synonymous to synonymous rate ratio of all protein-coding genes in a genome:
  • Jeffares DC, Tomiczek B, Sojo V, dos Reis M (2015). A Beginners Guide to Estimating the Non-synonymous to Synonymous Rate Ratio of all Protein-Coding Genes in a Genome. In: Peacock, C. (eds) Parasite Genomics Protocols. Methods in Molecular Biology, vol 1201. Humana Press, New York, NY..
• ... the protocol Beginner's guide on the use of PAML to detect positive selection and/or the corresponding GitHub tutorial on the positive-selection repository:
  • Álvarez-Carretero S, Kapli P, Yang Z (2023). Beginner's guide on the use of PAML to detect positive selection, Mol Biol Evol, 40(4):msad041.. Remember to read the supplementary material where we discuss (i) analyses and checks you should carry out before running tests of positive selection with CODEML, (ii) gene tree VS species tree, and (iii) the usage of rooted and unrooted trees.