thyra 2.2.1__tar.gz → 2.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thyra
-Version: 2.2.1
+Version: 2.2.3
 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.1 → thyra-2.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thyra"
-version = "2.2.1"
+version = "2.2.3"
 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.1 → thyra-2.2.3}/thyra/__init__.py

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

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

@@ -9,7 +9,7 @@ from numpy.typing import NDArray
 from pyimzml.ImzMLParser import ImzMLParser
 
 from ...core.base_extractor import MetadataExtractor
-from ...resampling.constants import ImzMLAccessions, SpectrumType
+from ...resampling.constants import BinaryDataType, ImzMLAccessions, SpectrumType
 from ..types import ComprehensiveMetadata, EssentialMetadata
 
 logger = logging.getLogger(__name__)
@@ -131,7 +131,7 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             if param_by_name is None or not isinstance(param_by_name, dict):
                 return False
 
-            return "continuous" in param_by_name
+            return BinaryDataType.CONTINUOUS in param_by_name
         except Exception:
             return False
 
@@ -522,19 +522,27 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             return None
 
     def _detect_centroid_spectrum(self) -> Optional[str]:
-        """Detect spectrum type by looking for MS:1000127 (centroid) or MS:1000128 (profile)."""
+        """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
+        :meth:`_guess_spectrum_type_from_storage_mode` for what that guess is
+        worth.
+        """
         try:
-            # Method 1: Check parser metadata first (no XML parsing needed)
-            result = self._check_parser_metadata_for_centroid()
+            # 1. The declaration, from metadata the parser already holds.
+            result = self._check_parser_metadata_for_spectrum_type()
             if result:
                 return result
 
-            # Method 2: Stream-parse XML for spectrum type markers (memory efficient)
+            # 2. The same declaration, wherever else in the document it sits.
+            #    Streams the XML, so it is tried only if step 1 came up empty.
             result = self._check_xml_for_spectrum_type()
             if result:
                 return result
 
-            return None
+            # 3. Nothing declared. Only now is a guess appropriate.
+            return self._guess_spectrum_type_from_storage_mode()
         except Exception as e:
             logger.debug(f"Could not detect spectrum type: {e}")
             return None
@@ -607,8 +615,13 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             logger.warning("defusedxml not available, using xml.etree.ElementTree")
             return ET
 
-    def _check_parser_metadata_for_centroid(self) -> Optional[str]:
-        """Check parser metadata for processed flag indicating centroid data."""
+    def _file_description_params(self) -> Optional[Dict[str, Any]]:
+        """Return the fileDescription cvParams the parser already parsed.
+
+        ``param_by_name`` maps a term's CV *name* to its parsed value, and a
+        valueless cvParam -- which is what a flag like ``profile spectrum``
+        is -- parses to ``True``.
+        """
         if not (hasattr(self.parser, "metadata") and self.parser.metadata):
             return None
 
@@ -616,13 +629,70 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             return None
 
         file_desc = self.parser.metadata.file_description
-        if not hasattr(file_desc, "param_by_name"):
+        params = getattr(file_desc, "param_by_name", None)
+        if not isinstance(params, dict):
+            return None
+
+        return params
+
+    def _check_parser_metadata_for_spectrum_type(self) -> Optional[str]:
+        """Read the declared spectrum representation out of the fileDescription.
+
+        Cheap: the parser has already read this, so no XML pass is needed.
+        ``SpectrumType.CENTROID`` and ``SpectrumType.PROFILE`` are the CV
+        names of ``MS:1000127`` and ``MS:1000128``, which is what
+        ``param_by_name`` is keyed on.
+        """
+        params = self._file_description_params()
+        if params is None:
+            return None
+
+        if params.get(SpectrumType.CENTROID, False):
+            logger.info(
+                f"Detected centroid spectrum from declared "
+                f"{ImzMLAccessions.CENTROID_SPECTRUM} in fileDescription"
+            )
+            return SpectrumType.CENTROID
+
+        if params.get(SpectrumType.PROFILE, False):
+            logger.info(
+                f"Detected profile spectrum from declared "
+                f"{ImzMLAccessions.PROFILE_SPECTRUM} in fileDescription"
+            )
+            return SpectrumType.PROFILE
+
+        return None
+
+    def _guess_spectrum_type_from_storage_mode(self) -> Optional[str]:
+        """Last-resort guess: assume a processed-mode file is centroided.
+
+        Processed and centroid are orthogonal. ``IMS:1000031`` says each
+        spectrum carries its own m/z array; it says nothing about whether
+        the peaks in it are centroided or profile. Plenty of instruments
+        export profile spectra in processed mode -- ``bellini.imzML`` is
+        processed *and* declares ``MS:1000128 profile spectrum``.
+
+        This used to run before the declared accession was ever read, so
+        every processed file was reported as centroid whatever it said about
+        itself. It now runs only when the file declares neither
+        ``MS:1000127`` nor ``MS:1000128`` anywhere, where a guess is all
+        there is. Peak lists are the common case for processed exports, so
+        centroid is the better guess -- but it is still a guess, hence the
+        warning.
+        """
+        params = self._file_description_params()
+        if params is None:
             return None
 
