spatialdata-io 0.1.3.post0__tar.gz → 0.1.5__tar.gz

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/.pre-commit-config.yaml

@@ -23,7 +23,7 @@ repos:
       hooks:
           - id: isort
     - repo: https://github.com/pre-commit/mirrors-mypy
-      rev: v1.10.1
+      rev: v1.11.0
       hooks:
           - id: mypy
             additional_dependencies: [numpy, types-PyYAML]
@@ -70,7 +70,7 @@ repos:
                 - flake8-bugbear
                 - flake8-blind-except
     - repo: https://github.com/asottile/pyupgrade
-      rev: v3.16.0
+      rev: v3.17.0
       hooks:
           - id: pyupgrade
             args: [--py3-plus, --py39-plus, --keep-runtime-typing]

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/CHANGELOG.md

@@ -8,7 +8,26 @@ and this project adheres to [Semantic Versioning][].
 [keep a changelog]: https://keepachangelog.com/en/1.0.0/
 [semantic versioning]: https://semver.org/spec/v2.0.0.html
 
-## [0.1.4] - xxxx-xx-xx
+## [0.1.5] - 2024-09-25
+
+### Added
+
+-   (Xenium) added `dims` parameter for more control in `xenium_aligned_image()`
+
+### Fixed
+
+-   Passing `rgb=None` to image model parser for both visium and visiumhd, leading to 3-4 channel images being
+    interpreted as RGB(A)
+-   Fix header bug Visium data #200
+-   (Visium HD) Fix path parsing when images are missing #204 #206
+
+## [0.1.4] - 2024-08-07
+
+### Changed
+
+-   (Xenium) changed default target of table to labels; radii of circles computed from cells, not nuclei #179
+-   (Visium HD) changed default geometry to squares from circles for the bins; added parameter to choose #183
+-   (CosMx) dropping points element with zero-length from the cosmx reader #191
 
 ## [0.1.3] - 2024-07-03
 

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: spatialdata-io
-Version: 0.1.3.post0
+Version: 0.1.5
 Summary: SpatialData IO for common techs
 Project-URL: Documentation, https://spatialdata-io.readthedocs.io/
 Project-URL: Source, https://github.com/scverse/spatialdata-io
@@ -48,7 +48,8 @@ Requires-Dist: pyarrow
 Requires-Dist: readfcs
 Requires-Dist: scanpy
 Requires-Dist: scikit-image
-Requires-Dist: spatialdata>=0.2.1
+Requires-Dist: spatialdata>=0.2.2
+Requires-Dist: tifffile>=2023.8.12
 Provides-Extra: dev
 Requires-Dist: bump2version; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
@@ -82,17 +83,20 @@ Description-Content-Type: text/markdown
 
 This package contains reader functions to load common spatial omics formats into SpatialData. Currently, we provide support for:
 
--   10x Genomics Visium
--   10x Genomics Visium HD
--   10x Genomics Xenium
--   Akoya PhenoCycler (formerly CODEX)
--   Curio Seeker
+-   10x Genomics Visium®
+-   10x Genomics Visium HD®
+-   10x Genomics Xenium®
+-   Akoya PhenoCycler® (formerly CODEX®)
+-   Curio Seeker®
 -   DBiT-seq
 -   MCMICRO (output data)
--   NanoString CosMx
+-   NanoString CosMx®
+-   Spatial Genomics GenePS® (seqFISH)
 -   Steinbock (output data)
--   STOmics Stereo-seq
--   Vizgen MERSCOPE (MERFISH)
+-   STOmics Stereo-seq®
+-   Vizgen MERSCOPE® (MERFISH)
+
+Note: all mentioned technologies are registered trademarks of their respective companies.
 
 ## Getting started
 
