Msprime 1.0 is a major update, recommended for all users. It introduces
new APIs and many new features, which still retaining compatibility
with nearly all existing code.
**New features**:
- Add new top-level functions `sim_ancestry` and `sim_mutations`, intended
as long term replacements for `simulate` and `mutate`.
- Add new `Demography` class as a replacement for the 0.x
``population_configurations``, ``migration_matrix`` and ``demographic_events``
parameters to simulate. Many new features to improve ease of use and to
help avoid errors.
- Change the underlying simulation from working in discrete genetic coordinates
and translating to physical coordinates, to simulating directly in physical
coordinates. This fixes some long standing bugs and makes it far simpler
to add features such as gene conversion. ({user}`daniel-goldstein`)
- Support discrete or continuous genomes in simulations directly.
- Gene conversion ({user}`fbaumdicker`)
- Selective sweeps and low-level infrastructure for the structured coalescent
({user}`andrewkern`, {user}`gbinux`)
- Multiple merger coalescent models ({user}`jerekoskela`, {user}`shajoezhu`,
{user}`TPPSellinger`)
- Different ploidy levels for coalescent models ({user}`jerekoskela`)
- Functions to parse species trees and set up simulation models according
to the species tree. ({user}`mmatschiner` {issue}`893` {issue}`929` {issue}`931`)
- Add an modern array oriented RateMap class as to replace the RecombinationMap
class ({user}`jeromekelleher`, {user}`grahamgower`, {user}`hyanwong`).
- Functions to compute the likelihood of a particular ARG realisation
under the coalescent with recombination ({user}`jerekoskela`).
- Mutations are assigned times ({user}`petrelharp`)
- Finite sites mutations ({user}`petrelharp`)
- Several instances of matrix mutation models: JC69, GTR, HKY, F84, BLOSUM62,
PAM. ({user}`GertjanBisschop`, {user}`petrelharp`).
- An implementation of the SLiM mutation model ({user}`petrelharp`)
- An infinite alleles mutation model ({user}`jeromekelleher`)
- Methods to track the possible location of lineages, and compute the
coalescence rates over time ({user}`apragsdale`, {user}`petrelharp`
{user}`grahamgower`).
- Two new CLI commands, `msp ancestry` and `msp mutations` which correspond
to the `sim_ancestry` and `sim_mutations` functions. These can be pipelined
using stdin/stdout. ({user}`winni2k`, {user}`jeromekelleher`)
- Complete provenance recording of all arguments to simulate and mutate.
Adds argument record_provenance to simulate, which allows recording of
provenances to be disabled, for example when they are large.
({user}`benjeffery` {pr}`914`).
- Add replicate_index to simulate, allowing output of a single tree sequence
from a set of replicates. ({user}`benjeffery` {pr}`914`).
- Details of the simulation are written to the DEBUG log periodically.
This can help debug long-running simulations. ({user}`jeromekelleher`,
{pr}`1080`).
- Binary wheels for PyPI ({user}`benjeffery`)
**Breaking changes**:
- Require Python 3.7+.
- The class form for specifying models (e.g., `msprime.StandardCoalescent()`)
no longer take a `reference_size` argument. ({user}`jeromekelleher`,
{pr}`1028`).
- The `simulate` function only takes one positional argument, and all other
arguments are keyword-only.
- The `msp` CLI has been stripped of all existing sub-commands except for
`simulate`. The old sub-commands are provided by the `tskit`
CLI or the `TreeSequence` API in `tskit`.
- The `end_time` option now allows events up to and including the specified
max time. Previously, events occurred strictly before the max time.
({user}`apragsdale`, {issue}`1304`, {pr}`1521`)
- The class msprime.Population now refers to the new demography API. This
may break old code that depends on the tskit table entities being
exported from msprime (other classes are now formally deprecated and
will raise a warning; see the deprecations section).
- The semantics of ``start_time`` and exponential growth models has changed;
previously, exponential population size changes would be calculated starting
at the simulation ``start_time`` at the beginning of the simulation. Now
population growth rates are always computed from time 0 (unless other
events occur). The old semantics, if needed, can be recovered by setting
the ``growth_rate`` to 0 in the initial population declaration and adding
a population parameters change event at the ``start_time`` to change the
``growth_rate`` to the desired value.
**Performance improvements**
- Much better simulation performance for models with large numbers
of populations ({user}`jeromekelleher`, {pr}`1069`).
- Significant performance improvements for simulating from recombination
maps ({user}`ivan-krukov`, {user}`castedo`)
**Deprecations**:
- Deprecate module attributes that were moved to tskit.
({user}`benjeffery`, {issue}`991`, {pr}`1158`)