-        params = file_desc.param_by_name
-        # If it's processed data, it's likely centroided
-        if params.get("processed", False):
-            logger.info("Assuming centroid spectrum for processed ImzML data")
+        if params.get(BinaryDataType.PROCESSED, False):
+            logger.warning(
+                "This imzML declares neither %s (centroid) nor %s (profile). "
+                "Assuming centroid, because it is stored in processed mode -- "
+                "but the two are independent, so check the result if the "
+                "spectra are actually profile.",
+                ImzMLAccessions.CENTROID_SPECTRUM,
+                ImzMLAccessions.PROFILE_SPECTRUM,
+            )
             return SpectrumType.CENTROID
 
         return None

{thyra-2.2.1 → thyra-2.2.3}/thyra/resampling/data_characteristics.py

@@ -66,6 +66,14 @@ class DataCharacteristics:
 
         Profile data typically has >5000 points per spectrum,
         indicating continuous signal rather than centroid peaks.
+
+        This says how densely the spectra are sampled. It says nothing about
+        which instrument produced them, so it **must not be used to pick a
+        resampling strategy or an axis type**: those encode assumptions about
+        the acquisition's physics. ``RapiflexDetector`` used to match on this
+        alone, which handed MALDI-TOF treatment to any dense profile data --
+        TOF-SIMS, Orbitrap, anything -- with no check that the data was
+        MALDI-TOF at all.
         """
         avg = self.avg_peaks_per_spectrum
         return (
@@ -76,7 +84,12 @@ class DataCharacteristics:
 
     @property
     def is_maldi_tof(self) -> bool:
-        """Check if this is MALDI-TOF data."""
+        """Check if this is MALDI-TOF data.
+
+        Carries the same caveat as :attr:`is_high_density_profile`, which its
+        last clause consults: density plus a vendor name is not a modality.
+        No detector calls this.
+        """
         return (
             self.is_rapiflex_format
             or self.instrument_type == "MALDI-TOF"

{thyra-2.2.1 → thyra-2.2.3}/thyra/resampling/instrument_detectors.py

@@ -52,6 +52,30 @@ class InstrumentDetector(ABC):
         """Get the recommended mass axis type for this instrument."""
         pass
 
+    @property
+    def source_grid_law(self) -> Optional[AxisType]:
+        """Spacing law of the *source* m/z grid, when it is known.
+
+        ``tic_preserving`` interpolates onto the target axis and then applies
+        one global scaling factor. That composite operator is exact only when
+        the source grid follows the same spacing law as the target axis; off
+        the diagonal it distorts the ratio between two peaks by exactly
+        ``(m_hi / m_lo) ** (p_target - p_source)``, with ``p`` = 0, 0.5, 1,
+        1.5, 2 for constant / linear_tof / reflector_tof / orbitrap / fticr.
+
+        SCiLS Lab gates its own TIC-preserving resampling on the same
+        condition -- "If all axis types are identical, a TIC preserving
+        resampling is applied, otherwise a linear interpolation is performed"
+        (SCiLS Lab 2026b User Guide, p.80).
+
+        ``None`` -- the default -- means Thyra does not know the source law.
+        That is the honest answer for every detector that matches on
+        something other than a vendor format whose grid Thyra itself lays
+        out, and :class:`InstrumentDetectorChain` refuses ``TIC_PRESERVING``
+        for such a detector.
+        """
+        return None
+
 
 class CentroidImzMLDetector(InstrumentDetector):
     """Detector for centroid ImzML data.
@@ -91,23 +115,33 @@ class RapiflexDetector(InstrumentDetector):
         return "Rapiflex MALDI-TOF"
 
     def matches(self, characteristics: DataCharacteristics) -> bool:
