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.