Finish up docs for plink and update CHANGELOG

Add the docs files

Author: jeromekelleher

CHANGELOG.md

@@ -1,10 +1,8 @@
 # 0.1.6 2025-0X-XX
 
-- Make format-specific dependencies optional (#385)
-
-- Add contigs to plink output (#344)
+- Initial version of supported plink2zarr (#390, #344, #382)
 
-- Add variant_length and indexing to plink output (#382)
+- Make format-specific dependencies optional (#385)
 
 Breaking changes
 
@@ -14,6 +12,8 @@ Breaking changes
 - Add dimensions and default compressor and filter settings to the schema.
   (#361)
 
+- Various changes to existing experimental plink encoding (#390)
+
 # 0.1.5 2025-03-31
 
 - Add support for merging contig IDs across multiple VCFs (#335)

docs/_toc.yml

@@ -6,6 +6,9 @@ chapters:
   sections:
   - file: vcf2zarr/tutorial
   - file: vcf2zarr/cli_ref
+- file: plink2zarr/overview
+  sections:
+  - file: plink2zarr/cli_ref
 - file: vcfpartition/overview
   sections:
   - file: vcfpartition/cli_ref

docs/intro.md

@@ -8,6 +8,9 @@
 - {ref}`sec-vcf2zarr` converts VCF data to
   [VCF Zarr](https://github.com/sgkit-dev/vcf-zarr-spec/) format.
 
+- {ref}`sec-plink2zarr` converts PLINK 1.0 data to
+  [VCF Zarr](https://github.com/sgkit-dev/vcf-zarr-spec/) format.
+
 - {ref}`sec-vcfpartition` is a utility to split an input
   VCF into a given number of partitions. This is useful for
   parallel processing of VCF data.
@@ -17,10 +20,8 @@
 `bio2zarr` is in development, contributions, feedback and issues are welcome
 at the [GitHub repository](https://github.com/sgkit-dev/bio2zarr).
 
-Support for converting PLINK data to VCF Zarr is partially implemented,
-and adding BGEN and [tskit](https://tskit.dev/) support is also planned.
 If you would like to see
-support for other formats (or an interested in helping with implementing),
+support for other formats such as BGEN (or an interested in helping with implementing),
 please open an [issue on Github](https://github.com/sgkit-dev/bio2zarr/issues)
 to discuss!
 

docs/plink2zarr/cli_ref.md

@@ -0,0 +1,17 @@
+(sec-plink2zarr-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-plink2zarr-convert:
+.. click:: bio2zarr.cli:convert_plink
+   :prog: plink2zarr convert
+   :nested: full
+

docs/plink2zarr/overview.md

@@ -0,0 +1,38 @@
+(sec-plink2zarr)=
+# plink2zarr
+
+Convert plink data to the
+[VCF Zarr specification](https://github.com/sgkit-dev/vcf-zarr-spec/)
+reliably in parallel.
+
+See {ref}`sec-plink2zarr-cli-ref` for detailed documentation on
+command line options.
+
+Conversion of the plink data model to VCF follows the semantics of plink1.9 as closely
+as possible. That is, given a binary plink fileset with prefix "fileset" (i.e.,
+fileset.bed, fileset.bim, fileset.fam), running
+```
+$ plink2zarr convert fileset out.vcz
+```
+should produce the same result in ``out.vcz`` as
+```
+$ plink1.9 --bfile fileset --keep-allele-order --recode vcf-iid --out tmp
+$ vcf2zarr convert tmp.vcf out.vcz
+```
+
+:::{warning}
+It is important to note that we follow the same conventions as plink 2.0
+where the A1 allele in the [bim file](https://www.cog-genomics.org/plink/2.0/formats#bim)
+is the VCF ALT and A2 is the REF.
+:::
+
+:::{note}
+Currently we only convert the basic VCF-like data from plink, and don't include
+phenotypes and pedigree information. These are planned as future enhancements.
+Please comment on [this issue](https://github.com/sgkit-dev/bio2zarr/issues/392)
+if you are interested in this functionality.
+:::
+
+
+
+