Table of contents:
PolyMoSim can simulate the evolution of nucleotide or amino acid sequences for a specified evolutionary models, model parameters and phylogenetic trees. PolyMoSim is a fast and flexible program that supports a large number of evolutionary models, allows different models on different branches, mixture models and even a site heterogeneity that differs on different branches of the tree.
It has been designed to test phylogenetic tree reconstruction programs and to train machine learning models for phylogenetic reconstruction.
- Download the project or clone the project locally.
- On the command line go to the project folder and type "make". This builds the program PolyMoSim.
- Type "make test" to run the tests in the tests folder.
- Type "make install" to copy PolyMoSim to /usr/local/bin, or "make install PREFIX=$HOME/.local" to copy it to $HOME/.local/bin. Alternatively, copy the PolyMoSim program to a folder that is listed in your $PATH variable so that your system can always find it, copy it to the folder you want to use it from or specify the full path to the program.
- The compiler and its options can be set with CXX, CXXFLAGS and LDFLAGS, e.g. "make CXX=clang++".
- "PolyMoSim --version" prints the version.
PolyMoSim can be compiled on all platforms, which provide a C++ compiler. In particular this includes Windows, MacOS and Linux operating systems. Here I will only explain how to compile it on Mac and Linux computers.
PolyMoSim requires two input files:
i) The model file, which contains a list specified evolutionary models with model parameters that can be used for the simulation. See the README-model-files.md. for more details.
ii) The tree file, which contains one or multiple lines specifying the partition size and evolutionary tree. Each line specifies the the information for one partition. See the README-tree-files.md for more details.
Quickstart: The simplest way to start PolyMoSim is as follows:
PolyMoSim -m model-file.txt -t tree-file.txt --outfile simulation-result.fas
or
PolyMoSim -m model-file.txt -t tree-file.txt 1> simulation-result.fas
PolyMoSim has two required paramters: the model file and the tree file. All other parameters are optional. Most of them have default values. Parameters you might want to have a look at are: output-file-name (-o), setting the seed for the random number generator (-s) setting the random number seed, which is important if you do multiple simulations, and the output format (-f). A full list of command line parameters is given below.
Example simulations are provided in the Examples folder. See the Examples/README-Examples.md for a list of examples and a brief explanation.
Evolutionary models have to be specified in the model file before they can be used in simulations. In simulations, different models can be specified at the root or at any internal node of a tree and independent for every partition of the dataset. Model usage is specified in the tree file. Independent models can be specified for each partiontion tree. Within each partition tree they have to be specified for the root and can be replaced at each internal node. A model specified for the root or an internal node will be used for all downstream branches unit a new model is specified.
Nucleotide and amino acid models have to be specified in the model file. Models that shall be used are specified in the tree file. There a model is specified for the whole tree. Models can be altered for each branch. Models that are changed on a branch will be used for the whole clade, unless another model is specified for a subclade.
A good starting point is to look at the examples in the Example folder.
Any number of nucleotide and amino acid substitution models can be specified in the model file. A model specification consists of a model name, the model type, and the model parameters.
Nucleotide models:
- For nucleotide models the following model types are known: JC, F81, K2P, F84, HKY, GTR.
Depending on the model type, different model parameters can be specified: tstv, rrates, shape, ncat, propinv, base_frequencies, siterate-distribution. The siterate-distribution parameter allows specifying a site rate distribution function using the following operations and functions: "+", "-", "*", "/", "^", "#", "$", "Dist_Gauss", "Dist_Gamma", "Dist_Uniform", "Heavy", "Gamma", "Dist_Beta", "Dist_Cauchy", "Dist_Uniform_Interval". More documentation will be added. The mathematical expression is parsed and evaluated in math_expression_parser.h.
Amino Acid models: JTT, LG, WAG_OLD, WAG, WAG_STAR, DAY, Qplant, Qpfam, Qpfam_GB, Qmammal, Qinsect, Qbird, Qlg, Qyeast. References for these models can be found in the code file models-aa.cpp. A user specified model is also possible. Here the relative rates and the amino acid frequencies have to be specified in the model file. An example is provided in the Example-3_aa-models folder.
As for nucleotide models, the following model parameters can be specified: rrates, shape, ncat, propinv, base_frequencies, siterate-distribution.
Remark: Amino acid substitution matrices are hard coded in the mymodel.cpp file. This file also contains references to the models.
Mixture models: Mixture models can be specified by using multiple partitions in the tree file.
PolyMoSim -m <string> -t <string>
[-o <string>] [-l <string>] [-n <unsigned>]
[--print_siterate_data <string>]
[--print_siterate_histogram <string>]
[--print_ancestral_seq <string>] [--post <string>]
[--pre <string>] [-s <unsigned int>] [-f <nexus|phylip
|phylip_no_spaces|fasta|site_pattern_freq_absolute
|site_pattern_freq_relative
|site_pattern_freq_absolute_fill
|site_pattern_freq_relative_fill>] [--verbosity <integer>]
[--] [-v] [-h]
PolyMoSim -m <string> -t <string> [OPTIONS]
| Flag | Description |
|---|---|
-m <string>, --modelfile <string> |
Model file for simulation. |
-t <string>, --treefile <string> |
Tree file for simulation. |
| Flag | Description |
|---|---|
-o <string>, --outfile <string> |
Name of output file the simulated sequence data is written to. Several different file formats can be chosen. If not specified, output is printed to console (standard output). |
-l <string>, --log <string> |
File to write log information to. |
--verbosity <integer> |
Level of additional information given to the user. Valid values: 0–200. Default: 1. Set to 0 for less output. Values above >=100 are used for debugging. Steps for which output changes: 0,1,2,3,4,100,200 |
| Flag | Description |
|---|---|
-n <unsigned>, --nreps <unsigned> |
Number of independent datasets generated in the simulation. Default: 1. |
-s <unsigned int>, --seed <unsigned int> |
Seed value for the random number generator. Default: current time. Do not rely on the default seed if you start many analyses simultaneously. |
-f <format>, --OutputFormat <format>
Controls the output format for the sequence data. Default: fasta.
| Format | Description |
|---|---|
nexus |
Nexus format. |
phylip |
Phylip format. |
phylip_no_spaces |
Phylip format without spaces. |
fasta |
FASTA format (default). |
site_pattern_freq_absolute |
Site pattern frequencies (absolute counts, observed patterns only). |
site_pattern_freq_relative |
Site pattern frequencies (relative counts, observed patterns only). |
site_pattern_freq_absolute_fill |
Site pattern frequencies (absolute counts, all patterns including unobserved). |
site_pattern_freq_relative_fill |
Site pattern frequencies (relative counts, all patterns including unobserved). |
The site_pattern formats list the site pattern frequencies instead of the alignment. The site_pattern*_fill formats list all patterns including those that do not exist in the file, the non-fill formats only list the site patterns that occurred in the simulated data set. Site pattern frequencies are needed e.g. when training neural networks that require site pattern frequencies as input. See e.g. DeepNNPhylogeny
The site_pattern_freq_relative_fill is useful for machine learning training based on site pattern frequencies.
| Flag | Description |
|---|---|
--print_ancestral_seq <string> |
Print the ancestral sequence to the specified file. Default: not printed. |
--print_siterate_data <string> |
Print site rate list for all models to the specified file. Default: not printed. |
--print_siterate_histogram <string> |
Print a site rate histogram for each model to the specified file. Default: not printed. |
| Flag | Description |
|---|---|
--pre <string> |
Content of this file is copied into the output before each generated dataset. Useful in the nexus format. |
--post <string> |
Content of this file is copied into the output after each generated dataset. Useful in the nexus format. |
| Flag | Description |
|---|---|
--, --ignore_rest |
Ignores all remaining labeled arguments after this flag. |
-v, --version |
Display version information and exit. |
-h, --help |
Display usage information and exit. |
Copyright (c) 2004-2026 Christoph Mayer
Author: Dr. Christoph Mayer, Leibniz Institute for the Analysis of Biodiversity Change (LIB), Bonn, Germany
Contributors:
- Stefan Richter (major early contributor, see History below)
- Nikita Kulikov and Dr. Iker Irisarri suggested features for using PolyMoSim with DeepNNPhylogeny.
- Dr. Anestis Gkanogiannis added the test suite,
make install, continuous integration via GitHub Actions, and the Conda package.
History: PolyMoSim was started in 2004 as a Diploma thesis project (Stefan Richter, supervised by Christoph Mayer). In particular he implemented the original nucleotide substitution models and sequence evolution.
PolyMoSim is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation (SPDX: GPL-3.0-only). See the LICENSE file for the full license text. PolyMoSim is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY.
PolyMoSim includes code from other projects:
discrete_gamma.cpp: routines from Ziheng Yang's PAML package, GNU GPL v3.CRandom.h,CRandom.cpp: Mersenne Twister MT19937 by Makoto Matsumoto and Takuji Nishimura, BSD 3-clause license.tclap/: Templatized C++ Command Line Parser by Michael E. Smoot, MIT license (seetclap/COPYING).