Merge pull request #315 from LucaMarconato/contribution-guide

Contribution guide

Author: LucaMarconato

.github/workflows/release.yaml

@@ -13,7 +13,7 @@ jobs:
             - name: Set up Python 3.12
               uses: actions/setup-python@v5
               with:
-                  python-version: "3.12"
+                  python-version: "3.13"
                   cache: pip
             - name: Install build dependencies
               run: python -m pip install --upgrade pip wheel twine build

.github/workflows/test.yaml

@@ -18,7 +18,7 @@ jobs:
         strategy:
             fail-fast: false
             matrix:
-                python: ["3.10", "3.12"]
+                python: ["3.11", "3.12", "3.13"]
                 os: [ubuntu-latest]
 
         env:
@@ -52,7 +52,7 @@ jobs:
                   pip install --pre -e ".[dev,test]"
 
             - name: Download artifact of test data
-              if: matrix.python == '3.12'
+              if: matrix.python == '3.13'
               uses: dawidd6/action-download-artifact@v9
               with:
                   workflow: prepare_test_data.yaml

README.md

@@ -14,6 +14,8 @@
 [badge-pypi]: https://badge.fury.io/py/spatialdata-io.svg
 [link-pypi]: https://pypi.org/project/spatialdata-io/
 
+_We encourage contributions from the community and from developers of spatial technologies. Please see the "How to Contribute" section below._
+
 This package contains reader functions to load common spatial omics formats into SpatialData. Currently, we provide support for:
 
 - 10x Genomics Visium®
@@ -32,6 +34,8 @@ This package contains reader functions to load common spatial omics formats into
 
 Note: all mentioned technologies are registered trademarks of their respective companies.
 
+Please refer to the list of [open Pull Requests](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen) for readers that are currently being developed.
+
 ## Known limitations
 
 Contributions for addressing the below limitations are very welcomed.
@@ -42,9 +46,7 @@ Contributions for addressing the below limitations are very welcomed.
 
 1. **Open a GitHub Issue**: Start by opening a new issue or commenting on an existing one in the repository. Clearly describe the problem and your proposed changes to avoid overlapping efforts with others.
 
