thyra 2.2.0__tar.gz → 2.2.2__tar.gz

{thyra-2.2.0 → thyra-2.2.2}/PKG-INFO

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

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

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

{thyra-2.2.0 → thyra-2.2.2}/thyra/readers/imzml/imzml_reader.py

@@ -415,9 +415,26 @@ class ImzMLReader(BaseMSIReader):
         # Initialize the parser
         logger.info(f"Initializing ImzML parser for {imzml_path}")
         try:
+            # ElementTree, NOT lxml. pyimzml prunes each <spectrum> out of the
+            # tree (`slist.remove(elem)`) while iterparse is still streaming the
+            # document, which invalidates libxml2's text-node coalescing
+            # accelerator: ctxt->nodelen/nodemem go on describing a text node
+            # inside the subtree that was just removed, so later character data
+            # is appended at a stale offset and the buffer is doubled on every
+            # miss until xmlRealloc fails. lxml surfaces libxml2's
+            # XML_ERR_NO_MEMORY as a *syntax* error, so it reads as a corrupt
+            # file when nothing is wrong with it:
+            #     XMLSyntaxError: xmlSAX2Characters, line 212575, column 1
+            # It only bites when the text between </spectrum> and <spectrum> is
+            # exactly "\r\n" -- CRLF with no indentation, how IONTOF SurfaceLab
+            # writes imzML. Indented or LF-only files coalesce differently and
+            # survive, which is why most files never hit it. ElementTree builds
+            # the tree in Python, so there is no C parser state to invalidate;
+            # it is also pyimzml's own default, parses byte-identically, and is
+            # faster here -- 67s vs 118s on a 2.1 GB imzML at the same peak RSS.
             self.parser = ImzMLParser(
                 filename=str(imzml_path),
-                parse_lib="lxml",
+                parse_lib="ElementTree",
                 ibd_file=self.ibd_file,
             )
         except Exception as e:

{thyra-2.2.0 → thyra-2.2.2}/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.0 → thyra-2.2.2}/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.