sgkit zarr 3 migration

.github/workflows/build-gpu.yml

@@ -49,7 +49,7 @@ jobs:
         run: |
           conda install -c nvidia cudatoolkit
           # Avoid building SciPy from source in CI.
-          uv pip install --only-binary scipy --python "$CONDA_PREFIX/bin/python" -e ".[bgen,plink]" --group test
+          uv pip install --only-binary scipy --python "$CONDA_PREFIX/bin/python" -e . --group test
 
       - name: Numba Information
         run: |

.github/workflows/build.yml

@@ -41,14 +41,11 @@ jobs:
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
 
-  test-zarr-version:
-    name: Test Zarr Python v3
+  test-xarray-minimum:
+    name: Test minimum Xarray
     # Scheduled runs only on the origin org
     if: (github.event_name == 'schedule' && github.repository_owner == 'sgkit-dev') || (github.event_name != 'schedule')
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        zarr: [">=3"]
     steps:
       - uses: actions/checkout@v7
       - uses: actions/setup-python@v7
@@ -63,10 +60,9 @@ jobs:
       - name: Install dependencies
         run: |
           uv sync --locked --all-extras --group test --no-default-groups --python 3.11
-      - name: Install zarr${{ matrix.zarr }}
+      - name: Install minimum supported Xarray
         run: |
-          uv pip install --python .venv --pre 'zarr${{ matrix.zarr }}'
-          uv pip uninstall --python .venv bio2zarr  # TODO: remove when bio2zarr supports Zarr Python 3
+          uv pip install --python .venv 'xarray==2026.9.0'
       - name: Run tests
         run: |
           uv run --no-sync pytest

.github/workflows/wheels.yml

@@ -81,10 +81,8 @@ jobs:
           # Avoid building SciPy from source in CI.
           wheel=$(ls artifact/sgkit-*.whl)
           uv venv --python "${{ matrix.python-version }}"
-          uv pip install --python .venv --only-binary scipy "${wheel}[bgen,plink]"
+          uv pip install --python .venv --only-binary scipy "${wheel}"
           uv run --no-sync python sgkit-copy/.github/scripts/test_sgkit.py
-          uv run --no-sync python sgkit-copy/.github/scripts/test_sgkit_bgen.py
-          uv run --no-sync python sgkit-copy/.github/scripts/test_sgkit_plink.py
 
   windows-test:
     # This workflow only runs on the origin org
@@ -120,10 +118,8 @@ jobs:
           # Avoid building SciPy from source in CI.
           $wheel = (Get-ChildItem artifact/sgkit-*.whl).FullName
           uv venv --python "${{ matrix.python-version }}"
-          uv pip install --python .venv --only-binary scipy "${wheel}[bgen,plink]"
+          uv pip install --python .venv --only-binary scipy "${wheel}"
           uv run --no-sync python sgkit-copy/.github/scripts/test_sgkit.py
-          uv run --no-sync python sgkit-copy/.github/scripts/test_sgkit_bgen.py
-          uv run --no-sync python sgkit-copy/.github/scripts/test_sgkit_plink.py
 
 
   pypi-upload:

README.md

