Command line interface#

usage: demes [-h] [--version] {parse,ms} ...

Demes model parser and converter.

positional arguments:
{parse,ms}
parse     Parse models and write them to stdout in canonical form.
ms        Build a Demes model using ms command line arguments.

options:
-h, --help  show this help message and exit
--version   show program's version number and exit


demes parse#

usage: demes parse [-h] [-j | --ms REFERENCE_SIZE] [-s] filename

Parse models and write them to stdout. YAML is output by default, but JSON or
ms commands may instead be written. See options below.

positional arguments:
filename             Filename of the model. The special value '-' may be
used to read from stdin. The file may be in YAML or
JSON format, but will be parsed as YAML. Multi-document
YAML is supported.

options:
-h, --help           show this help message and exit
-j, --json           Output a JSON-formatted model.
--ms REFERENCE_SIZE  Output ms command line arguments, using the given
reference population size (N0) to translate into
coalescent units (see the 'ms' subcommand for
interpretation of this value). The sampling
configuration in the output will need editing prior to
simulation. The order of deme IDs matches the order of
demes in the input model.
-s, --simplified     Output a simplified model. This is a compact
representation in which many default values are
omitted. As only the essential details are retained,
this is usually easier for humans to read. The
simplified output is guaranteed to be a valid Demes
model that can be resolved identically to the input
model. But exactly which fields are simplified, and how
simplification is performed, may change over time. Thus
users should not rely on details of the output such as
presence or absence of specific fields, or other
details that do not alter how the model is resolved. A
fully-resolved model is output by default.


demes ms#

usage: demes ms [-h] -N0 REFERENCE_SIZE [-f filename] [-I num_demes [n1 ...]]
[-n i x] [-g i alpha] [-G alpha] [-m i j rate]
[-ma entry [entry ...]] [-eG t alpha] [-eg t i alpha]
[-eN t x] [-en t i x] [-eM t x] [-em t i j rate]
[-ema t [entry ...]] [-es t i p] [-ej t i j]

Build a Demes model from commands accepted by Hudson's classic ms simulator.
https://doi.org/10.1093/bioinformatics/18.2.337

Ms commands correspond to a backwards-time model of population dynamics,
and use coalescent units for times t, population sizes x, and migration
rates m. These are converted to more familiar units using the reference
size N0 according to the following rules:

- time (in generations) = 4 * N0 * t,
- deme size (diploid individuals) = N0 * x,
- migration rate (per generation) = m / (4 * N0).

Deme IDs are 1-based, and migration matrix entry M[i, j] is the
forwards-time fraction of deme i which is made up of migrants from
deme j each generation.

Please refer to the ms manual for the precise semantics of each command.
http://home.uchicago.edu/~rhudson1/source/mksamples.html

options:
-h, --help            show this help message and exit

required arguments:
-N0 REFERENCE_SIZE, --reference-size REFERENCE_SIZE
The reference population size used to translate from
coalescent units. For an existing ms command, this can
be calculated as theta / (4 * mu * L), where theta is
the value given to the -t option, mu is the per-
generation mutation rate, and L is the length of the
sequence being simulated.

ms arguments:
-f filename           Insert commands from a file at this point in the
command line.
-I num_demes [n1 ...]
Set the number of demes and the sampling
configuration. The arguments are of the form
'num_demes n1 n2 ... [4N0m]', specifying the number of
demes, the sample configuration, and optionally, the
migration rate for a symmetric island model (in units
of 4 * N0). While values must be provided for the
sample configuration, they are not used for
constructing the Demes model.
-n i x                Set the size of deme i to x * N0.
-g i alpha            Set the growth rate of deme i to alpha.
-G alpha              Set the growth rate to alpha for all demes.
-m i j rate           Sets an entry M[i, j] in the migration matrix to the
specified rate. i and j are (1-indexed) deme IDs.
-ma entry [entry ...]
Sets the migration matrix from the specified vector of
values. The entries are in the order M[1, 1], M[1, 2],
..., M[2, 1], M[2, 2], ..., M[N, N], where N is the
number of demes. Diagonal entries may be written as
'x'.
-eG t alpha           Set the growth rate for all demes to alpha at time t.
-eg t i alpha         Set the growth rate of deme i to alpha at time t.
-eN t x               Set the size of all demes to x * N0 at time t.
-en t i x             Set the size of deme i to x * N0 at time t.
-eM t x               Set the symmetric island model migration rate to 'x /
(num_demes - 1)' at time t.
-em t i j rate        Sets the entry M[i, j] in the migration matrix to the
specified rate at time t. i and j are (1-indexed) deme
IDs.
-ema t [entry ...]    Sets the migration matrix from the specified vector of
values at time t. The entries are in the order M[1,
1], M[1, 2], ..., M[2, 1], M[2, 2], ..., M[N, N],
where N is the number of demes. Diagonal entries may
be written as 'x'.
-es t i p             Split deme i into a new deme, such that the specified
proportion p of lineages remains in deme i. The new
deme has ID num_demes + 1, and has size N0, growth
rate 0, and migration rates to and from the new deme
are set to 0. Forwards in time this corresponds to an
admixture event with the extinction of the new deme.
-ej t i j             Move all lineages in deme i to j at time t. All
migration rates for deme i are set to zero. Forwards
in time, this corresponds to a branch event in which
lineages in j split into i.