Rewrite codex() and add phenocycler() for Akoya CODEX / PhenoCycler-Fusion data

CHANGELOG.md

@@ -22,12 +22,32 @@ Release notes for `v0.7.1` and earlier are available on the [Releases][] page.
   and the raster cell/nucleus labels are reconstructed by rasterizing the boundary polygons. The
   cell feature matrix falls back to a `cell_feature_matrix/` MatrixMarket directory or
   `cell_feature_matrix.tar.gz` when `cell_feature_matrix.h5` is missing.
+- `phenocycler()` reader and CLI command for Akoya PhenoCycler-Fusion 1.x/2.x `.qptiff` / `.er.qptiff` scans
+  (incl. Opal mode) and other PerkinElmer/Akoya QPTIFFs (Vectra Polaris, PhenoImager HT, inForm component data):
+  lazy images with channel names from the page XML, scan metadata in `sdata.attrs["akoya"]`, optional `.xpd` /
+  `*channels.csv` sidecars and segmentation masks (`labels`); `read_all_bit_depths=True` also reads the 8-bit scan.
 
 ### Changed
 
 - Adopted the current `cookiecutter-scverse` template: `hatch`-managed test environments, `uv`-based CI and
   documentation builds, `mypy` type checking of `src` and `tests`, `biome`/`pyproject-fmt`/`zizmor` pre-commit hooks,
   and Dependabot updates.
+- Requires `tifffile>=2026.5.2` and `zarr>=3.2`, the first versions whose zarr store the lazy Akoya TIFF reads work with.
+- Requires `flowio>=1.4`, the first version with `FlowData.pnn_labels`, with which `codex()` detects CODEX FCS tables.
+- `codex()` was rewritten to read CODEX Processor, CODEX Uploader and CODEX Instrument Manager (`.qptiff`)
+  outputs, sharing the QPTIFF core with `phenocycler()`. Breaking changes:
+  - Element names are `{region}_image`, `{region}_cells`, `{region}_labels` and `table` (were `images`, `{region}`).
+  - All regions are read (was the first file found); `regions=[...]` subsets. Unrelated regions get one coordinate
+    system each; regions of one slide are placed at their stage positions in `"global"`.
+  - `table.var_names` and image channels carry marker names (FCS `$PnS`, CSV `cycCCC_chHHH:<marker>`,
+    `channelNames.txt`), not `cycCCC_chHHH`.
+  - New keyword-only parameters `regions`, `channel_names`, `cells_table`, `labels`, `*_models_kwargs`;
+    `imread_kwargs` is ignored with a warning.
+
+### Fixed
+
+- `codex()` read the CSV table and the image relative to the current working directory instead of `path`, and an
+  operator-precedence bug in the table check made it ignore `fcs`.
 
 ### Removed
 

README.md

@@ -21,7 +21,8 @@ This package contains reader functions to load common spatial omics formats into
 - 10x Genomics Visium®
 - 10x Genomics Visium HD®
 - 10x Genomics Xenium®
-- Akoya PhenoCycler® (formerly CODEX®)
+- Akoya PhenoCycler® (formerly CODEX®): CODEX Processor/Uploader/Instrument Manager outputs and PhenoCycler-Fusion 1.x/2.x,
+  Vectra® Polaris™ / PhenoImager® HT QPTIFFs and inForm® component TIFFs
 - Curio Seeker®
 - DBiT-seq
 - MCMICRO (output data)

docs/api.md

@@ -25,6 +25,7 @@ I/O for the `spatialdata` project.
     experimental.iss
     mcmicro
     merscope
+    phenocycler
     seqfish
     steinbock
     stereoseq

pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
   "anndata",
   "click",
   "dask-image",
+  "flowio>=1.4",
   "h5py",
   "imagecodecs",
   "joblib",
@@ -40,8 +41,9 @@ dependencies = [
   # for debug logging (referenced from the issue template)
   "session-info2",
   "spatialdata>=0.7.3a0",
-  "tifffile>=2023.8.12",
+  "tifffile>=2026.5.2",
   "xmltodict",
+  "zarr>=3.2",
 ]
 # https://docs.pypi.org/project_metadata/#project-urls
 urls.Documentation = "https://spatialdata-io.readthedocs.io/"
