thyra 2.2.3__tar.gz → 2.3.0__tar.gz

{thyra-2.2.3 → thyra-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thyra
-Version: 2.2.3
+Version: 2.3.0
 Summary: A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics
 License: MIT
 License-File: LICENSE
@@ -39,7 +39,7 @@ Requires-Dist: pyimzML (>=1.4.0)
 Requires-Dist: scipy (>=1.7.0)
 Requires-Dist: spatialdata (>=0.8.0,<0.9)
 Requires-Dist: tqdm (>=4.50.0)
-Requires-Dist: zarr (>=3.0.0,<3.2)
+Requires-Dist: zarr (>=3.1.4,<3.2)
 Project-URL: Bug Tracker, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/issues
 Project-URL: Changelog, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CHANGELOG.md
 Project-URL: Contributing, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CONTRIBUTING.md

{thyra-2.2.3 → thyra-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thyra"
-version = "2.2.3"
+version = "2.3.0"
 description = "A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics"
 authors = ["Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>"]
 maintainers = ["Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>"]
@@ -86,7 +86,16 @@ spatialdata = ">=0.8.0, <0.9"       # tested 0.8.0
 # bit ome_zarr 0.12.x with newer dask, and spatialdata 0.8 requires >= 0.16.
 ome-zarr = ">=0.16.0, <0.19"        # tested 0.18.0
 tqdm = ">=4.50.0"
-zarr = ">=3.0.0, <3.2"              # tested 3.1.3
+# Floor is 3.1.4, and it is load-bearing. anndata >= 0.13 writes every zarr v3
+# array with `shards="auto"`. zarr < 3.1.4 sized the auto chunk with
+# `max_bytes=1024` where its own comment says "aim for a 1MiB chunk" (compare
+# `_auto_partition` in 3.1.3 vs 3.1.4), so one shard -- one FILE -- came out at
+# ~1 KB. Measured on test_data/pea.imzML: 393,310 files for a single table and
+# 434 s of a 445 s conversion spent in the write, against 12 files and 2.7 s on
+# 3.1.6. Nothing in Thyra changed; the anndata 0.13 bump alone did this.
+# 3.1.4 is also where `array.target_shard_size_bytes` arrives, which is the
+# knob _chunking.table_write_config sets to claim the budget from anndata.
+zarr = ">=3.1.4, <3.2"              # tested 3.1.6
 imagecodecs = ">=2024.1.1"  # For reading compressed TIFF optical images
 # Floor is 0.13.2, not 0.13.0. anndata 0.13.0 imports
 # `typing_extensions.sentinel` (needs typing-extensions >= 4.16) but declares

{thyra-2.2.3 → thyra-2.3.0}/thyra/__init__.py

@@ -36,7 +36,7 @@ warnings.filterwarnings(
     category=FutureWarning,
 )
 
-__version__ = "2.2.3"
+__version__ = "2.3.0"
 
 # Import key components - avoid wildcard imports
 try:

{thyra-2.2.3 → thyra-2.3.0}/thyra/__main__.py

@@ -261,11 +261,21 @@ def _build_resampling_config(
 def _build_reader_options(
     use_recalibrated: bool,
     intensity_threshold: Optional[float],
-) -> dict[str, bool | float]:
-    """Build reader options dictionary from CLI parameters."""
-    options: dict[str, bool | float] = {"use_recalibrated_state": use_recalibrated}
+    spectrum_type: str = "auto",
+) -> dict[str, bool | float | str]:
+    """Build reader options dictionary from CLI parameters.
+
+    ``spectrum_type="auto"`` is the CLI's way of saying "no override", so it is
+    omitted entirely rather than forwarded -- readers take ``None``/absent to
+    mean detect, and ``"auto"`` is not a representation.
+    """
+    options: dict[str, bool | float | str] = {
+        "use_recalibrated_state": use_recalibrated
+    }
     if intensity_threshold is not None:
         options["intensity_threshold"] = intensity_threshold
+    if spectrum_type != "auto":
+        options["spectrum_type"] = spectrum_type
     return options
 
 
@@ -548,6 +558,17 @@ class GroupedCommand(click.Command):
         "(default: no limit)"
     ),
 )
