Merge pull request #396 from jeromekelleher/docs-mist

Random bag of docs updates.

README.md

@@ -13,6 +13,12 @@ If you would like to help make ``msprime`` better, please see the
 [developer documentation](https://msprime.readthedocs.org/en/latest/development.html)
 to get started.
 
+If you are looking for help on a specific issue or would like to ask a
+question to fellow ``msprime`` users, please send an email to the
+[mailing list](https://groups.google.com/group/msprime-users). By asking
+questions on the mailing list, you can help to build a searchable knowledge
+base.
+
 If you use ``msprime`` in your work, please cite the [PLOS Computational
 Biology](http://dx.doi.org/10.1371/journal.pcbi.1004842) paper.
 See [here](https://msprime.readthedocs.org/en/latest/CITATION.html) for

README.rst

@@ -0,0 +1,23 @@
+=======
+msprime
+=======
+
+Msprime is a coalescent simulator and library for processing
+tree-based genetic data. Msprime can simulate the coalescent with
+recombination over whole chromosomes for hundreds of thousands of
+samples, and very efficiently process the resulting genealogies.
+It is also possible to efficiently read data from external
+sources via a well defined and efficient `interchange API
+<https://msprime.readthedocs.org/en/stable/interchange.html>`_.
+
+If you use ``msprime`` in your work, please cite the `PLOS Computational
+Biology <http://dx.doi.org/10.1371/journal.pcbi.1004842>`_ paper.
+See `here <https://msprime.readthedocs.org/en/stable/CITATION.html>`__ for
+full citation details.
+
+Please see the `documentation <https://msprime.readthedocs.org/en/stable/>`_
+for further details.
+
+Msprime is very portable, and provides a number of installation options.
+See `here <https://msprime.readthedocs.org/en/stable/installation.html>`_ for
+details.

docs/conf.py

@@ -138,11 +138,10 @@ def handle_item(fieldarg, content):
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-# Following advice from setuptools_scm at
-# https://github.com/pypa/setuptools_scm
 try:
-    release = pkg_resources.get_distribution('msprime').version
-    version = '.'.join(release.split('.')[:2])
+    from setuptools_scm import get_version
+    release = get_version(root='..', relative_to=__file__)
+    version = release[:3]
 except pkg_resources.DistributionNotFound:
     release = "0.0.0"
     version = "0.0.0"

docs/index.rst

@@ -9,6 +9,12 @@ Welcome to msprime's documentation!
 This is the documentation for ``msprime``, a reimplementation of Hudson's
 classical :command:`ms` simulator.
 
+If you are looking for help on a specific issue or would like to ask a
+question to fellow ``msprime`` users, please send an email to the
+`mailing list <https://groups.google.com/group/msprime-users>`_. By asking
+questions on the mailing list, you can help to build a searchable knowledge
+base.
+
 Contents:
 =========
 

docs/introduction.rst

@@ -20,7 +20,7 @@ scenarios. The library is a reimplementation of Hudson's seminal
 2. ``msprime`` is primarily designed to be used through its
    :ref:`Python API <sec_api>` to simplify the workflow associated with
    running and analysing simulations. (However, we do provide an
-   ``ms``_compatible :ref:`command line interface <sec_cli>` to
+   ``ms`` compatible :ref:`command line interface <sec_cli>` to
    plug in to existing workflows.) For many simulations we first
    write a script to generate the command line parameters we
    want to run, then fork shell processes to run the simulations,
@@ -36,3 +36,12 @@ scenarios. The library is a reimplementation of Hudson's seminal
    format allows us to store genealogical data very concisely,
    particularly for large sample sizes.
 
+
+The ``msprime`` library has also evolved to support data
+from external sources, and can work with data conforming to
+the :ref:`sec_interchange` definitions. In the near future, the
+efficient algorithms and data structures used to process tree
+sequence data will be moved into a new library, provisiononally
+called ``tskit``. Once this transition is complete, ``msprime``
+will depend on this library, and will become primarily concerned
+with simulating backwards-in-time population processes.

msprime/simulations.py

@@ -619,6 +619,24 @@ def __init__(self, positions, rates, num_loci=None):
 
     @classmethod
     def uniform_map(cls, length, rate, num_loci=None):
+        """
+        Returns a :class:`.RecombinationMap` instance in which the recombination
+        rate is constant over a chromosome of the specified length. The optional
+        ``num_loci`` controls the number of discrete loci in the underlying
+        simulation, and is by default large enough to be effectively be
+        a continuous model.
+
+        The following map can be used to simulate a true finite locus model
+        with a fixed number of loci ``m``::
+
+            >>> recomb_map = RecombinationMap.uniform_map(m, rate, num_loci=m)
+
+        :param float length: The length of the chromosome.
+        :param float rate: The rate of recombination per unit of sequence length
+            along this chromosome.
+        :param int num_loci: The number of discrete loci in the underlying
+            simulation. By default this is set to a large number.
+        """
         return cls([0, length], [rate, 0], num_loci)
 
     @classmethod

msprime/tables.py

@@ -1193,6 +1193,12 @@ def sort_tables(
     - child node ID, then
     - left endpoint.
 
+    Note that this sorting order exceeds the
+    :ref:`edge sorting requirements <sec_edge_requirements>` for a valid
+    tree sequence. For a valid tree sequence, we require that all edges for a
+    given parent ID are adjacent, but we do not require that they be listed in
+    sorted order.
+
     Sites are sorted by position.
 
     Mutations are sorted by site ID.

setup.py

@@ -19,6 +19,8 @@
 from __future__ import division
 from __future__ import print_function
 
+from setuptools import setup, Extension
+
 import subprocess
 import platform
 import os
@@ -42,15 +44,6 @@
 except ImportError:
     warn("numpy not available. Some features will not work.")
 
-# First, we try to use setuptools. If it's not available locally,
-# we fall back on ez_setup.
-try:
-    from setuptools import setup, Extension
-except ImportError:
-    from ez_setup import use_setuptools
-    use_setuptools()
-    from setuptools import setup, Extension
-
 
 class PathConfigurator(object):
     """
@@ -170,7 +163,7 @@ def __getitem__(self, index):
     library_dirs=configurator.library_dirs,
 )
 
-with open("README.txt") as f:
+with open("README.rst") as f:
     long_description = f.read()
 
 setup(