First pass at documenting tskit + Python API

Author: jeromekelleher

bio2zarr/tskit.py

@@ -241,8 +241,8 @@ def generate_schema(
 
 
 def convert(
-    ts_path,
-    zarr_path,
+    ts_or_path,
+    vcz_path,
     *,
     model_mapping=None,
     contig_id=None,
@@ -252,8 +252,14 @@ def convert(
     worker_processes=1,
     show_progress=False,
 ):
+    """
+    Convert a :class:`tskit.TreeSequence` (or path to a tree sequence
+    file) to VCF Zarr format stored at the specified path.
+
+    .. todo:: Document parameters
+    """
     tskit_format = TskitFormat(
-        ts_path,
+        ts_or_path,
         model_mapping=model_mapping,
         contig_id=contig_id,
         isolated_as_missing=isolated_as_missing,
@@ -262,7 +268,7 @@ def convert(
         variants_chunk_size=variants_chunk_size,
         samples_chunk_size=samples_chunk_size,
     )
-    zarr_path = pathlib.Path(zarr_path)
+    zarr_path = pathlib.Path(vcz_path)
     vzw = vcz.VcfZarrWriter(TskitFormat, zarr_path)
     # Rough heuristic to split work up enough to keep utilisation high
     target_num_partitions = max(1, worker_processes * 4)

docs/_config.yml

@@ -24,14 +24,15 @@ html:
   extra_footer: |
       <p>
       Documentation available under the terms of the
-      <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a> 
+      <a href="https://creativecommons.org/publicdomain/zero/1.0/">CC0 1.0</a>
       license.
       </p>
 
 sphinx:
   extra_extensions:
     - sphinx_click.ext
     - sphinx.ext.todo
+    - sphinx.ext.autodoc
   config:
     html_show_copyright: false
     # This is needed to make sure that text is output in single block from
@@ -40,3 +41,6 @@ sphinx:
     todo_include_todos: true
     myst_enable_extensions:
       - colon_fence
+    intersphinx_mapping:
+      python: ["https://docs.python.org/3/", null]
+      tskit: ["https://tskit.dev/tskit/docs/stable", null]

docs/_toc.yml

@@ -9,6 +9,10 @@ chapters:
 - file: plink2zarr/overview
   sections:
   - file: plink2zarr/cli_ref
+- file: tskit2zarr/overview
+  sections:
+  - file: tskit2zarr/python_api
+  - file: tskit2zarr/cli_ref
 - file: vcfpartition/overview
   sections:
   - file: vcfpartition/cli_ref

docs/plink2zarr/cli_ref.md

@@ -14,4 +14,4 @@
 .. click:: bio2zarr.cli:convert_plink
    :prog: plink2zarr convert
    :nested: full
-
+```

docs/tskit2zarr/cli_ref.md

@@ -0,0 +1,18 @@
+(sec-tskit2zarr-cli-ref)=
+# CLI Reference
+
+% A note on cross references... There's some weird long-standing problem with
+% cross referencing program values in Sphinx, which means that we can't use
+% the built-in labels generated by sphinx-click. We can make our own explicit
+% targets, but these have to have slightly weird names to avoid conflicting
+% with what sphinx-click is doing. So, hence the cmd- prefix.
+% Based on: https://github.com/skypilot-org/skypilot/pull/2834
+
+```{eval-rst}
+
+.. _cmd-tskit2zarr-convert:
+.. click:: bio2zarr.cli:convert_tskit
+   :prog: tskit2zarr convert
+   :nested: full
+
+```

docs/tskit2zarr/overview.md

@@ -0,0 +1,10 @@
+(sec-tskit2zarr)=
+# tskit2zarr
+
+Convert tskit data to the
+[VCF Zarr specification](https://github.com/sgkit-dev/vcf-zarr-spec/)
+reliably in parallel.
+
+See {ref}`sec-tskit2zarr-cli-ref` for detailed documentation on
+command line options.
+

docs/tskit2zarr/python_api.md

@@ -0,0 +1,36 @@
+(sec-tskit2zarr-python-api)=
+# Python API
+
+Basic usage:
+```python
+import bio2zarr.tskit as ts2z
+
+ts2z.convert(ts_path, vcz_path, worker_processes=8)
+```
+
+This will convert the [tskit](https://tskit.dev) tree sequence stored
+at ``ts_path`` to VCF Zarr stored at ``vcz_path`` using 8 worker processes.
+The details of how we map from the
+tskit {ref}`tskit:sec_data_model` to VCF Zarr are taken care of by
+TreeSequence.map_to_vcf_model method, which is called with no
+parameters by default if the ``model_mapping`` parameter to
+{func}`~bio2zarr.tskit.convert` is not specified.
+
+For more control over the properties of the output, for example
+to pick a specific subset of individuals, you can use
+TreeSequence.map_to_vcf_model
+to return the required mapping:
+
+```python
+model_mapping = ts.map_vcf_model(individuals=[0, 1])
+ts2z.convert(ts, vcz_path, model_mapping=model_mapping)
+```
+
+
+## API reference
+
+```{eval-rst}
+
+.. autofunction:: bio2zarr.tskit.convert
+
+```