-2. **Submit a Pull Request (PR)**: Once the issue is discussed, submit a PR to the `spatialdata-io` repository. Ensure your PR includes information about a suitable dataset for testing the reader, ideally no larger than 10 GB. Include clear instructions for accessing the data, preferably with a `curl` or `wget` command for easy downloading.
-
-3. **Optional Enhancements**: To facilitate reproducibility and ease of data access, consider adding a folder in the [spatialdata-sandbox](https://github.com/giovp/spatialdata-sandbox) repository. Include a `download.py` and `to_zarr.py` script (refer to examples in the repository) to enable others to reproduce your reader by simply running these scripts sequentially.
+2. **Submit a Pull Request (PR)**: Once the issue is discussed, submit a PR to the `spatialdata-io` repository. If you are contributing a new reader, or extending the reader for a new versions of a technologies, please consult our [contribution guide](https://spatialdata.scverse.org/projects/io/en/latest/contributing.html), which describes the steps to ensure that the pull request can be tested on suitable example data and reviewed efficiently.
 
 ## Getting started
 

docs/conf.py

@@ -23,7 +23,7 @@
 info = metadata("spatialdata-io")
 project_name = info["Name"]
 author = info["Author"]
-copyright = f"{datetime.now():%Y}, {author}."
+copyright = f"{datetime.now():%Y}, {author}"
 version = info["Version"]
 repository_url = f"https://github.com/scverse/{project_name}"
 

docs/contributing.md

@@ -10,7 +10,7 @@ dynamic= [
 ]
 description = "SpatialData IO for common techs"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 license = {file = "LICENSE"}
 authors = [
     {name = "scverse"},

pyproject.toml

@@ -25,6 +25,6 @@ def skip_if_below_python_version() -> pytest.mark.skipif:
     >>> def test_some_feature():
     >>>     assert True
     """
-    MIN_VERSION = (3, 12)
+    MIN_VERSION = (3, 13)
     reason = f"Test requires Python {'.'.join(map(str, MIN_VERSION))} or higher"
     return pytest.mark.skipif(sys.version_info < MIN_VERSION, reason=reason)

tests/_utils.py

@@ -5,7 +5,8 @@
 import numpy as np
 import pytest
 from click.testing import CliRunner
-from spatialdata import read_zarr
+from spatialdata import match_table_to_element, read_zarr
+from spatialdata.models import TableModel, get_table_keys
 
 from spatialdata_io.__main__ import xenium_wrapper
 from spatialdata_io.readers.xenium import (
@@ -51,11 +52,17 @@ def test_roundtrip_with_data_limits() -> None:
 @pytest.mark.parametrize(
     "dataset,expected",
     [
-        ("Xenium_V1_human_Breast_2fov_outs", "{'y': (0, 3529), 'x': (0, 5792), 'z': (10, 25)}"),
-        ("Xenium_V1_human_Lung_2fov_outs", "{'y': (0, 3553), 'x': (0, 5793), 'z': (7, 32)}"),
+        (
+            "Xenium_V1_human_Breast_2fov_outs",
+            "{'y': (0, 3529), 'x': (0, 5792), 'z': (10, 25)}",
+        ),
+        (
+            "Xenium_V1_human_Lung_2fov_outs",
+            "{'y': (0, 3553), 'x': (0, 5793), 'z': (7, 32)}",
+        ),
     ],
 )
-def test_example_data(dataset: str, expected: str) -> None:
+def test_example_data_data_extent(dataset: str, expected: str) -> None:
     f = Path("./data") / dataset
     assert f.is_dir()
     sdata = xenium(f, cells_as_circles=False)
@@ -66,6 +73,67 @@ def test_example_data(dataset: str, expected: str) -> None:
     assert str(extent) == expected
 
 
+# TODO: add tests for Xenium 3.0.0
+@skip_if_below_python_version()
+@pytest.mark.parametrize("dataset", ["Xenium_V1_human_Breast_2fov_outs", "Xenium_V1_human_Lung_2fov_outs"])
+def test_example_data_index_integrity(dataset: str) -> None:
+    f = Path("./data") / dataset
+    assert f.is_dir()
+    sdata = xenium(f, cells_as_circles=False)
+
+    if dataset == "Xenium_V1_human_Breast_2fov_outs":
+        # fmt: off
+        # test elements
+        assert sdata["morphology_focus"]["scale0"]["image"].sel(c="DAPI", y=20.5, x=20.5).data.compute() == 94
+        assert sdata["morphology_focus"]["scale0"]["image"].sel(c="AlphaSMA/Vimentin", y=3528.5, x=5775.5).data.compute() == 1
+        assert sdata["cell_labels"]["scale0"]["image"].sel(y=73.5, x=33.5).data.compute() == 4088
+        assert sdata["cell_labels"]["scale0"]["image"].sel(y=76.5, x=33.5).data.compute() == 4081
+        assert sdata["nucleus_labels"]["scale0"]["image"].sel(y=11.5, x=1687.5).data.compute() == 5030
+        assert sdata["nucleus_labels"]["scale0"]["image"].sel(y=3515.5, x=4618.5).data.compute() == 6392
+        assert np.allclose(sdata['transcripts'].compute().loc[[0, 10000, 1113949]]['x'], [2.608911, 194.917831, 1227.499268])
+        assert np.isclose(sdata['cell_boundaries'].loc['oipggjko-1'].geometry.centroid.x,736.4864931162789)
+        assert np.isclose(sdata['nucleus_boundaries'].loc['oipggjko-1'].geometry.centroid.x,736.4931256878282)
+        assert np.array_equal(sdata['table'].X.indices[:3], [1, 3, 34])
+        # fmt: on
+
+        # test table annotation
+        region, region_key, instance_key = get_table_keys(sdata["table"])
+        assert region == "cell_labels"
+        matched_table = match_table_to_element(sdata, element_name=region, table_name="table")
+        assert len(matched_table) == 7275
+        assert matched_table.obs["cell_id"][:3].tolist() == [
+            "aaaiikim-1",
+            "aaaljapa-1",
+            "aabhbgmg-1",
+        ]
+    else:
+        assert dataset == "Xenium_V1_human_Lung_2fov_outs"
+        # fmt: off
+        # test elements
+        assert sdata["morphology_focus"]["scale0"]["image"].sel(c="DAPI", y=0.5, x=2215.5).data.compute() == 1
+        assert sdata["morphology_focus"]["scale0"]["image"].sel(c="DAPI", y=11.5, x=4437.5).data.compute() == 2007
+        assert sdata["cell_labels"]["scale0"]["image"].sel(y=0.5, x=2940.5).data.compute() == 2605
+        assert sdata["cell_labels"]["scale0"]["image"].sel(y=3.5, x=4801.5).data.compute() == 7618
+        assert sdata["nucleus_labels"]["scale0"]["image"].sel(y=8.5, x=4359.5).data.compute() == 7000
+        assert sdata["nucleus_labels"]["scale0"]["image"].sel(y=18.5, x=3015.5).data.compute() == 2764
+        assert np.allclose(sdata['transcripts'].compute().loc[[0, 10000, 20000]]['x'], [174.258392, 12.210024, 214.759186])
+        assert np.isclose(sdata['cell_boundaries'].loc['aaanbaof-1'].geometry.centroid.x, 43.96894317275074)
+        assert np.isclose(sdata['nucleus_boundaries'].loc['aaanbaof-1'].geometry.centroid.x,43.31874577809517)
+        assert np.array_equal(sdata['table'].X.indices[:3], [1, 8, 19])
+        # fmt: on
+
+        # test table annotation
+        region, region_key, instance_key = get_table_keys(sdata["table"])
+        assert region == "cell_labels"
+        matched_table = match_table_to_element(sdata, element_name=region, table_name="table")
+        assert len(matched_table) == 11898
+        assert matched_table.obs["cell_id"][:3].tolist() == [
+            "aaafiiei-1",
+            "aaanbaof-1",
+            "aabdiein-1",
+        ]
+
+
 # TODO: add tests for Xenium 3.0.0
 @skip_if_below_python_version()
 @pytest.mark.parametrize("dataset", ["Xenium_V1_human_Breast_2fov_outs", "Xenium_V1_human_Lung_2fov_outs"])