Merge pull request #328 from 10XGenomics/stephen/spaceranger4.0

Feat: Support for Visium HD cell segmentation in Space Ranger 4.0

Author: LucaMarconato

.github/workflows/prepare_test_data.yaml

@@ -49,7 +49,7 @@ jobs:
                   # the Visium HD dataset is licensed as CC BY 4.0, as shown here
                   # https://www.10xgenomics.com/support/software/space-ranger/latest/resources/visium-hd-example-data
 
-                  # 10x Genomics Visium HD 4.0.1 3' Mouse Brain
+                  # 10x Genomics Visium HD 4.0.1 3' Mouse Brain Chunk
                   curl -O https://cf.10xgenomics.com/samples/spatial-exp/4.0.1/Visium_HD_Tiny_3prime_Dataset/Visium_HD_Tiny_3prime_Dataset_outs.zip
 
                   # -------

pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "joblib",
     "imagecodecs",
     "dask-image",
-    "pyarrow",
+    "pyarrow<22.0.0",  # https://github.com/scverse/spatialdata-io/issues/334
     "readfcs",
     "tifffile>=2023.8.12",
     "ome-types",

src/spatialdata_io/__main__.py

@@ -412,11 +412,24 @@ def visium_wrapper(
     default=False,
     help="If true, annotates the table by labels. [default: False]",
 )
+@click.option(
+    "--load-segmentations-only",
+    default=None,
+    help="If `True`, only the segmented cell boundaries and their associated counts will be loaded. All binned data will be skipped. [default: None, which will fall back to `False` with a deprecation warning]",
+)
+@click.option(
+    "--load-nucleus-segmentations",
+    type=bool,
+    default=False,
+    help="If `True` and nucleus segmentation files are present, load nucleus segmentation polygons and the corresponding nucleus-filtered count table. [default: False]",
+)
 def visium_hd_wrapper(
     input: str,
     output: str,
     dataset_id: str | None = None,
     filtered_counts_file: bool = True,
+    load_segmentations_only: bool | None = None,
+    load_nucleus_segmentations: bool = False,
     bin_size: int | list[int] | None = None,
     bins_as_squares: bool = True,
     fullres_image_file: str | Path | None = None,
@@ -428,6 +441,8 @@ def visium_hd_wrapper(
         path=input,
         dataset_id=dataset_id,
         filtered_counts_file=filtered_counts_file,
+        load_segmentations_only=load_segmentations_only,
+        load_nucleus_segmentations=load_nucleus_segmentations,
         bin_size=bin_size,
         bins_as_squares=bins_as_squares,
         fullres_image_file=fullres_image_file,

src/spatialdata_io/_constants/_constants.py

@@ -356,11 +356,16 @@ class VisiumHDKeys(ModeEnum):
     BIN_PREFIX = "square_"
     MICROSCOPE_IMAGE = "microscope_image"
     BINNED_OUTPUTS = "binned_outputs"
+    SEGMENTATION_OUTPUTS = "segmented_outputs"
 
     # counts and locations files
     FILTERED_COUNTS_FILE = "filtered_feature_bc_matrix.h5"
     RAW_COUNTS_FILE = "raw_feature_bc_matrix.h5"
     TISSUE_POSITIONS_FILE = "tissue_positions.parquet"
+    BARCODE_MAPPINGS_FILE = "barcode_mappings.parquet"
+    FILTERED_CELL_COUNTS_FILE = "filtered_feature_cell_matrix.h5"
+    CELL_SEGMENTATION_GEOJSON_PATH = "cell_segmentations.geojson"
+    NUCLEUS_SEGMENTATION_GEOJSON_PATH = "nucleus_segmentations.geojson"
 
     # images
     IMAGE_HIRES_FILE = "tissue_hires_image.png"
@@ -402,3 +407,7 @@ class VisiumHDKeys(ModeEnum):
     MICROSCOPE_COLROW_TO_SPOT_COLROW = ("microscope_colrow_to_spot_colrow",)
     SPOT_COLROW_TO_MICROSCOPE_COLROW = ("spot_colrow_to_microscope_colrow",)
     FILE_FORMAT = "file_format"
+
+    # Cell Segmentation keys
+    CELL_SEG_KEY_HD = "cell_segmentations"
+    NUCLEUS_SEG_KEY_HD = "nucleus_segmentations"