Finalise tskit

[jeromekelleher]

Closes #232
Fixes #377

[coveralls]

coverage: 98.286% (+0.07%) from 98.212%
when pulling bf317ff on jeromekelleher:finalise-tskit
into 6eb88ed on sgkit-dev:main.

[jeromekelleher]

I think this is nearly ready to go. There's some details about how we deal with coordinate systems between tskit and VCZ which I'm going to punt on, but I think we should be able to handle the vast majority of inputs well with this.

I've added an initial framework for the Python API, just documenting a single function bio2zarr.tskit.convert. I think this is a good start (and will add the same for vcf when I get a chance). I had to skip some of the intersphinx linking for now, as the latest version of the docs don't seem to be live for tskit.

[benjeffery]

Looks, good. One nit in the docs.

One concern I have is that a key argument to convert is a tskit VcfModelMapping (or something that duck-types to a VCFModelMapping) that is currently undocumented in tskit. We should add docs in tskit and make its constructor part of the public API.

[benjeffery]

To answer the comment question: The base class defines Source.path which is used when we process out-of-core to put the path in metadata. This isn't used for tskit (at least for now) so I guess TskitFormat.path could just raise NotImplemented and the path not be stored.

[hyanwong]

Can .convert() (or perhaps another function) return a handle to the vcz object, for use in tsinfer? So that we can do

tsinfer.infer(tsinfer.VariantData(returned_handle, ancestral_state="ancestral_allele"))

[jeromekelleher]

No, that's out of scope because would greatly complicate the semantics (should the returned object be a Zarr hierarchy, or an Xarray dataset? Should it be in read-only mode?). Bio2zarr just deals with the on-disk formats, not providing python APIs for working with them. Bio2zarr will always create an on-disk representation, so returning a handle would just be abstracting the details of where the temporary files are kept.

I think tsinfer should probably write a wrapper which creates a temporary directory and does the conversion so that you can use it like this:

with tsinfer.VariantData.from_tree_sequence(ts) as data:
    tsinfer.infer(data)

That'll take care of a lot of the messiness.

[hyanwong]

Ah, OK. I had gathered that bio2zarr might also create in-memory representations, which I use quite a lot. But yes, a wrapper would be fine, I guess, assuming temporary directories etc are available.