Bacmeta is free for use, under the terms of BSD 3-clause License. See LICENSE.txt.
It has been described in article:
Aleksi Sipola, Pekka Marttinen, Jukka Corander; Bacmeta: simulator for genomic evolution in bacterial metapopulations, Bioinformatics, , bty093, https://doi.org/10.1093/bioinformatics/bty093
Please cite the article if you are publishing any work done with help of Bacmeta!
Developer welcomes all forms of feedback, help inquiries, developing suggestions and general correspondence about the program via email!
Simulator for forward-simulating evolution of bacterial genomes in multiple, diversely connected populations.
Simulation starts with a single genotype, which can consist of one or multiple loci of desired length, and proceeds in discrete time, "generation-by-generation". Single nucleotide mutations, indels of Zipf distributed length and recombinations of whole loci or segments of geometrically distributed lengths are modelled as Poisson processes. Migration and microepidemics are also modelled as Poisson processes, with options for migration probabilities and microepidemic sizes. Metadata about each simulated level and object, i.e. locus, individual, population or metapopulation, can be considered and data of various aspects are provided, together with the main output files of sequences and loci-wise pairwise distances.
InputOutputManual.pdf for further information.
Only requirements are C++11 and g++ compiler. Windows users need cygwin.
Download bacmeta from
bitbucket.com/aleksisipola/bacmeta. Extract and place the acquired folder
/bacmeta/ into a preferred location. Note that all the output files will be created into the subfolder
***/bacmeta/outputs/. All source code files and make file for compilation are included in
/bacmeta/outputs/ will be created automatically when the simulator is run for the first time.
Simulator must be compiled with the included makefile to create an executable simulator program
simu. This needs to be done only once, or when updating. Open a terminal and cd into
***/bacmeta/src/, and enter
make. Successful make should result in text:
g++ Bac.o Gene.o Para.o Pop.o Simu.o Superpop.o -o ../simu. After compiling, all files needed for running the simulator, i.e. input files and simulator executable itself, are located in main folder
Setting up simulation:
Parameters for the simulation run are set with the plain text file:
or with help of command line options, variation of the filename can be used:
where in place of
123 any short, alphanumeric string can be used. Use of the command line options is described further in this README. Normal text editor or command line programs such as
sed can be used to edit the input files. All parameter options are shown in
default.params and those lines can be copied into and modified in
simu.input. Note that
default.params should not be edited as it is always used for initializing all necessary parameters. Furthermore, only contents of
simu.input are documented for simulation runs.
When using non-identical migration rates between populations, the rates are set with file:
or, like with general parameters file, custom name can be used with command line options.
Note that, if parameters are set without consideration, output files might get excessively numerous or large.
InputOutputManual.pdf for more information.
Simulation is run on terminal in the main folder
/bacmeta/ with command
or with command line options e.g.
./simu -p 123 -m 321 -o 213
If you want to STOP the simulation, press
Notice that any previous output files with same filename modifier parameter value are overwritten!
In the beginning Bacmeta goes through initializing, after which simulation progress is shown in intervals of 1000 generations. Successful run will end with line:
Simulation finished and output files created.
Previous simulations can be replicated using the same seed value that is documented into
rundetails***.txt using the same platform. However, the results can differ if runs are made in different platforms. This is due to the freedom of random number generation implementations in the C++ standard.
Command line options:
-p Specify 'simu---.input' file for parameter input. The argument replaces '---'.
For example './simu -p 123' would use simu123.input.
-m Specify 'migration---.input' file for migration rate matrix input.
For example './simu -p 123 -m 333' would use migration333.input (and simu123.input).
-b Specify both of the files above with same suffix.
For example './simu -b 123' would use simu123.input AND migration123.input.
-o Specify modifier for the output filenames.
For example './simu -p 123 -o 456' would use simu123.input BUT output files would have filename modifier 456, ignoring the value in simu123.input.
Arguments work at least with numbers and alphabetic letters. Symbols have NOT been tested and are not recommended.
(These command line option descriptions are also shown with the command
./simu -h. No simulation is run when using
-h command line option.)
Variety of output files can be created by a simulation run. Output files are created into folder
/bacmeta/outputs/, which is created automatically if one does not already exist. All files have the filename modifier suffix given in
simu.input or with the flag
-o. Some of the output files can have multiple occurrences at intervals. To exclude certain documentation, give negative number for documentation interval, or toggle off with
0 according to the comments in input file.
These files can reach relatively large sizes if parameters for documentation are not set accordingly for big simulations.
More thorough descriptions of outputs are given in
InputOutputManual.pdf, and examples are provided in
This program is written for and tested in UNIX-environment. Main developing platform currently is Linux Mint 18 (Sarah).
Current version has also been tested successfully on OS X Mavericks and Windows 10 with cygwin. Though current version has not been tested on these, previous versions have run well on Debian (Jessie), Ubuntu, OS X Yosemite and Windows 7 and 10 both with cygwin and VMware player running Ubuntu virtual machine.