Pyslim

***************************

**Bugfixes**:

- The last bugfix introduced a small bug: recapitation on a tree sequence
whose roots are at least 100,000 ticks ago would produce an msprime error:
"Attempt to sample a lineage from an inactive population". Reported by
Meaghan Clark. (:user:`petrelharp`, :pr:`322`)

***************************

***************************

**Bugfixes**:

- From 1.0.1 back to 0.700, there was a bug in `recapitate` when using the
`ancestral_Ne` parameter that introduced a bottleneck to diploid size Ne=1
for each SLiM subpopulation for 1 or 2 generations *unless* either (a) it
was a WF simulation, with calls to addSubPop() in first() or early() and
treeSeqOutput() in late(), or (b) it was a nonWF simulation, with calls to
addSubPop() in first() and treeSeqOutput() in early() or late(). The fix
correctly starts the msprime population with effective size `ancestral_Ne`
at the time of the roots, which might be at the value of
`ts.metadata['SLiM']['tick']`, this value minus 1, or this value minus 2.
Furthermore, `recapitate` now throws an error if any roots of any trees
are not at the same time as the others. (:user:`petrelharp`, :pr:`308`)


***************************

***************************

This was a bugfix release that was pushed out without the actual bug fix.
Please don't use this one.

***************************

***************************

- Documentation of how to empirically measure generation time
and check that it is correct
(:user:`silastittes`, :user:`petrelharp`, :pr:`301`, :pr:`293`).

- Minor modifications to `convert_alleles` and `generate_nucleotides`
so that they run in a reasonable amount of time
(:user:`petrelharp`, :pr:`299`).

- Addition of method to find the next SLiM mutation ID,
`pyslim.next_slim_id` (:user:`mufernando`, :pr:`290`).


***************************

***************************

**Breaking changes**:

- Removed `SlimTreeSequence` class entirely (it was previously deprecated).
All its methods are either available in `tskit.TreeSequence`
or are now called by `pyslim.fn(ts, ...)` instead of `ts.fn(...)`.

- TODO: Deprecated `util.unique_labels_by_group`.

- Moved some methods of `SlimTreeSequence` to pyslim:
* instead of `slim_ts.slim_time(t)` do `pyslim.slim_time(ts, t)`
* instead of `slim_ts.individuals_alive_at(t)` do `pyslim.individuals_alive_at(ts, t)`
* instead of `slim_ts.individuals_parents(t)` do `pyslim.individuals_parents(ts, t)`
* instead of `slim_ts.individuals_ages(t)` do `pyslim.individuals_ages(ts, t)`

- The methods `slim_ts.mutation_at( )` and `slim_ts.nucleotide_at( )`
are now methods of pyslim, whose first argument is the tree sequence.

- In SLiM v4 "generation" has been renamed to "tick", and so corresponding things
in pyslim have been renamed: top-level metadata now has `ts.metadata["SLiM"]["tick"]`
instead of `ts.metadata["SLiM"]["generation"]`

- Renamed `pyslim.annotate_defaults()` to `pyslim.annotate()`, with slight
changes in behavior: since msprime.sim_ancestry() now simulates individuals
by default, annotation does not set up individuals: if you have a tree
sequence without individuals (e.g., produced by msprime.simulate()) then you
need to set up those individuals yourself.

- To update a tree sequence produced by an old version of SLiM to the current one,
use `pyslim.update( )`. (However, note that reading it in to SLiM and
writing it out again might be even easier.)

- The method `pyslim.set_tree_sequence_metadata` now has arguments `tick` and `cycle`
instead of `generation`.

- Removed `pyslim.make_slim_provenance_dict`.

**Other notable changes**:

- Top-level metadata now has a `tick` attribute that is (for now) a synonym
for `generation`; the latter will be deprecated at some point in the future.

- Methods for getting time, population, and location information about individuals
are now in tskit:
* `SlimTreeSequence.individual_times` is now `TreeSequence.individuals_time()`
* `SlimTreeSequence.individual_populations` is now `TreeSequence.individuals_population()`
* `SlimTreeSequence.individual_locations` is now `TreeSequence.individuals_location()`
However, this will be invisible to the user. In each case note the the
location of the "s" has moved (to "individual*s* time" instead of "individual
time*s*"), but the original version remains an undocumented alias.

**New features**:

- Methods like `pyslim.individuals_alive_at( )` now deal with the new `stage="first"`.


********************

********************

**Breaking changes**:

- `pyslim.recapitate` is updated to use new demography features in msprime 1.0,
and differs from `SlimTreeSequence.recapitate()` (now deprecated). Since
the backend is now `msprime.sim_ancestry()` instead of `msprime.simulate()`,
the argument `Ne` should be replaced with `ancestral_Ne`.

- `reference_sequence` is now a tskit TreeSequence attribute, no longer managed
by pyslim. It is no longer mutable on tree sequences (only TableCollections),
and previous calls to `ts.reference_sequence` to get the actual sequence
should be replaced by `ts.reference_sequence.data`.

- Old-style "legacy" metadata (previously deprecated) has been removed.
See `the documentation <https://tskit.dev/pyslim/docs/previous_versions.html>`_
for instructions on migrating your code.


**New features**:

- Added `pyslim.population_size( )` to compute an array giving numbers of
individuals across a grid of space and time bins. ({user}giliapatterson)


********************