thyra 2.0.3__tar.gz → 2.1.0__tar.gz

{thyra-2.0.3 → thyra-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thyra
-Version: 2.0.3
+Version: 2.1.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

{thyra-2.0.3 → thyra-2.1.0}/pyproject.toml

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

{thyra-2.0.3 → thyra-2.1.0}/thyra/__init__.py

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

{thyra-2.0.3 → thyra-2.1.0}/thyra/__main__.py

@@ -243,6 +243,7 @@ def _build_resampling_config(
     resample_max_mz: Optional[float],
     resample_width_at_mz: Optional[float],
     resample_reference_mz: float,
+    resample_gap_tolerance: Optional[float] = None,
 ) -> dict:
     """Build resampling configuration dictionary."""
     return {
@@ -253,6 +254,7 @@ def _build_resampling_config(
         "max_mz": resample_max_mz,
         "width_at_mz": resample_width_at_mz,
         "reference_mz": resample_reference_mz,
+        "gap_tolerance_da": resample_gap_tolerance,
     }
 
 
@@ -536,6 +538,16 @@ class GroupedCommand(click.Command):
     default=1000.0,
     help="Reference m/z for width specification (default: 1000.0)",
 )
+@click.option(
+    "--resample-gap-tolerance",
+    type=float,
+    default=None,
+    help=(
+        "For tic_preserving only: discard target bins farther than this many "
+        "Da from any measured m/z, instead of interpolating across the gap "
+        "(default: no limit)"
+    ),
+)
 # -- Bruker-specific --
 @click.option(
     "--use-recalibrated/--no-recalibrated",
@@ -583,6 +595,7 @@ def main(
     resample_max_mz: Optional[float],
     resample_width_at_mz: Optional[float],
     resample_reference_mz: float,
+    resample_gap_tolerance: Optional[float],
     mass_axis_type: str,
     sparse_format: str,
     include_optical: bool,
@@ -604,6 +617,9 @@ def main(
         resample_width_at_mz,
         resample_reference_mz,
     )
+    _validate_positive_float(
+        resample_gap_tolerance, "resample_gap_tolerance", "Gap tolerance"
+    )
     _validate_positive_float(
         intensity_threshold, "intensity_threshold", "Intensity threshold"
     )
@@ -641,6 +657,7 @@ def main(
             resample_max_mz,
             resample_width_at_mz,
             resample_reference_mz,
+            resample_gap_tolerance,
         )
         if resample
         else None

{thyra-2.0.3 → thyra-2.1.0}/thyra/convert.py

@@ -283,10 +283,13 @@ def convert_msi(
               use active/recalibrated calibration (default True).
             - max_mass_axis_length: int - For processed-mode imzML
               converted with --no-resample, give up once the raw
-              mass axis exceeds this many unique m/z values.
-              Default: None (unlimited). Useful when the peak
-              lists share no m/z values, where the raw axis grows
-              to roughly one column per peak in the whole dataset.
+              mass axis exceeds this many unique m/z values. This
+              matters when the peak lists share no m/z values,
+              where the raw axis grows to roughly one column per
+              peak in the whole dataset. Default: 10,000,000,
+              which is the limit SCiLS Lab places on the same
+              quantity (2026b User Guide, p.76). Pass None for
+              no limit.
         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.0.3 → thyra-2.1.0}/thyra/converters/spatialdata/base_spatialdata_converter.py

@@ -17,6 +17,7 @@ from ...core.base_converter import BaseMSIConverter, PixelSizeSource
 from ...core.base_reader import BaseMSIReader
 from ...metadata.types import ComprehensiveMetadata, EssentialMetadata
 from ...resampling import ResamplingDecisionTree, ResamplingMethod
+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
@@ -137,6 +138,7 @@ def _normalize_resampling_config(
         ),
         min_mz=config.get("min_mz"),
         max_mz=config.get("max_mz"),
+        gap_tolerance_da=config.get("gap_tolerance_da"),
     )
 
 
@@ -378,6 +380,12 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         self._max_mz = config.max_mz
         self._width_at_mz = config.mass_width_da
         self._reference_mz = config.reference_mz
+        self._gap_tolerance_da = config.gap_tolerance_da
+        if self._gap_tolerance_da is not None:
+            logger.info(
+                f"Interpolation gap tolerance: {self._gap_tolerance_da} Da "
+                "(target bins farther than this from any source m/z are zeroed)"
+            )
 
     def _get_cached_metadata_for_resampling(self) -> Dict[str, Any]:
         """Get cached metadata for resampling decision tree to avoid multiple reader calls."""
@@ -1082,8 +1090,13 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         # bincount without minlength is fastest
         accumulated = np.bincount(indices_clipped, weights=intensities)
 
-        # Extract non-zero bins for sparse representation
-        nonzero_mask = accumulated > 0
+        # Extract non-zero bins for sparse representation. The test is
+        # ``!= 0`` rather than ``> 0`` because a bin whose accumulated value is
+        # negative is still a measurement: dropping it silently raises the
+        # stored TIC above the input's. Baseline-subtracted data can carry
+        # negative intensities, though every export seen so far filters them
+        # out upstream.
+        nonzero_mask = accumulated != 0
         nonzero_indices = np.where(nonzero_mask)[0].astype(np.int_)
         nonzero_values = accumulated[nonzero_mask]
 
@@ -1111,6 +1124,11 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         When the axis spans the spectrum, which is the default, that share
         is the whole input TIC.
 
+        When ``ResamplingConfig.gap_tolerance_da`` is set, bins farther than
+        that from any source m/z are zeroed before the rescale, so
+        interpolation cannot claim regions nothing was measured in. See
+        ``thyra.resampling.gaps``.
+
         Args:
             mzs: Original m/z values from the spectrum.
             intensities: Corresponding intensity values.
@@ -1158,6 +1176,16 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             right=0,
         )
 
+        # Discard bins no source point vouches for, before the rescale so the
+        # intensity returns to the bins that were measured rather than being
+        # deleted. No-op when no tolerance was configured.
+        zero_across_gaps(
+            resampled,
+            axis,
+            mzs_sorted,
+            getattr(self, "_gap_tolerance_da", None),
+        )
+
         # Rescale to the required TIC. This is the step that makes the
         # method live up to its name.
         return rescale_to_preserved_tic(resampled, axis, mzs_sorted, intensities_sorted)

{thyra-2.0.3 → thyra-2.1.0}/thyra/readers/imzml/imzml_reader.py

@@ -27,6 +27,16 @@ _MASS_AXIS_BATCH_VALUES = 1 << 20
 # Bounds that function's temporaries to O(block) rather than O(batch).
 _MASS_AXIS_PROBE_BLOCK = 1 << 20
 
+# Default cap on the number of unique m/z values the processed-mode raw mass
+# axis may reach, in ELEMENTS. Taken from SCiLS Lab, which applies the same
+# limit to the same quantity: "Data sets in SCiLS Lab are limited to a maximum
+# of 10 million bins on the common mass axis" (SCiLS Lab 2026b User Guide,
+# p.76). The cap previously defaulted to None because no defensible number was
+# available; this is one, from the tool Thyra's resampling was designed
+# against. Override with ``reader_options={"max_mass_axis_length": N}``, or
+# pass None for the old unlimited behaviour.
+DEFAULT_MAX_MASS_AXIS_LENGTH = 10_000_000
+
 
 def _dedupe_sorted(a: NDArray[Any]) -> NDArray[Any]:
     """Deduplicate an ALREADY-SORTED array, as ``np.unique`` would.
@@ -337,14 +347,20 @@ class ImzMLReader(BaseMSIReader):
             cache_coordinates: Whether to cache coordinates upfront
             **kwargs: Additional arguments. ``max_mass_axis_length`` caps the
                 number of unique m/z values the processed-mode raw axis may
-                reach before the build gives up; None (the default) is
-                unlimited. See ``_extract_continuous_mass_axis``.
+                reach before the build gives up. Defaults to
+                ``DEFAULT_MAX_MASS_AXIS_LENGTH`` (10 million, SCiLS Lab's own
+                limit); pass ``None`` explicitly for unlimited. See
+                ``_extract_continuous_mass_axis``.
         """
         super().__init__(data_path, **kwargs)
         self.filepath: Optional[Union[str, Path]] = data_path
         self.batch_size: int = batch_size
         self.cache_coordinates: bool = cache_coordinates
-        self.max_mass_axis_length: Optional[int] = kwargs.get("max_mass_axis_length")
+        # Absent means "use the default"; an explicit None means "unlimited",
+        # so this cannot be a bare ``.get(...)`` with a None fallback.
+        self.max_mass_axis_length: Optional[int] = kwargs.get(
+            "max_mass_axis_length", DEFAULT_MAX_MASS_AXIS_LENGTH
+        )
         self.parser: Optional[ImzMLParser] = None
         self.ibd_file: Optional[Any] = None
         self.imzml_path: Optional[Path] = None

thyra-2.1.0/thyra/resampling/gaps.py

@@ -0,0 +1,76 @@
+"""Refusing to interpolate across regions that were never measured.
+
+``np.interp`` has no notion of a gap. Handed a spectrum whose m/z values are
+sparse or thresholded, it draws a straight line from the last point before the
+gap to the first point after it, and every target bin in between comes back
+with a fabricated intensity. Nothing was measured there.
+
+On real data this is not a rounding-scale effect. Forcing ``tic_preserving``
+onto ``bellini.imzML`` -- 2,222 points per spectrum, median source spacing
+0.0072 Da, largest gap 1,269 Da -- puts 80.6% of the output total ion current
+into m/z regions more than 0.5 Da from any measured point.
+
+The fix is the parameter Cardinal (``tolerance``) and matter
+(``approx1(..., tol=)``) both expose: how far a target m/z may sit from the
+nearest source m/z before its interpolated value is discarded rather than
+trusted.
+
+Order matters
+-------------
+
+Masking happens **before** the TIC rescale, not after. The intensity was
+measured; it belongs somewhere. Interpolation had spread it across a gap where
+nothing was recorded, so returning it to the bins that do have measurements
+behind them keeps ``ResamplingMethod.TIC_PRESERVING``'s promise intact. Masking
+after the rescale would instead delete that intensity and quietly break the
+method's defining property.
+"""
+
+from typing import Any, Optional
+
+import numpy as np
+import numpy.typing as npt
+
+
+def zero_across_gaps(
+    resampled: npt.NDArray[Any],
+    axis: npt.NDArray[np.floating[Any]],
+    mzs: npt.NDArray[np.floating[Any]],
+    tolerance: Optional[float],
+) -> npt.NDArray[Any]:
+    """Zero the bins of ``resampled`` that no source point vouches for.
+
+    Modifies ``resampled`` in place and returns it.
+
+    A bin survives when some source m/z lies within ``tolerance`` of it. On a
+    source grid of uniform step ``s`` the farthest any target point can be
+    from a source point is ``s / 2``, so any tolerance of at least half the
+    source spacing leaves such a spectrum untouched -- which is what makes it
+    safe to switch on for continuous profile data. Half the *widest* source
+    gap is the rule to size it by; exactly half is a floating-point knife
+    edge, so give it a hair of margin.
+
+    Args:
+        resampled: Interpolated intensities on ``axis``, modified in place.
+        axis: The target mass axis, ascending.
+        mzs: Source m/z values, ascending.
+        tolerance: Maximum distance in Da from a target bin to the nearest
+            source m/z. ``None`` disables the check and returns ``resampled``
+            untouched, as does a non-positive tolerance.
+
+    Returns:
+        ``resampled``, with unsupported bins set to zero.
+    """
+    if tolerance is None or tolerance <= 0.0 or mzs.size == 0:
+        return resampled
+
+    # Distance from each target bin to the nearest source m/z. searchsorted
+    # gives the insertion point; the nearest source point is on one side or
+    # the other of it.
+    right = np.searchsorted(mzs, axis)
+    lo = np.clip(right - 1, 0, mzs.size - 1)
+    hi = np.clip(right, 0, mzs.size - 1)
+    nearest = np.minimum(np.abs(axis - mzs[lo]), np.abs(axis - mzs[hi]))
+
+    resampled[nearest > tolerance] = 0.0
+    return resampled

{thyra-2.0.3 → thyra-2.1.0}/thyra/resampling/strategies/nearest_neighbor.py

@@ -2,6 +2,23 @@
 
 This strategy is optimal for centroid data (e.g., from timsTOF
 instruments) where each peak represents a discrete mass value.
+
+Not to be confused with the converters' ``_nearest_neighbor_resample``
+(``thyra/converters/spatialdata/base_spatialdata_converter.py``), which is
+what ``ResamplingMethod.NEAREST_NEIGHBOR`` actually selects during a
+conversion. The two share a name and do opposite things with intensity:
+
+- This class INTERPOLATES. Each target point takes the intensity of the
+  nearest source point, so one source peak is replicated across every
+  target point closer to it than to any other. Summed intensity therefore
+  scales with how densely the target axis is laid out, and is not
+  preserved. That is the defining behaviour of nearest-neighbour
+  interpolation, not a defect -- but it means this class is the wrong tool
+  if you care about total ion current.
+- The converter's version BINS. Each source peak is accumulated into
+  exactly one target bin, so summed intensity is preserved exactly.
+
+If you want the conversion pipeline's behaviour, use the converter.
 """
 
 from typing import Any
@@ -24,6 +41,10 @@ class NearestNeighborStrategy(ResamplingStrategy):
         and assigns its intensity. This preserves the discrete nature
         of centroid data.
 
+        Does NOT preserve total ion current -- a source peak is repeated
+        at every target point nearest to it, so the sum grows with the
+        target axis density. See the module docstring.
+
         Parameters
         ----------
         spectrum : Spectrum

{thyra-2.0.3 → thyra-2.1.0}/thyra/resampling/strategies/tic_preserving.py

@@ -13,11 +13,12 @@ cropped intensity rather than redistributing it over the bins that remain.
 When the axis spans the spectrum, the whole TIC is preserved exactly.
 """
 
-from typing import Any
+from typing import Any, Optional
 
 import numpy as np
 import numpy.typing as npt
 
+from ..gaps import zero_across_gaps
 from ..tic import preserved_tic, rescale_to_preserved_tic
 from .base import ResamplingStrategy, Spectrum
 
@@ -25,6 +26,18 @@ from .base import ResamplingStrategy, Spectrum
 class TICPreservingStrategy(ResamplingStrategy):
     """TIC-preserving linear interpolation strategy for profile data."""
 
+    def __init__(self, gap_tolerance_da: Optional[float] = None) -> None:
+        """Initialize the strategy.
+
+        Args:
+            gap_tolerance_da: How far, in Daltons, a target bin may sit from
+                the nearest source m/z before its interpolated value is
+                discarded. ``None`` (the default) keeps ``np.interp``'s own
+                behaviour of drawing straight lines across unmeasured
+                regions. See :mod:`thyra.resampling.gaps`.
+        """
+        self.gap_tolerance_da = gap_tolerance_da
+
     def resample(
         self, spectrum: Spectrum, target_axis: npt.NDArray[np.floating[Any]]
     ) -> Spectrum:
@@ -109,6 +122,15 @@ class TICPreservingStrategy(ResamplingStrategy):
         # Ensure no negative values (can happen with extrapolation)
         interpolated_intensity = np.maximum(interpolated_intensity, 0.0)
 
+        # Discard bins no source point vouches for, before the rescale so the
+        # intensity returns to the measured bins rather than being deleted.
+        zero_across_gaps(
+            interpolated_intensity,
+            np.asarray(target_axis, dtype=np.float64),
+            mzs_sorted,
+            self.gap_tolerance_da,
+        )
+
         # Scale onto the TIC the target axis is entitled to carry. Shared
         # with the converters' hot path so the two cannot drift apart again.
         rescale_to_preserved_tic(

{thyra-2.0.3 → thyra-2.1.0}/thyra/resampling/types.py

@@ -70,7 +70,13 @@ class MassAxis:
         return np.diff(self.mz_values)
 
     def resolution_at(self, mz: float) -> float:
-        """Calculate resolution at given m/z."""
+        """Return ``mz`` divided by the local bin width.
+
+        This is a property of the AXIS, not of the data on it. A finely
+        spaced axis reports a large number here whether or not the spectra
+        stored on it resolve anything at that scale, so it must not be
+        reported to users as the acquisition's resolving power.
+        """
         idx = int(np.searchsorted(self.mz_values, mz))
         if idx > 0 and idx < len(self.mz_values):
             delta_mz = float(self.mz_values[idx] - self.mz_values[idx - 1])
@@ -91,8 +97,11 @@ class ResamplingConfig:
         axis_type: Mass axis spacing model.  ``None`` auto-detects from
             the instrument metadata.
         target_bins: Number of bins in the resampled axis.  ``None``
-            lets the resampler choose a bin count that preserves the
-            native resolution.
+            derives the count from ``mass_width_da`` at ``reference_mz``
+            across the mass range.  Note that this is a fixed target
+            width, not a measurement: the source spectra's own point
+            spacing is never consulted, so the resulting axis can be
+            finer or coarser than the data it will hold.
         mass_width_da: Bin width in Daltons at ``reference_mz``.
             Alternative to ``target_bins`` -- specify one or the other.
         reference_mz: Reference m/z for ``mass_width_da``.  Default
@@ -100,6 +109,13 @@ class ResamplingConfig:
             default.
         min_mz: Override the lower bound of the mass range.
         max_mz: Override the upper bound of the mass range.
+        gap_tolerance_da: How far, in Daltons, a target bin may sit from the
+            nearest source m/z before ``tic_preserving`` discards its
+            interpolated value instead of trusting it.  ``None`` -- the
+            default -- means no check, which is how ``np.interp`` behaves:
+            straight lines are drawn across regions where nothing was
+            measured.  Only affects ``tic_preserving``; ``nearest_neighbor``
+            never invents a bin.  See :mod:`thyra.resampling.gaps`.
     """
 
     method: Optional[ResamplingMethod] = None
@@ -109,3 +125,4 @@ class ResamplingConfig:
     reference_mz: float = DEFAULT_REFERENCE_MZ
     min_mz: Optional[float] = None
     max_mz: Optional[float] = None
+    gap_tolerance_da: Optional[float] = None