@@ -10,6 +10,14 @@ general-purpose frameworks such as [Xarray](http://xarray.pydata.org/en/stable/)
 
 For more information on using sgkit, see the [documentation](https://sgkit-dev.github.io/sgkit/).
 
+**Genetic file conversion:** Use [bio2zarr](https://sgkit-dev.github.io/bio2zarr/)
+to convert genetic file formats to Zarr, then load them with `sgkit.load_dataset`.
+The BGEN reader, conversion functions and `bgen` extra have been removed;
+sgkit no longer depends on cbgen. Use a bio2zarr version with BGEN support
+(tracked in [bio2zarr issue 417](https://github.com/sgkit-dev/bio2zarr/issues/417)).
+See the [BGEN migration guide](docs/user_guide.rst#bgen) for details and
+`unpack_variables`, retained only for existing legacy packed Zarr stores.
+
 [//]: # (numfocus-fiscal-sponsor-attribution)
 
 The sgkit project uses a [custom governance model](./GOVERNANCE.md) 

docs/api.rst

@@ -9,32 +9,33 @@ IO/imports and exports
 
 See :ref:`reading_and_writing_genetic_data`
 
+.. important::
+
+   **Use bio2zarr for genetic file format conversion to Zarr**, then load the
+   converted dataset with :func:`sgkit.load_dataset`. The BGEN and PLINK
+   readers and conversion functions have been removed. See
+   :ref:`bgen_conversion_migration` and :ref:`plink_conversion_migration`
+   for migration guidance.
+
 BGEN
 -----
 
+Only the helper for existing legacy packed stores remains; it does not read
+BGEN files or require an optional backend.
+
 .. currentmodule:: sgkit.io.bgen
 .. autosummary::
    :toctree: generated/
 
-   bgen_to_zarr
-   read_bgen
-   rechunk_bgen
+   unpack_variables
 
 PLINK
 -----
 
-.. deprecated:: 0.11.0
-   Functions for reading and writing plink are deprecated, please use the `bio2zarr <https://github.com/sgkit-dev/bio2zarr>`_
-   and `vcztools <https://github.com/sgkit-dev/vcztools>`_ packages.
-
-.. currentmodule:: sgkit.io.plink
-.. autosummary::
-   :toctree: generated/
-
-   plink_to_zarr
-   read_plink
-   write_plink
-   zarr_to_plink
+Functions for reading and writing PLINK have been removed from sgkit. Use
+`bio2zarr <https://github.com/sgkit-dev/bio2zarr>`_ for conversion to Zarr and
+`vcztools <https://github.com/sgkit-dev/vcztools>`_ for export.
+See :ref:`plink_conversion_migration`.
 
 VCF
 -------------

docs/changelog.rst

@@ -11,26 +11,57 @@ Changelog
 .. New Features
 .. ~~~~~~~~~~~~
 
-.. Breaking changes
-.. ~~~~~~~~~~~~~~~~
+Breaking changes
+~~~~~~~~~~~~~~~~
+
+- Require Zarr Python >= 3 and Xarray >= 2026.9.0. The default on-disk Zarr
+  format remains 2. (:issue:`1355`)
+- **Remove BGEN reading and conversion**: ``sgkit.io.bgen.read_bgen``,
+  ``sgkit.io.bgen.bgen_to_zarr`` and ``sgkit.io.bgen.rechunk_bgen``, along with
+  the ``bgen`` extra and the cbgen and rechunker dependencies.
+  **Use bio2zarr for genetic file format conversion to Zarr**, and load the
+  result with :func:`load_dataset`. BGEN input requires a bio2zarr version
+  with BGEN support
+  (`bio2zarr issue 417 <https://github.com/sgkit-dev/bio2zarr/issues/417>`_).
+  The dependency-free :func:`sgkit.io.bgen.unpack_variables` helper remains
+  for existing legacy packed stores. See :ref:`bgen_conversion_migration`.
+  (:pr:`1325`, :issue:`1355`)
+- **Remove PLINK reading and writing**: the ``sgkit.io.plink`` module and its
+  ``read_plink``, ``plink_to_zarr``, ``write_plink`` and ``zarr_to_plink``
+  functions, along with the ``plink`` extra and bed-reader dependency.
+  Use bio2zarr for conversion to Zarr and vcztools for export.
+  See :ref:`plink_conversion_migration`, including companion-file metadata
+  differences. (:pr:`1324`, :pr:`1362`, :issue:`1318`)
 
 Deprecations
 ~~~~~~~~~~~~
 
-- Functions for reading and writing plink are deprecated, please use the `bio2zarr <https://github.com/sgkit-dev/bio2zarr>`_
-  and `vcztools <https://github.com/sgkit-dev/vcztools>`_ packages.
+- BGEN reading and conversion have moved out of sgkit. Use
+  `bio2zarr <https://github.com/sgkit-dev/bio2zarr>`_ for BGEN-to-Zarr conversion
+  and :func:`load_dataset` for analysis. ``read_bgen``, ``bgen_to_zarr`` and
+  ``rechunk_bgen`` are already removed
+  in this release; see Breaking changes above and
+  :ref:`bgen_conversion_migration`. Only the dependency-free
+  :func:`sgkit.io.bgen.unpack_variables` helper remains for legacy packed stores.
+  (:pr:`1325`, :issue:`1331`, :issue:`1355`)
+- Previously deprecated PLINK reading and writing functions are now removed;
+  see Breaking changes above and :ref:`plink_conversion_migration`.
+  Use the `bio2zarr <https://github.com/sgkit-dev/bio2zarr>`_ and
+  `vcztools <https://github.com/sgkit-dev/vcztools>`_ packages instead.
   (:user:`tomwhite`, :pr:`1324`, :issue:`1318`)
-- Using rechunker for rechunking in sgkit is deprecated, please use the the
-  `Xarray chunk <https://docs.xarray.dev/en/stable/generated/xarray.Dataset.chunk.html#xarray.Dataset.chunk>`_
-  function directly.
-  (:user:`tomwhite`, :pr:`1325`)
 
 .. Improvements
 .. ~~~~~~~~~~~~
 
 Bug fixes
 ~~~~~~~~~
 
+- Unpacking legacy BGEN-derived Zarr datasets no longer imports or requires
+  cbgen. Use :func:`sgkit.io.bgen.unpack_variables`; the original
+  ``sgkit.io.bgen.bgen_reader.unpack_variables`` import is also preserved.
+  Its documentation explains the legacy packing convention and when unpacking
+  is needed; ordinary unpacked datasets and new bio2zarr output do not need it.
+  (:issue:`1331`)
 - Fixed bug causing high memory usage in :func:`pedigree_kinship` when
   evaluating a chunked relationship matrix with the Hamilton-Kerr method.
   (:user:`timothymillar`, :pr:`1335`, :issue:`1333`)
@@ -187,14 +218,14 @@ Documentation
 New Features
 ~~~~~~~~~~~~
 
-- Add :func:`sgkit.io.plink.write_plink` function.
+- Add ``sgkit.io.plink.write_plink`` function.
   (:user:`tomwhite`, :pr:`1003`, :issue:`926`)
 
 - Add ``phased`` option to :func:`simulate_genotype_call_dataset` function.
   (:user:`tomwhite`, :pr:`1022`, :issue:`973`)
 
-- Add :func:`sgkit.io.plink.plink_to_zarr` and
-  :func:`sgkit.io.plink.zarr_to_plink` convenience functions
+- Add ``sgkit.io.plink.plink_to_zarr`` and
+  ``sgkit.io.plink.zarr_to_plink`` convenience functions
   (:user:`tomwhite`, :pr:`1047`, :issue:`1004`)
 
 - Add :func:`sgkit.convert_call_to_index` method.
@@ -315,7 +346,7 @@ Breaking changes
 
 - Remove support for Python 3.7.
   (:user:`tomwhite`, :pr:`927`, :issue:`802`)
-- The ``count_a1`` parameter to :func:`sgkit.io.plink.read_plink` previously
+- The ``count_a1`` parameter to ``sgkit.io.plink.read_plink`` previously
   defaulted to ``True`` but now defaults to ``False``. Furthermore, ``True``
   is no longer supported since it is not clear how it should behave.
   (:user:`tomwhite`, :pr:`952`, :issue:`947`)

docs/conf.py

@@ -117,7 +117,11 @@ def filter(self, record: pylogging.LogRecord) -> bool:
 
 autosummary_generate = True
 
-nitpick_ignore = [("py:class", "sgkit.display.GenotypeDisplay")]
+nitpick_ignore = [
+    ("py:class", "sgkit.display.GenotypeDisplay"),
+    # Zarr's StoreLike alias is rendered as an undocumented TypeAliasType.
+    ("py:class", "zarr.storage._common.TypeAliasType"),
+]
 
 
 # FIXME: Workaround for linking xarray module
@@ -130,6 +134,7 @@ def filter(self, record: pylogging.LogRecord) -> bool:
 
 intersphinx_mapping = dict(
     dask=("https://docs.dask.org/en/stable/", None),
+    fsspec=("https://filesystem-spec.readthedocs.io/en/latest/", None),
     xarray=("https://docs.xarray.dev/en/stable/", None),
     zarr=("https://zarr.readthedocs.io/en/stable", None),
     numpy=("https://numpy.org/doc/stable/", None),

docs/contributing.rst

@@ -95,7 +95,7 @@ Install `uv <https://docs.astral.sh/uv/getting-started/installation/>`_
   uv sync
 
 This installs sgkit in editable mode with the ``dev`` dependency group, including
-the dependencies needed to test its optional I/O formats. Use ``uv run`` to run
+the dependencies needed to test compatibility with bio2zarr. Use ``uv run`` to run
 commands in this environment without activating it.