Command line interface¶
Two command_line applications are provided with
msprime: msp and
mspms. The msp program is an experimental interface for
interacting with the library, and is a POSIX compliant command line
interface. The mspms program is a fully-ms compatible
interface. This is useful for those who wish to get started quickly with using
the library, and also as a means of plugging
msprime into existing work
flows. However, there is a substantial overhead involved in translating data
msprime’s native history file into legacy formats, and so new code
should use the Python API where possible.
msp program provides a convenient interface to the msprime API. It is based on subcommands that either generate or consume a
tree sequence file. The
simulate subcommand runs a
simulation storing the results in a file. The other commands are concerned with
converting this file into other formats.
This tool is very new, and the interface may need to change over time. This should be considered an alpha feature!
msp simulate provides a command line interface to the
msprime.simulate() API function. Using the parameters provided at the
command line, we run a simulation and then save the resulting tree sequence
to the file provided as an argument.
The way in which recombination and mutation rates are specified is different to ms. In ms these rates are scaled by the length of the simulated region, whereas we use rates per unit distance. The rationale for this change is to simplify running simulations on a variety of sequence lengths, so that we need to change only one parameter and not three simultaneously. See API Documentation for more on this point.
The mspms program is an ms-compatible
command line interface to the
msprime library. This interface should
be useful for legacy applications, where it can be used as a drop-in
replacement for ms. This interface is not recommended for new applications,
particularly if the simulated trees are required as part of the output
as Newick is very inefficient. The Python API is the recommended interface,
providing direct access to the structures used within
mspms supports a subset of ms’s functionality. Please open an issue on GitHub if there is a feature of ms that you would like to see added. We currently support:
- Basic functionality (sample size, replicates, tree and haplotype output);
- Recombination (via the
- Spatial structure with arbitrary migration matrices;
- Support for ms demographic events. (The implementation of the
-esoption is limited, and has restrictions on how it may be combined with other options.)
Gene-conversion is not currently supported, but is planned for a future release.