+@click.option(
+    "--spectrum-type",
+    type=click.Choice(["auto", "profile", "centroid"]),
+    default="auto",
+    help=(
+        "Spectrum representation (default: auto-detect from the file). "
+        "Overrides what the imzML declares via MS:1000127/MS:1000128; "
+        "contradicting a declaration is logged as a warning. SCiLS Lab spells "
+        "this --rep_type. imzML only."
+    ),
+)
 # -- Bruker-specific --
 @click.option(
     "--use-recalibrated/--no-recalibrated",
@@ -597,6 +618,7 @@ def main(
     resample_reference_mz: float,
     resample_gap_tolerance: Optional[float],
     mass_axis_type: str,
+    spectrum_type: str,
     sparse_format: str,
     include_optical: bool,
     intensity_threshold: Optional[float],
@@ -664,7 +686,9 @@ def main(
     )
 
     # Build reader options for format-specific settings
-    reader_options = _build_reader_options(use_recalibrated, intensity_threshold)
+    reader_options = _build_reader_options(
+        use_recalibrated, intensity_threshold, spectrum_type
+    )
 
     # Perform conversion
     success = convert_msi(

{thyra-2.2.3 → thyra-2.3.0}/thyra/convert.py

@@ -290,6 +290,17 @@ def convert_msi(
               which is the limit SCiLS Lab places on the same
               quantity (2026b User Guide, p.76). Pass None for
               no limit.
+            - spectrum_type: str - For imzML, declare the spectrum
+              representation explicitly: 'profile' or 'centroid'
+              (the full CV names are accepted too). Outranks the
+              file's own MS:1000127/MS:1000128, so it can correct a
+              file that declares the wrong thing; contradicting a
+              declaration is logged as a warning. SCiLS Lab spells
+              this --rep_type (2026b User Guide, p.81). Default:
+              None, meaning detect. **Changes stored values** for
+              files where it disagrees with what detection would
+              have chosen, because the representation feeds
+              instrument and axis-type selection.
         sparse_format: Sparse matrix format ('csc' or 'csr')
         include_optical: Include optical images (default: True)
         apply_optical_alignment: If True (default) and the MSI source

thyra-2.3.0/thyra/converters/spatialdata/_chunking.py

@@ -0,0 +1,89 @@
+"""Chunk/shard policy for the zarr Thyra writes: rasters and the MSI table.
+
+Single source of truth for how Thyra chunks the raster images it writes to
+SpatialData zarr -- and the designated seam for tile-aligned zarr v3 sharding
+once scverse/spatialdata PR #1106 (``raster_write_kwargs``) lands.
+
+Cross-repo contract: the viewer (Ousia) morphology tile server streams
+``DEFAULT_TILE_SIZE`` (= 512) edge tiles. Once sharding lands, the zarr INNER
+chunk edge must equal that so one served tile == one decompress. Thyra is a
+separate package and CANNOT import Ousia, so the coupling is DUPLICATED BY
+CONTRACT here -- keep ``INNER_TILE_EDGE`` numerically in sync with Ousia's
+``DEFAULT_TILE_SIZE``; a silent divergence reintroduces cold-tile amplification
+on the viewer. See the Ousia ADR docs/ADR-pyramid-tile-sharding.md.
+
+The raster policy above is passed per-array. The TABLE policy below cannot be:
+``SpatialData.write`` hands the table straight to ``anndata.write_elem`` and
+exposes no ``dataset_kwargs`` seam, so the only supported lever is zarr's own
+config. ``table_write_config()`` is that lever, and every writer that reaches
+zarr through spatialdata (the 2D, 3D and streaming-COO converters, all via
+``_save_output``) must hold it open across the write. The streaming-PCS writer
+hand-rolls its ``create_array`` calls and sizes them itself.
+"""
+
+from contextlib import contextmanager
+from typing import Iterator, Tuple
+
+import zarr
+
+# Outer chunk edge used TODAY (pre-sharding the chunk IS the outer block): a 4096
+# block means a viewer 512-tile read decompresses at most one chunk per request.
+IMAGE_CHUNK_EDGE = 4096
+
+# Future zarr INNER chunk edge once #1106 lands == Ousia DEFAULT_TILE_SIZE (512).
+# Duplicated by contract (Thyra cannot import Ousia).
+INNER_TILE_EDGE = 512
+
+# Uncompressed byte budget for ONE SHARD of a table array -- X/data, X/indices,
+# X/indptr and every obs/var column anndata writes. One shard is one FILE, so
+# this is what keeps a 36M-nnz table (test_data/bellini.imzML) in 11 files
+# instead of 394,699.
+#
+# anndata >= 0.13 turns on ``shards="auto"`` for zarr v3 and would otherwise
+# pick its own 1 GB budget; it explicitly yields to a caller-set value (see
+# ``anndata._io.specs.methods.zarr_v3_sharding``). We set a smaller one because
+# a shard is assembled in memory before it is written -- anndata's own comment
+# says so -- and Thyra converts multi-GB acquisitions on workstations, where a
+# 1 GB write buffer is a real cost. 128 MiB is still enormous relative to the
+# file counts that hurt: test_data/pea.imzML (60.1M nnz, 481 MB of X/data)
+# lands in 4 data files, so even a table 100x that size stays in the hundreds.
+#
+# The INNER chunk stays zarr's ~1 MiB auto pick: that is the unit a random read
+# decompresses, and it is the size the non-sharded path used before anndata
+# began auto-sharding, so read amplification is unchanged.
+TABLE_SHARD_TARGET_BYTES = 128 * 1024 * 1024
+
+# zarr < 3.1.4 computed the auto chunk with ``max_bytes=1024`` where 1 MiB was
+# meant, so ``shards="auto"`` produced ~1 KB shards -- one file per KB of table.
+# It also predates ``array.target_shard_size_bytes``, making the budget above
+# unenforceable. pyproject pins the floor at 3.1.4 for exactly this reason;
+# this constant is what the regression test checks the floor still buys us.
+MIN_TABLE_SHARD_BYTES = 64 * 1024
+
+
+@contextmanager
+def table_write_config() -> Iterator[None]:
+    """Hold Thyra's table shard budget open across a ``SpatialData.write``.
+
+    Wraps zarr's global config, so it must stay open for the *whole* write --
+    the arrays are created lazily inside anndata, not up front.
+    """
+    with zarr.config.set({"array.target_shard_size_bytes": TABLE_SHARD_TARGET_BYTES}):
+        yield
+
+
+def image_chunks(spatial_ndim: int, edge: int = IMAGE_CHUNK_EDGE) -> Tuple[int, ...]:
+    """The zarr chunk tuple for a Thyra-written raster image (leading channel axis).
+
+    ``spatial_ndim == 2`` (c, y, x) -> ``(1, edge, edge)``;
+    ``spatial_ndim == 3`` (c, z, y, x) -> ``(1, 1, edge, edge)``.
+
+    This is the ONE place the future inner=``INNER_TILE_EDGE`` + outer-shard policy
+    will live when spatialdata PR #1106 ships ``raster_write_kwargs``. Today it
+    returns the pre-sharding behaviour, byte-for-byte.
+    """
+    if spatial_ndim == 2:
+        return (1, edge, edge)
+    if spatial_ndim == 3:
+        return (1, 1, edge, edge)
+    raise ValueError(f"spatial_ndim must be 2 or 3, got {spatial_ndim}")

{thyra-2.2.3 → thyra-2.3.0}/thyra/converters/spatialdata/base_spatialdata_converter.py

@@ -21,7 +21,7 @@ from ...resampling.gaps import zero_across_gaps
 from ...resampling.tic import preserved_tic, rescale_to_preserved_tic
 from ...resampling.types import ResamplingConfig
 from ...utils.zarr_atomic_write import install_windows_atomic_write_retry
-from ._chunking import image_chunks
+from ._chunking import image_chunks, table_write_config
 
 logger = logging.getLogger(__name__)
 
@@ -494,56 +494,72 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         except Exception as e:
             logger.debug(f"Could not extract spectrum metadata: {e}")
 
-    def _add_metadata_to_uns(self, adata) -> None:
-        """Add MSI metadata to AnnData .uns for preservation in SpatialData.
-
-        This stores comprehensive metadata including:
-        - Essential metadata (dimensions, mass range, source)
-        - Format-specific metadata (FlexImaging areas, teaching points, etc.)
-        - Acquisition parameters
-        - Instrument information
-        - Raw metadata (complete original metadata for future use)
+    def build_uns_metadata(self) -> Dict[str, Any]:
+        """The provenance block every write path must persist, identically.
+
+        Single source of truth for what lands in the table's ``uns``:
+
+        - ``essential_metadata`` -- dimensions, mass range, source path,
+          spectrum type and the Thyra version that wrote the store.
+        - ``format_specific`` -- vendor metadata (FlexImaging areas,
+          teaching points, imzML file mode, ...).
+        - ``acquisition_params`` / ``instrument_info`` -- when the reader
+          has them.
+        - ``raw_metadata`` -- the source metadata as read.
+        - ``regions`` -- the acquisition region summary, as JSON.
+
+        This exists because the converters have two write paths and they
+        drifted. The in-memory and streaming-COO paths hand the table to
+        ``anndata``'s writer, which serialises whatever is in
+        ``adata.uns``; the streaming-PCS path hand-writes the Zarr layout
+        and used to compose its own, much smaller block -- with
+        ``spectrum_type`` hardcoded to ``"processed"``, which is not even
+        a value the extractors produce. A dataset that crossed
+        ``StreamingSpatialDataConverter.PCS_SIZE_THRESHOLD_GB`` therefore
+        came out claiming a spectrum representation it did not have, and
+        without any of the other sections, while a slightly smaller one
+        from the same instrument came out complete. Both paths now render
+        this mapping, so a section added here reaches every store.
+
+        Sections the reader has nothing for are omitted rather than
+        written empty, so consumers can tell "not available from this
+        format" from "available and empty".
+
+        Returns:
+            Mapping of ``uns`` key to the value to store. Empty if the
+            reader cannot produce comprehensive metadata at all.
         """
         try:
             comp_meta = self.reader.get_comprehensive_metadata()
+        except Exception as e:
+            # Non-fatal: a store without provenance still holds the
+            # spectra. But it is not a debug-level event -- the whole
+            # point of the block is that a consumer can say where the
+            # data came from, so losing it has to be visible in the log.
+            logger.warning("Could not read metadata for uns provenance: %s", e)
+            return {}
+
+        uns: Dict[str, Any] = {}
+        try:
+            self._collect_essential_metadata(uns, comp_meta)
+            self._collect_optional_sections(uns, comp_meta)
+            self._collect_region_info(uns)
+        except Exception as e:
+            logger.warning("Could not build the full uns provenance block: %s", e)
 
-            self._store_format_specific(adata, comp_meta)
-            self._store_acquisition_params(adata, comp_meta)
-            self._store_instrument_info(adata, comp_meta)
-            self._store_essential_metadata(adata, comp_meta)
-            self._store_raw_metadata(adata, comp_meta)
-            self._store_region_info(adata)
+        return uns
 
-            logger.debug("Added MSI metadata to AnnData .uns")
-        except Exception as e:
-            logger.debug(f"Could not add metadata to .uns: {e}")
-
-    def _store_format_specific(self, adata, comp_meta) -> None:
-        """Store format-specific metadata (FlexImaging areas, teaching points)."""
-        if hasattr(comp_meta, "format_specific") and comp_meta.format_specific:
-            adata.uns["format_specific"] = comp_meta.format_specific
-
-    def _store_acquisition_params(self, adata, comp_meta) -> None:
-        """Store acquisition parameters."""
-        if hasattr(comp_meta, "acquisition_params") and comp_meta.acquisition_params:
-            adata.uns["acquisition_params"] = comp_meta.acquisition_params
-
-    def _store_instrument_info(self, adata, comp_meta) -> None:
-        """Store instrument information."""
-        if hasattr(comp_meta, "instrument_info") and comp_meta.instrument_info:
-            adata.uns["instrument_info"] = comp_meta.instrument_info
-
-    def _store_essential_metadata(self, adata, comp_meta) -> None:
-        """Store essential metadata (convert tuples to lists for Zarr)."""
-        if not hasattr(comp_meta, "essential"):
+    def _collect_essential_metadata(self, uns: Dict[str, Any], comp_meta: Any) -> None:
+        """Add ``essential_metadata`` (tuples become lists for Zarr)."""
+        essential = getattr(comp_meta, "essential", None)
+        if essential is None:
             return
 
-        essential = comp_meta.essential
         dims = essential.dimensions
         mrange = essential.mass_range
         from thyra import __version__
 
-        adata.uns["essential_metadata"] = {
+        uns["essential_metadata"] = {
             "source_path": str(essential.source_path),
             "dimensions": list(dims) if dims else None,
             "mass_range": list(mrange) if mrange else None,
@@ -551,13 +567,19 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             "thyra_version": __version__,
         }
 
-    def _store_raw_metadata(self, adata, comp_meta) -> None:
-        """Store raw metadata (complete original data for future use)."""
-        if hasattr(comp_meta, "raw_metadata") and comp_meta.raw_metadata:
-            adata.uns["raw_metadata"] = self._serialize_for_zarr(comp_meta.raw_metadata)
+    def _collect_optional_sections(self, uns: Dict[str, Any], comp_meta: Any) -> None:
+        """Add the vendor sections the reader actually populated."""
+        for key in ("format_specific", "acquisition_params", "instrument_info"):
+            value = getattr(comp_meta, key, None)
+            if value:
+                uns[key] = self._serialize_for_zarr(value)
+
+        raw_metadata = getattr(comp_meta, "raw_metadata", None)
+        if raw_metadata:
+            uns["raw_metadata"] = self._serialize_for_zarr(raw_metadata)
 
-    def _store_region_info(self, adata) -> None:
-        """Store acquisition region summary in uns as JSON.
+    def _collect_region_info(self, uns: Dict[str, Any]) -> None:
+        """Add the acquisition region summary as JSON.
 
         Stored as a JSON string because AnnData/zarr cannot round-trip
         a list of dicts (they get stringified individually). JSON
@@ -568,7 +590,13 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         """
         region_info = getattr(self, "_region_info", None)
         if region_info:
-            adata.uns["regions"] = json.dumps(self._serialize_for_zarr(region_info))
+            uns["regions"] = json.dumps(self._serialize_for_zarr(region_info))
+
+    def _add_metadata_to_uns(self, adata) -> None:
+        """Apply :meth:`build_uns_metadata` to an AnnData about to be written."""
+        uns = self.build_uns_metadata()
+        adata.uns.update(uns)
+        logger.debug("Added MSI metadata to AnnData .uns: %s", sorted(uns))
 
     def _serialize_for_zarr(self, obj):
         """Recursively convert tuples to lists for Zarr serialization."""
@@ -1921,8 +1949,12 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             # Add metadata
             self.add_metadata(sdata)
 
-            # Write to disk
-            with _suppress_upstream_warnings():
+            # Write to disk. table_write_config() must wrap the write itself,
+            # not just the SpatialData construction: anndata creates the table's
+            # zarr arrays lazily inside sdata.write, and that is where the shard
+            # budget is read. Without it the table lands in ~1 KB shards -- one
+            # file per KB -- and the write dominates conversion wall-clock.
+            with _suppress_upstream_warnings(), table_write_config():
                 sdata.write(str(self.output_path))
                 zarr.consolidate_metadata(str(self.output_path))
             logger.info(f"Successfully saved SpatialData to {self.output_path}")

{thyra-2.2.3 → thyra-2.3.0}/thyra/converters/spatialdata/spatialdata_3d_converter.py

@@ -221,6 +221,11 @@ class SpatialData3DConverter(BaseSpatialDataConverter):
                     per_region[str(r)] = total / max(count, 1)
                 adata.uns["average_spectrum_per_region"] = per_region
 
+            # Add MSI metadata to .uns. The 2D and streaming paths have
+            # always done this; the 3D one never did, so a volume came
+            # out with no record of where it came from at all.
+            self._add_metadata_to_uns(adata)
+
             # Make sure region column exists and is correct
             region_key = f"{self.dataset_id}_pixels"
             if "region" not in adata.obs.columns:

{thyra-2.2.3 → thyra-2.3.0}/thyra/converters/spatialdata/streaming_converter.py

@@ -1296,6 +1296,27 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
 
         return mm_indices, mm_data
 
+    def _write_uns_provenance(self, uns_group: "zarr.Group") -> None:
+        """Write the shared provenance block into a hand-written ``uns`` group.
+
+        This path composes the Zarr layout itself, so it cannot reach
+        ``adata.uns`` the way ``_save_output`` does. It renders the same
+        mapping through anndata's own element writer instead, which is
+        what produces the ``encoding-type`` / ``encoding-version`` pairs
+        ``read_lazy`` needs -- getting those right by hand is exactly
+        what this path used to have to do, and exactly where it drifted
+        from the other one.
+
+        Only ``uns`` goes through anndata here. ``obs``/``var`` stay
+        hand-written: they carry the pandas string dtypes this path
+        exists to sidestep, whereas the provenance block is plain dicts,
+        strings, lists and numbers.
+        """
+        from anndata.io import write_elem
+
+        for key, value in self.build_uns_metadata().items():
+            write_elem(uns_group, key, value)
+
     def _write_csc_arrays_to_zarr(
         self,
         mm_indices: np.memmap,
@@ -1540,40 +1561,7 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         a.attrs["encoding-type"] = "string"
         a.attrs["encoding-version"] = "0.2.0"
 
-        em_group = uns_group.create_group("essential_metadata")
-        em_group.attrs["encoding-type"] = "dict"
-        em_group.attrs["encoding-version"] = "0.1.0"
-        a = em_group.create_array(
-            "dimensions", data=np.asarray(np.array(self._dimensions))
-        )
-        a.attrs["encoding-type"] = "array"
-        a.attrs["encoding-version"] = "0.2.0"
-        a = em_group.create_array(
-            "mass_range",
-            data=np.array([mz_values.min(), mz_values.max()]),
-        )
-        a.attrs["encoding-type"] = "array"
-        a.attrs["encoding-version"] = "0.2.0"
-        a = em_group.create_array(
-            "source_path",
-            data=np.array(str(self.reader.data_path), dtype=str_dtype),
-        )
-        a.attrs["encoding-type"] = "string"
-        a.attrs["encoding-version"] = "0.2.0"
-        a = em_group.create_array(
-            "spectrum_type",
-            data=np.array("processed", dtype=str_dtype),
-        )
-        a.attrs["encoding-type"] = "string"
-        a.attrs["encoding-version"] = "0.2.0"
-        from thyra import __version__
-
-        a = em_group.create_array(
-            "thyra_version",
-            data=np.array(__version__, dtype=str_dtype),
-        )
-        a.attrs["encoding-type"] = "string"
-        a.attrs["encoding-version"] = "0.2.0"
+        self._write_uns_provenance(uns_group)
 
         a = uns_group.create_array("average_spectrum", data=avg_spectrum)
         a.attrs["encoding-type"] = "array"

{thyra-2.2.3 → thyra-2.3.0}/thyra/metadata/extractors/imzml_extractor.py

@@ -9,7 +9,12 @@ from numpy.typing import NDArray
 from pyimzml.ImzMLParser import ImzMLParser
 
 from ...core.base_extractor import MetadataExtractor
-from ...resampling.constants import BinaryDataType, ImzMLAccessions, SpectrumType
+from ...resampling.constants import (
+    BinaryDataType,
+    ImzMLAccessions,
+    SpectrumType,
+    normalize_spectrum_type,
+)
 from ..types import ComprehensiveMetadata, EssentialMetadata
 
 logger = logging.getLogger(__name__)
@@ -18,16 +23,32 @@ logger = logging.getLogger(__name__)
 class ImzMLMetadataExtractor(MetadataExtractor):
     """ImzML-specific metadata extractor with optimized two-phase extraction."""
 
-    def __init__(self, parser: ImzMLParser, imzml_path: Path):
+    def __init__(
+        self,
+        parser: ImzMLParser,
+        imzml_path: Path,
+        spectrum_type: Optional[str] = None,
+    ):
         """Initialize ImzML metadata extractor.
 
         Args:
             parser: Initialized ImzML parser
             imzml_path: Path to the ImzML file
+            spectrum_type: Optional override for the spectrum representation,
+                ``"profile"`` or ``"centroid"`` (SCiLS Lab spells this
+                ``--rep_type``). When given, it wins over anything the file
+                says. ``None`` -- the default -- leaves detection alone.
+
+        Raises:
+            ValueError: If ``spectrum_type`` is not a recognised
+                representation.
         """
         super().__init__(parser)
         self.parser = parser
         self.imzml_path = imzml_path
+        # Normalised at construction so a typo fails here rather than silently
+        # falling through to auto-detection during extraction.
+        self.spectrum_type_override = normalize_spectrum_type(spectrum_type)
 
     def _extract_essential_impl(self) -> EssentialMetadata:
         """Extract essential metadata optimized for speed."""
@@ -524,12 +545,19 @@ class ImzMLMetadataExtractor(MetadataExtractor):
     def _detect_centroid_spectrum(self) -> Optional[str]:
         """Detect spectrum type by looking for MS:1000127 (centroid) or MS:1000128 (profile).
 
-        What the file *declares* wins, wherever it is written. Only when the
-        file declares nothing does Thyra guess -- see
+        An explicit ``spectrum_type`` override wins over everything, so a user
+        can correct a file that declares the wrong thing. Otherwise what the
+        file *declares* wins, wherever it is written, and only when the file
+        declares nothing does Thyra guess -- see
         :meth:`_guess_spectrum_type_from_storage_mode` for what that guess is
         worth.
         """
         try:
+            # 0. An explicit override outranks the file.
+            if self.spectrum_type_override is not None:
+                self._report_spectrum_type_override()
+                return self.spectrum_type_override
+
             # 1. The declaration, from metadata the parser already holds.
             result = self._check_parser_metadata_for_spectrum_type()
             if result:
@@ -547,6 +575,49 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             logger.debug(f"Could not detect spectrum type: {e}")
             return None
 
+    def _report_spectrum_type_override(self) -> None:
+        """Log an override, loudly when it contradicts the file's declaration.
+
+        Overriding a declared ``MS:1000127``/``MS:1000128`` is a legitimate
+        thing to want -- files do declare the wrong representation -- and it is
+        also a good way to corrupt a conversion silently. So the two cases are
+        not logged alike: agreeing with the file, or overriding a file that
+        declares nothing, is INFO; contradicting an explicit declaration is
+        WARNING and names both values.
+
+        This still reads the file's *declarations* (steps 1 and 2) in order to
+        compare, but never its guess -- there is nothing informative about
+        contradicting a guess. That costs at most the same bounded XML scan
+        detection would have done, and only on the opt-in path.
+        """
+        override = self.spectrum_type_override
+        declared = self._check_parser_metadata_for_spectrum_type()
+        if declared is None:
+            declared = self._check_xml_for_spectrum_type()
+
+        if declared is None:
+            logger.info(
+                "Using spectrum_type override %r; the file declares neither %s "
+                "(centroid) nor %s (profile).",
+                override,
+                ImzMLAccessions.CENTROID_SPECTRUM,
+                ImzMLAccessions.PROFILE_SPECTRUM,
+            )
+        elif declared == override:
+            logger.info(
+                "Using spectrum_type override %r, which agrees with the file.",
+                override,
+            )
+        else:
+            logger.warning(
+                "spectrum_type override %r CONTRADICTS the file, which declares "
+                "%r. Proceeding with the override -- the stored spectrum type, "
+                "and any decision Thyra makes from it, will not match what the "
+                "file says about itself. Remove the override to trust the file.",
+                override,
+                declared,
+            )
+
     def _check_xml_for_spectrum_type(self) -> Optional[str]:
         """Check XML for spectrum type markers using streaming parser.
 

{thyra-2.2.3 → thyra-2.3.0}/thyra/readers/imzml/imzml_reader.py

@@ -12,6 +12,7 @@ from ...core.base_extractor import MetadataExtractor
 from ...core.base_reader import BaseMSIReader
 from ...core.registry import register_reader
 from ...metadata.extractors.imzml_extractor import ImzMLMetadataExtractor
+from ...resampling.constants import normalize_spectrum_type
 
 logger = logging.getLogger(__name__)
 
@@ -351,6 +352,14 @@ class ImzMLReader(BaseMSIReader):
                 ``DEFAULT_MAX_MASS_AXIS_LENGTH`` (10 million, SCiLS Lab's own
                 limit); pass ``None`` explicitly for unlimited. See
                 ``_extract_continuous_mass_axis``.
+
+                ``spectrum_type`` declares the spectrum representation
+                explicitly -- ``"profile"`` or ``"centroid"`` -- instead of
+                letting Thyra read or guess it. SCiLS Lab spells the same thing
+                ``--rep_type``. Use it when a file declares the wrong
+                representation; it outranks the file's own ``MS:1000127`` /
+                ``MS:1000128``, and contradicting a declaration is logged as a
+                warning. Defaults to ``None`` (detect).
         """
         super().__init__(data_path, **kwargs)
         self.filepath: Optional[Union[str, Path]] = data_path
@@ -361,6 +370,11 @@ class ImzMLReader(BaseMSIReader):
         self.max_mass_axis_length: Optional[int] = kwargs.get(
             "max_mass_axis_length", DEFAULT_MAX_MASS_AXIS_LENGTH
         )
+        # Validated here rather than at extraction time, so a bad value fails
+        # while the caller is still looking at its own arguments.
+        self.spectrum_type: Optional[str] = normalize_spectrum_type(
+            kwargs.get("spectrum_type")
+        )
         self.parser: Optional[ImzMLParser] = None
         self.ibd_file: Optional[Any] = None
         self.imzml_path: Optional[Path] = None
@@ -499,7 +513,9 @@ class ImzMLReader(BaseMSIReader):
         if not self.imzml_path:
             raise ValueError("ImzML path not available")
 
-        return ImzMLMetadataExtractor(self.parser, self.imzml_path)
+        return ImzMLMetadataExtractor(
+            self.parser, self.imzml_path, spectrum_type=self.spectrum_type
+        )
 
     @property
     def has_shared_mass_axis(self) -> bool:

thyra-2.3.0/thyra/resampling/constants.py

@@ -0,0 +1,91 @@
+"""Constants for resampling and instrument detection."""
+
+from typing import Dict, Optional
+
+
+class ImzMLAccessions:
+    """PSI-MS and imzML controlled vocabulary accession codes."""
+
+    # Spectrum type (MS ontology)
+    CENTROID_SPECTRUM = "MS:1000127"
+    PROFILE_SPECTRUM = "MS:1000128"
+
+    # Binary data type (imzML ontology)
+    CONTINUOUS_BINARY = "IMS:1000030"
+    PROCESSED_BINARY = "IMS:1000031"
+
+    # Software identifiers
+    SCILS_LAB = "MS:1002384"
+
+
+class Thresholds:
+    """Threshold values for data classification."""
+
+    # Peak density threshold for detecting profile data
+    # Profile data typically has >5000 points per spectrum
+    PROFILE_PEAK_DENSITY = 5000
+
+    # Dataset size threshold for streaming converter (GB)
+    STREAMING_SIZE_GB = 10
+
+    # Dataset size threshold for PCS method in streaming converter (GB)
+    PCS_SIZE_GB = 30
+
+
+class SpectrumType:
+    """Spectrum type string constants."""
+
+    CENTROID = "centroid spectrum"
+    PROFILE = "profile spectrum"
+
+
+# What a caller may write for a spectrum representation, mapped to the CV name
+# Thyra stores. The bare words match SCiLS Lab's ``--rep_type PROFILE|CENTROID``
+# (2026b User Guide p.81); the full CV names are what MS:1000127 / MS:1000128
+# are called, and are what comes back out of the store, so both are accepted.
+SPECTRUM_TYPE_ALIASES: Dict[str, str] = {
+    "centroid": SpectrumType.CENTROID,
+    "centroided": SpectrumType.CENTROID,
+    "centroid spectrum": SpectrumType.CENTROID,
+    "profile": SpectrumType.PROFILE,
+    "profile spectrum": SpectrumType.PROFILE,
+}
+
+
+def normalize_spectrum_type(value: Optional[object]) -> Optional[str]:
+    """Map a user-supplied spectrum representation onto a :class:`SpectrumType`.
+
+    Args:
+        value: ``"profile"``, ``"centroid"``, either CV name, or ``None``.
+            Case and surrounding whitespace are ignored.
+
+    Returns:
+        The matching :class:`SpectrumType` constant, or ``None`` for ``None``.
+
+    Raises:
+        ValueError: If the value is not a recognised representation. A typo
+            here would otherwise be indistinguishable from "no override" and
+            would silently hand the file back to auto-detection, so this fails
+            loudly instead.
+    """
+    if value is None:
+        return None
+
+    if not isinstance(value, str):
+        raise ValueError(
+            f"spectrum_type must be a string or None, got {type(value).__name__}"
+        )
+
+    key = value.strip().lower()
+    if key in SPECTRUM_TYPE_ALIASES:
+        return SPECTRUM_TYPE_ALIASES[key]
+
+    accepted = ", ".join(repr(k) for k in sorted(SPECTRUM_TYPE_ALIASES))
+    raise ValueError(f"Unknown spectrum_type {value!r}. Accepted values: {accepted}.")
+
+
+class BinaryDataType:
+    """Binary data type string constants."""
+
+    CONTINUOUS = "continuous"
+    PROCESSED = "processed"

thyra-2.2.3/thyra/converters/spatialdata/_chunking.py

@@ -1,41 +0,0 @@
-"""Image chunk/shard policy for Thyra-written SpatialData rasters.
-
-Single source of truth for how Thyra chunks the raster images it writes to
-SpatialData zarr -- and the designated seam for tile-aligned zarr v3 sharding
-once scverse/spatialdata PR #1106 (``raster_write_kwargs``) lands.
-
-Cross-repo contract: the viewer (Ousia) morphology tile server streams
-``DEFAULT_TILE_SIZE`` (= 512) edge tiles. Once sharding lands, the zarr INNER
-chunk edge must equal that so one served tile == one decompress. Thyra is a
-separate package and CANNOT import Ousia, so the coupling is DUPLICATED BY
-CONTRACT here -- keep ``INNER_TILE_EDGE`` numerically in sync with Ousia's
-``DEFAULT_TILE_SIZE``; a silent divergence reintroduces cold-tile amplification
-on the viewer. See the Ousia ADR docs/ADR-pyramid-tile-sharding.md.
-"""
-
-from typing import Tuple
-
-# Outer chunk edge used TODAY (pre-sharding the chunk IS the outer block): a 4096
-# block means a viewer 512-tile read decompresses at most one chunk per request.
-IMAGE_CHUNK_EDGE = 4096
-
-# Future zarr INNER chunk edge once #1106 lands == Ousia DEFAULT_TILE_SIZE (512).
-# Duplicated by contract (Thyra cannot import Ousia).
-INNER_TILE_EDGE = 512
-
-
-def image_chunks(spatial_ndim: int, edge: int = IMAGE_CHUNK_EDGE) -> Tuple[int, ...]:
-    """The zarr chunk tuple for a Thyra-written raster image (leading channel axis).
-
-    ``spatial_ndim == 2`` (c, y, x) -> ``(1, edge, edge)``;
-    ``spatial_ndim == 3`` (c, z, y, x) -> ``(1, 1, edge, edge)``.
-
-    This is the ONE place the future inner=``INNER_TILE_EDGE`` + outer-shard policy
-    will live when spatialdata PR #1106 ships ``raster_write_kwargs``. Today it
-    returns the pre-sharding behaviour, byte-for-byte.
-    """
-    if spatial_ndim == 2:
-        return (1, edge, edge)
-    if spatial_ndim == 3:
-        return (1, 1, edge, edge)
-    raise ValueError(f"spatial_ndim must be 2 or 3, got {spatial_ndim}")

thyra-2.2.3/thyra/resampling/constants.py

@@ -1,44 +0,0 @@
-"""Constants for resampling and instrument detection."""
-
-
-class ImzMLAccessions:
-    """PSI-MS and imzML controlled vocabulary accession codes."""
-
-    # Spectrum type (MS ontology)
-    CENTROID_SPECTRUM = "MS:1000127"
-    PROFILE_SPECTRUM = "MS:1000128"
-
-    # Binary data type (imzML ontology)
-    CONTINUOUS_BINARY = "IMS:1000030"
-    PROCESSED_BINARY = "IMS:1000031"
-
-    # Software identifiers
-    SCILS_LAB = "MS:1002384"
-
-
-class Thresholds:
-    """Threshold values for data classification."""
-
-    # Peak density threshold for detecting profile data
-    # Profile data typically has >5000 points per spectrum
-    PROFILE_PEAK_DENSITY = 5000
-
-    # Dataset size threshold for streaming converter (GB)
-    STREAMING_SIZE_GB = 10
-
-    # Dataset size threshold for PCS method in streaming converter (GB)
-    PCS_SIZE_GB = 30
-
-
-class SpectrumType:
-    """Spectrum type string constants."""
-
-    CENTROID = "centroid spectrum"
-    PROFILE = "profile spectrum"
-
-
-class BinaryDataType:
-    """Binary data type string constants."""
-
-    CONTINUOUS = "continuous"
-    PROCESSED = "processed"