spatialdata-io 0.5.1__tar.gz → 0.7.0__tar.gz

{spatialdata_io-0.5.1 → spatialdata_io-0.7.0}/.github/workflows/prepare_test_data.yaml

@@ -4,7 +4,8 @@ on:
     schedule:
         - cron: "0 0 1 * *" # run once a month to prevent artifact expiration
     workflow_dispatch:
-# uncomment and adjust the branch name if you need to add new datasets to the artifact
+    # Uncomment and adjust the branch name if you need to add new datasets to the artifact.
+    # It needs to be a branch in the spatialdata-io origin repository, not from a fork.
 #    push:
 #        branches:
 #            - main
@@ -57,6 +58,14 @@ jobs:
                   # Spatial Genomics seqFISH v2
                   curl -O https://s3.embl.de/spatialdata/raw_data/seqfish-2-test-dataset.zip
 
+                  # -------
+                  # MACSima OMAP datasets are licensed as CC BY 4.0
+                  # OMAP23 for format v1.x.x
+                  curl -o OMAP23_small.zip "https://zenodo.org/api/records/18196452/files-archive"
+
+                  # OMAP10 for format v0.x.x
+                  curl -o OMAP10_small.zip "https://zenodo.org/api/records/18196366/files-archive"
+
             - name: Unzip files
               run: |
                   cd ./data

{spatialdata_io-0.5.1 → spatialdata_io-0.7.0}/.gitignore

@@ -6,6 +6,7 @@ temp/
 
 # Compiled files
 __pycache__/
+.ipynb_checkpoints/
 
 # Distribution / packaging
 /build/
@@ -34,10 +35,17 @@ __pycache__/
 _version.py
 node_modules/
 .code-workspace
+.asv/
+uv.lock
+
+# memray report
+*.bin
+
+# speedscope report
+profile.speedscope.json
 
 # test datasets (e.g. Xenium ones)
-# symlinks
-data
 # data folder
 data/
 tests/data
+.venv

{spatialdata_io-0.5.1 → spatialdata_io-0.7.0}/.pre-commit-config.yaml

@@ -7,17 +7,17 @@ default_stages:
 minimum_pre_commit_version: 2.16.0
 repos:
     - repo: https://github.com/rbubley/mirrors-prettier
-      rev: v3.6.2
+      rev: v3.8.3
       hooks:
           - id: prettier
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.14.1
+      rev: v0.15.12
       hooks:
           - id: ruff
             args: [--fix, --exit-non-zero-on-fix, --unsafe-fixes]
           - id: ruff-format
     - repo: https://github.com/pre-commit/mirrors-mypy
-      rev: v1.18.2
+      rev: v1.20.2
       hooks:
           - id: mypy
             additional_dependencies: [numpy, types-PyYAML]

