Merge pull request #159 from jeromekelleher/v0.1.5-changes

V0.1.5 changes

Author: jeromekelleher

docs/conf.py

@@ -46,10 +46,10 @@ def __getattr__(cls, name):
 copyright = '2018-2019, Tskit developers'
 author = 'Tskit developers'
 
-# The short X.Y version
-version = ''
-# The full version, including alpha/beta/rc tags
-release = ''
+# Following https://github.com/pypa/setuptools_scm#usage-from-sphinx
+from pkg_resources import get_distribution
+release = get_distribution(project).version
+version = '.'.join(release.split('.')[:2])
 
 ###################################################################
 #

python/CHANGELOG.rst

@@ -1,14 +1,25 @@
 --------------------
-[0.1.5] - 2019-XX-XX
+[0.1.5] - 2019-03-27
 --------------------
 
-Under development.
-
-This release removes support for Python 2.
+This release removes support for Python 2, adds more flexible tree access and a
+new ``tskit`` command line interface.
 
 **New features**
 
 - Remove support for Python 2 (:user:`hugovk`). See :issue:`137` and :pr:`140`.
+- More flexible tree API (:pr:`121`). Adds ``TreeSequence.at`` and
+  ``TreeSequence.at_index`` methods to find specific trees, and efficient support
+  for backwards traversal using ``reversed(ts.trees())``.
+- Add initial ``tskit`` CLI (:issue:`80`)
+- Add ``tskit info`` CLI command (:issue:`66`)
+- Enable drawing SVG trees with coloured edges (:user:`hyanwong`; :issue:`149`).
+- Add ``Tree.is_descendant`` method (:issue:`120`)
+- Add ``Tree.copy`` method (:issue:`122`)
+
+**Bugfixes**
+
+- Fixes to the low-level C API (:issue:`132` and :issue:`157`)
 
 --------------------
 [0.1.4] - 2019-02-01

python/tests/test_highlevel.py

@@ -35,6 +35,7 @@
 import unittest
 import warnings
 import uuid as _uuid
+import pathlib
 
 import numpy as np
 import msprime
@@ -1482,6 +1483,15 @@ def test_removed_methods(self):
         self.assertRaises(NotImplementedError, ts.diffs)
         self.assertRaises(NotImplementedError, ts.newick_trees)
 
+    def test_dump_pathlib(self):
+        ts = msprime.simulate(5, random_seed=1)
+        path = pathlib.Path(self.temp_dir) / "tmp.trees"
+        self.assertTrue(path.exists)
+        self.assertTrue(path.is_file)
+        ts.dump(path)
+        other_ts = tskit.load(path)
+        self.assertEqual(ts.tables, other_ts.tables)
+
     def test_zlib_compression_warning(self):
         ts = msprime.simulate(5, random_seed=1)
         with warnings.catch_warnings(record=True) as w:

python/tskit/_version.py

@@ -1,2 +1,2 @@
 # Definitive location for the version number.
-tskit_version = "0.1.5.dev0"
+tskit_version = "0.1.5"

python/tskit/formats.py

@@ -255,7 +255,8 @@ def raise_hdf5_format_error(filename, original_exception):
                 "File format {} is too old. Please use the ``tskit upgrade`` command "
                 "to upgrade this file to the latest version".format(version))
     except (IOError, OSError, KeyError):
-        raise exceptions.FileFormatError(str(original_exception))
+        # We want to keep a useful error message here as well as the chaining history.
+        raise exceptions.FileFormatError(str(original_exception)) from original_exception
 
 
 def _dump_legacy_hdf5_v2(tree_sequence, root):

python/tskit/provenance.py

@@ -131,4 +131,4 @@ def validate_provenance(provenance):
     try:
         jsonschema.validate(provenance, schema)
     except jsonschema.exceptions.ValidationError as ve:
-        raise exceptions.ProvenanceValidationError(str(ve))
+        raise exceptions.ProvenanceValidationError from ve

python/tskit/trees.py

@@ -1891,7 +1891,7 @@ def aslist(self):
     @classmethod
     def load(cls, path):
         ts = _tskit.TreeSequence()
-        ts.load(path)
+        ts.load(str(path))
         return TreeSequence(ts)
 
     @classmethod
@@ -1911,7 +1911,8 @@ def dump(self, path, zlib_compression=False):
             warnings.warn(
                 "The zlib_compression option is no longer supported and is ignored",
                 RuntimeWarning)
-        self._ll_tree_sequence.dump(path)
+        # Convert the path to str to allow us use Pathlib inputs
+        self._ll_tree_sequence.dump(str(path))
 
     @property
     def tables(self):
@@ -2774,17 +2775,56 @@ def write_vcf(self, output, ploidy=1, contig_id="1"):
         to the prefix ``msp_`` such that we would have the sample names
         ``msp_0``, ``msp_1`` and ``msp_2`` in the running example.
 
-        Example usage:
-
-        >>> with open("output.vcf", "w") as vcf_file:
-        >>>     tree_sequence.write_vcf(vcf_file, 2)
-
         .. warning::
             This output function does not currently use information in the
             :class:`IndividualTable`, and so will only correctly produce
             non-haploid output if the nodes corresponding to each individual
             are contiguous as described above.
 
+        Example usage:
+
+        .. code-block:: python
+
+            with open("output.vcf", "w") as vcf_file:
+                tree_sequence.write_vcf(vcf_file, 2)
+
+        The VCF output can also be compressed using the :mod:`gzip` module, if you wish:
+
+        .. code-block:: python
+
+            import gzip
+            with gzip.open("output.vcf.gz", "wt") as f:
+                ts.write_vcf(f)
+
+        However, this gzipped VCF may not be fully compatible with downstream tools
+        such as tabix, which may require the VCF use the specialised bgzip format.
+        A general way to convert VCF data to various formats is to pipe the text
+        produced by ``tskit`` into ``bcftools``, as done here:
+
+        .. code-block:: python
+
+            import os
+            import subprocess
+
+            read_fd, write_fd = os.pipe()
+            write_pipe = os.fdopen(write_fd, "w")
+            with open("output.bcf", "w") as bcf_file:
+                proc = subprocess.Popen(
+                    ["bcftools", "view", "-O", "b"], stdin=read_fd, stdout=bcf_file)
+                ts.write_vcf(write_pipe)
+                write_pipe.close()
+                os.close(read_fd)
+                proc.wait()
+                if proc.returncode != 0:
+                    raise RuntimeError("bcftools failed with status:", proc.returncode)
+
+        This can also be achieved on the command line use the ``tskit vcf`` command,
+        e.g.:
+
+        .. code-block:: bash
+
+            $ tskit vcf example.trees | bcftools view -O b > example.bcf
+
         :param File output: The file-like object to write the VCF output.
         :param int ploidy: The ploidy of the individuals to be written to
             VCF. This sample size must be evenly divisible by ploidy.