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

CHANGELOG.md

@@ -16,6 +16,7 @@ Release notes for `v0.7.1` and earlier are available on the [Releases][] page.
 ### Added
 
 - `spatialdata_io` ships a `py.typed` marker, so downstream type checkers use its annotations.
+- Experimental `pyxa` reader (Stellaromics Pyxa): table (sparse counts, Pyxa Studio clusters/UMAP), transcripts, segmentation shapes, mosaic image (directory or zip), and with `labels=True` 3D cell labels on the mosaic grid.
 
 ### Changed
 

README.md

@@ -48,6 +48,16 @@ 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).
+  `labels=True` adds 3D cell labels on the mosaic grid.
+
 ## Getting started
 
 Please refer to the [documentation][link-docs]. In particular, the

pyproject.toml

@@ -33,6 +33,7 @@ dependencies = [
   "joblib",
   "numpy",
   "ome-types",
+  "pillow",
   "pyarrow",
   "readfcs",
   "scanpy",
@@ -157,6 +158,7 @@ exclude = "^tests/data/"
 module = [
   "dask_image.*",
   "h5py.*",
+  "joblib.*",
   "multiscale_spatial_image.*",
   "pyarrow.*",
   "rasterio.*",

src/spatialdata_io/__main__.py

@@ -910,6 +910,61 @@ 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",
+    type=click.Path(exists=True, file_okay=True, dir_okay=True),
+    default=None,
+    help="Mosaic OME-Zarr directory or zip, if not in the input directory. [default: found in the input]",
+)
+@click.option("--no-image", is_flag=True, default=False, help="Leave out the mosaic even if present.")
+@click.option(
+    "--pyxa-studio",
+    type=click.Path(exists=True, file_okay=True, dir_okay=False),
+    default=None,
+    help="Path to a Pyxa Studio export (cluster labels, UMAP) outside the input directory. [default: None]",
+)
+@click.option(
+    "--skip",
+    type=click.Choice(["cell_assigned_gene", "segmentation_geometries", "pyxa_studio"]),
+    multiple=True,
+    help="Optional input file to leave out even if present; repeatable. [default: none]",
+)
+@click.option("--labels", is_flag=True, default=False, help="Rasterize 3D cell labels onto the mosaic's grid.")
+@click.option(
+    "--shapes/--no-shapes",
+    default=None,
+    help="Return the polygons as shapes. [default: when read and --labels is not set]",
+)
+def pyxa_wrapper(
+    input: str,
+    output: str,
+    dataset_id: str = "pyxa",
+    image: str | None = None,
+    no_image: bool = False,
+    pyxa_studio: str | None = None,
+    skip: tuple[str, ...] = (),
+    labels: bool = False,
+    shapes: bool | None = None,
+) -> None:
+    """Pyxa (Stellaromics) conversion to SpatialData."""
+    from spatialdata_io.experimental import pyxa
+
+    if no_image and image is not None:
+        raise click.UsageError("--image and --no-image are mutually exclusive")
+    inputs: dict[str, str | bool] = dict.fromkeys(skip, False)
+    if pyxa_studio is not None and "pyxa_studio" not in skip:
+        inputs["pyxa_studio"] = pyxa_studio
+    if no_image:
+        inputs["image"] = False
+    elif image is not None:
+        inputs["image"] = image
+    sdata = pyxa(input, dataset_id=dataset_id, labels=labels, shapes=shapes, **inputs)  # type: ignore[arg-type]
+    sdata.write(output)
+
+
 @cli.command(name="generic")
 @click.option(
     "--input",

src/spatialdata_io/_constants/_constants.py

@@ -409,3 +409,59 @@ 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"
+    # Pyxa Studio export: cells that passed Pyxa's filters, with cluster labels and a 3D UMAP
+    PYXA_STUDIO_FILE = "pyxa_studio_v1.csv"
+
+    # 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"
+    CLUSTER = "Cluster"
+    X_UMAP = "X_UMAP"
+    Y_UMAP = "Y_UMAP"
+    Z_UMAP = "Z_UMAP"
+
+    # 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"
+    UMAP_KEY = "X_umap"
+
+    # mosaic image, looked up in the Pyxa directory (unzipped or zipped, as on the Hub)
+    MOSAIC_FILE = "mosaic_3d.ome.zarr"
+    MOSAIC_ZIP_FILE = "mosaic_3d.ome.zarr.zip"
+    # 3D cell labels rasterized from the segmentation polygons onto the mosaic's grid
+    CELL_LABELS = "cell_labels"
+    LABEL_ID = "label_id"

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