thyra 2.2.4__tar.gz → 2.3.1__tar.gz

{thyra-2.2.4 → thyra-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thyra
-Version: 2.2.4
+Version: 2.3.1
 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

{thyra-2.2.4 → thyra-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thyra"
-version = "2.2.4"
+version = "2.3.1"
 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>"]

{thyra-2.2.4 → thyra-2.3.1}/thyra/__init__.py

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

{thyra-2.2.4 → thyra-2.3.1}/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.4 → thyra-2.3.1}/thyra/convert.py

@@ -147,27 +147,51 @@ def _determine_pixel_size(
 
 
 def _should_use_streaming(streaming: Union[bool, Literal["auto"]], reader: Any) -> bool:
-    """Determine if streaming converter should be used."""
+    """Determine if streaming converter should be used.
+
+    Args:
+        streaming: True to force streaming, False to force the standard
+            converter, ``"auto"`` to pick on estimated size.
+        reader: The reader for the input.
+
+    Returns:
+        True if the streaming converter should be used.
+
+    Raises:
+        Exception: Whatever ``reader.get_essential_metadata()`` raises. A
+            reader that refuses its input must not be silenced here.
+    """
     if streaming is True:
         return True
     if streaming != "auto":
         return False
 
-    # Auto-detect based on estimated dataset size (>10GB)
+    # Deliberately outside the try below. This is often the first call that
+    # builds the reader's parser, so it is the call a refused file fails on --
+    # and swallowing it here logged the reason at DEBUG, returned False, and
+    # let the converter parse the whole file a second time before failing the
+    # same way. On a 2.1 GB imzML that is about two minutes of apparent
+    # progress with the real reason invisible.
+    essential_meta = reader.get_essential_metadata()
+
+    # Auto-detect based on estimated dataset size (>10GB). Only the estimate
+    # itself is best-effort: a reader whose dimensions are missing or oddly
+    # shaped simply does not get the automatic upgrade.
     try:
-        essential_meta = reader.get_essential_metadata()
         dims = essential_meta.dimensions
         n_pixels = dims[0] * dims[1] * dims[2]
         # Rough estimate: assume average 10k peaks per spectrum, 8 bytes each
         estimated_gb = (n_pixels * 10000 * 8) / (1024**3)
-        if estimated_gb > 10:
-            logger.info(
-                f"Auto-detected large dataset (~{estimated_gb:.1f} GB), "
-                "using streaming converter"
-            )
-            return True
     except Exception as e:
         logger.debug(f"Could not estimate dataset size for auto-streaming: {e}")
+        return False
+
+    if estimated_gb > 10:
+        logger.info(
+            f"Auto-detected large dataset (~{estimated_gb:.1f} GB), "
+            "using streaming converter"
+        )
+        return True
     return False
 
 
@@ -290,6 +314,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.2.4 → thyra-2.3.1}/thyra/converters/spatialdata/base_spatialdata_converter.py

@@ -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."""

{thyra-2.2.4 → thyra-2.3.1}/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.4 → thyra-2.3.1}/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.4 → thyra-2.3.1}/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.