Add experimental Pyxa (Stellaromics) reader

[ckmah]

Adds an experimental reader for Stellaromics Pyxa output, spatialdata_io.experimental.pyxa(), plus a pyxa CLI command.

What it reads

File	Element
cell_by_gene_v1.csv + cell_metadata_v1.csv (required)	rna table: sparse counts in X, obsm["spatial"] in µm
pyxa_studio_v1.csv	Cluster (categorical) and obsm["X_umap"] on the rna table; cells Pyxa Studio filtered out keep missing values
cell_assigned_gene_v1.csv	transcripts (3D points; unassigned transcripts, with a cell_id ending in _-1, are kept and flagged by an assigned column)
segmentation_geometries_v1.parquet	cell_boundaries (one footprint per cell, annotated by rna) and cell_boundaries_z (one polygon per cell per z-plane)
mosaic_3d.ome.zarr, or mosaic_3d.ome.zarr.zip read in place	mosaic_image, multiscale, using the pyramid levels already in the store
segmentation_geometries_v1.parquet + mosaic, with labels=True	cell_labels: 3D labels on the mosaic's voxel grid (same levels and transform as mosaic_image), annotated by rna

Each optional file is read when it is in path. Passing False skips it, True requires it, and a path reads that file from elsewhere. image= works the same way for the mosaic, directory or zip. shapes= controls the shapes: by default they are returned when the polygons are read and labels is False.

Every element is in µm in the global coordinate system:

• The segmentation polygons are stored in pixels. The reader scales them to µm, then repairs and checks the ones that the float scaling makes self-intersecting.
• Their z-plane centre is added as a Z_um column, since shapes are 2D in spatialdata.
• The xy and z voxel sizes are fitted from a sample of cell_metadata rows, where each cell centroid is given in both pixels and µm. The reader raises an error if the two aren't related by a pure scale.

Each cell's centroid in cell_metadata is exactly the area-weighted centroid of its polygons, which the tests check in x, y and z.

Cells stacked in z have overlapping footprints. cell_boundaries is therefore meant for 2D display and table annotation, not for 2D spatial aggregation.

3D cell labels (labels=True)

The polygons are rasterized onto the mosaic's grid, so labels and image overlay voxel for voxel. The table then annotates cell_labels through an integer label_id: the trailing integer of cell_id (Region_17 → 17) when those are unique, positive and below 2³¹, otherwise 1..n in table order.

• Lazy. Level 0 is one dask.delayed drawing task per 32 × 1024 × 1024 tile, run when the element is computed or written. Coarser levels are strided (nearest-neighbour) views of level 0, sampled at block centres like the mosaic's own pyramid, with steps taken from the mosaic's OME-NGFF scales. spatialdata writes all levels in one compute, so each tile is drawn once per write.
• Polygon decoding is eager. It runs one task per parquet row group in joblib worker processes (prefer="processes"; configurable with joblib.parallel_config), streaming 65,536-row batches. The workers are shut down afterwards.
• Drawing uses Pillow. Where two cells overlap on a plane, the higher label wins. Holes are filled.
• Scale. On a full region (492k cells, 23.2M polygons, 284 × 9,786 × 11,889 mosaic): reading takes about 1.5 min, writing about 6 min, with a peak of about 30 GB. On a 32 × 1024 × 1024 window, level-0 voxels agreed 99.9994% with an independent rasterizer. That was measured before a tile-seam fix; the fix changed only voxels on tile seams.

Specification

There is no public format specification yet, so the reader is under experimental. It is validated against the public Stellaromics/demo dataset (BSD 3-Clause).

Test data

• xsmall/ in that dataset is a 100 × 100 × 100 µm crop: 187 cells, about 23k transcripts and the DAPI mosaic, about 8 MB in total.
• prepare_test_data.yaml downloads it to data/pyxa_xsmall.
• Until the shared CI artifact is regenerated with pyxa_xsmall (the workflow notes this needs a branch in this repository), tests/test_pyxa.py downloads the same 5 files from the Hub when data/pyxa_xsmall is missing, in a way that is safe with pytest -n auto, and skips the module if the download fails. That fallback can be removed once the artifact has the data.

Scripts to download and convert the dataset are in giovp/spatialdata-sandbox#65 (pyxa_v1_io).

Tests (tests/test_pyxa.py, 75)

• Example data: data extent, index integrity of every element, the table annotation joins, and the CLI (--labels, --no-shapes, --image/--no-image, --skip).
• Mosaic: loading from the directory, from a zip (a single top-level entry, the group at the root, or with __MACOSX/ present), default lookup, image=False.
• Labels:
  • label-id rules and fallbacks;
  • ring decoding (empty parquet, polygons off the z range, cells not in the table, several row groups, batches smaller than a row group);
  • tile planning and drawing (a square, higher label wins, seams at fractional edges and for random rings);
  • laziness, and each level-0 tile drawn once per write;
  • coarse levels exactly equal to level 0 sampled at block centres, with the guard when a level cannot fit;
  • the worker-pool shutdown and parallel_config;
  • a write/read round trip with label_id resolving.
• Helpers: column validation, voxel-size fit, geometry repair, footprint union, multiscale image loading, µm conversion, sparse counts.

Checklist

• Reader under experimental/; string constants in PyxaKeys
• Small public test dataset with a permissive license (BSD 3-Clause)
• Extent and index-integrity proxy tests; tests for the helper functions
• Visual check of the alignment between image, polygons and transcripts
• CLI command
• Download and conversion scripts for spatialdata-sandbox
• 3D labels checked on a full region against an independent rasterizer

[codecov-commenter]

Codecov Report

❌ Patch coverage is 97.53788% with 13 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.42%. Comparing base (261578f) to head (9a85304).

Files with missing lines	Patch %	Lines
src/spatialdata_io/readers/pyxa.py	97.23%	13 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #425      +/-   ##
==========================================
+ Coverage   63.53%   68.42%   +4.89%     
==========================================
  Files          26       27       +1     
  Lines        3263     3791     +528     
==========================================
+ Hits         2073     2594     +521     
- Misses       1190     1197       +7     

Files with missing lines	Coverage Δ
src/spatialdata_io/__main__.py	85.95% <100.00%> (+1.40%)	⬆️
src/spatialdata_io/_constants/_constants.py	100.00% <100.00%> (ø)
src/spatialdata_io/experimental/__init__.py	100.00% <100.00%> (+100.00%)	⬆️
src/spatialdata_io/readers/pyxa.py	97.23% <97.23%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.