Add experimental Pyxa (Stellaromics) reader

.github/workflows/prepare_test_data.yaml

@@ -85,6 +85,17 @@ jobs:
           # OMAP10 for format v0.x.x
           curl -o OMAP10_small.zip "https://zenodo.org/api/records/18196366/files-archive"
 
+          # -------
+          # Stellaromics Pyxa, 100 um cube cropped from the public demo dataset
+          # https://huggingface.co/datasets/Stellaromics/demo
+          mkdir -p pyxa_xsmall
+          for file in cell_assigned_gene_v1.csv cell_by_gene_v1.csv cell_metadata_v1.csv segmentation_geometries_v1.parquet mosaic_3d.ome.zarr.zip; do
+              curl -L -o "pyxa_xsmall/$file" "https://huggingface.co/datasets/Stellaromics/demo/resolve/main/xsmall/$file"
+          done
+          # the zipped OME-Zarr mosaic is extracted in place (it contains a single `mosaic_3d.ome.zarr/` directory)
+          unzip -q pyxa_xsmall/mosaic_3d.ome.zarr.zip -d pyxa_xsmall
+          rm pyxa_xsmall/mosaic_3d.ome.zarr.zip
+
       - name: Unzip files
         run: |
           cd ./data

README.md

@@ -48,6 +48,15 @@ Contributions for addressing the below limitations are very welcomed.
 
 - Only Stereo-seq 7.x is supported, 8.x is not currently supported. https://github.com/scverse/spatialdata-io/issues/161
 
+## Experimental readers
+
+Readers without (yet) a public specification for their raw data format live
+in `spatialdata_io.experimental` rather than the main technology list above.
+No stability guarantees are made for these.
+
+- Pyxa (Stellaromics): no public format specification yet; validated against
+  the public [demo dataset](https://huggingface.co/datasets/Stellaromics/demo).
+
 ## Getting started
 
 Please refer to the [documentation][link-docs]. In particular, the

src/spatialdata_io/__main__.py

@@ -910,6 +910,23 @@ def macsima_wrapper(
     sdata.write(output)
 
 
+@cli.command(name="pyxa")
+@_input_output_click_options
+@click.option("--dataset-id", type=str, default="pyxa", help="Dataset ID. [default: pyxa]")
+@click.option(
+    "--image-path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True),
+    default=None,
+    help="Path to a mosaic OME-Zarr image directory (e.g. DAPI). [default: None]",
+)
+def pyxa_wrapper(input: str, output: str, dataset_id: str = "pyxa", image_path: str | None = None) -> None:
+    """Pyxa (Stellaromics) conversion to SpatialData."""
+    from spatialdata_io.experimental import pyxa
+
+    sdata = pyxa(input, dataset_id=dataset_id, image_path=image_path)
+    sdata.write(output)
+
+
 @cli.command(name="generic")
 @click.option(
     "--input",

src/spatialdata_io/_constants/_constants.py

@@ -409,3 +409,45 @@ class VisiumHDKeys(ModeEnum):
     # Cell Segmentation keys
     CELL_SEG_KEY_HD = "cell_segmentations"
     NUCLEUS_SEG_KEY_HD = "nucleus_segmentations"
+
+
+class PyxaKeys(ModeEnum):
+    """Keys for *Pyxa* (Stellaromics) output.
+
+    No public specification exists yet; keys are validated against the public
+    demo dataset at https://huggingface.co/datasets/Stellaromics/demo.
+    """
+
+    # files
+    CELL_ASSIGNED_GENE_FILE = "cell_assigned_gene_v1.csv"
+    CELL_BY_GENE_FILE = "cell_by_gene_v1.csv"
+    CELL_METADATA_FILE = "cell_metadata_v1.csv"
+    SEGMENTATION_GEOMETRIES_FILE = "segmentation_geometries_v1.parquet"
+
+    # shared columns
+    CELL_ID = "cell_id"
+    GENE = "Gene"
+    X_UM = "X_um"
+    Y_UM = "Y_um"
+    Z_UM = "Z_um"
+    X_PIXELS = "X_pixels"
+    Y_PIXELS = "Y_pixels"
+    Z_PIXELS = "Z_pixels"
+    VOLUME_UM3 = "Volume_um3"
+    ROI = "ROI"
+    Z_INDEX = "ZIndex"
+    BORDER = "Border"
+    FOV = "FOV"
+
+    # unassigned transcripts have cell_id ending in this suffix, e.g. "Region_-1"
+    UNASSIGNED_SUFFIX = "_-1"
+
+    # constructed metadata
+    REGION_KEY = "region"
+    # per-cell footprint (union of the cell's z-plane polygons), annotated by the table
+    REGION = "cell_boundaries"
+    # per-cell, per-z-plane polygons, as stored on disk
+    CELL_BOUNDARIES_Z = "cell_boundaries_z"
+    INSTANCE_KEY = "cell_id"
+    ASSIGNED = "assigned"
+    MOSAIC_IMAGE = "mosaic_image"

src/spatialdata_io/experimental/__init__.py

@@ -3,9 +3,11 @@
     to_legacy_anndata,
 )
 from spatialdata_io.readers.iss import iss
+from spatialdata_io.readers.pyxa import pyxa
 
 _readers_technologies = [
     "iss",
+    "pyxa",
 ]
 _readers_file_types: list[str] = [
     # add experimental readers for new file types here