thyra 3.7.0__tar.gz → 3.7.2__tar.gz

{thyra-3.7.0 → thyra-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thyra
-Version: 3.7.0
+Version: 3.7.2
 Summary: A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics
 Project-URL: Homepage, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra
 Project-URL: Repository, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra

{thyra-3.7.0 → thyra-3.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thyra"
-version = "3.7.0"
+version = "3.7.2"
 description = "A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics"
 authors = [{ name = "Theodoros Visvikis", email = "t.visvikis@maastrichtuniversity.nl" }]
 maintainers = [{ name = "Theodoros Visvikis", email = "t.visvikis@maastrichtuniversity.nl" }]

{thyra-3.7.0 → thyra-3.7.2}/thyra/__init__.py

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

{thyra-3.7.0 → thyra-3.7.2}/thyra/converters/spatialdata/base_spatialdata_converter.py

@@ -215,6 +215,126 @@ def _calc_optical_scale_factors(
     return factors
 
 
+def _nn_map_to_bins(
+    axis: NDArray[np.float64], mzs: NDArray[np.float64]
+) -> NDArray[np.int_]:
+    """Map in-range m/z values to their nearest bin on ``axis``.
+
+    Ties (a peak exactly between two bins) resolve to the right bin,
+    matching the strict ``<`` comparison this code has always used.
+
+    A module-level function rather than a method so the unbound-call test
+    harnesses (a ``SimpleNamespace`` posing as the converter) keep working.
+
+    Args:
+        axis: The target mass axis, ascending.
+        mzs: m/z values, all within ``[axis[0], axis[-1]]``.
+
+    Returns:
+        The nearest-bin index of each m/z value, same length as ``mzs``.
+    """
+    # Find insertion points using vectorized binary search
+    indices = np.searchsorted(axis, mzs)
+
+    # Clip to valid range. Everything reaching here is inside the axis,
+    # so this only pins searchsorted's one-past-the-end result for a
+    # value equal to axis[-1]; it can no longer pull an outside peak in.
+    indices_clipped = np.clip(indices, 0, len(axis) - 1)
+
+    # For non-boundary points, check if left is closer
+    # Only check where we're not at the left edge
+    check_left = indices > 0
+    if np.any(check_left):
+        # Get distances only for points that need checking
+        mz_values = axis[indices_clipped[check_left]]
+        mz_values_left = axis[indices_clipped[check_left] - 1]
+        mz_query = mzs[check_left]
+
+        # Use left if it's closer
+        use_left = np.abs(mz_values_left - mz_query) < np.abs(mz_values - mz_query)
+        indices_clipped[check_left] = np.where(
+            use_left, indices_clipped[check_left] - 1, indices_clipped[check_left]
+        )
+    return indices_clipped
+
+
+def _nn_accumulate(
+    idx: NDArray[np.int_], intensities: NDArray[np.float64]
+) -> Tuple[NDArray[np.int_], NDArray[np.float64]]:
+    """Sum intensities per bin and return the non-zero bins, ascending.
+
+    Two equivalent routes. When ``idx`` is non-decreasing -- true whenever
+    the spectrum's m/z values are ascending, which every format seen so
+    far produces -- equal bins form contiguous runs, so the per-bin sums
+    are ``np.add.reduceat`` over the run starts. That is O(n_peaks),
+    where the ``np.bincount`` fallback is O(n_bins): for a centroid
+    spectrum of hundreds of peaks against an axis of 10^5 bins the
+    difference is roughly 7x per spectrum. Both sum left-to-right over
+    the same float64 values, so the results are bit-identical; the
+    fallback keeps unsorted input correct.
+
+    The kept-bin 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.
+    """
+    # bincount always promotes its weights to float64; match it so both
+    # accumulation routes return the same dtype and the same rounding.
+    vals = intensities.astype(np.float64, copy=False)
+
+    if idx.size and bool(np.all(idx[1:] >= idx[:-1])):
+        starts = np.concatenate(([0], np.flatnonzero(np.diff(idx)) + 1))
+        if starts.size == idx.size:
+            # Every peak already sits in its own bin (the common case
+            # for both centroid and profile data): nothing to sum.
+            bins = idx
+            sums = vals
+        else:
+            bins = idx[starts]
+            sums = np.add.reduceat(vals, starts)
+        keep = sums != 0
+        return bins[keep].astype(np.int_, copy=False), sums[keep]
+
+    accumulated = np.bincount(idx, weights=vals)
+    nonzero_mask = accumulated != 0
+    nonzero_indices = np.where(nonzero_mask)[0].astype(np.int_)
+    nonzero_values = accumulated[nonzero_mask]
+    return nonzero_indices, nonzero_values.astype(np.float64)
+
+
+class _SharedAxisNNCache:
+    """Precomputed nearest-neighbor mapping for one recurring m/z array.
+
+    Built the first time :meth:`_nearest_neighbor_resample` sees a spectrum,
+    and reused for every later spectrum that carries the same m/z array.
+    ``key`` is a private copy so a caller-side mutation of the original
+    array cannot fool the equality check; ``key_ref`` keeps the original
+    object for the O(1) identity test that readers yielding one shared
+    array (Rapiflex, Waters, PHI) hit every time.
+    """
+
+    __slots__ = (
+        "key",
+        "key_ref",
+        "n_total",
+        "n_dropped",
+        "lo",
+        "hi",
+        "starts",
+        "bins",
+    )
+
+    key: NDArray[np.float64]
+    key_ref: NDArray[np.float64]
+    n_total: int
+    n_dropped: int
+    lo: int
+    hi: int
+    starts: Optional[NDArray[np.int_]]
+    bins: NDArray[np.int_]
+
+
 class BaseSpatialDataConverter(BaseMSIConverter, ABC):
     """Base converter for MSI data to SpatialData format with shared functionality."""
 
@@ -345,6 +465,15 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         # Cache for dense mass axis indices (to avoid repeated np.arange calls)
         self._cached_mass_axis_indices: Optional[NDArray[np.int_]] = None
 
+        # Shared-axis nearest-neighbor cache. Continuous imzML, Rapiflex,
+        # Waters and PHI all hand every spectrum the same m/z array, so the
+        # peak-to-bin mapping is computed once and verified per spectrum by
+        # array equality instead of being re-derived by searchsorted. None
+        # means "not built yet"; False means "tried and the data does not
+        # share an axis, stop checking". See _nearest_neighbor_resample.
+        self._nn_shared_cache: Any = None
+        self._nn_cache_misses: int = 0
+
         # Optical-MSI alignment (computed from FlexImaging Area definitions)
         self._alignment_result: Optional[AreaAlignmentResult] = None
         # Affine matrix mapping TIC raster indices to optical image pixels
@@ -1263,6 +1392,22 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             raise ValueError("Common mass axis is not initialized")
 
         axis = self._common_mass_axis
+
+        # Shared-axis fast path: when every spectrum carries the same m/z
+        # array (continuous imzML, Rapiflex, Waters, PHI), the peak-to-bin
+        # mapping is a property of the axis pair, not of the spectrum. It is
+        # computed once; each later spectrum only proves its m/z array is
+        # the same one -- an exact array comparison, which is far cheaper
+        # than re-deriving the mapping by binary search per spectrum.
+        # ``False`` means the cache disabled itself (processed-mode data).
+        # getattr rather than a bare read: test harnesses drive this method
+        # unbound on a stub that predates the cache, and they exercise the
+        # generic path below, which is exactly what "no cache" selects.
+        if getattr(self, "_nn_shared_cache", False) is not False:
+            result = self._nn_resample_via_cache(axis, mzs, intensities)
+            if result is not None:
+                return result
+
         in_range = (mzs >= axis[0]) & (mzs <= axis[-1])
         if not in_range.all():
             self._count_out_of_range(int(mzs.size - in_range.sum()), int(mzs.size))
@@ -1271,45 +1416,101 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             if mzs.size == 0:
                 return np.array([], dtype=np.int_), np.array([], dtype=np.float64)
 
-        # Find insertion points using vectorized binary search
-        indices = np.searchsorted(axis, mzs)
-
-        # OPTIMIZED: Handle boundary and nearest neighbor in one pass
-        # Clip to valid range. Everything reaching here is inside the axis,
-        # so this only pins searchsorted's one-past-the-end result for a
-        # value equal to axis[-1]; it can no longer pull an outside peak in.
-        indices_clipped = np.clip(indices, 0, len(axis) - 1)
-
-        # For non-boundary points, check if left is closer
-        # Only check where we're not at the left edge
-        check_left = indices > 0
-        if np.any(check_left):
-            # Get distances only for points that need checking
-            mz_values = axis[indices_clipped[check_left]]
-            mz_values_left = axis[indices_clipped[check_left] - 1]
-            mz_query = mzs[check_left]
-
-            # Use left if it's closer
-            use_left = np.abs(mz_values_left - mz_query) < np.abs(mz_values - mz_query)
-            indices_clipped[check_left] = np.where(
-                use_left, indices_clipped[check_left] - 1, indices_clipped[check_left]
-            )
+        return _nn_accumulate(_nn_map_to_bins(axis, mzs), intensities)
 
-        # OPTIMIZATION: Use pandas-style groupby or bincount for accumulation
-        # bincount without minlength is fastest
-        accumulated = np.bincount(indices_clipped, weights=intensities)
+    def _build_nn_shared_cache(
+        self, axis: NDArray[np.float64], mzs: NDArray[np.float64]
+    ) -> Optional[_SharedAxisNNCache]:
+        """Precompute the nearest-neighbor mapping for one m/z array.
 
-        # 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]
+        Returns None when the array cannot be cached -- empty, or not
+        ascending, which the contiguous in-range slice below relies on.
+        The mapping itself comes from the same :meth:`_nn_map_to_bins`
+        the generic path uses, so a cache hit and a fresh computation
+        agree bin for bin.
+        """
+        if mzs.size == 0 or not bool(np.all(mzs[1:] >= mzs[:-1])):
+            return None
+
+        # Ascending m/z makes the in-range subset one contiguous slice,
+        # with the same inclusive endpoints as the generic path's mask.
+        lo = int(np.searchsorted(mzs, axis[0], side="left"))
+        hi = int(np.searchsorted(mzs, axis[-1], side="right"))
+
+        cache = _SharedAxisNNCache()
+        cache.key = mzs.copy()
+        cache.key_ref = mzs
+        cache.n_total = int(mzs.size)
+        cache.n_dropped = int(mzs.size - (hi - lo))
+        cache.lo = lo
+        cache.hi = hi
+        if hi <= lo:
+            cache.starts = None
+            cache.bins = np.array([], dtype=np.int_)
+            return cache
+
+        idx = _nn_map_to_bins(axis, mzs[lo:hi])
+        # Ascending m/z onto an ascending axis gives non-decreasing bins,
+        # so equal bins form contiguous runs.
+        starts = np.concatenate(([0], np.flatnonzero(np.diff(idx)) + 1))
+        if starts.size == idx.size:
+            # Every peak in its own bin: per-spectrum work reduces to a
+            # zero-filter over the raw intensities.
+            cache.starts = None
+            cache.bins = idx.astype(np.int_, copy=False)
+        else:
+            cache.starts = starts
+            cache.bins = idx[starts].astype(np.int_, copy=False)
+        return cache
+
+    def _nn_resample_via_cache(
+        self,
+        axis: NDArray[np.float64],
+        mzs: NDArray[np.float64],
+        intensities: NDArray[np.float64],
+    ) -> Optional[Tuple[NDArray[np.int_], NDArray[np.float64]]]:
+        """Resample through the shared-axis cache, or return None to decline.
+
+        The cache is built from the first spectrum seen. A hit requires the
+        spectrum's m/z array to be the cached one -- same object, or equal
+        element for element -- so a lying reader cannot get a stale mapping;
+        it can only miss. After five consecutive misses the cache disables
+        itself so processed-mode data stops paying for the comparison
+        (its size check is O(1) in the common case anyway).
+        """
+        cache = self._nn_shared_cache
+        if cache is False:
+            return None
+        if cache is None:
+            cache = self._build_nn_shared_cache(axis, mzs)
+            if cache is None:
+                self._nn_shared_cache = False
+                return None
+            self._nn_shared_cache = cache
+
+        if not (
+            mzs is cache.key_ref
+            or (mzs.size == cache.n_total and bool(np.array_equal(mzs, cache.key)))
+        ):
+            self._nn_cache_misses += 1
+            if self._nn_cache_misses > 4:
+                self._nn_shared_cache = False
+            return None
 
-        return nonzero_indices, nonzero_values.astype(np.float64)
+        if cache.n_dropped:
+            self._count_out_of_range(cache.n_dropped, cache.n_total)
+        if cache.hi <= cache.lo:
+            return np.array([], dtype=np.int_), np.array([], dtype=np.float64)
+
+        # Match bincount's float64 promotion so cached and generic results
+        # carry the same rounding.
+        vals = intensities[cache.lo : cache.hi].astype(np.float64, copy=False)
+        if cache.starts is None:
+            sums = vals
+        else:
+            sums = np.add.reduceat(vals, cache.starts)
+        keep = sums != 0
+        return cache.bins[keep], sums[keep]
 
     def _tic_preserving_resample(
         self, mzs: NDArray[np.float64], intensities: NDArray[np.float64]
@@ -1798,6 +1999,8 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
                 )
         else:
             # Standard physical coordinates (micrometers)
+            from shapely import box as shapely_box_vectorized
+
             x_coords: NDArray[np.float64] = adata.obs["spatial_x"].values
             y_coords: NDArray[np.float64] = adata.obs["spatial_y"].values
             half_pixel_um = self.pixel_size_um / 2
@@ -1805,12 +2008,15 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             # Footprints are flat, on every route including volumes. A
             # slice's depth lives on the TIC image's Scale and in
             # obs["spatial_z"]; see the docstring for why it is not also
-            # put on the geometry.
-            for i in range(len(adata)):
-                x, y = x_coords[i], y_coords[i]
-                x0, y0 = x - half_pixel_um, y - half_pixel_um
-                x1, y1 = x + half_pixel_um, y + half_pixel_um
-                geometries.append(box(x0, y0, x1, y1))
+            # put on the geometry. Built through shapely's vectorised box
+            # constructor -- one C call for the whole table instead of one
+            # Python-level geometry per pixel.
+            geometries = shapely_box_vectorized(
+                x_coords - half_pixel_um,
+                y_coords - half_pixel_um,
+                x_coords + half_pixel_um,
+                y_coords + half_pixel_um,
+            )
 
         # Create GeoDataFrame with appropriate index
         if valid_indices is not None:

{thyra-3.7.0 → thyra-3.7.2}/thyra/converters/spatialdata/spatialdata_2d_converter.py

@@ -206,20 +206,30 @@ class SpatialData2DConverter(BaseSpatialDataConverter):
         # Calculate TIC for this pixel
         tic_value = float(np.sum(intensities))
 
-        # Update total intensity for average spectrum calculation using sparse indexing
-        # OPTIMIZATION: Use np.add.at for vectorized sparse accumulation
-        np.add.at(data_structures["total_intensity"], mz_indices, intensities)
+        # Update total intensity for average spectrum calculation. The dense
+        # resampling path hands the cached full-axis arange, where a plain
+        # vector add is ~5x cheaper than the scatter np.add.at performs;
+        # sparse indices keep the scatter.
+        total_intensity = data_structures["total_intensity"]
+        is_dense = (
+            mz_indices is self._cached_mass_axis_indices
+            or mz_indices is self._identity_mass_indices
+        ) and intensities.size == total_intensity.size
+        if is_dense:
+            total_intensity += intensities
+        else:
+            np.add.at(total_intensity, mz_indices, intensities)
         data_structures["pixel_count"] += 1
 
         # Per-region accumulation for multi-region datasets
         if "region_total_intensity" in data_structures:
             region_num = self._region_map.get((x, y), -1)
             if region_num in data_structures["region_total_intensity"]:
-                np.add.at(
-                    data_structures["region_total_intensity"][region_num],
-                    mz_indices,
-                    intensities,
-                )
+                region_total = data_structures["region_total_intensity"][region_num]
+                if is_dense:
+                    region_total += intensities
+                else:
+                    np.add.at(region_total, mz_indices, intensities)
                 data_structures["region_pixel_count"][region_num] += 1
 
         # Add data to the appropriate slice

{thyra-3.7.0 → thyra-3.7.2}/thyra/converters/spatialdata/spatialdata_3d_converter.py

@@ -120,12 +120,17 @@ class SpatialData3DConverter(BaseSpatialDataConverter):
             # Resampled case - intensities match common mass axis length
             data_structures["total_intensity"] += intensities
         else:
-            # Non-resampled case - need to map to indices
-            for i, intensity in enumerate(intensities):
-                if i < len(mz_indices) and mz_indices[i] < len(
-                    data_structures["total_intensity"]
-                ):
-                    data_structures["total_intensity"][mz_indices[i]] += intensity
+            # Sparse case - scatter onto the mapped indices. Guard the
+            # lengths the way the old per-element loop did: only pairs
+            # that exist in both arrays, only in-bounds indices.
+            n = min(len(intensities), len(mz_indices))
+            idx = mz_indices[:n]
+            in_bounds = idx < len(data_structures["total_intensity"])
+            np.add.at(
+                data_structures["total_intensity"],
+                idx[in_bounds],
+                intensities[:n][in_bounds],
+            )
         data_structures["pixel_count"] += 1
 
         # Per-region accumulation for multi-region datasets

{thyra-3.7.0 → thyra-3.7.2}/thyra/converters/spatialdata/streaming_converter.py

@@ -24,6 +24,7 @@ from numpy.typing import NDArray
 from scipy import sparse
 from tqdm import tqdm
 
+from ...resampling import ResamplingMethod
 from .base_spatialdata_converter import (
     SPATIALDATA_AVAILABLE,
     BaseSpatialDataConverter,
@@ -125,6 +126,15 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         self._zarr_store: Optional[zarr.Group] = None
         self._temp_path: Optional[Path] = None
 
+        # Resolved once here rather than per spectrum: _process_spectrum is
+        # the hottest call in both passes, and re-importing ResamplingMethod
+        # plus re-checking the attribute there measured ~35 us per call.
+        self._nn_route: bool = (
+            self._resampling_config is not None
+            and getattr(self, "_resampling_method", None)
+            == ResamplingMethod.NEAREST_NEIGHBOR
+        )
+
     def _suppress_reader_progress(self) -> None:
         """Suppress progress output from reader during streaming passes."""
         setattr(self.reader, "_quiet_mode", True)
@@ -750,19 +760,17 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         all_idx = all_idx[order]
         all_dat = all_dat[order]
 
-        # Write contiguous runs in bulk
+        # Find run boundaries vectorised, then write one Zarr slice per
+        # contiguous run. The previous element-at-a-time Python walk cost
+        # ~2.5 s per 5M-entry flush against ~27 ms for the same answer.
         n = len(all_pos)
-        i = 0
-        while i < n:
-            start_pos = all_pos[i]
-            # Find end of contiguous run
-            j = i + 1
-            while j < n and all_pos[j] == all_pos[j - 1] + 1:
-                j += 1
-            # Write the contiguous block
-            indices_arr[int(start_pos) : int(start_pos) + (j - i)] = all_idx[i:j]
-            data_arr[int(start_pos) : int(start_pos) + (j - i)] = all_dat[i:j]
-            i = j
+        breaks = np.flatnonzero(np.diff(all_pos) != 1)
+        starts = np.concatenate(([0], breaks + 1))
+        ends = np.concatenate((breaks + 1, [n]))
+        for i, j in zip(starts.tolist(), ends.tolist()):
+            start_pos = int(all_pos[i])
+            indices_arr[start_pos : start_pos + (j - i)] = all_idx[i:j]
+            data_arr[start_pos : start_pos + (j - i)] = all_dat[i:j]
 
         del all_pos, all_idx, all_dat
         gc.collect()
@@ -787,21 +795,18 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
             mz_indices = self._map_mass_to_indices(mzs)
             return mz_indices, intensities
 
-        # Check for optimized nearest-neighbor path
-        if hasattr(self, "_resampling_method"):
-            from ...resampling import ResamplingMethod
-
-            if self._resampling_method == ResamplingMethod.NEAREST_NEIGHBOR:
-                mz_indices, resampled = self._nearest_neighbor_resample(
-                    mzs, intensities
-                )
-                return mz_indices, resampled
+        # Optimized nearest-neighbor path; the route is resolved once in
+        # __init__ because this runs once per spectrum per pass.
+        if self._nn_route:
+            return self._nearest_neighbor_resample(mzs, intensities)
 
         # Fallback: general resampling with zero filtering
         resampled_ints = self._resample_spectrum(mzs, intensities)
         if self._common_mass_axis is None:
             raise RuntimeError("Common mass axis not initialized")
-        mz_indices = np.arange(len(self._common_mass_axis))
+        mz_indices = self._cached_mass_axis_indices
+        if mz_indices is None or mz_indices.size != len(self._common_mass_axis):
+            mz_indices = np.arange(len(self._common_mass_axis))
         mask = resampled_ints != 0
         return mz_indices[mask], resampled_ints[mask]
 
@@ -1373,10 +1378,6 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         # Current write position for each column
         write_pos = indptr[:-1].copy()
 
-        # Periodic flush to reduce memory pressure
-        flush_interval = 100_000
-        spectra_since_flush = 0
-
         # Reset reader for second pass
         # For real readers (ImzML, Bruker), iter_spectra() is a generator factory
         # that creates a fresh iterator each time - no need to recreate the reader.
@@ -1419,15 +1420,13 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
                     write_pos[mz_indices] += 1
 
                 pbar.update(1)
-                spectra_since_flush += 1
-
-                # Periodic flush
-                if spectra_since_flush >= flush_interval:
-                    mm_indices.flush()
-                    mm_data.flush()
-                    spectra_since_flush = 0
 
-        # Final flush
+        # One flush at the end. A periodic flush used to run every 100k
+        # spectra, but ``np.memmap.flush`` writes back the whole mapping
+        # synchronously, serialising disk writeback into the compute loop;
+        # the OS pager already writes dirty pages back in the background.
+        # Scatter writes each position exactly once, so nothing is dirtied
+        # twice and the deferred writeback costs the same total I/O.
         mm_indices.flush()
         mm_data.flush()
 

{thyra-3.7.0 → thyra-3.7.2}/thyra/core/base_converter.py

@@ -110,6 +110,11 @@ class BaseMSIConverter(ABC):
         self.z_spacing_source = ZSpacingSource.ASSUMED_ISOTROPIC
         self.options: Dict[str, Any] = kwargs
         self._common_mass_axis: Optional[NDArray[np.float64]] = None
+        # Identity-mapping cache for _map_mass_to_indices: shared-axis
+        # readers hand every spectrum the very m/z array the common axis
+        # was built from, so the exact-match search is the identity map.
+        self._identity_mass_indices: Optional[NDArray[np.int_]] = None
+        self._axis_strictly_increasing: Optional[bool] = None
         self._dimensions: Optional[Tuple[int, int, int]] = None
         self._metadata: Optional[dict[str, Any]] = None
         from ..config import DEFAULT_BUFFER_SIZE
@@ -568,11 +573,23 @@ class BaseMSIConverter(ABC):
     def _map_mass_to_indices(self, mzs: NDArray[np.float64]) -> NDArray[np.int_]:
         """Map m/z values to indices in the common mass axis with high accuracy.
 
+        The returned array is parallel to ``mzs`` (same length, same order),
+        so callers may pair it element-for-element with the spectrum's
+        intensity array.
+
         Args:
             mzs: Array of m/z values
 
         Returns:
-            Array of indices in common mass axis
+            Array of indices in common mass axis, parallel to ``mzs``
+
+        Raises:
+            ValueError: If any m/z value has no common-axis entry within
+                tolerance. Without resampling the axis is built from the
+                spectra themselves, so every value must match exactly; a
+                near-miss means the axis and the data have diverged, and
+                dropping the value silently would desync the index and
+                intensity arrays downstream.
         """
         if self._common_mass_axis is None:
             raise ValueError("Common mass axis is not initialized.")
@@ -580,18 +597,52 @@ class BaseMSIConverter(ABC):
         if mzs.size == 0:
             return np.array([], dtype=int)
 
-        # Use searchsorted for exact mapping
-        indices = np.searchsorted(self._common_mass_axis, mzs)
-
-        # Ensure indices are within bounds
-        indices = np.clip(indices, 0, len(self._common_mass_axis) - 1)
+        axis = self._common_mass_axis
+
+        # Identity fast path. On a shared-axis reader (continuous imzML,
+        # Rapiflex, Waters, PHI) every spectrum's m/z array is the very
+        # array the common axis was built from, so the exact-match search
+        # below returns 0..n-1 -- yet used to be re-derived by binary
+        # search per spectrum, twice per streaming conversion. Equality is
+        # proven, not assumed: an O(1) size check gates a full array
+        # comparison, and the arange shortcut is only valid when the axis
+        # is strictly increasing (searchsorted maps duplicates to their
+        # first occurrence, which is not the identity).
+        if mzs.size == axis.size and (mzs is axis or bool(np.array_equal(mzs, axis))):
+            if self._axis_strictly_increasing is None:
+                self._axis_strictly_increasing = bool(np.all(np.diff(axis) > 0))
+            if self._axis_strictly_increasing:
+                cached = self._identity_mass_indices
+                if cached is None or cached.size != axis.size:
+                    cached = np.arange(axis.size, dtype=np.intp)
+                    self._identity_mass_indices = cached
+                return cached
+
+        # searchsorted returns the right-hand neighbor; the nearest axis
+        # entry may sit on either side, so compare both before validating.
+        right = np.clip(np.searchsorted(axis, mzs), 0, len(axis) - 1)
+        left = np.maximum(right - 1, 0)
+        indices = np.where(
+            np.abs(axis[right] - mzs) <= np.abs(axis[left] - mzs), right, left
+        )
 
-        # For complete accuracy, validate the indices
         # Very small tolerance threshold for floating point differences
         max_diff = 1e-6
-        mask = np.abs(self._common_mass_axis[indices] - mzs) <= max_diff
+        diffs = np.abs(axis[indices] - mzs)
+        bad = diffs > max_diff
+        if np.any(bad):
+            worst = int(np.argmax(diffs))
+            raise ValueError(
+                f"{int(np.count_nonzero(bad))} of {mzs.size} m/z values have "
+                f"no common mass axis entry within {max_diff:g} (worst: m/z "
+                f"{mzs[worst]!r} is {diffs[worst]:.6g} from nearest axis "
+                f"entry {axis[indices[worst]]!r}). The common mass axis does "
+                f"not cover this spectrum; refusing to drop values silently "
+                f"because callers pair these indices with the full intensity "
+                f"array."
+            )
 
-        return indices[mask]
+        return indices
 
     def _add_to_sparse_matrix(
         self,