@@ -156,6 +158,7 @@ exclude = "^tests/data/"
 [[tool.mypy.overrides]]
 module = [
   "dask_image.*",
+  "flowio.*",
   "h5py.*",
   "multiscale_spatial_image.*",
   "pyarrow.*",

src/spatialdata_io/__init__.py

@@ -13,6 +13,7 @@
     "macsima": "spatialdata_io.readers.macsima",
     "mcmicro": "spatialdata_io.readers.mcmicro",
     "merscope": "spatialdata_io.readers.merscope",
+    "phenocycler": "spatialdata_io.readers.phenocycler",
     "seqfish": "spatialdata_io.readers.seqfish",
     "steinbock": "spatialdata_io.readers.steinbock",
     "stereoseq": "spatialdata_io.readers.stereoseq",
@@ -38,6 +39,7 @@
     "macsima",
     "mcmicro",
     "merscope",
+    "phenocycler",
     "seqfish",
     "steinbock",
     "stereoseq",
@@ -88,6 +90,7 @@ def __dir__() -> list[str]:
     from spatialdata_io.readers.macsima import macsima
     from spatialdata_io.readers.mcmicro import mcmicro
     from spatialdata_io.readers.merscope import merscope
+    from spatialdata_io.readers.phenocycler import phenocycler
     from spatialdata_io.readers.seqfish import seqfish
     from spatialdata_io.readers.steinbock import steinbock
     from spatialdata_io.readers.stereoseq import stereoseq

src/spatialdata_io/__main__.py

@@ -40,36 +40,112 @@ def _input_output_click_options(func: Callable[..., None]) -> Callable[..., None
 
 def _parse_json_param(value: str, param_name: str) -> dict[str, Any]:
     try:
-        result: dict[str, Any] = json.loads(value)
-        return result
+        result = json.loads(value)
     except json.JSONDecodeError as e:
         raise click.BadParameter(f"Invalid JSON for {param_name!r}: {e}") from e
+    if not isinstance(result, dict):
+        raise click.BadParameter(f"{param_name!r} must be a JSON object, got {value!r}.")
+    return result
+
+
+def _parse_path_or_mapping_param(value: str | None, param_name: str) -> str | dict[str, Any] | None:
+    """A path, or a JSON mapping from region to path if ``value`` starts with ``{``."""
+    if value is None or not value.lstrip().startswith("{"):
+        return value
+    mapping = _parse_json_param(value, param_name)
+    if not all(isinstance(path, str) for path in mapping.values()):
+        raise click.BadParameter(f"{param_name!r} must be a path or a JSON object mapping regions to paths.")
+    return mapping
+
+
+def _akoya_click_options(func: Callable[..., None]) -> Callable[..., None]:
+    """Decorator adding the options shared by the Akoya readers (``codex``, ``phenocycler``)."""
+    options = [
+        click.option("--output", "-o", type=click.Path(), help="Path to the output.zarr file.", required=True),
+        click.option("--regions", multiple=True, help="A region to read (repeat for several); all if omitted."),
+        click.option(
+            "--channel-names",
+            multiple=True,
+            help="A channel name overriding the discovered ones (repeat for every channel).",
+        ),
+        click.option(
+            "--labels",
+            type=str,
+            default=None,
+            help="Path to a segmentation mask, or a JSON mapping from region to path. [default: None]",
+        ),
+        click.option(
+            "--image-models-kwargs",
+            type=str,
+            default="{}",
+            help="JSON string of keyword arguments passed to Image2DModel. [default: {}]",
+        ),
+        click.option(
+            "--labels-models-kwargs",
+            type=str,
+            default="{}",
+            help="JSON string of keyword arguments passed to Labels2DModel. [default: {}]",
+        ),
+    ]
+    for option in reversed(options):
+        func = option(func)
+    return func
 
 
 @cli.command(name="codex")
-@_input_output_click_options
+@click.option(
+    "--input",
+    "-i",
+    type=click.Path(exists=True),
+    help="Path to a CODEX output directory or to a single .qptiff/.tif image.",
+    required=True,
+)
+@_akoya_click_options
+@click.option(
+    "--cells-table",
+    type=str,
+    default=None,
+    help='Path to a CODEX cell table, or a JSON mapping from region to path, e.g. \'{"reg001": "a.csv"}\'. '
+    "[default: None]",
+)
 @click.option(
     "--fcs",
     type=bool,
     default=True,
-    help="Whether the .fcs file is provided if False a .csv file is expected. [default: True]",
+    help="Whether to prefer .fcs over .csv cell tables when both exist. [default: True]",
 )
 @click.option(
     "--imread-kwargs",
     type=str,
     default="{}",
-    help="JSON string of keyword arguments passed to imread. [default: {}]",
+    help="Ignored, with a warning; kept for backward compatibility. [default: {}]",
 )
 def codex_wrapper(
     input: str,
     output: str,
     fcs: bool = True,
+    regions: tuple[str, ...] = (),
+    channel_names: tuple[str, ...] = (),
+    cells_table: str | None = None,
+    labels: str | None = None,
     imread_kwargs: str = "{}",
+    image_models_kwargs: str = "{}",
+    labels_models_kwargs: str = "{}",
 ) -> None:
     """Codex conversion to SpatialData."""
     from spatialdata_io.readers.codex import codex
 
-    sdata = codex(input, fcs=fcs, imread_kwargs=_parse_json_param(imread_kwargs, "imread_kwargs"))
+    sdata = codex(
+        input,
+        fcs=fcs,
+        regions=list(regions) or None,
+        channel_names=list(channel_names) or None,
+        cells_table=_parse_path_or_mapping_param(cells_table, "cells_table"),
+        labels=_parse_path_or_mapping_param(labels, "labels"),
+        imread_kwargs=_parse_json_param(imread_kwargs, "imread_kwargs"),
+        image_models_kwargs=_parse_json_param(image_models_kwargs, "image_models_kwargs"),
+        labels_models_kwargs=_parse_json_param(labels_models_kwargs, "labels_models_kwargs"),
+    )
     sdata.write(output)
 
 
@@ -357,6 +433,46 @@ def merscope_wrapper(
     sdata.write(output)
 
 
+@cli.command(name="phenocycler")
+@click.option(
+    "--input",
+    "-i",
+    type=click.Path(exists=True),
+    help="Path to a .qptiff file or to a directory containing .qptiff files.",
+    required=True,
+)
+@_akoya_click_options
+@click.option(
+    "--read-all-bit-depths/--no-read-all-bit-depths",
+    default=False,
+    help="Read both the 8-bit .qptiff and the extended-range .er.qptiff of a scan (the 8-bit one as region "
+    "'<region>_8bit'). [default: no-read-all-bit-depths]",
+)
+def phenocycler_wrapper(
+    input: str,
+    output: str,
+    regions: tuple[str, ...] = (),
+    channel_names: tuple[str, ...] = (),
+    labels: str | None = None,
+    read_all_bit_depths: bool = False,
+    image_models_kwargs: str = "{}",
+    labels_models_kwargs: str = "{}",
+) -> None:
+    """PhenoCycler-Fusion conversion to SpatialData."""
+    from spatialdata_io.readers.phenocycler import phenocycler
+
+    sdata = phenocycler(
+        input,
+        regions=list(regions) or None,
+        channel_names=list(channel_names) or None,
+        labels=_parse_path_or_mapping_param(labels, "labels"),
+        read_all_bit_depths=read_all_bit_depths,
+        image_models_kwargs=_parse_json_param(image_models_kwargs, "image_models_kwargs"),
+        labels_models_kwargs=_parse_json_param(labels_models_kwargs, "labels_models_kwargs"),
+    )
+    sdata.write(output)
+
+
 @cli.command(name="seqfish")
 @_input_output_click_options
 @click.option("--load-images", type=bool, default=True, help="Whether to load images. [default: True]")

src/spatialdata_io/_constants/_constants.py

@@ -10,6 +10,9 @@ class CodexKeys(ModeEnum):
     # files and directories
     FCS_FILE = ".fcs"
     FCS_FILE_CSV = ".csv"
+    CHANNEL_NAMES_FILE = "channelNames.txt"
+    EXPERIMENT_FILE = "experiment.json"
+    QPTIFF = ".qptiff"
     # metadata
     REGION_KEY = "region"
     INSTANCE_KEY = "cell_id"
@@ -18,6 +21,26 @@ class CodexKeys(ModeEnum):
     IMAGE_TIF = ".tif"
 
 
+@unique
+class PhenocyclerKeys(ModeEnum):
+    """Keys for *Akoya PhenoCycler-Fusion* (and CIM QPTIFF) formatted dataset."""
+
+    # files and directories
+    QPTIFF_SUFFIX = ".qptiff"
+    ER_QPTIFF_SUFFIX = ".er.qptiff"
+    XPD_SUFFIX = ".xpd"
+    CHANNELS_CSV_SUFFIX = "channels.csv"
+    # elements
+    IMAGE_SUFFIX = "_image"
+    LABELS_SUFFIX = "_labels"
+    CELLS_SUFFIX = "_cells"
+    TABLE_KEY = "table"
+    # metadata
+    REGION_KEY = "region"
+    INSTANCE_KEY = "cell_id"
+    ATTRS_KEY = "akoya"
+
+
 class CurioKeys(ModeEnum):
     """Keys for *Curio* formatted dataset."""