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_assigned_gene_v1.csv	transcripts (3D points; unassigned transcripts, with a cell_id ending in _-1, are kept and flagged by an assigned column)
cell_by_gene_v1.csv + cell_metadata_v1.csv	rna table, with obsm["spatial"] in µm
segmentation_geometries_v1.parquet	cell_boundaries (one footprint per cell, annotated by rna) and cell_boundaries_z (one polygon per cell per z-plane)
optional mosaic OME-Zarr (image_path=)	mosaic_image, multiscale, using the pyramid levels already in the store

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.

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.
• Maintainers: the test data artifact has to be regenerated for CI to pick it up. The workflow notes that this needs a branch in this repository.

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

Tests (tests/test_pyxa.py)

• Example data: data extent, index integrity of every element (image pixels, transcripts, footprint and per-plane polygons, table values), the table annotation joins, and the CLI with the mosaic.
• Helpers:
  • column validation;
  • voxel-size fit, including sampling and rejecting metadata that isn't a pure scale;
  • geometry repair;
  • footprint union;
  • multiscale image loading, where a level that was read is distinguishable from one that was recomputed;
  • µm conversion.

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