thyra 2.0.0__tar.gz → 2.0.2__tar.gz

{thyra-2.0.0 → thyra-2.0.2}/PKG-INFO

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

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

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

{thyra-2.0.0 → thyra-2.0.2}/thyra/convert.py

@@ -281,6 +281,12 @@ def convert_msi(
               to include. Default: None (no filtering).
             - use_recalibrated_state: bool - For Bruker data,
               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.
         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.0 → thyra-2.0.2}/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.tic import preserved_tic, rescale_to_preserved_tic
 from ...resampling.types import ResamplingConfig
 from ...utils.zarr_atomic_write import install_windows_atomic_write_retry
 from ._chunking import image_chunks
@@ -1091,11 +1092,38 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
     def _tic_preserving_resample(
         self, mzs: NDArray[np.float64], intensities: NDArray[np.float64]
     ) -> NDArray[np.float64]:
-        """Resample using TIC-preserving linear interpolation - optimized."""
+        """Resample onto the common axis, preserving total ion current.
+
+        Linear interpolation onto the target axis, followed by rescaling so
+        the resampled spectrum carries the same total ion current as the
+        input -- the behaviour ``ResamplingMethod.TIC_PRESERVING`` and
+        docs/resampling.md both describe.
+
+        The rescaling is not cosmetic. Interpolation samples the spectrum at
+        every target point, so the raw interpolated sum scales with the
+        density of the target axis rather than staying fixed. Onto the
+        default 190,000-bin axis, 4,000 source points came back with 47x the
+        input TIC, and a 150-peak centroid spectrum with over 1000x.
+
+        The TIC preserved is the share of the spectrum lying inside the
+        target axis range -- see ``thyra.resampling.tic``, which holds the
+        rule and the reasoning, and which ``TICPreservingStrategy`` uses too.
+        When the axis spans the spectrum, which is the default, that share
+        is the whole input TIC.
+
+        Args:
+            mzs: Original m/z values from the spectrum.
+            intensities: Corresponding intensity values.
+
+        Returns:
+            Intensities on the common mass axis, of the axis's length.
+        """
         if self._common_mass_axis is None:
             raise RuntimeError("Common mass axis is not initialized")
+
+        axis = self._common_mass_axis
         if mzs.size == 0:
-            return np.zeros(len(self._common_mass_axis))
+            return np.zeros(len(axis))
 
         # OPTIMIZED: Check if already sorted to avoid unnecessary sorting
         if np.all(mzs[:-1] <= mzs[1:]):
@@ -1108,18 +1136,31 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             mzs_sorted = mzs[sort_indices]
             intensities_sorted = intensities[sort_indices]
 
+        if mzs_sorted.size == 1:
+            # np.interp cannot interpolate a lone point onto a grid that
+            # does not contain it -- it would return all zeros and lose the
+            # peak. Place it in its nearest bin, as the nearest_neighbor
+            # path and TICPreservingStrategy both do.
+            resampled = np.zeros(len(axis))
+            target_tic = preserved_tic(
+                mzs_sorted, intensities_sorted, float(axis[0]), float(axis[-1])
+            )
+            if target_tic > 0.0:
+                resampled[int(np.argmin(np.abs(axis - mzs_sorted[0])))] = target_tic
+            return resampled
+
         # Interpolate onto the common mass axis (np.interp is highly optimized)
-        if self._common_mass_axis is None:
-            raise RuntimeError("Common mass axis is not initialized")
         resampled = np.interp(
-            self._common_mass_axis,
+            axis,
             mzs_sorted,
             intensities_sorted,
             left=0,
             right=0,
         )
 