@@ -129,9 +133,13 @@ If you found a bug, please use the [issue tracker][issue-tracker].
 Technologies that can be read into `SpatialData` objects using third-party libraries:
 
 -   METASPACE (MALDI, ...): [metaspace-converter](https://github.com/metaspace2020/metaspace-converter)
--   PhenoCycler: [SOPA](https://github.com/gustaveroussy/sopa)
--   MACSima: [SOPA](https://github.com/gustaveroussy/sopa)
--   Hyperion (Imaging Mass Cytometry): [SOPA](https://github.com/gustaveroussy/sopa)
+-   PhenoCycler®: [SOPA](https://github.com/gustaveroussy/sopa)
+-   MACSima®: [SOPA](https://github.com/gustaveroussy/sopa)
+-   Hyperion® (Imaging Mass Cytometry): [SOPA](https://github.com/gustaveroussy/sopa)
+
+## Disclaimer
+
+This library is community maintained and is not officially endorsed by the aforementioned spatial technology companies. As such, we cannot offer any warranty of the correctness of the representation. Furthermore, we cannot ensure the correctness of the readers for every data version as the technologies evolve and update their formats. If you find a bug or notice a misrepresentation of the data please report it via our [Bug Tracking System](https://github.com/scverse/spatialdata-io/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen) so that it can be addressed either by the maintainers of this library or by the community.
 
 ## Citation
 

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/README.md

@@ -12,17 +12,20 @@
 
 This package contains reader functions to load common spatial omics formats into SpatialData. Currently, we provide support for:
 
--   10x Genomics Visium
--   10x Genomics Visium HD
--   10x Genomics Xenium
--   Akoya PhenoCycler (formerly CODEX)
--   Curio Seeker
+-   10x Genomics Visium®
+-   10x Genomics Visium HD®
+-   10x Genomics Xenium®
+-   Akoya PhenoCycler® (formerly CODEX®)
+-   Curio Seeker®
 -   DBiT-seq
 -   MCMICRO (output data)
--   NanoString CosMx
+-   NanoString CosMx®
+-   Spatial Genomics GenePS® (seqFISH)
 -   Steinbock (output data)
--   STOmics Stereo-seq
--   Vizgen MERSCOPE (MERFISH)
+-   STOmics Stereo-seq®
+-   Vizgen MERSCOPE® (MERFISH)
+
+Note: all mentioned technologies are registered trademarks of their respective companies.
 
 ## Getting started
 
@@ -59,9 +62,13 @@ If you found a bug, please use the [issue tracker][issue-tracker].
 Technologies that can be read into `SpatialData` objects using third-party libraries:
 
 -   METASPACE (MALDI, ...): [metaspace-converter](https://github.com/metaspace2020/metaspace-converter)
--   PhenoCycler: [SOPA](https://github.com/gustaveroussy/sopa)
--   MACSima: [SOPA](https://github.com/gustaveroussy/sopa)
--   Hyperion (Imaging Mass Cytometry): [SOPA](https://github.com/gustaveroussy/sopa)
+-   PhenoCycler®: [SOPA](https://github.com/gustaveroussy/sopa)
+-   MACSima®: [SOPA](https://github.com/gustaveroussy/sopa)
+-   Hyperion® (Imaging Mass Cytometry): [SOPA](https://github.com/gustaveroussy/sopa)
+
+## Disclaimer
+
+This library is community maintained and is not officially endorsed by the aforementioned spatial technology companies. As such, we cannot offer any warranty of the correctness of the representation. Furthermore, we cannot ensure the correctness of the readers for every data version as the technologies evolve and update their formats. If you find a bug or notice a misrepresentation of the data please report it via our [Bug Tracking System](https://github.com/scverse/spatialdata-io/issues?q=sort%3Aupdated-desc+is%3Aissue+is%3Aopen) so that it can be addressed either by the maintainers of this library or by the community.
 
 ## Citation
 

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.3.post0'
-__version_tuple__ = version_tuple = (0, 1, 3)
+__version__ = version = '0.1.5'
+__version_tuple__ = version_tuple = (0, 1, 5)

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/pyproject.toml

@@ -25,7 +25,7 @@ dependencies = [
     "anndata",
     "numpy",
     "scanpy",
-    "spatialdata>=0.2.1",
+    "spatialdata>=0.2.2",
     "scikit-image",
     "h5py",
     "joblib",
@@ -33,6 +33,7 @@ dependencies = [
     "dask-image",
     "pyarrow",
     "readfcs",
+    "tifffile>=2023.8.12",
 ]
 
 [project.optional-dependencies]

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/_constants/_constants.py

@@ -353,9 +353,9 @@ class VisiumHDKeys(ModeEnum):
     TISSUE_POSITIONS_FILE = "tissue_positions.parquet"
 
     # images
-    IMAGE_HIRES_FILE = "spatial/tissue_hires_image.png"
-    IMAGE_LOWRES_FILE = "spatial/tissue_lowres_image.png"
-    IMAGE_CYTASSIST = "spatial/cytassist_image.tiff"
+    IMAGE_HIRES_FILE = "tissue_hires_image.png"
+    IMAGE_LOWRES_FILE = "tissue_lowres_image.png"
+    IMAGE_CYTASSIST = "cytassist_image.tiff"
 
     # scalefactors
     SCALEFACTORS_FILE = "scalefactors_json.json"

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/converters/legacy_anndata.py

@@ -268,6 +268,8 @@ def from_legacy_anndata(adata: AnnData) -> SpatialData:
             keys = set(adata.uns[SPATIAL][dataset_id].keys())
             tissue_hires_scalef = None
             tissue_lowres_scalef = None
+            hires = None
+            lowres = None
             if SCALEFACTORS in keys:
                 scalefactors = adata.uns[SPATIAL][dataset_id][SCALEFACTORS]
                 if TISSUE_HIRES_SCALEF in scalefactors:

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/_utils/_utils.py

@@ -18,8 +18,8 @@ try:
 
     NDArrayA = NDArray[Any]
 except (ImportError, TypeError):
-    NDArray = np.ndarray  # type: ignore[misc]
-    NDArrayA = np.ndarray  # type: ignore[misc]
+    NDArray = np.ndarray
+    NDArrayA = np.ndarray
 
 
 def _read_counts(

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/codex.py

@@ -80,6 +80,7 @@ def codex(
             "images": Image2DModel.parse(
                 image,
                 scale_factors=[2, 2],
+                rgb=None,
             )
         }
         sdata = SpatialData(images=images, shapes={str(region): shapes}, table=table)

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/cosmx.py

@@ -200,6 +200,7 @@ def cosmx(
                         "global_only_image": aff,
                     },
                     dims=("y", "x", "c"),
+                    rgb=None,
                     **image_models_kwargs,
                 )
                 images[f"{fov}_image"] = parsed_im
@@ -271,17 +272,18 @@ def cosmx(
                 sub_table[CosmxKeys.INSTANCE_KEY] = sub_table[CosmxKeys.INSTANCE_KEY].astype("category")
                 # we rename z because we want to treat the data as 2d
                 sub_table.rename(columns={"z": "z_raw"}, inplace=True)
-                points[f"{fov}_points"] = PointsModel.parse(
-                    sub_table,
-                    coordinates={"x": CosmxKeys.X_LOCAL_TRANSCRIPT, "y": CosmxKeys.Y_LOCAL_TRANSCRIPT},
-                    feature_key=CosmxKeys.TARGET_OF_TRANSCRIPT,
-                    instance_key=CosmxKeys.INSTANCE_KEY,
-                    transformations={
-                        fov: Identity(),
-                        "global": aff,
-                        "global_only_labels": aff,
-                    },
-                )
+                if len(sub_table) > 0:
+                    points[f"{fov}_points"] = PointsModel.parse(
+                        sub_table,
+                        coordinates={"x": CosmxKeys.X_LOCAL_TRANSCRIPT, "y": CosmxKeys.Y_LOCAL_TRANSCRIPT},
+                        feature_key=CosmxKeys.TARGET_OF_TRANSCRIPT,
+                        instance_key=CosmxKeys.INSTANCE_KEY,
+                        transformations={
+                            fov: Identity(),
+                            "global": aff,
+                            "global_only_labels": aff,
+                        },
+                    )
 
     # TODO: what to do with fov file?
     # if fov_file is not None:

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/mcmicro.py

@@ -100,7 +100,7 @@ def mcmicro(
         assert len(samples) == 1
         data = imread(samples[0], **imread_kwargs)
         # , scale_factors=[2, 2]
-        data = Image2DModel.parse(data, transformations=_get_transformation(), **image_models_kwargs)
+        data = Image2DModel.parse(data, transformations=_get_transformation(), rgb=None, **image_models_kwargs)
         images["tma_map"] = data
 
         image_dir = path / McmicroKeys.IMAGES_DIR_TMA
@@ -116,7 +116,7 @@ def mcmicro(
             image_id = core_id
 
         data = imread(sample, **imread_kwargs)
-        data = Image2DModel.parse(data, c_coords=marker_names, **image_models_kwargs)
+        data = Image2DModel.parse(data, c_coords=marker_names, rgb=None, **image_models_kwargs)
         transformations = _get_transformation(
             tma=int(core_id) if tma else None, tma_centroids=tma_centroids, raster_data=data
         )
@@ -131,7 +131,9 @@ def mcmicro(
             raw_name = raw_image.with_name(raw_image.stem).with_suffix("").stem
 
             data = imread(raw_image, **imread_kwargs)
-            images[raw_name] = Image2DModel.parse(data, transformations={raw_name: Identity()}, **image_models_kwargs)
+            images[raw_name] = Image2DModel.parse(
+                data, transformations={raw_name: Identity()}, rgb=None, **image_models_kwargs
+            )
 
     illumination_dir = path / McmicroKeys.ILLUMINATION_DIR
     if illumination_dir.exists():
@@ -143,7 +145,7 @@ def mcmicro(
 
             data = imread(illumination_image, **imread_kwargs)
             images[illumination_name] = Image2DModel.parse(
-                data, transformations={raw_name: Identity()}, **image_models_kwargs
+                data, transformations={raw_name: Identity()}, rgb=None, **image_models_kwargs
             )
 
     samples_labels = list((path / McmicroKeys.LABELS_DIR).glob("*/*" + McmicroKeys.IMAGE_SUFFIX))

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/merscope.py

@@ -273,7 +273,7 @@ def _rioxarray_load_merscope(
         dim="c",
     )
 
-    return Image2DModel.parse(im, c_coords=stainings, **image_models_kwargs)
+    return Image2DModel.parse(im, c_coords=stainings, rgb=None, **image_models_kwargs)
 
 
 def _dask_image_load_merscope(
@@ -292,6 +292,7 @@ def _dask_image_load_merscope(
         im,
         dims=("c", "y", "x"),
         c_coords=stainings,
+        rgb=None,
         **image_models_kwargs,
     )
 

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/steinbock.py

@@ -97,7 +97,7 @@ def _get_images(
     image_models_kwargs: Mapping[str, Any] = MappingProxyType({}),
 ) -> Union[SpatialImage, MultiscaleSpatialImage]:
     image = imread(path / SteinbockKeys.IMAGES_DIR / f"{sample}{SteinbockKeys.IMAGE_SUFFIX}", **imread_kwargs)
-    return Image2DModel.parse(data=image, transformations={sample: Identity()}, **image_models_kwargs)
+    return Image2DModel.parse(data=image, transformations={sample: Identity()}, rgb=None, **image_models_kwargs)
 
 
 def _get_labels(

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/visium.py

@@ -4,7 +4,6 @@ import json
 import os
 import re
 from collections.abc import Mapping
-from functools import partial
 from pathlib import Path
 from types import MappingProxyType
 from typing import Any
@@ -138,7 +137,6 @@ def visium(
     if (path / "spatial" / VisiumKeys.SPOTS_FILE_1).exists() or (
         tissue_positions_file is not None and str(VisiumKeys.SPOTS_FILE_1) in str(tissue_positions_file)
     ):
-        read_coords = partial(pd.read_csv, header=None, index_col=0)
         tissue_positions_file = (
             path / "spatial" / VisiumKeys.SPOTS_FILE_1
             if tissue_positions_file is None
@@ -147,7 +145,6 @@ def visium(
     elif (path / "spatial" / VisiumKeys.SPOTS_FILE_2).exists() or (
         tissue_positions_file is not None and str(VisiumKeys.SPOTS_FILE_2) in str(tissue_positions_file)
     ):
-        read_coords = partial(pd.read_csv, header=0, index_col=0)
         tissue_positions_file = (
             path / "spatial" / VisiumKeys.SPOTS_FILE_2
             if tissue_positions_file is None
@@ -155,11 +152,18 @@ def visium(
         )
     else:
         raise ValueError(f"Cannot find `tissue_positions` file in `{path}`.")
-    coords = read_coords(tissue_positions_file)
+    coords = pd.read_csv(tissue_positions_file, header=None, index_col=0)
 
-    # to handle spaceranger_version < 2.0.0, where no column names are provided
-    if "in_tissue" not in coords.columns:
-        coords.columns = ["in_tissue", "array_row", "array_col", "pxl_row_in_fullres", "pxl_col_in_fullres"]
+    if tissue_positions_file.name == VisiumKeys.SPOTS_FILE_1:
+        # spaceranger_version < 2.0.0 but header detected: https://github.com/scverse/spatialdata-io/issues/146
+        if "in_tissue" in coords.iloc[0].tolist():
+            coords = pd.read_csv(tissue_positions_file, header=0, index_col=0)
+        else:
+            assert "in_tissue" not in coords.columns
+            coords.columns = ["in_tissue", "array_row", "array_col", "pxl_row_in_fullres", "pxl_col_in_fullres"]
+    else:
+        assert tissue_positions_file.name == VisiumKeys.SPOTS_FILE_2
+        coords = pd.read_csv(tissue_positions_file, header=0, index_col=0)
 
     adata.obs = pd.merge(adata.obs, coords, how="left", left_index=True, right_index=True)
     coords = adata.obs[[VisiumKeys.SPOTS_X, VisiumKeys.SPOTS_Y]].values
@@ -217,6 +221,7 @@ def visium(
                 full_image,
                 scale_factors=[2, 2, 2, 2],
                 transformations={"global": transform_original},
+                rgb=None,
                 **image_models_kwargs,
             )
         else:
@@ -226,13 +231,15 @@ def visium(
         image_hires = imread(path / VisiumKeys.IMAGE_HIRES_FILE, **imread_kwargs).squeeze().transpose(2, 0, 1)
         image_hires = DataArray(image_hires, dims=("c", "y", "x"))
         images[dataset_id + "_hires_image"] = Image2DModel.parse(
-            image_hires, transformations={"downscaled_hires": Identity()}
+            image_hires, transformations={"downscaled_hires": Identity()}, rgb=None
         )
     if (path / VisiumKeys.IMAGE_LOWRES_FILE).exists():
         image_lowres = imread(path / VisiumKeys.IMAGE_LOWRES_FILE, **imread_kwargs).squeeze().transpose(2, 0, 1)
         image_lowres = DataArray(image_lowres, dims=("c", "y", "x"))
         images[dataset_id + "_lowres_image"] = Image2DModel.parse(
-            image_lowres, transformations={"downscaled_lowres": Identity()}
+            image_lowres,
+            transformations={"downscaled_lowres": Identity()},
+            rgb=None,
         )
 
     return SpatialData(images=images, shapes=shapes, table=table)

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/visium_hd.py

@@ -14,6 +14,7 @@ import numpy as np
 import pandas as pd
 import scanpy as sc
 from dask_image.imread import imread
+from geopandas import GeoDataFrame
 from imageio import imread as imread2
 from multiscale_spatial_image import MultiscaleSpatialImage
 from spatial_image import SpatialImage
@@ -38,6 +39,7 @@ def visium_hd(
     dataset_id: str | None = None,
     filtered_counts_file: bool = True,
     bin_size: int | list[int] | None = None,
+    bins_as_squares: bool = True,
     fullres_image_file: str | Path | None = None,
     load_all_images: bool = False,
     imread_kwargs: Mapping[str, Any] = MappingProxyType({}),
@@ -63,6 +65,9 @@ def visium_hd(
     bin_size
         When specified, load the data of a specific bin size, or a list of bin sizes. By default, it loads all the
         available bin sizes.
+    bins_as_squares
+        If `True`, the bins are represented as squares. If `False`, the bins are represented as circles. For a correct
+        visualization one should use squares.
     fullres_image_file
         Path to the full-resolution image. By default the image is searched in the ``{vx.MICROSCOPE_IMAGE!r}``
         directory.
@@ -81,15 +86,14 @@ def visium_hd(
     SpatialData object for the Visium HD data.
     """
     path = Path(path)
+    all_files = [file for file in path.rglob("*") if file.is_file()]
     tables = {}
     shapes = {}
     images: dict[str, Any] = {}
 
     if dataset_id is None:
         dataset_id = _infer_dataset_id(path)
-        filename_prefix = f"{dataset_id}_"
-    else:
-        filename_prefix = ""
+    filename_prefix = f"{dataset_id}_"
 
     def load_image(path: Path, suffix: str, scale_factors: list[int] | None = None) -> None:
         _load_image(
@@ -122,8 +126,12 @@ def visium_hd(
             ]
         )
 
-    if VisiumHDKeys.BINNED_OUTPUTS in os.listdir(path):
-        path_bins = path / VisiumHDKeys.BINNED_OUTPUTS
+    all_path_bins = [path_bin for path_bin in all_files if VisiumHDKeys.BINNED_OUTPUTS in str(path_bin)]
+    if len(all_path_bins) != 0:
+        path_bins_parts = all_path_bins[
+            -1
+        ].parts  # just choosing last one here as users might have tar file which would be first
+        path_bins = Path(*path_bins_parts[: path_bins_parts.index(VisiumHDKeys.BINNED_OUTPUTS) + 1])
     else:
         path_bins = path
     all_bin_sizes = _get_bins(path_bins)
@@ -219,19 +227,27 @@ def visium_hd(
             axes=("x", "y"),
         )
         # parse shapes
+        shapes_name = dataset_id + "_" + bin_size_str
+        radius = scalefactors[VisiumHDKeys.SCALEFACTORS_SPOT_DIAMETER_FULLRES] / 2.0
+        transformations = {
+            "global": transform_original,
+            "downscaled_hires": transform_hires,
+            "downscaled_lowres": transform_lowres,
+        }
         circles = ShapesModel.parse(
             adata.obsm["spatial"],
             geometry=0,
-            radius=scalefactors[VisiumHDKeys.SCALEFACTORS_SPOT_DIAMETER_FULLRES] / 2.0,
+            radius=radius,
             index=adata.obs[VisiumHDKeys.INSTANCE_KEY].copy(),
-            transformations={
-                "global": transform_original,
-                "downscaled_hires": transform_hires,
-                "downscaled_lowres": transform_lowres,
-            },
+            transformations=transformations,
         )
-        shapes_name = dataset_id + "_" + bin_size_str
-        shapes[shapes_name] = circles
+        if not bins_as_squares:
+            shapes[shapes_name] = circles
+        else:
+            squares_series = circles.buffer(radius, cap_style=3)
+            shapes[shapes_name] = ShapesModel.parse(
+                GeoDataFrame(geometry=squares_series), transformations=transformations
+            )
 
         # parse table
         adata.obs[VisiumHDKeys.REGION_KEY] = shapes_name
@@ -253,15 +269,26 @@ def visium_hd(
             fullres_image_filenames = [
                 f for f in os.listdir(path_fullres) if os.path.isfile(os.path.join(path_fullres, f))
             ]
-            if len(fullres_image_filenames) > 1:
-                warnings.warn(
-                    f"Multiple files found in {path_fullres}, using the first one: {fullres_image_filenames[0]}. Please"
-                    " specify the path to the full resolution image manually using the `fullres_image_file` argument.",
-                    UserWarning,
-                    stacklevel=2,
-                )
-            fullres_image_filename = fullres_image_filenames[0]
-            fullres_image_file = path_fullres / fullres_image_filename
+            fullres_image_paths = [path_fullres / image_filename for image_filename in fullres_image_filenames]
+        elif list((path_fullres := (path / f"{filename_prefix}tissue_image")).parent.glob(f"{path_fullres.name}.*")):
+            fullres_image_paths = list(path_fullres.parent.glob(f"{path_fullres.name}.*"))
+        else:
+            fullres_image_paths = []
+        if len(fullres_image_paths) > 1:
+            warnings.warn(
+                f"Multiple files found in {path_fullres}, using the first one: {fullres_image_paths[0].stem}. Please"
+                " specify the path to the full resolution image manually using the `fullres_image_file` argument.",
+                UserWarning,
+                stacklevel=2,
+            )
+        if len(fullres_image_paths) == 0:
+            warnings.warn(
+                "No full resolution image found. If incorrect, please specify the path in the "
+                "`fullres_image_file` parameter when calling the `visium_hd` reader function.",
+                UserWarning,
+                stacklevel=2,
+            )
+        fullres_image_file = fullres_image_paths[0] if len(fullres_image_paths) > 0 else None
 
     if fullres_image_file is not None:
         load_image(
@@ -271,8 +298,15 @@ def visium_hd(
         )
 
     # hires image
+    hires_image_path = [path for path in all_files if VisiumHDKeys.IMAGE_HIRES_FILE in str(path)]
+    if len(hires_image_path) == 0:
+        warnings.warn(
+            f"No image path found containing the hires image: {VisiumHDKeys.IMAGE_HIRES_FILE}",
+            UserWarning,
+            stacklevel=2,
+        )
     load_image(
-        path=path / VisiumHDKeys.IMAGE_HIRES_FILE,
+        path=hires_image_path[0],
         suffix="_hires_image",
     )
     set_transformation(
@@ -282,8 +316,15 @@ def visium_hd(
     )
 
     # lowres image
+    lowres_image_path = [path for path in all_files if VisiumHDKeys.IMAGE_LOWRES_FILE in str(path)]
+    if len(lowres_image_path) == 0:
+        warnings.warn(
+            f"No image path found containing the lowres image: {VisiumHDKeys.IMAGE_LOWRES_FILE}",
+            UserWarning,
+            stacklevel=2,
+        )
     load_image(
-        path=path / VisiumHDKeys.IMAGE_LOWRES_FILE,
+        path=lowres_image_path[0],
         suffix="_lowres_image",
     )
     set_transformation(
@@ -293,9 +334,16 @@ def visium_hd(
     )
 
     # cytassist image
+    cytassist_path = [path for path in all_files if VisiumHDKeys.IMAGE_CYTASSIST in str(path)]
+    if len(cytassist_path) == 0:
+        warnings.warn(
+            f"No image path found containing the cytassist image: {VisiumHDKeys.IMAGE_CYTASSIST}",
+            UserWarning,
+            stacklevel=2,
+        )
     if load_all_images:
         load_image(
-            path=path / VisiumHDKeys.IMAGE_CYTASSIST,
+            path=cytassist_path[0],
             suffix="_cytassist_image",
         )
         image = images[dataset_id + "_cytassist_image"]
@@ -339,7 +387,7 @@ def _load_image(
             # dask_image doesn't recognize .btf automatically and imageio v3 throws error due to pixel limit -> use imageio v2
             data = imread2(path, **imread_kwargs).squeeze().transpose(2, 0, 1)
         image = DataArray(data, dims=("c", "y", "x"))
-        parsed = Image2DModel.parse(image, scale_factors=scale_factors, **image_models_kwargs)
+        parsed = Image2DModel.parse(image, scale_factors=scale_factors, rgb=None, **image_models_kwargs)
         images[dataset_id + suffix] = parsed
     else:
         warnings.warn(f"File {path} does not exist, skipping it.", UserWarning, stacklevel=2)

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/src/spatialdata_io/readers/xenium.py

@@ -22,12 +22,11 @@ import zarr
 from anndata import AnnData
 from dask.dataframe import read_parquet
 from dask_image.imread import imread
+from datatree.datatree import DataTree
 from geopandas import GeoDataFrame
 from joblib import Parallel, delayed
-from multiscale_spatial_image.multiscale_spatial_image import MultiscaleSpatialImage
 from pyarrow import Table
 from shapely import Polygon
-from spatial_image import SpatialImage
 from spatialdata import SpatialData
 from spatialdata._core.query.relational_query import get_element_instances
 from spatialdata._types import ArrayLike
@@ -39,6 +38,7 @@ from spatialdata.models import (
     TableModel,
 )
 from spatialdata.transformations.transformations import Affine, Identity, Scale
+from xarray import DataArray
 
 from spatialdata_io._constants._constants import XeniumKeys
 from spatialdata_io._docs import inject_docs
@@ -56,7 +56,7 @@ def xenium(
     *,
     cells_boundaries: bool = True,
     nucleus_boundaries: bool = True,
-    cells_as_circles: bool = True,
+    cells_as_circles: bool | None = None,
     cells_labels: bool = True,
     nucleus_labels: bool = True,
     transcripts: bool = True,
@@ -96,10 +96,8 @@ def xenium(
     nucleus_boundaries
         Whether to read nucleus boundaries (polygons).
     cells_as_circles
-        Whether to read cells also as circles. Useful for performant visualization. The radii of the nuclei,
-        not the ones of cells, will be used; using the radii of cells would make the visualization too cluttered
-        (the cell boundaries are computed as a maximum expansion of the nuclei location and therefore the
-        corresponding circles would show considerable overlap).
+        Whether to read cells also as circles (the center and the radius of each circle is computed from the
+        corresponding labels cell).
     cells_labels
         Whether to read cell labels (raster). The polygonal version of the cell labels are simplified
         for visualization purposes, and using the raster version is recommended for analysis.
@@ -113,7 +111,9 @@ def xenium(
     morphology_focus
         Whether to read the morphology focus image.
     aligned_images
-        Whether to also parse, when available, additional H&E or IF aligned images.
+        Whether to also parse, when available, additional H&E or IF aligned images. For more control over the aligned
+        images being read, in particular, to specify the axes of the aligned images, please set this parameter to
+        `False` and use the `xenium_aligned_image` function directly.
     cells_table
         Whether to read the cell annotations in the `AnnData` table.
     n_jobs
@@ -128,7 +128,34 @@ def xenium(
     Returns
     -------
     :class:`spatialdata.SpatialData`
+
+    Notes
+    -----
+    Old versions. Until spatialdata-io v0.1.3post0: previously, `cells_as_circles` was `True` by default; the table was associated to the
+    circles when `cells_as_circles` was `True`, and the table was associated to the polygons when `cells_as_circles`
+    was `False`; the radii of the circles were computed form the nuclei instead of the cells.
+
+    Performance. You can improve visualization performance (at the cost of accuracy) by setting `cells_as_circles` to `True`.
+
+    Examples
+    --------
+    This code shows how to change the annotation target of the table from the cell circles to the cell labels.
+    >>> from spatialdata_io import xenium
+    >>> sdata = xenium("path/to/raw/data", cells_as_circles=True)
+    >>> sdata["table"].obs["region"] = "cell_labels"
+    >>> sdata.set_table_annotates_spatialelement(
+    ...     table_name="table", region="cell_labels", region_key="region", instance_key="cell_labels"
+    ... )
+    >>> sdata.write("path/to/data.zarr")
     """
+    if cells_as_circles is None:
+        cells_as_circles = True
+        warnings.warn(
+            "The default value of `cells_as_circles` will change to `False` in the next release. "
+            "Please pass `True` explicitly to maintain the current behavior.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
     image_models_kwargs, labels_models_kwargs = _initialize_raster_models_kwargs(
         image_models_kwargs, labels_models_kwargs
     )
@@ -138,7 +165,7 @@ def xenium(
     # to trigger the warning if the version cannot be parsed
     version = _parse_version_of_xenium_analyzer(specs, hide_warning=False)
 
-    specs["region"] = "cell_circles" if cells_as_circles else "cell_boundaries"
+    specs["region"] = "cell_circles" if cells_as_circles else "cell_labels"
 
     # the table is required in some cases
     if not cells_table:
@@ -210,14 +237,16 @@ def xenium(
         if cell_labels_indices_mapping is not None and table is not None:
             if not pd.DataFrame.equals(cell_labels_indices_mapping["cell_id"], table.obs[str(XeniumKeys.CELL_ID)]):
                 warnings.warn(
-                    "The cell_id column in the cell_labels_table does not match the cell_id column derived from the cell "
-                    "labels data. This could be due to trying to read a new version that is not supported yet. Please "
-                    "report this issue.",
+                    "The cell_id column in the cell_labels_table does not match the cell_id column derived from the "
+                    "cell labels data. This could be due to trying to read a new version that is not supported yet. "
+                    "Please report this issue.",
                     UserWarning,
                     stacklevel=2,
                 )
             else:
                 table.obs["cell_labels"] = cell_labels_indices_mapping["label_index"]
+                if not cells_as_circles:
+                    table.uns[TableModel.ATTRS_KEY][TableModel.INSTANCE_KEY] = "cell_labels"
 
     if nucleus_boundaries:
         polygons["nucleus_boundaries"] = _get_polygons(
@@ -486,6 +515,7 @@ def _get_points(path: Path, specs: dict[str, Any]) -> Table:
         feature_key=XeniumKeys.FEATURE_NAME,
         instance_key=XeniumKeys.CELL_ID,
         transformations={"global": transform},
+        sort=True,
     )
     return points
 
@@ -506,7 +536,7 @@ def _get_tables_and_circles(
     table = TableModel.parse(adata, region=specs["region"], region_key="region", instance_key=str(XeniumKeys.CELL_ID))
     if cells_as_circles:
         transform = Scale([1.0 / specs["pixel_size"], 1.0 / specs["pixel_size"]], axes=("x", "y"))
-        radii = np.sqrt(adata.obs[XeniumKeys.CELL_NUCLEUS_AREA].to_numpy() / np.pi)
+        radii = np.sqrt(adata.obs[XeniumKeys.CELL_AREA].to_numpy() / np.pi)
         circles = ShapesModel.parse(
             circ,
             geometry=0,
@@ -523,7 +553,7 @@ def _get_images(
     file: str,
     imread_kwargs: Mapping[str, Any] = MappingProxyType({}),
     image_models_kwargs: Mapping[str, Any] = MappingProxyType({}),
-) -> SpatialImage | MultiscaleSpatialImage:
+) -> DataArray | DataTree:
     image = imread(path / file, **imread_kwargs)
     if "c_coords" in image_models_kwargs and "dummy" in image_models_kwargs["c_coords"]:
         # Napari currently interprets 4 channel images as RGB; a series of PRs to fix this is almost ready but they will
@@ -532,7 +562,7 @@ def _get_images(
         # let's add a dummy channel as a temporary workaround.
         image = da.concatenate([image, da.zeros_like(image[0:1])], axis=0)
     return Image2DModel.parse(
-        image, transformations={"global": Identity()}, dims=("c", "y", "x"), **image_models_kwargs
+        image, transformations={"global": Identity()}, dims=("c", "y", "x"), rgb=None, **image_models_kwargs
     )
 
 
@@ -540,7 +570,7 @@ def _add_aligned_images(
     path: Path,
     imread_kwargs: Mapping[str, Any] = MappingProxyType({}),
     image_models_kwargs: Mapping[str, Any] = MappingProxyType({}),
-) -> dict[str, MultiscaleSpatialImage]:
+) -> dict[str, DataTree]:
     """Discover and parse aligned images."""
     images = {}
     ome_tif_files = list(path.glob("*.ome.tif"))
@@ -571,7 +601,8 @@ def xenium_aligned_image(
     alignment_file: str | Path | None,
     imread_kwargs: Mapping[str, Any] = MappingProxyType({}),
     image_models_kwargs: Mapping[str, Any] = MappingProxyType({}),
-) -> MultiscaleSpatialImage:
+    dims: tuple[str, ...] | None = None,
+) -> DataTree:
     """
     Read an image aligned to a Xenium dataset, with an optional alignment file.
 
@@ -583,6 +614,12 @@ def xenium_aligned_image(
         Path to the alignment file, if not passed it is assumed that the image is aligned.
     image_models_kwargs
         Keyword arguments to pass to the image models.
+    dims
+        Dimensions of the image (tuple of axes names); valid strings are "c", "x" and "y". If not passed, the function
+        will try to infer the dimensions from the image shape. Please use this argument when the default behavior fails.
+        Example: for an image with shape (1, y, 1, x, 3), use dims=("anystring", "y", "dummy", "x", "c"). Values that
+        are not "c", "x" or "y" are considered dummy dimensions and will be squeezed (the data must have len 1 for
+        those axes).
 
     Returns
     -------
@@ -600,19 +637,28 @@ def xenium_aligned_image(
     # In fact, it could be that the len(image.shape) == 4 has actually dimes (1, x, y, c) and not (1, y, x, c). This is
     # not a problem because the transformation is constructed to be consistent, but if is the case, the data orientation
     # would be transposed compared to the original image, not ideal.
-    if len(image.shape) == 4:
-        assert image.shape[0] == 1
-        assert image.shape[-1] == 3
-        image = image.squeeze(0)
-        dims = ("y", "x", "c")
+    if dims is None:
+        if len(image.shape) == 4:
+            assert image.shape[0] == 1
+            assert image.shape[-1] == 3
+            image = image.squeeze(0)
+            dims = ("y", "x", "c")
+        else:
+            assert len(image.shape) == 3
+            assert image.shape[0] in [3, 4]
+            if image.shape[0] == 4:
+                # as explained before in _get_images(), we need to add a dummy channel until we support 4-channel images as
+                # non-RGBA images in napari
+                image = da.concatenate([image, da.zeros_like(image[0:1])], axis=0)
+            dims = ("c", "y", "x")
     else:
-        assert len(image.shape) == 3
-        assert image.shape[0] in [3, 4]
-        if image.shape[0] == 4:
-            # as explained before in _get_images(), we need to add a dummy channel until we support 4-channel images as
-            # non-RGBA images in napari
-            image = da.concatenate([image, da.zeros_like(image[0:1])], axis=0)
-        dims = ("c", "y", "x")
+        logging.info(f"Image has shape {image.shape}, parsing with dims={dims}.")
+        image = DataArray(image, dims=dims)
+        # squeeze spurious dimensions away
+        to_squeeze = [dim for dim in dims if dim not in ["c", "x", "y"]]
+        dims = tuple(dim for dim in dims if dim in ["c", "x", "y"])
+        for dim in to_squeeze:
+            image = image.squeeze(dim)
 
     if alignment_file is None:
         transformation = Identity()
@@ -735,3 +781,6 @@ def prefix_suffix_uint32_from_cell_id_str(cell_id_str: ArrayLike) -> tuple[Array
     cell_id_prefix = [int(x, 16) for x in cell_id_prefix_hex]
 
     return np.array(cell_id_prefix, dtype=np.uint32), np.array(dataset_suffix_int)
+
+
+##

{spatialdata_io-0.1.3.post0 → spatialdata_io-0.1.5}/tests/test_xenium.py

@@ -51,13 +51,13 @@ def test_roundtrip_with_data_limits() -> None:
     "dataset,expected",
     [
         ("Xenium_V1_human_Breast_2fov_outs", "{'y': (0, 3529), 'x': (0, 5792), 'z': (10, 25)}"),
-        ("Xenium_V1_human_Lung_2fov_outs", "{'y': (-1, 3556), 'x': (0, 5794), 'z': (7, 32)}"),
+        ("Xenium_V1_human_Lung_2fov_outs", "{'y': (0, 3553), 'x': (0, 5793), 'z': (7, 32)}"),
     ],
 )
 def test_example_data(dataset: str, expected: str) -> None:
     f = Path("./data") / dataset
     assert f.is_dir()
-    sdata = xenium(f)
+    sdata = xenium(f, cells_as_circles=False)
     from spatialdata import get_extent
 
     extent = get_extent(sdata, exact=False)