# Command line interface

## Contents

# 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.
```