-        return resampled
+        # 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)
 
     def _process_resampled_spectrum(
         self,

{thyra-2.0.0 → thyra-2.0.2}/thyra/converters/spatialdata/streaming_converter.py

@@ -40,6 +40,12 @@ if SPATIALDATA_AVAILABLE:
 
 logger = logging.getLogger(__name__)
 
+# Elements per chunk when building the string index arrays. Bounds the
+# transient cost of formatting to this many entries rather than the whole
+# axis; measured at 17.5 bytes per entry at peak against 88 for a one-shot
+# build, and 32 for an unchunked vectorised one.
+_INDEX_BUILD_CHUNK = 1_000_000
+
 
 class StreamingSpatialDataConverter(BaseSpatialDataConverter):
     """Memory-efficient streaming converter for MSI data to SpatialData format.
@@ -491,11 +497,19 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         indptr_arr.attrs["encoding-type"] = "array"
         indptr_arr.attrs["encoding-version"] = "0.2.0"
 
+        # Column indices are bounded by n_cols, not by total_nnz, so they need
+        # their own dtype decision. Hardcoding int32 here wrapped silently
+        # above 2,147,483,647 m/z bins: zarr truncates an oversized write
+        # without warning, and the resulting negative indices survive all the
+        # way into scipy without an error. This is the same switch point scipy
+        # uses, so the matrix rebuilt from these arrays needs no cast.
+        indices_dtype = np.int64 if n_cols > np.iinfo(np.int32).max else np.int32
+
         chunk_size_zarr = min(total_nnz, 1000000)
         indices_arr = X_group.create_array(
             "indices",
             shape=(total_nnz,),
-            dtype=np.int32,
+            dtype=indices_dtype,
             chunks=(chunk_size_zarr,),
         )
         indices_arr.attrs["encoding-type"] = "array"
@@ -566,7 +580,11 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
                     pos = write_pos[pixel_idx]
                     positions = np.arange(pos, pos + nnz)
                     buf_positions.append(positions)
-                    buf_indices.append(mz_indices.astype(np.int32))
+                    # Take the dtype from the destination array rather than
+                    # re-deriving it, so the buffer and the store cannot drift
+                    # apart. Zarr accepts an oversized write and truncates it
+                    # silently, so a mismatch here would be invisible.
+                    buf_indices.append(mz_indices.astype(indices_arr.dtype))
                     buf_data.append(resampled_ints.astype(np.float64))
                     write_pos[pixel_idx] += nnz
                     buf_size += nnz
@@ -716,11 +734,15 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
 
         logger.info(f"Loaded CSR components: {len(data):,} entries")
 
-        # For large datasets (>2.1B entries), ensure 64-bit indices for scipy
+        # indices already carries the dtype chosen at write time, keyed on the
+        # column count (see _coo_setup_zarr_arrays), so there is nothing to fix
+        # up here. Upcasting it was never a safeguard anyway: it widened values
+        # that had already been truncated on the way in, and it was keyed on
+        # the wrong quantity. indptr is bounded by nnz, hence the check below.
+        # copy=False makes the no-op case free rather than a full-size copy.
         if len(data) > np.iinfo(np.int32).max:
             logger.info("Large dataset detected, using 64-bit sparse matrix indices")
-            indptr = indptr.astype(np.int64)
-            indices = indices.astype(np.int64)
+            indptr = indptr.astype(np.int64, copy=False)
 
         # Create CSR matrix directly (no COO intermediate)
         sparse_matrix: Union[sparse.csr_matrix, sparse.csc_matrix] = sparse.csr_matrix(
@@ -1417,7 +1439,9 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
 
         y_values = np.repeat(np.arange(n_y, dtype=np.int32), n_x)
         x_values = np.tile(np.arange(n_x, dtype=np.int32), n_y)
-        instance_ids = np.array([str(i) for i in range(n_rows)], dtype=str_dtype)
+        # Same reasoning as the var index below, but n_rows is the pixel count
+        # and stays far smaller than n_cols, so one shot needs no chunking.
+        instance_ids = np.arange(n_rows, dtype=np.int64).astype(str_dtype)
         spatial_x = x_values.astype(np.float64) * self.pixel_size_um
         spatial_y = y_values.astype(np.float64) * self.pixel_size_um
 
@@ -1464,7 +1488,17 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         mz_values = self._common_mass_axis
         if mz_values is None:
             raise RuntimeError("Common mass axis not initialized")
-        mz_index = np.array([f"mz_{i}" for i in range(n_cols)], dtype=str_dtype)
+        # Built in chunks rather than from a list comprehension. Materialising
+        # n_cols Python str objects first costs about 88 bytes per entry at
+        # peak, against 17.5 for this; at 10 million bins that is 883 MB
+        # versus 175 MB, on a path whose docstring promises roughly 200 MB
+        # regardless of dataset size. The values are identical.
+        mz_index = np.empty(n_cols, dtype=str_dtype)
+        for start in range(0, n_cols, _INDEX_BUILD_CHUNK):
+            stop = min(start + _INDEX_BUILD_CHUNK, n_cols)
+            mz_index[start:stop] = np.strings.add(
+                "mz_", np.arange(start, stop, dtype=np.int64).astype(str_dtype)
+            )
         a = var_group.create_array("_index", data=mz_index)
         a.attrs["encoding-type"] = "string-array"
         a.attrs["encoding-version"] = "0.2.0"

{thyra-2.0.0 → thyra-2.0.2}/thyra/readers/imzml/imzml_reader.py

@@ -15,6 +15,308 @@ from ...metadata.extractors.imzml_extractor import ImzMLMetadataExtractor
 
 logger = logging.getLogger(__name__)
 
+# Scratch buffer floor for the processed-mode mass axis build, in ELEMENTS.
+# 1Mi elements is 8 MiB at float64. Measured at a 512 MiB m/z payload on a
+# shared grid (peak extra RSS / wall clock): 2^14 -> 7.14 MiB / 3.04 s,
+# 2^17 -> 6.90 / 3.06, 2^20 -> 15.30 / 2.30, 2^22 -> 40.29 / 2.11,
+# 2^24 -> 148.38 / 2.06. A 1024x sweep of the knob moves wall clock 1.5x with
+# no cliff anywhere, so this is a knee rather than a fragile constant.
+_MASS_AXIS_BATCH_VALUES = 1 << 20
+
+# Block size for the searchsorted probe in ``_filter_absent``, in ELEMENTS.
+# Bounds that function's temporaries to O(block) rather than O(batch).
+_MASS_AXIS_PROBE_BLOCK = 1 << 20
+
+
+def _dedupe_sorted(a: NDArray[Any]) -> NDArray[Any]:
+    """Deduplicate an ALREADY-SORTED array, as ``np.unique`` would.
+
+    Reproduces numpy's ``_unique1d`` mask including its ``equal_nan=True``
+    behaviour, which collapses a trailing run of NaNs to its first element.
+    Unlike ``np.unique`` it does not make the extra full-size ``flatten()``
+    copy, which is one of the three payload-sized allocations the old
+    collect-everything-then-unique build paid for.
+
+    Args:
+        a: A sorted array.
+
+    Returns:
+        The distinct values of ``a``, in order.
+    """
+    n = a.size
+    if n == 0:
+        return a[:0].copy()
+
+    mask = np.empty(n, dtype=bool)
+    mask[0] = True
+
+    if a.dtype.kind == "f" and bool(np.isnan(a[-1])):
+        first_nan = int(np.searchsorted(a, a[-1], side="left"))
+        # The ``first_nan > 0`` guard is load-bearing: an all-NaN input makes
+        # the slices empty and ``np.not_equal`` raises on the shape mismatch.
+        if first_nan > 0:
+            np.not_equal(a[1:first_nan], a[: first_nan - 1], out=mask[1:first_nan])
+        mask[first_nan] = True
+        mask[first_nan + 1 :] = False
+    else:
+        np.not_equal(a[1:], a[:-1], out=mask[1:])
+
+    return a[mask]
+
+
+def _filter_absent(
+    acc: NDArray[Any],
+    s: NDArray[Any],
+    block: int = _MASS_AXIS_PROBE_BLOCK,
+) -> NDArray[Any]:
+    """Return the elements of ``s`` that are not already in ``acc``.
+
+    Both arrays must be sorted and free of duplicates. ``s`` is walked in
+    blocks so the search temporaries stay O(block) rather than O(len(s)).
+    Returns ``s`` itself, uncopied, when none of its values are present --
+    the all-distinct fast path, worth half a payload at peak.
+
+    Args:
+        acc: The running axis, sorted and unique.
+        s: A candidate batch, sorted and unique.
+        block: Probe block size in elements.
+
+    Returns:
+        The subset of ``s`` absent from ``acc``.
+    """
+    n = s.size
+    # ``acc.size == 0`` must be handled here: the ``np.minimum`` below would
+    # otherwise index ``acc[-1]`` on an empty array and raise IndexError.
+    if n == 0 or acc.size == 0:
+        return s
+
+    keep = np.empty(n, dtype=bool)
+    n_keep = 0
+    is_float = acc.dtype.kind == "f"
+    a_len = acc.size
+
+    for lo in range(0, n, block):
+        hi = min(lo + block, n)
+        sb = s[lo:hi]
+        pos = np.searchsorted(acc, sb, side="left")
+        out_of_range = pos >= a_len
+        np.minimum(pos, a_len - 1, out=pos)
+        va = acc[pos]
+        eq = va == sb
+        if is_float:
+            # searchsorted routes a NaN key onto acc's first NaN, but NaN does
+            # not compare equal to itself, so without this the same NaN would
+            # be re-inserted on every fold.
+            np.logical_or(eq, np.isnan(va) & np.isnan(sb), out=eq)
+        np.logical_and(eq, ~out_of_range, out=eq)
+        np.logical_not(eq, out=eq)
+        keep[lo:hi] = eq
+        n_keep += int(np.count_nonzero(eq))
+        del pos, out_of_range, va, eq, sb
+
+    if n_keep == n:
+        return s
+    if n_keep == 0:
+        return s[:0]
+    return s[keep]
+
+
+def _merge_disjoint(box_a: List[Any], box_b: List[Any]) -> NDArray[Any]:
+    """Merge two DISJOINT sorted arrays, releasing each once it is copied.
+
+    The inputs arrive boxed in one-element lists so this function can drop the
+    caller's reference as soon as each side has been copied. Passing them as
+    plain parameters would keep both alive for the whole call and add a full
+    copy of the larger side to the peak.
+
+    The result needs no second deduplication because ``_filter_absent`` has
+    already removed the overlap, which saves another full-size copy.
+
+    Args:
+        box_a: One-element list holding the first sorted array.
+        box_b: One-element list holding the second sorted array.
+
+    Returns:
+        The sorted union of the two inputs.
+    """
+    a, b = box_a[0], box_b[0]
+    out = np.empty(a.size + b.size, dtype=a.dtype)
+
+    n_a = a.size
+    out[:n_a] = a
+    box_a[0] = None
+    del a
+
+    out[n_a:] = b
+    box_b[0] = None
+    del b
+
+    # Exactly two ascending runs, which is the case quicksort handles best.
+    out.sort(kind="quicksort")
+    return out
+
+
+def _read_spectrum_mzs(parser: Any, idx: int) -> Optional[NDArray[Any]]:
+    """Read one spectrum's m/z values, or None if missing or unreadable.
+
+    Args:
+        parser: An initialized ImzML parser.
+        idx: Spectrum index.
+
+    Returns:
+        The m/z array, or None when the spectrum is empty or failed to read.
+    """
+    try:
+        spectrum_data = parser.getspectrum(idx)
+    except Exception as e:
+        logger.warning(f"Error getting spectrum {idx}: {e}")
+        return None
+
+    if spectrum_data is None or len(spectrum_data) < 1:
+        return None
+    mzs = spectrum_data[0]
+    return mzs if mzs.size else None
+
+
+class _MassAxisAccumulator:
+    """Builds a sorted, unique m/z axis without holding every spectrum.
+
+    Values are copied into a scratch buffer; when that buffer fills, it is
+    sorted, deduplicated, and merged into the running axis. The buffer's
+    capacity tracks the axis length, so the number of merges is logarithmic in
+    the input rather than linear -- a fixed batch size would re-copy the
+    accumulator once per batch, which is the quadratic behaviour that makes a
+    naive ``np.union1d`` fold far slower than the code it replaces.
+
+    Peak memory therefore depends on the number of *unique* m/z values rather
+    than on the size of the file.
+    """
+
+    def __init__(self, total_spectra: int, max_length: Optional[int] = None) -> None:
+        """Initialize the accumulator.
+
+        Args:
+            total_spectra: Spectrum count, used only in the error message.
+            max_length: Cap on unique m/z values, or None for unlimited.
+        """
+        self._total_spectra = total_spectra
+        self._max_length = max_length
+        self._acc: Optional[NDArray[Any]] = None
+        self._buf: Optional[NDArray[Any]] = None
+        self._cap = 0
+        self._cap_target = _MASS_AXIS_BATCH_VALUES
+        self._n = 0
+        self.saw_any = False
+
+    def add(self, mzs: NDArray[Any], index: int) -> None:
+        """Buffer one spectrum's m/z values, folding first if the buffer is full.
+
+        Args:
+            mzs: The spectrum's m/z values. Not modified.
+            index: Spectrum index, used only in the error message.
+        """
+        m = mzs.size
+        if not m:
+            return
+        self.saw_any = True
+
+        if self._buf is None:
+            self._allocate(m, mzs.dtype)
+        elif self._n + m > self._cap:
+            self._fold(index)
+            if self._buf is None:
+                self._allocate(m, mzs.dtype)
+            elif m > self._cap:
+                self._buf = None
+                self._allocate(m, mzs.dtype, exact=True)
+
+        assert self._buf is not None
+        self._buf[self._n : self._n + m] = mzs
+        self._n += m
+
+    def finish(self, index: int) -> NDArray[Any]:
+        """Fold whatever is buffered and return the axis.
+
+        Args:
+            index: Last spectrum index, used only in the error message.
+
+        Returns:
+            Sorted, unique m/z values.
+
+        Raises:
+            ValueError: If no spectrum yielded any m/z values.
+        """
+        self._fold(index)
+        self._buf = None
+
+        if not self.saw_any or self._acc is None:
+            raise ValueError("No spectra found to build common mass axis")
+        if self._acc.size == 0:
+            raise ValueError("Failed to extract any m/z values")
+        return self._acc
+
+    def _allocate(self, m: int, dtype: Any, exact: bool = False) -> None:
+        """Allocate the scratch buffer, at least large enough for one spectrum."""
+        self._cap = m if exact else max(self._cap_target, m)
+        self._buf = np.empty(self._cap, dtype=dtype)
+
+    def _fold(self, index: int) -> None:
+        """Sort, deduplicate and merge the buffered batch into the axis."""
+        if self._n == 0 or self._buf is None:
+            return
+
+        view = self._buf[: self._n]
+        view.sort(kind="quicksort")
+        run = _dedupe_sorted(view)
+        self._n = 0
+
+        if self._cap > _MASS_AXIS_BATCH_VALUES:
+            # The scratch has grown to axis size, so release it before the
+            # merge allocates. Gating on the batch floor keeps this from firing
+            # on every one of the thousands of folds a shared-grid dataset
+            # performs, where re-faulting the buffer each time costs more than
+            # the memory it frees.
+            view = None
+            self._buf = None
+            self._cap = 0
+
+        if self._acc is None:
+            self._acc = run
+        else:
+            new = _filter_absent(self._acc, run)
+            run = None  # drop the batch before the merge allocates
+            if new.size:
+                box_a, box_b = [self._acc], [new]
+                self._acc = None
+                new = None
+                self._acc = _merge_disjoint(box_a, box_b)
+
+        self._check_limit(index)
+
+        # Record the next capacity but do NOT allocate it here. On the final
+        # fold the stream is already exhausted, so allocating would commit a
+        # whole axis-sized buffer that is never written.
+        self._cap_target = max(_MASS_AXIS_BATCH_VALUES, self._acc.size)
+        if self._cap and self._cap != self._cap_target:
+            self._buf = None
+            self._cap = 0
+
+    def _check_limit(self, index: int) -> None:
+        """Stop if the axis has outgrown ``max_length``."""
+        if self._max_length is None or self._acc is None:
+            return
+        if self._acc.size <= self._max_length:
+            return
+        raise ValueError(
+            f"Common mass axis exceeded {self._max_length:,} unique m/z values "
+            f"after {index + 1:,} of {self._total_spectra:,} spectra "
+            f"({self._acc.size:,} so far). The peak lists in this dataset do "
+            "not share m/z values, so a raw axis grows to roughly one column "
+            "per peak, which is not usable downstream. Convert with resampling "
+            "instead (it is the default; --no-resample disables it), or raise "
+            "max_mass_axis_length."
+        )
+
 
 @register_reader("imzml")
 class ImzMLReader(BaseMSIReader):
@@ -33,12 +335,16 @@ class ImzMLReader(BaseMSIReader):
             data_path: Path to the imzML file
             batch_size: Default batch size for spectrum iteration
             cache_coordinates: Whether to cache coordinates upfront
-            **kwargs: Additional arguments
+            **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``.
         """
         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")
         self.parser: Optional[ImzMLParser] = None
         self.ibd_file: Optional[Any] = None
         self.imzml_path: Optional[Path] = None
@@ -207,25 +513,46 @@ class ImzMLReader(BaseMSIReader):
         return self._common_mass_axis
 
     def _extract_continuous_mass_axis(self, parser: ImzMLParser) -> NDArray[np.float64]:
-        """Extract continuous mass axis from processed data."""
-        # For processed data, collect unique m/z values across spectra
+        """Build the common mass axis for processed-mode data.
+
+        Returns exactly what ``np.unique(np.concatenate(all_mzs))`` returned:
+        sorted, deduplicated, with the dtype following the file's mzPrecision.
+
+        This streams the file rather than collecting it. The previous
+        implementation held every spectrum's m/z array in a list, concatenated
+        that into one array, and handed the result to ``np.unique`` -- three
+        live copies of the whole m/z payload P, plus the output. Measured peak
+        was 3.40-3.51x P on data whose spectra share m/z values and 4.32-4.39x
+        P when every value is distinct, which put a hard ceiling around a
+        40 GB input on a 128 GB machine.
+
+        Here each spectrum is copied into a scratch buffer, and when that
+        buffer fills it is sorted, deduplicated, and merged into the running
+        axis. Peak memory becomes a function of the number of *unique* values
+        rather than the payload: measured 15.2-15.5 MiB, flat, for payloads
+        from 32 MiB to 16 GiB of shared-grid data, and 2.00x P in the
+        all-distinct case, which is the structural floor for an out-of-place
+        merge.
+
+        Args:
+            parser: An initialized ImzML parser.
+
+        Returns:
+            Sorted, unique m/z values across all spectra.
+
+        Raises:
+            ValueError: If no spectrum yielded any m/z values, or if
+                ``max_mass_axis_length`` is set and the axis outgrows it.
+        """
         logger.info(
             "Building common mass axis from all unique m/z values " "(processed mode)"
         )
 
         total_spectra = len(parser.coordinates)
-        all_mzs = self._collect_processed_mzs(parser, total_spectra)
-
-        if not all_mzs:
-            raise ValueError("No spectra found to build common mass axis")
-
-        return self._finalize_mass_axis(all_mzs)
-
-    def _collect_processed_mzs(
-        self, parser: ImzMLParser, total_spectra: int
-    ) -> List[NDArray[np.float64]]:
-        """Collect m/z values from all processed spectra."""
-        all_mzs: List[NDArray[np.float64]] = []
+        accumulator = _MassAxisAccumulator(
+            total_spectra, getattr(self, "max_mass_axis_length", None)
+        )
+        idx = -1
 
         with tqdm(
             total=total_spectra,
@@ -233,38 +560,18 @@ class ImzMLReader(BaseMSIReader):
             unit="spectrum",
         ) as pbar:
             for idx in range(total_spectra):
-                try:
-                    spectrum_data = parser.getspectrum(idx)
-                    if spectrum_data is None or len(spectrum_data) < 1:
-                        continue
-
-                    mzs = spectrum_data[0]
-                    if mzs.size > 0:
-                        all_mzs.append(mzs)
-                except Exception as e:
-                    logger.warning(f"Error getting spectrum {idx}: {e}")
+                mzs = _read_spectrum_mzs(parser, idx)
+                if mzs is not None:
+                    # Deliberately outside the read's try/except: a
+                    # max_mass_axis_length failure must not be swallowed and
+                    # logged as a per-spectrum warning.
+                    accumulator.add(mzs, idx)
+                mzs = None
                 pbar.update(1)
 
-        return all_mzs
-
-    def _finalize_mass_axis(
-        self, all_mzs: List[NDArray[np.float64]]
-    ) -> NDArray[np.float64]:
-        """Finalize the mass axis from collected m/z values."""
-        try:
-            combined_mzs = np.concatenate(all_mzs)
-            unique_mzs = np.unique(combined_mzs)
-
-            if unique_mzs.size == 0:
-                raise ValueError("Failed to extract any m/z values")
-
-            logger.info(
-                f"Created common mass axis with {len(unique_mzs)} unique " f"m/z values"
-            )
-            return unique_mzs
-        except Exception as e:
-            # Re-raise with more context
-            raise ValueError(f"Error creating common mass axis: {e}") from e
+        axis = accumulator.finish(idx)
+        logger.info(f"Created common mass axis with {axis.size} unique m/z values")
+        return axis
 
     def _get_spectrum_coordinates(
         self, parser: ImzMLParser, idx: int