thyra 3.2.2__tar.gz → 3.3.0__tar.gz

{thyra-3.2.2 → thyra-3.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thyra
-Version: 3.2.2
+Version: 3.3.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
@@ -81,7 +81,7 @@ for a full walkthrough, including the published example dataset
 
 ## Features
 
-- **Multiple Input Formats**: ImzML, Bruker (.d directories), Waters (.raw directories)
+- **Multiple Input Formats**: ImzML, Bruker (.d directories), Waters (.raw directories), PHI SmartSoft-TOF ToF-SIMS (.raw files)
 - **SpatialData Output**: Modern, cloud-ready format with Zarr backend
 - **Memory Efficient**: Handles large datasets (100+ GB) through streaming processing
 - **Optical Alignment**: Automatic MSI-to-optical image registration for Bruker data
@@ -107,10 +107,17 @@ thyra input.imzML output.zarr
 # Bruker data with verbose logging
 thyra data.d output.zarr -v DEBUG
 
+# PHI SmartSoft-TOF ToF-SIMS (a .raw file, not a directory)
+thyra tofsims_run.raw output.zarr
+
 # Disable resampling
 thyra input.imzML output.zarr --no-resample
 ```
 
+Thyra auto-detects the input format. Note that `.raw` is claimed by two
+vendors and resolved by shape: Waters writes a directory, PHI writes a single
+file. See [Supported Formats](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/supported-formats/).
+
 ### Python API
 
 ```python

{thyra-3.2.2 → thyra-3.3.0}/README.md

@@ -27,7 +27,7 @@ for a full walkthrough, including the published example dataset
 
 ## Features
 
-- **Multiple Input Formats**: ImzML, Bruker (.d directories), Waters (.raw directories)
+- **Multiple Input Formats**: ImzML, Bruker (.d directories), Waters (.raw directories), PHI SmartSoft-TOF ToF-SIMS (.raw files)
 - **SpatialData Output**: Modern, cloud-ready format with Zarr backend
 - **Memory Efficient**: Handles large datasets (100+ GB) through streaming processing
 - **Optical Alignment**: Automatic MSI-to-optical image registration for Bruker data
@@ -53,10 +53,17 @@ thyra input.imzML output.zarr
 # Bruker data with verbose logging
 thyra data.d output.zarr -v DEBUG
 
+# PHI SmartSoft-TOF ToF-SIMS (a .raw file, not a directory)
+thyra tofsims_run.raw output.zarr
+
 # Disable resampling
 thyra input.imzML output.zarr --no-resample
 ```
 
+Thyra auto-detects the input format. Note that `.raw` is claimed by two
+vendors and resolved by shape: Waters writes a directory, PHI writes a single
+file. See [Supported Formats](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/supported-formats/).
+
 ### Python API
 
 ```python

{thyra-3.2.2 → thyra-3.3.0}/pyproject.toml

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

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

{thyra-3.2.2 → thyra-3.3.0}/thyra/converters/spatialdata/base_spatialdata_converter.py

@@ -614,9 +614,14 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         logger.debug("Added MSI metadata to AnnData .uns: %s", sorted(uns))
 
     def _serialize_for_zarr(self, obj):
-        """Recursively convert tuples to lists for Zarr serialization."""
+        """Recursively convert tuples to lists for Zarr serialization.
+
+        Dict keys are coerced to strings: Zarr group members must be named,
+        and a non-string key otherwise fails at write time, after the whole
+        conversion has already been done.
+        """
         if isinstance(obj, dict):
-            return {k: self._serialize_for_zarr(v) for k, v in obj.items()}
+            return {str(k): self._serialize_for_zarr(v) for k, v in obj.items()}
         elif isinstance(obj, (list, tuple)):
             return [self._serialize_for_zarr(item) for item in obj]
         elif hasattr(obj, "__dict__"):
@@ -1434,11 +1439,64 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
         if self._common_mass_axis is None:
             raise ValueError("Common mass axis is not initialized")
 
+        n_channels = len(self._common_mass_axis)
+        columns: Dict[str, Any] = {"mz": self._common_mass_axis}
+        columns.update(self._validated_mass_axis_annotations())
+
         return pd.DataFrame(
-            {"mz": self._common_mass_axis},
-            index=[f"mz_{i}" for i in range(len(self._common_mass_axis))],
+            columns,
+            index=[f"mz_{i}" for i in range(n_channels)],
         )
 
+    def _validated_mass_axis_annotations(self) -> Dict[str, Any]:
+        """Reader-supplied per-channel columns that fit the axis being written.
+
+        A reader whose native axis is not m/z (flight time, drift time) can
+        keep that axis alongside ``mz`` so the conversion stays reversible.
+        Annotations whose length does not match are dropped rather than
+        raising: that is the expected outcome when resampling rebuilds the
+        axis, and it must not fail an otherwise good conversion.
+        """
+        if self._common_mass_axis is None:
+            return {}
+        n_channels = len(self._common_mass_axis)
+
+        # getattr rather than a bare call: readers predating this hook, and
+        # test doubles that do not subclass BaseMSIReader, simply have nothing
+        # to contribute and should not have to raise to say so.
+        getter = getattr(self.reader, "get_mass_axis_annotations", None)
+        if getter is None:
+            return {}
+
+        try:
+            annotations = getter()
+        except Exception as exc:  # pragma: no cover - reader-defined
+            # Format eagerly. Passing the exception itself to the logger keeps
+            # it alive inside the log record, and with it its traceback, the
+            # caller frames reachable through tb_frame.f_back, and any memmap
+            # those frames hold -- which on Windows leaves the backing file
+            # locked long after the conversion has finished.
+            detail = f"{type(exc).__name__}: {exc}"
+            logger.warning("Reader failed to supply mass axis annotations: %s", detail)
+            return {}
+
+        validated: Dict[str, Any] = {}
+        for name, values in (annotations or {}).items():
+            if name == "mz":
+                logger.warning("Ignoring mass axis annotation named 'mz'")
+                continue
+            if len(values) != n_channels:
+                logger.info(
+                    "Dropping mass axis annotation %r: %d values for a "
+                    "%d channel axis (expected when resampling rebuilds it)",
+                    name,
+                    len(values),
+                    n_channels,
+                )
+                continue
+            validated[name] = values
+        return validated
+
     def _get_pixel_index(self, x: int, y: int, z: int) -> int:
         """Calculate linear pixel index from 3D coordinates.
 

{thyra-3.2.2 → thyra-3.3.0}/thyra/converters/spatialdata/streaming_converter.py

@@ -1700,7 +1700,10 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         var_group.attrs["encoding-type"] = "dataframe"
         var_group.attrs["encoding-version"] = "0.2.0"
         var_group.attrs["_index"] = "_index"
-        var_group.attrs["column-order"] = ["mz"]
+        # A reader whose native axis is not m/z keeps that axis here too, so
+        # this route stores the same columns as the dataframe-based ones.
+        annotations = self._validated_mass_axis_annotations()
+        var_group.attrs["column-order"] = ["mz"] + sorted(annotations)
 
         mz_values = self._common_mass_axis
         if mz_values is None:
@@ -1723,6 +1726,11 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
         a.attrs["encoding-type"] = "array"
         a.attrs["encoding-version"] = "0.2.0"
 
+        for name in sorted(annotations):
+            a = var_group.create_array(name, data=np.asarray(annotations[name]))
+            a.attrs["encoding-type"] = "array"
+            a.attrs["encoding-version"] = "0.2.0"
+
         # uns (metadata)
         uns_group = table_group.create_group("uns")
         uns_group.attrs["encoding-type"] = "dict"

{thyra-3.2.2 → thyra-3.3.0}/thyra/core/base_reader.py

@@ -213,6 +213,30 @@ class BaseMSIReader(ABC):
         # Return only the valid indices and their corresponding intensities
         return indices[indices_valid], intensities[indices_valid]
 
+    def get_mass_axis_annotations(
+        self,
+    ) -> Optional[dict]:
+        """Get extra per-channel columns to store alongside the m/z axis.
+
+        Returns a mapping of column name to an array with one entry per
+        entry of :meth:`get_common_mass_axis`. These are written into the
+        table's ``var`` next to ``mz``.
+
+        This exists so a format whose native axis is not m/z can keep that
+        axis in the output. Time-of-flight instruments measure flight time
+        and derive m/z from a calibration, so storing the flight time makes
+        the conversion reversible without the reader: a later recalibration
+        can be applied to the stored times directly.
+
+        Annotations are dropped if their length does not match the axis the
+        converter actually writes, which is what happens when resampling is
+        enabled and the axis is rebuilt.
+
+        Returns:
+            Mapping of column name to per-channel values, or None.
+        """
+        return None
+
     def get_region_map(self) -> Optional[dict]:
         """Get per-pixel region mapping for multi-region datasets.
 

{thyra-3.2.2 → thyra-3.3.0}/thyra/core/registry.py

@@ -36,11 +36,12 @@ class MSIRegistry:
         self._lock = RLock()
         self._readers: Dict[str, Type[BaseMSIReader]] = {}
         self._converters: Dict[str, Type[BaseMSIConverter]] = {}
-        # Extension mapping for file-based formats
+        # Extension mapping for file-based formats. '.raw' is deliberately
+        # absent: it is claimed by both Waters and PHI and can only be
+        # resolved by inspecting the path (see _detect_raw_format).
         self._extension_to_format = {
             ".imzml": "imzml",
             ".d": "bruker",
-            ".raw": "waters",
         }
 
     def register_reader(
@@ -112,6 +113,25 @@ class MSIRegistry:
             pass
         return False
 
+    def _detect_phi_format(self, path: Path) -> bool:
+        """Check if path is a PHI SmartSoft-TOF .raw file.
+
+        PHI writes a single file whose ASCII header opens with the four-byte
+        ``SOFH`` magic. This is what distinguishes it from Waters .raw data,
+        which is a directory.
+
+        Args:
+            path: File path to check
+
+        Returns:
+            True if the file starts with the PHI SOFH magic
+        """
+        try:
+            with path.open("rb") as handle:
+                return handle.read(4) == b"SOFH"
+        except (OSError, PermissionError):
+            return False
+
     def detect_format(self, input_path: Path) -> str:
         """Detect MSI format from input path.
 
@@ -120,6 +140,7 @@ class MSIRegistry:
         - .d directories (Bruker timsTOF)
         - Folders with .dat + _poslog.txt (Bruker Rapiflex)
         - .raw directories (Waters MassLynx)
+        - .raw files (PHI SmartSoft-TOF ToF-SIMS)
         """
         if not input_path.exists():
             raise ValueError(f"Input path does not exist: {input_path}")
@@ -136,7 +157,7 @@ class MSIRegistry:
         if extension == ".d":
             return self._detect_bruker_d_format(input_path)
         if extension == ".raw":
-            return self._detect_waters_raw_format(input_path)
+            return self._detect_raw_format(input_path)
         if input_path.is_dir():
             return self._detect_directory_format(input_path)
         self._raise_unsupported_format(input_path)
@@ -152,16 +173,25 @@ class MSIRegistry:
             return bruker_format
         raise ValueError("Bruker .d directory missing analysis " f"files: {input_path}")
 
-    def _detect_waters_raw_format(self, input_path: Path) -> str:
-        """Validate and detect Waters format from .raw directory."""
-        if not input_path.is_dir():
+    def _detect_raw_format(self, input_path: Path) -> str:
+        """Resolve a .raw path to the vendor that wrote it.
+
+        Two vendors claim the extension and they are distinguished by shape:
+        Waters .raw is a directory of _FUNC*.DAT files, PHI .raw is a single
+        file whose header begins with the SOFH magic.
+        """
+        if input_path.is_dir():
+            if self._detect_waters_format(input_path):
+                return "waters"
             raise ValueError(
-                "Waters format requires .raw directory, " f"got file: {input_path}"
+                "Waters .raw directory missing " f"_FUNC*.DAT files: {input_path}"
             )
-        if self._detect_waters_format(input_path):
-            return "waters"
+        if self._detect_phi_format(input_path):
+            return "phi"
         raise ValueError(
-            "Waters .raw directory missing " f"_FUNC*.DAT files: {input_path}"
+            f"Unrecognised .raw file: {input_path}. Expected either a Waters "
+            "directory containing _FUNC*.DAT files, or a PHI SmartSoft-TOF "
+            "file beginning with the SOFH magic."
         )
 
     def _detect_directory_format(self, input_path: Path) -> str:
@@ -179,7 +209,8 @@ class MSIRegistry:
             ".imzml",
             ".d (timsTOF)",
             "folder (Rapiflex)",
-            ".raw (Waters)",
+            ".raw directory (Waters)",
+            ".raw file (PHI SmartSoft-TOF)",
         ]
         raise ValueError(
             f"Unsupported format for '{input_path}'. "
@@ -265,8 +296,7 @@ def detect_format(input_path: Path) -> str:
         input_path: Path to MSI data file or directory
 
     Returns:
-        Format name ('imzml', 'bruker', 'rapiflex',
-        or 'waters')
+        Format name ('imzml', 'bruker', 'rapiflex', 'waters', or 'phi')
     """
     return _registry.detect_format(input_path)
 

{thyra-3.2.2 → thyra-3.3.0}/thyra/metadata/extractors/__init__.py

@@ -30,12 +30,14 @@ Example usage:
 
 from .bruker_extractor import BrukerMetadataExtractor
 from .imzml_extractor import ImzMLMetadataExtractor
+from .phi_extractor import PhiMetadataExtractor
 from .waters_extractor import WatersMetadataExtractor
 
 # Public API
 __all__ = [
     "BrukerMetadataExtractor",
     "ImzMLMetadataExtractor",
+    "PhiMetadataExtractor",
     "WatersMetadataExtractor",
 ]
 
@@ -46,6 +48,7 @@ FORMAT_EXTRACTORS = {
     "tsf": BrukerMetadataExtractor,
     "tdf": BrukerMetadataExtractor,
     "waters": WatersMetadataExtractor,
+    "phi": PhiMetadataExtractor,
 }
 
 

thyra-3.3.0/thyra/metadata/extractors/phi_extractor.py

@@ -0,0 +1,178 @@
+# thyra/metadata/extractors/phi_extractor.py
+"""Metadata extractor for PHI SmartSoft-TOF ToF-SIMS data.
+
+Reads from the parsed acquisition header and the reader's aggregated event
+index, so no additional file passes are needed.
+"""
+
+import json
+import logging
+from typing import TYPE_CHECKING, Any, Dict
+
+import numpy as np
+
+from ...core.base_extractor import MetadataExtractor
+from ..types import ComprehensiveMetadata, EssentialMetadata
+
+if TYPE_CHECKING:
+    from ...readers.phi.phi_reader import PhiReader
+
+logger = logging.getLogger(__name__)
+
+
+class PhiMetadataExtractor(MetadataExtractor):
+    """PHI-specific metadata extractor.
+
+    Args:
+        reader: The :class:`PhiReader` to describe.
+    """
+
+    def __init__(self, reader: "PhiReader"):
+        """Initialise the extractor.
+
+        Args:
+            reader: The :class:`PhiReader` to describe.
+        """
+        super().__init__(reader)
+        self._reader = reader
+
+    def _extract_essential_impl(self) -> EssentialMetadata:
+        """Extract metadata needed to drive conversion."""
+        reader = self._reader
+        dimensions = reader.dimensions
+        n_x, n_y, _ = dimensions
+
+        peak_counts = reader.get_peak_counts_per_pixel()
+        assert peak_counts is not None
+        total_peaks = int(peak_counts.sum())
+        n_spectra = int(np.count_nonzero(peak_counts))
+
+        pixel_size = None
+        size_um = reader.pixel_size_um
+        if size_um:
+            pixel_size = (float(size_um), float(size_um))
+
+        return EssentialMetadata(
+            dimensions=dimensions,
+            coordinate_bounds=(0.0, float(n_x - 1), 0.0, float(n_y - 1)),
+            mass_range=reader.mass_axis.mass_range,
+            pixel_size=pixel_size,
+            n_spectra=n_spectra,
+            total_peaks=total_peaks,
+            estimated_memory_gb=(total_peaks * 2 * 8) / (1024**3),
+            source_path=str(reader.data_path),
+            coordinate_offsets=(0, 0, 0),
+            # A sparse histogram on the detector's regular time-channel grid,
+            # not a peak-picked list.
+            spectrum_type="profile spectrum",
+            peak_counts_per_pixel=peak_counts,
+        )
+
+    def _extract_comprehensive_impl(self) -> ComprehensiveMetadata:
+        """Extract full metadata including vendor-specific detail."""
+        return ComprehensiveMetadata(
+            essential=self.get_essential(),
+            format_specific=self._extract_format_specific(),
+            acquisition_params=self._extract_acquisition_params(),
+            instrument_info=self._extract_instrument_info(),
+            raw_metadata=self._extract_raw_metadata(),
+        )
+
+    def _extract_format_specific(self) -> Dict[str, Any]:
+        reader = self._reader
+        header = reader.header
+        index = reader.block_index
+        axis = reader.mass_axis
+        return {
+            "format": "PHI SmartSoft-TOF raw",
+            "raw_file_format_version": header.entries.get("RawFileFormatVersion"),
+            "header_size": header.header_size,
+            "image_pixels": header.image_pixels,
+            "n_mass_channels": len(axis),
+            "bin_size_ns": header.bin_size_ns,
+            "flight_time_range_us": (
+                header.start_flight_time_us,
+                header.stop_flight_time_us,
+            ),
+            "n_event_blocks": len(index.data_spans),
+            "n_records": index.n_records,
+            "frames_in_stream": index.n_frames,
+            # Zarr group members must be named, so the block ids are keyed
+            # as strings rather than the ints they are in the file.
+            "block_id_counts": {
+                f"block_{block_id}": int(count)
+                for block_id, count in sorted(index.block_counts.items())
+            },
+            "block_chain_complete": index.clean,
+            "mosaic_tiles": index.tile_grid,
+            "declared_tiles": header.declared_tiles,
+            "pixel_size_source": reader.pixel_size_source,
+            "raster_size_um": header.raster_size_um,
+            "raster_size_calibration": header.raster_size_calibration,
+        }
+
+    def _extract_acquisition_params(self) -> Dict[str, Any]:
+        header = self._reader.header
+        acq = header.sections.get("Acq Base", {})
+        return {
+            "polarity": header.polarity,
+            "technique": header.entries.get("Technique"),
+            "acquisition_type": header.entries.get("AcquisitionType"),
+            "n_frames": header.n_frames,
+            "msms_active": header.msms_active,
+            "primary_species": header.entries.get("AcqPrimSpecies"),
+            "primary_current_na": header.entries.get("AcqPrimCurrent(nA)"),
+            "pulse_width_ns": header.entries.get("AcqPulseWidth"),
+            "raster_pattern": acq.get("Raster Pattern"),
+            "raster_resolution": acq.get("Raster Resolution"),
+            "mass_range_amu": (header.start_mz, header.stop_mz),
+            "acquisition_date": header.entries.get("AcqFileDate"),
+        }
+
+    def _extract_instrument_info(self) -> Dict[str, Any]:
+        header = self._reader.header
+        return {
+            "vendor": "Physical Electronics (PHI)",
+            "software_version": header.entries.get("SoftwareVersion"),
+            "platform": header.entries.get("Platform"),
+            "primary_gun": header.entries.get("AcqPrimGun"),
+            "emitter": header.entries.get("LmigEmitter"),
+            "detector_scan_mode": header.entries.get("DetectorScanMode"),
+        }
+
+    def _extract_raw_metadata(self) -> Dict[str, Any]:
+        reader = self._reader
+        header = reader.header
+        axis = reader.mass_axis
+        calibration: Dict[str, Any] = {
+            "source": reader.calibration_source,
+            "mass_slope_used": axis.slope,
+            "mass_offset_used": axis.offset,
+            "header_mass_slope": header.mass_slope,
+            "header_mass_offset": header.mass_offset,
+            "header_calibrated_flag": header.entries.get("Calibrated"),
+            # JSON strings: AnnData/zarr cannot round-trip a list of dicts.
+            "acquisition_calibrants": json.dumps(
+                [
+                    {
+                        "measured_mz": c.measured_mz,
+                        "species": c.species,
+                        "theoretical_mz": c.theoretical_mz,
+                    }
+                    for c in header.calibrants
+                ]
+            ),
+        }
+        appended = reader.block_index.appended
+        if appended:
+            calibration["appended_blocks"] = json.dumps(appended)
+        # The vendor's own key names are not valid Zarr group members --
+        # 'Mass/Time' contains a forward slash -- so the header is preserved
+        # verbatim as JSON rather than being mangled into a group hierarchy.
+        return {
+            "header_entries": json.dumps(dict(header.entries)),
+            "header_sections": json.dumps(
+                {k: dict(v) for k, v in header.sections.items()}
+            ),
+            "calibration": calibration,
+        }

{thyra-3.2.2 → thyra-3.3.0}/thyra/readers/__init__.py

@@ -5,12 +5,17 @@ This package provides reader implementations for different MSI data formats:
 - ImzML: Open format for MSI data
 - Bruker: timsTOF and Rapiflex data
 - Waters: MassLynx .raw imaging data
+- PHI: SmartSoft-TOF .raw ToF-SIMS data
 
 Reader organization:
 - bruker/: All Bruker formats (timsTOF, Rapiflex)
 - imzml/: ImzML format reader
 - waters/: Waters .raw format reader (native DLL via ctypes)
+- phi/: PHI SmartSoft-TOF .raw reader (pure Python, no vendor SDK)
+
+Note that ``.raw`` is claimed by two vendors: Waters stores a directory,
+PHI a single file. See :meth:`thyra.core.registry.MSIRegistry.detect_format`.
 """
 
 # Import readers to trigger registration
-from . import bruker, imzml, waters  # noqa: F401
+from . import bruker, imzml, phi, waters  # noqa: F401

thyra-3.3.0/thyra/readers/phi/__init__.py

@@ -0,0 +1,27 @@
+# thyra/readers/phi/__init__.py
+"""PHI SmartSoft-TOF MSI reader implementation.
+
+Reads ToF-SIMS imaging data from PHI (Physical Electronics) nanoTOF
+instruments, stored as a single ``.raw`` file holding an ASCII acquisition
+header followed by a block-structured stream of individual ion events.
+
+No vendor SDK or native library is required.
+"""
+
+from .event_stream import BlockIndex, DataSpan, iter_event_batches, scan_blocks
+from .mass_axis import PhiMassAxis, build_mass_axis
+from .phi_header import Calibrant, PhiHeader, parse_phi_header
+from .phi_reader import PhiReader
+
+__all__ = [
+    "BlockIndex",
+    "Calibrant",
+    "DataSpan",
+    "PhiHeader",
+    "PhiMassAxis",
+    "PhiReader",
+    "build_mass_axis",
+    "iter_event_batches",
+    "parse_phi_header",
+    "scan_blocks",
+]