{spatialdata_io-0.5.1 → spatialdata_io-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatialdata-io
-Version: 0.5.1
+Version: 0.7.0
 Summary: SpatialData IO for common techs
 Project-URL: Documentation, https://spatialdata-io.readthedocs.io/
 Project-URL: Source, https://github.com/scverse/spatialdata-io
@@ -50,8 +50,9 @@ Requires-Dist: pyarrow
 Requires-Dist: readfcs
 Requires-Dist: scanpy
 Requires-Dist: scikit-image
-Requires-Dist: spatialdata>=0.2.6
+Requires-Dist: spatialdata>=0.7.3a0
 Requires-Dist: tifffile>=2023.8.12
+Requires-Dist: xmltodict
 Provides-Extra: dev
 Requires-Dist: bump2version; extra == 'dev'
 Requires-Dist: pre-commit; extra == 'dev'
@@ -63,13 +64,15 @@ Requires-Dist: sphinx-book-theme>=1.0.0; extra == 'doc'
 Requires-Dist: sphinx-click; extra == 'doc'
 Requires-Dist: sphinx-copybutton; extra == 'doc'
 Requires-Dist: sphinx-design; extra == 'doc'
-Requires-Dist: sphinx>=4.5; extra == 'doc'
+Requires-Dist: sphinx<9,>=4.5; extra == 'doc'
 Requires-Dist: sphinxcontrib-bibtex>=1.0.0; extra == 'doc'
 Provides-Extra: pre
-Requires-Dist: spatialdata>=0.4.0rc0; extra == 'pre'
+Requires-Dist: spatialdata>=0.7.3a0; extra == 'pre'
 Provides-Extra: test
+Requires-Dist: pyarrow!=22; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-mock; extra == 'test'
 Description-Content-Type: text/markdown
 
 ![SpatialData banner](https://github.com/scverse/spatialdata/blob/main/docs/_static/img/spatialdata_horizontal.png?raw=true)
@@ -108,7 +111,7 @@ This package contains reader functions to load common spatial omics formats into
 
 Note: all mentioned technologies are registered trademarks of their respective companies.
 
-Please refer to the list of [open Pull Requests](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen) for readers that are currently being developed.
+Please refer to the list of [open Pull Requests](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen) for readers that are currently being developed. The list of [closed but unmerged PRs](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aunmerged+is%3Aclosed) may also contain useful code from old drafts of readers. Please get in touch if you would like to [contribute](https://github.com/scverse/spatialdata-io/blob/main/docs/contributing.md) and iterate on a PR, or reopen a closed one.
 
 ## Known limitations
 

{spatialdata_io-0.5.1 → spatialdata_io-0.7.0}/README.md

@@ -34,7 +34,7 @@ This package contains reader functions to load common spatial omics formats into
 
 Note: all mentioned technologies are registered trademarks of their respective companies.
 
-Please refer to the list of [open Pull Requests](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen) for readers that are currently being developed.
+Please refer to the list of [open Pull Requests](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aopen) for readers that are currently being developed. The list of [closed but unmerged PRs](https://github.com/scverse/spatialdata-io/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aunmerged+is%3Aclosed) may also contain useful code from old drafts of readers. Please get in touch if you would like to [contribute](https://github.com/scverse/spatialdata-io/blob/main/docs/contributing.md) and iterate on a PR, or reopen a closed one.
 
 ## Known limitations
 

spatialdata_io-0.7.0/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.7.0'
+__version_tuple__ = version_tuple = (0, 7, 0)
+
+__commit_id__ = commit_id = None

spatialdata_io-0.7.0/asv.conf.json

@@ -0,0 +1,23 @@
+{
+    "version": 1,
+    "project": "spatialdata-io",
+    "project_url": "https://github.com/scverse/spatialdata-io",
+    "repo": ".",
+    "branches": ["faster-imports", "main"],
+    "dvcs": "git",
+    "environment_type": "virtualenv",
+    "pythons": ["3.13"],
+    "build_command": [],
+    "install_command": ["python -m pip install {build_dir}[test]"],
+    "uninstall_command": ["python -m pip uninstall -y {project}"],
+    "env_dir": ".asv/env",
+    "results_dir": ".asv/results",
+    "html_dir": ".asv/html",
+    "benchmark_dir": "benchmarks",
+    "hash_length": 8,
+    "build_cache_size": 2,
+    "install_timeout": 600,
+    "repeat": 5,
+    "processes": 1,
+    "attribute_selection": ["time_*", "peakmem_*"]
+}

spatialdata_io-0.7.0/benchmarks/__init__.py

@@ -0,0 +1 @@
+# ASV benchmarks for spatialdata-io

spatialdata_io-0.7.0/benchmarks/benchmark_image.py

@@ -0,0 +1,180 @@
+"""Benchmarks for SpatialData IO operations for large images.
+
+Instructions:
+    See benchmark_xenium.py for instructions.
+"""
+
+import logging
+import logging.handlers
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import tifffile
+from spatialdata import SpatialData
+from spatialdata._logging import logger
+from xarray import DataArray
+
+from spatialdata_io import image
+
+# =============================================================================
+# CONFIGURATION - Edit these values to match your setup
+# =============================================================================
+# Image dimensions: (channels, height, width)
+IMAGE_SHAPE = (3, 30000, 30000)
+# =============================================================================
+
+
+class IOBenchmarkImage:
+    """Benchmark IO read operations with different parameter combinations."""
+
+    timeout = 3600
+    repeat = 3
+    number = 1
+    warmup_time = 0
+    processes = 1
+
+    # Parameter combinations: scale_factors, (use_tiff_memmap, compressed), chunks
+    # Combinations: (memmap=False, compressed=True), (memmap=False, compressed=False), (memmap=True, compressed=False)
+    params = [
+        [None, [2, 2]],  # scale_factors
+        [(False, True), (False, False), (True, False)],  # (use_tiff_memmap, compressed)
+        [(1, 250, 250), (3, 250, 250)],  # chunks
+    ]
+    param_names = ["scale_factors", "memmap_compressed", "chunks"]
+
+    # Class-level temp directory for image files (persists across all benchmarks)
+    _images_temp_dir: tempfile.TemporaryDirectory[str] | None = None
+    _path_read_uncompressed: Path | None = None
+    _path_read_compressed: Path | None = None
+
+    @classmethod
+    def _setup_images(cls) -> None:
+        """Create fake image data once for all benchmarks."""
+        if cls._images_temp_dir is not None:
+            return
+
+        cls._images_temp_dir = tempfile.TemporaryDirectory()
+        images_dir = Path(cls._images_temp_dir.name)
+        cls._path_read_uncompressed = images_dir / "image_uncompressed.tif"
+        cls._path_read_compressed = images_dir / "image_compressed.tif"
+
+        # Generate fake image data
+        rng = np.random.default_rng(42)
+        data = rng.integers(0, 255, size=IMAGE_SHAPE, dtype=np.uint8)
+
+        # Write uncompressed TIFF (memmappable)
+        tifffile.imwrite(cls._path_read_uncompressed, data, compression=None)
+        # Write compressed TIFF (not memmappable)
+        tifffile.imwrite(cls._path_read_compressed, data, compression="zlib")
+
+    def setup(self, *_: Any) -> None:
+        """Set up paths for benchmarking."""
+        # Create images once (shared across all benchmark runs)
+        self._setup_images()
+        self.path_read_uncompressed = self._path_read_uncompressed
+        self.path_read_compressed = self._path_read_compressed
+
+        # Create a separate temp directory for output (cleaned up after each run)
+        self._output_temp_dir = tempfile.TemporaryDirectory()
+        self.path_write = Path(self._output_temp_dir.name) / "data_benchmark.zarr"
+
+    def teardown(self, *_: Any) -> None:
+        """Clean up output directory after each benchmark run."""
+        if hasattr(self, "_output_temp_dir"):
+            self._output_temp_dir.cleanup()
+
+    def _convert_image(
+        self, scale_factors: list[int] | None, memmap_compressed: tuple[bool, bool], chunks: tuple[int, ...]
+    ) -> SpatialData:
+        """Read image data with specified parameters."""
+        use_tiff_memmap, compressed = memmap_compressed
+        # Select file based on compression setting
+        path_read = self.path_read_compressed if compressed else self.path_read_uncompressed
+        assert path_read is not None
+
+        # Capture log messages to verify memmappable warning behavior
+        log_capture = logging.handlers.MemoryHandler(capacity=100)
+        log_capture.setLevel(logging.WARNING)
+        logger.addHandler(log_capture)
+        original_propagate = logger.propagate
+        logger.propagate = True
+
+        try:
+            im = image(
+                input=path_read,
+                data_axes=("c", "y", "x"),
+                coordinate_system="global",
+                use_tiff_memmap=use_tiff_memmap,
+                chunks=chunks,
+                scale_factors=scale_factors,
+            )
+        finally:
+            logger.removeHandler(log_capture)
+            logger.propagate = original_propagate
+
+        # Check warning behavior: when use_tiff_memmap=True with uncompressed file, no warning should be raised
+        log_messages = [record.getMessage() for record in log_capture.buffer]
+        has_memmap_warning = any("image data is not memory-mappable" in msg for msg in log_messages)
+        if use_tiff_memmap and not compressed:
+            assert not has_memmap_warning, (
+                "Uncompressed TIFF with memmap=True should not trigger memory-mappable warning"
+            )
+
+        sdata = SpatialData.init_from_elements({"image": im})
+        # sanity check: chunks is (c, y, x)
+        if scale_factors is None:
+            assert isinstance(sdata["image"], DataArray)
+            if chunks is not None:
+                assert (
+                    sdata["image"].chunksizes["x"][0] == chunks[2]
+                    or sdata["image"].chunksizes["x"][0] == sdata["image"].shape[2]
+                )
+                assert (
+                    sdata["image"].chunksizes["y"][0] == chunks[1]
+                    or sdata["image"].chunksizes["y"][0] == sdata["image"].shape[1]
+                )
+        else:
+            assert len(sdata["image"].keys()) == len(scale_factors) + 1
+            if chunks is not None:
+                assert (
+                    sdata["image"]["scale0"]["image"].chunksizes["x"][0] == chunks[2]
+                    or sdata["image"]["scale0"]["image"].chunksizes["x"][0]
+                    == sdata["image"]["scale0"]["image"].shape[2]
+                )
+                assert (
+                    sdata["image"]["scale0"]["image"].chunksizes["y"][0] == chunks[1]
+                    or sdata["image"]["scale0"]["image"].chunksizes["y"][0]
+                    == sdata["image"]["scale0"]["image"].shape[1]
+                )
+
+        return sdata
+
+    def time_io(
+        self, scale_factors: list[int] | None, memmap_compressed: tuple[bool, bool], chunks: tuple[int, ...]
+    ) -> None:
+        """Walltime for data parsing."""
+        sdata = self._convert_image(scale_factors, memmap_compressed, chunks)
+        sdata.write(self.path_write)
+
+    def peakmem_io(
+        self, scale_factors: list[int] | None, memmap_compressed: tuple[bool, bool], chunks: tuple[int, ...]
+    ) -> None:
+        """Peak memory for data parsing."""
+        sdata = self._convert_image(scale_factors, memmap_compressed, chunks)
+        sdata.write(self.path_write)
+
+
+# if __name__ == "__main__":
+#     # Run a single test case for quick verification
+#     bench = IOBenchmarkImage()
+#
+#     bench.setup()
+#     bench.time_io(None, (True, False), (1, 5000, 5000))
+#     bench.teardown()
+#
+#     # Clean up the shared images temp directory at the end
+#     if IOBenchmarkImage._images_temp_dir is not None:
+#         IOBenchmarkImage._images_temp_dir.cleanup()
+#         IOBenchmarkImage._images_temp_dir = None

spatialdata_io-0.7.0/benchmarks/benchmark_imports.py

@@ -0,0 +1,103 @@
+"""ASV benchmarks for spatialdata-io import times.
+
+Measures how long it takes to import the package and individual readers
+in a fresh subprocess, isolating import overhead from runtime work.
+
+Running (with the current environment, no virtualenv rebuild):
+    # Quick sanity check (single iteration):
+    asv run --python=same --quick --show-stderr -v -b ImportBenchmark
+
+    # Full benchmark on current commit:
+    asv run --python=same --show-stderr -v -b ImportBenchmark
+
+    # Compare two branches (using --python=same, one-liner):
+    git stash && git checkout main && pip install -e . -q \
+        && asv run --python=same -v -b ImportBenchmark \
+        && git checkout faster-imports && git stash pop && pip install -e . -q \
+        && asv run --python=same -v -b ImportBenchmark
+    # Then view the comparison:
+    asv compare $(git rev-parse main) $(git rev-parse faster-imports)
+
+    # Compare two branches (let ASV build virtualenvs, slower first run):
+    asv continuous --show-stderr -v -b ImportBenchmark main faster-imports
+
+    # Generate an HTML report:
+    asv publish && asv preview
+"""
+
+import subprocess
+import sys
+
+
+def _import_time(statement: str) -> float:
+    """Time an import in a fresh subprocess. Returns seconds."""
+    code = f"import time; t0=time.perf_counter(); {statement}; print(time.perf_counter()-t0)"
+    result = subprocess.run(
+        [sys.executable, "-c", code],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr)
+    return float(result.stdout.strip())
+
+
+class ImportBenchmark:
+    """Import-time benchmarks for spatialdata-io.
+
+    Each ``time_*`` method is a separate ASV benchmark.
+    They run in isolated subprocesses so that one import
+    does not warm the cache for the next.
+    """
+
+    # ASV settings tuned for subprocess-based import timing:
+    timeout = 120  # seconds before ASV kills a benchmark; generous since each
+    # call spawns a subprocess (~2s each × 10 repeats = ~20s worst case)
+    repeat = 5  # number of timing samples ASV collects; high because import
+    # times have variance from OS caching / disk I/O / background load;
+    # ASV reports the median and IQR from these samples
+    number = 1  # calls per sample; must be 1 because each call spawns a fresh
+    # subprocess — running >1 would just re-import in a warm process
+    warmup_time = 0  # seconds of warm-up iterations before timing; disabled because
+    # each call is already a cold subprocess — warming up the parent
+    # process is meaningless
+    processes = 1  # number of ASV worker processes; 1 avoids parallel subprocesses
+    # competing for CPU / disk and inflating timings
+
+    # -- top-level package -------------------------------------------------
+
+    def time_import_spatialdata_io(self) -> float:
+        """Wall time: ``import spatialdata_io`` (lazy, no readers loaded)."""
+        return _import_time("import spatialdata_io")
+
+    # -- single reader via the public API ----------------------------------
+
+    def time_from_spatialdata_io_import_xenium(self) -> float:
+        """Wall time: ``from spatialdata_io import xenium``."""
+        return _import_time("from spatialdata_io import xenium")
+
+    def time_from_spatialdata_io_import_visium(self) -> float:
+        """Wall time: ``from spatialdata_io import visium``."""
+        return _import_time("from spatialdata_io import visium")
+
+    def time_from_spatialdata_io_import_visium_hd(self) -> float:
+        """Wall time: ``from spatialdata_io import visium_hd``."""
+        return _import_time("from spatialdata_io import visium_hd")
+
+    def time_from_spatialdata_io_import_merscope(self) -> float:
+        """Wall time: ``from spatialdata_io import merscope``."""
+        return _import_time("from spatialdata_io import merscope")
+
+    def time_from_spatialdata_io_import_cosmx(self) -> float:
+        """Wall time: ``from spatialdata_io import cosmx``."""
+        return _import_time("from spatialdata_io import cosmx")
+
+    # -- key dependencies (reference) --------------------------------------
+
+    def time_import_spatialdata(self) -> float:
+        """Wall time: ``import spatialdata`` (reference)."""
+        return _import_time("import spatialdata")
+
+    def time_import_anndata(self) -> float:
+        """Wall time: ``import anndata`` (reference)."""
+        return _import_time("import anndata")

spatialdata_io-0.7.0/benchmarks/benchmark_xenium.py

@@ -0,0 +1,108 @@
+"""Benchmarks for SpatialData IO operations.
+
+Configuration:
+    Edit SANDBOX_DIR and DATASET below to point to your data.
+
+Setup:
+    cd <SANDBOX_DIR>/<DATASET>
+    python download.py  # use the same env where spatialdata is installed
+
+Running:
+    cd /path/to/spatialdata-io
+
+    # Quick benchmark (single run, for testing):
+    asv run --python=same -b IOBenchmarkXenium --quick --show-stderr -v
+
+    # Full benchmark (multiple runs, for accurate results):
+    asv run --python=same -b IOBenchmarkXenium --show-stderr -v
+
+Comparing branches:
+    # Run on specific commits:
+    asv run main^! -b IOBenchmarkXenium --show-stderr -v
+    asv run xenium-labels-dask^! -b IOBenchmarkXenium --show-stderr -v
+
+    # Or compare two branches directly:
+    asv continuous main xenium-labels-dask -b IOBenchmarkXenium --show-stderr -v
+
+    # View comparison:
+    asv compare main xenium-labels-dask
+
+Results:
+    - Console output shows timing and memory after each run
+    - JSON results saved to: .asv/results/
+    - Generate HTML report: asv publish && asv preview
+"""
+
+import inspect
+import shutil
+from pathlib import Path
+
+from spatialdata import SpatialData
+
+from spatialdata_io import xenium
+
+# =============================================================================
+# CONFIGURATION - Edit these paths to match your setup
+# =============================================================================
+SANDBOX_DIR = Path(__file__).parent.parent.parent / "spatialdata-sandbox"
+DATASET = "xenium_2.0.0_io"
+# =============================================================================
+
+
+def get_paths() -> tuple[Path, Path]:
+    """Get paths for benchmark data."""
+    path = SANDBOX_DIR / DATASET
+    path_read = path / "data"
+    path_write = path / "data_benchmark.zarr"
+
+    if not path_read.exists():
+        raise ValueError(f"Data directory not found: {path_read}")
+
+    return path_read, path_write
+
+
+class IOBenchmarkXenium:
+    timeout = 3600
+    repeat = 3
+    number = 1
+    warmup_time = 0
+    processes = 1
+
+    def setup(self) -> None:
+        """Set up paths for benchmarking."""
+        self.path_read, self.path_write = get_paths()
+        if self.path_write.exists():
+            shutil.rmtree(self.path_write)
+
+    def _read_xenium(self) -> SpatialData:
+        """Read xenium data with version-compatible kwargs."""
+        signature = inspect.signature(xenium)
+        kwargs = {}
+        if "cleanup_labels_zarr_tmpdir" in signature.parameters:
+            kwargs["cleanup_labels_zarr_tmpdir"] = False
+
+        return xenium(
+            path=str(self.path_read),
+            n_jobs=8,
+            cell_boundaries=True,
+            nucleus_boundaries=True,
+            morphology_focus=True,
+            cells_as_circles=True,
+            **kwargs,
+        )
+
+    def time_io(self) -> None:
+        """Walltime for data parsing."""
+        sdata = self._read_xenium()
+        sdata.write(self.path_write)
+
+    def peakmem_io(self) -> None:
+        """Peak memory for data parsing."""
+        sdata = self._read_xenium()
+        sdata.write(self.path_write)
+
+
+if __name__ == "__main__":
+    benchmark = IOBenchmarkXenium()
+    benchmark.setup()
+    benchmark.time_io()

{spatialdata_io-0.5.1 → spatialdata_io-0.7.0}/docs/conf.py

@@ -127,6 +127,7 @@ nitpick_ignore = [
     # If building the documentation fails because of a missing link that is outside your control,
     # you can add an exception to this list.
     ("py:class", "Path"),
+    ("py:class", "pathlib._local.Path"),
     ("py:class", "AnnData"),
     ("py:class", "SpatialData"),
     ("py:func", "imageio.imread"),  # maybe this can be fixed