-        """Check if data matches Rapiflex, Bruker MALDI-TOF, or high-density profile."""
+        """Check if data came from Bruker flexImaging/Rapiflex.
+
+        Both branches below are written by one producer, the Rapiflex
+        metadata extractor, so a match here means the spectra arrive on the
+        uniform-in-m/z grid ``RapiflexReader`` builds.
+
+        Peak density is deliberately *not* consulted. It used to be: any
+        profile data averaging more than
+        ``Thresholds.PROFILE_PEAK_DENSITY`` points per spectrum was handed
+        MALDI-TOF treatment regardless of what instrument produced it. That
+        made the detector modality-blind -- a dense TOF-SIMS or Orbitrap
+        profile acquisition would have been resampled by MALDI-TOF logic
+        onto a MALDI-shaped axis, silently. SCiLS Lab does not guess
+        modality either; its importer takes ``--project TIMSTOF|TOF|FT`` as
+        an argument (2026b User Guide, p.81). Unknown-provenance profile
+        data now falls through to :class:`DefaultDetector`, which bins
+        counts rather than interpolating and so is safe for any modality.
+        """
         # Direct Rapiflex format detection
         if characteristics.is_rapiflex_format:
             return True
 
         # Bruker MALDI-TOF detection
-        if (
+        return (
             characteristics.instrument_type == "MALDI-TOF"
             and characteristics.manufacturer == "Bruker"
-        ):
-            return True
-
-        # Profile data with high peak density (likely MALDI-TOF)
-        if characteristics.is_high_density_profile:
-            return True
-
-        return False
+        )
 
     def get_resampling_method(self) -> ResamplingMethod:
         """Return TIC-preserving for profile MALDI-TOF data."""
@@ -117,6 +151,19 @@ class RapiflexDetector(InstrumentDetector):
         """Return constant axis matching SCiLS Lab convention."""
         return AxisType.CONSTANT
 
+    @property
+    def source_grid_law(self) -> Optional[AxisType]:
+        """Report the constant law of the flexImaging source grid.
+
+        ``RapiflexReader.get_common_mass_axis`` lays every spectrum out with
+        ``np.linspace(mass_start, mass_end, n_points)``, so the source
+        spacing is constant in m/z -- the same law as the ``constant`` target
+        axis :meth:`get_axis_type` asks for. Source law equal to target law
+        is what makes ``tic_preserving`` exact here, and it is the reason
+        this is the only route on which the chain permits it.
+        """
+        return AxisType.CONSTANT
+
 
 class TimsTOFDetector(InstrumentDetector):
     """Detector for Bruker timsTOF data.
@@ -273,6 +320,9 @@ class InstrumentDetectorChain:
     ) -> ResamplingMethod:
         """Get resampling method for the detected instrument.
 
+        ``TIC_PRESERVING`` additionally has to clear the matching-axis-law
+        gate; see :meth:`_gate_tic_preserving`.
+
         Args:
             characteristics: Data characteristics to match
 
@@ -280,10 +330,51 @@ class InstrumentDetectorChain:
             Recommended resampling method for the instrument
         """
         detector = self.detect(characteristics)
-        method = detector.get_resampling_method()
+        method = self._gate_tic_preserving(detector)
         logger.info(f"Selected resampling method: {method.name}")
         return method
 
+    @staticmethod
+    def _gate_tic_preserving(detector: InstrumentDetector) -> ResamplingMethod:
+        """Allow ``TIC_PRESERVING`` only when source and target laws agree.
+
+        SCiLS Lab applies TIC-preserving resampling to profile data only
+        when all the mass axes being combined are of the same type, and
+        linear interpolation otherwise (2026b User Guide, p.80). That is
+        also precisely the condition under which Thyra's operator --
+        interpolate, then rescale by one global factor -- is exact. See
+        :attr:`InstrumentDetector.source_grid_law` for the error off the
+        diagonal.
+
+        A detector that has not declared its source grid law does not clear
+        the gate. Auto-selection therefore cannot reach the interpolating
+        path on data whose acquisition Thyra has not actually identified.
+
+        Args:
+            detector: The detector that matched.
+
+        Returns:
+            The detector's method, or ``NEAREST_NEIGHBOR`` in its place.
+        """
+        method = detector.get_resampling_method()
+        if method is not ResamplingMethod.TIC_PRESERVING:
+            return method
+
+        axis_type = detector.get_axis_type()
+        source_law = detector.source_grid_law
+        if source_law is axis_type:
+            return method
+
+        logger.info(
+            "%s asks for TIC_PRESERVING onto a %s axis, but the source grid "
+            "law is %s. TIC-preserving resampling is exact only when the two "
+            "match, so NEAREST_NEIGHBOR is used instead.",
+            detector.name,
+            axis_type.name,
+            "unknown" if source_law is None else source_law.name,
+        )
+        return ResamplingMethod.NEAREST_NEIGHBOR
+
     def get_axis_type(self, characteristics: DataCharacteristics) -> AxisType:
         """Get axis type for the detected instrument.