thyra 4.3.1__tar.gz → 4.3.3__tar.gz

{thyra-4.3.1 → thyra-4.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: thyra
-Version: 4.3.1
+Version: 4.3.3
 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-4.3.1 → thyra-4.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thyra"
-version = "4.3.1"
+version = "4.3.3"
 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-4.3.1 → thyra-4.3.3}/thyra/__init__.py

@@ -67,7 +67,7 @@ warnings.filterwarnings(
     category=FutureWarning,
 )
 
-__version__ = "4.3.1"
+__version__ = "4.3.3"
 
 #: Public name -> the module that defines it, imported on first access.
 _LAZY_ATTRS = {

{thyra-4.3.1 → thyra-4.3.3}/thyra/convert.py

@@ -358,9 +358,12 @@ def _determine_pixel_size(
     essential_metadata = reader.get_essential_metadata()
 
     if essential_metadata.pixel_size is None:
-        logger.error("Pixel size not found in metadata")
-        logger.error("Use --pixel-size parameter (e.g., --pixel-size 25)")
-        raise ConversionRefused("Pixel size not found in metadata")
+        # Said once: the refusal is logged where it is caught. Logging it
+        # here as well printed the same line twice.
+        raise ConversionRefused(
+            "Pixel size not found in metadata. Pass it with --pixel-size "
+            "(for example --pixel-size 25)."
+        )
 
     final_pixel_size = essential_metadata.pixel_size[0]  # Use X size
     logger.info(f"Detected pixel size: {final_pixel_size:.1f} um")

{thyra-4.3.1 → thyra-4.3.3}/thyra/converters/spatialdata/optical_image.py

@@ -126,7 +126,7 @@ from ._chunking import image_chunks
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from ...alignment.teaching_points import RegionMapping
-    from ...core.base_reader import BaseMSIReader
+    from ...core.base_reader import BaseMSIReader, OpticalImageLabel
 
 logger = logging.getLogger(__name__)
 
@@ -944,6 +944,11 @@ def _calc_optical_scale_factors(
     return factors
 
 
+def _clean_stem(stem: str) -> str:
+    """A file stem made fit for an element name: lowercase, at most 30 long."""
+    return stem.lower().replace(" ", "_").replace("-", "_")[:30]
+
+
 class OpticalImages:
     """The optical images of one conversion: alignment, declaration, streaming.
 
@@ -1459,9 +1464,11 @@ class OpticalImages:
             images: The store's images, to add the placeholder to
         """
         # Generate a clean name for the image layer
-        image_name = self._element_name(image_path)
+        label = self._reader_label(image_path)
+        image_name = self._element_name(image_path, label)
+        source_file = label.source_file if label is not None else image_path.name
 
-        logger.info(f"Loading optical image: {image_path.name} as '{image_name}'")
+        logger.info(f"Loading optical image: {source_file} as '{image_name}'")
 
         # Only the page header is read here. The pixels never enter this
         # process whole: the element is declared to SpatialData as a lazy
@@ -1584,8 +1591,10 @@ class OpticalImages:
         # rewrites the stem (_0000 -> highres, and a stem over 30
         # characters is truncated), and the alignment image is only
         # distinguishable by its transform, and only when the alignment
-        # was applied. Recorded here, written by the root attrs.
-        self._sources[image_name] = image_path.name
+        # was applied. Recorded here, written by the root attrs. For an
+        # image a reader copied out of a container, the member it came
+        # from, not the copy.
+        self._sources[image_name] = source_file
         if is_primary:
             self._alignment_element = image_name
 
@@ -1688,18 +1697,39 @@ class OpticalImages:
             "global": {**systems["global"], "reference_element": None},
         }
 
-    def _element_name(self, image_path: Path) -> str:
+    def _reader_label(self, image_path: Path) -> Optional[OpticalImageLabel]:
+        """The reader's name for an image it copied out of its source.
+
+        Asked for with ``getattr`` for the reason
+        :meth:`_adopt_reader_primary_optical` gives: a reader here need not
+        inherit from ``BaseMSIReader``.
+        """
+        resolve = getattr(self.reader, "get_optical_image_label", None)
+        if not callable(resolve):
+            return None
+        label: Optional[OpticalImageLabel] = resolve(image_path)
+        return label
+
+    def _element_name(
+        self, image_path: Path, label: Optional[OpticalImageLabel] = None
+    ) -> str:
         """Generate a clean name for an optical image layer.
 
         The suffix is dropped, so the same acquisition exported as a .tif or
-        a .jpg lands under the same element name.
+        a .jpg lands under the same element name. The ``_0000`` / ``_0001``
+        rule is for files named by the acquisition software; an image a
+        reader copied out of a container is named by the reader's label.
 
         Args:
             image_path: Path to the optical image
+            label: The reader's name for the image, if it gave one.
 
         Returns:
             Clean name for the image layer (e.g., 'optical_0000', 'optical_deriv')
         """
+        if label is not None:
+            return f"{self.dataset_id}_optical_{_clean_stem(label.name)}"
+
         stem = image_path.stem.lower()
 
         # Extract meaningful suffix from filename
@@ -1710,11 +1740,7 @@ class OpticalImages:
         elif "deriv" in stem:
             suffix = "overview"
         else:
-            # Use stem with special chars replaced
-            suffix = stem.replace(" ", "_").replace("-", "_")
-            # Truncate if too long
-            if len(suffix) > 30:
-                suffix = suffix[:30]
+            suffix = _clean_stem(stem)
 
         return f"{self.dataset_id}_optical_{suffix}"
 

{thyra-4.3.1 → thyra-4.3.3}/thyra/core/base_reader.py

@@ -52,7 +52,16 @@ for all seven readers at once, so the next change to it is a visible one.
 import logging
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import TYPE_CHECKING, Dict, Generator, List, Optional, Tuple, Union
+from typing import (
+    TYPE_CHECKING,
+    Dict,
+    Generator,
+    List,
+    NamedTuple,
+    Optional,
+    Tuple,
+    Union,
+)
 
 import numpy as np
 from numpy.typing import NDArray
@@ -70,6 +79,22 @@ from .mass_axis import validate_max_mass_axis_length
 logger = logging.getLogger(__name__)
 
 
+class OpticalImageLabel(NamedTuple):
+    """What a store calls an optical image whose file name is not the source's.
+
+    A reader that copies images out of a container hands the converter files
+    it named itself. Their names say nothing, and the name rule written for
+    vendor folders (``_0000`` is the high resolution scan) would read meaning
+    into them.
+    """
+
+    name: str
+    """The element name after ``<dataset_id>_optical_``."""
+
+    source_file: str
+    """What the store records the element came from."""
+
+
 class BaseMSIReader(ABC):
     """Abstract base class for reading MSI data formats."""
 
@@ -169,6 +194,22 @@ class BaseMSIReader(ABC):
         """
         return None
 
+    def get_optical_image_label(self, path: Path) -> Optional[OpticalImageLabel]:
+        """Name an optical image this reader copied out of its source.
+
+        Default implementation returns None: the file is the source's own,
+        and its name is what the store is named after. Override alongside
+        :meth:`get_optical_image_paths` when the reader names the files.
+
+        Args:
+            path: One of the paths :meth:`get_optical_image_paths` returned.
+
+        Returns:
+            The element name and the source file to record, or None to name
+            the element after the file.
+        """
+        return None
+
     @abstractmethod
     def get_common_mass_axis(self) -> NDArray[np.float64]:
         """Return the common mass axis for all spectra.

{thyra-4.3.1 → thyra-4.3.3}/thyra/metadata/extractors/imzml_extractor.py

@@ -10,7 +10,7 @@ from pyimzml.ImzMLParser import ImzMLParser
 
 from ...core.base_extractor import MetadataExtractor
 from ...errors import ConversionRefused
-from ...utils.imzml_coordinate_base import coordinate_bases
+from ...utils.imzml_coordinate_base import coordinate_bases, recorded_offsets
 from ...utils.pyimzml_direct import read_spectrum_mzs_only
 from ..constants import (
     BinaryDataType,
@@ -159,6 +159,138 @@ def _family_from_model_text(text: str) -> Optional[str]:
     return None
 
 
+def instrument_info_from_configurations(configs: List[Any]) -> Dict[str, Any]:
+    """Instrument model, serial number, analyzer and family of a run.
+
+    ``configs`` are instrument configurations shaped as pyimzml parses
+    them: each has ``param_by_accession`` and ``param_by_name`` dicts, a
+    valueless term reads as ``True``, and ``components`` lists objects with
+    a ``type`` and their own ``param_by_accession``. The imzML extractor
+    passes pyimzml's own; the mzPeak extractor builds the same shape from
+    the archive's JSON.
+
+    Returns:
+        ``instrument_model``, ``instrument_serial_number``, ``analyzer`` and
+        ``instrument_type``, each only when the configurations state it.
+    """
+    info: Dict[str, Any] = {}
+    if not configs:
+        return info
+
+    model = _instrument_model(configs)
+    if model:
+        info["instrument_model"] = model
+
+    serial = _config_param(configs, "MS:1000529")
+    if isinstance(serial, str) and serial.strip():
+        info["instrument_serial_number"] = serial.strip()
+
+    analyzer_accession = _analyzer_accession(configs)
+    if analyzer_accession is not None:
+        info["analyzer"] = ONTOLOGY.terms[analyzer_accession][0]
+
+    family = _analyzer_family(configs, analyzer_accession, model)
+    if family is not None:
+        info["instrument_type"] = family
+
+    return info
+
+
+def _config_param(configs: List[Any], accession: str) -> Any:
+    """The first value any configuration declares for ``accession``."""
+    for config in configs:
+        params = getattr(config, "param_by_accession", None)
+        if isinstance(params, dict) and accession in params:
+            return params[accession]
+    return None
+
+
+def _instrument_model(configs: List[Any]) -> Optional[str]:
+    """The declared instrument model, from the shape the exporter chose.
+
+    Vendors write the model two ways: generic ``MS:1000031 instrument
+    model`` carrying the name as free text, or the model's own child term
+    as a valueless flag (``MS:1001549 solariX``, ``MS:1003124 timsTOF
+    fleX``).  The explicit value wins; a known model accession resolves
+    through the shipped ontology table; and a term newer than the table is
+    still usable when its *name* identifies a family.
+    """
+    value = _config_param(configs, "MS:1000031")
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+
+    for config in configs:
+        params = getattr(config, "param_by_accession", None)
+        if not isinstance(params, dict):
+            continue
+        for accession in params:
+            if accession in _MODEL_FAMILIES:
+                return ONTOLOGY.terms[accession][0]
+
+    for config in configs:
+        params = getattr(config, "param_by_name", None)
+        if not isinstance(params, dict):
+            continue
+        for name, value in params.items():
+            if (
+                isinstance(name, str)
+                and value is True
+                and _family_from_model_text(name) is not None
+            ):
+                return name
+
+    return None
+
+
+def _analyzer_accession(configs: List[Any]) -> Optional[str]:
+    """The highest-priority analyzer term declared on any componentList."""
+    declared: set = set()
+    for config in configs:
+        for component in getattr(config, "components", None) or []:
+            if getattr(component, "type", None) != "analyzer":
+                continue
+            params = getattr(component, "param_by_accession", None)
+            if isinstance(params, dict):
+                declared.update(params)
+
+    for accession in _ANALYZER_ACCESSIONS:
+        if accession in declared:
+            return accession
+    return None
+
+
+def _analyzer_family(
+    configs: List[Any],
+    analyzer_accession: Optional[str],
+    model: Optional[str],
+) -> Optional[str]:
+    """Resolve the axis family, preferring the analyzer declaration.
+
+    The analyzer cvParam states the physics outright, so it outranks the
+    model term, which outranks a substring match on free-form model text.
+    A file that declares none of the three resolves to ``None``.
+    """
+    if analyzer_accession in _ANALYZER_FAMILIES:
+        return _ANALYZER_FAMILIES[analyzer_accession]
+    if analyzer_accession is not None:
+        # A recognised analyzer outside the family table (TOF, ion trap)
+        # is a real declaration; do not second-guess it from the model.
+        return None
+
+    for config in configs:
+        params = getattr(config, "param_by_accession", None)
+        if not isinstance(params, dict):
+            continue
+        for accession in params:
+            family = _MODEL_FAMILIES.get(accession)
+            if family is not None:
+                return family
+
+    if model is not None:
+        return _family_from_model_text(model)
+    return None
+
+
 class ImzMLMetadataExtractor(MetadataExtractor):
     """ImzML-specific metadata extractor with optimized two-phase extraction."""
 
@@ -220,8 +352,11 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             # store can say where its origin came from: the converter
             # writes it to coordinate_systems.global.coordinate_offsets_px.
             # (1, 1, 1) for an ordinary 1-based file, (0, 0, ...) for a
-            # 0-based one -- see _coordinate_bases() (issue #244).
-            coordinate_offsets=self._coordinate_bases(coords),
+            # 0-based one -- see _coordinate_bases() (issue #244). z is 0
+            # when the file states none (D30).
+            coordinate_offsets=recorded_offsets(
+                self._coordinate_bases(coords), coords[:, 2], self.imzml_path
+            ),
             spectrum_type=spectrum_type,
         )
 
@@ -824,29 +959,12 @@ class ImzMLMetadataExtractor(MetadataExtractor):
           chain matches on (``"FT-ICR"`` / ``"Orbitrap"``), when the analyzer
           or the model resolves to a family the chain distinguishes.  Absent
           otherwise: an unstated analyzer stays unstated.
-        """
-        info: Dict[str, Any] = {}
-        configs = self._instrument_configurations()
-        if not configs:
-            return info
-
-        model = self._instrument_model(configs)
-        if model:
-            info["instrument_model"] = model
-
-        serial = self._config_param(configs, "MS:1000529")
-        if isinstance(serial, str) and serial.strip():
-            info["instrument_serial_number"] = serial.strip()
-
-        analyzer_accession = self._analyzer_accession(configs)
-        if analyzer_accession is not None:
-            info["analyzer"] = ONTOLOGY.terms[analyzer_accession][0]
-
-        family = self._analyzer_family(configs, analyzer_accession, model)
-        if family is not None:
-            info["instrument_type"] = family
 
-        return info
+        The rules live in :func:`instrument_info_from_configurations`, which
+        the mzPeak extractor calls too, so an archive and the imzML it was
+        made from resolve to the same instrument.
+        """
+        return instrument_info_from_configurations(self._instrument_configurations())
 
     def _instrument_configurations(self) -> List[Any]:
         """The parsed instrumentConfiguration ParamGroups, in document order."""
@@ -856,100 +974,6 @@ class ImzMLMetadataExtractor(MetadataExtractor):
             return []
         return list(configs.values())
 
-    @staticmethod
-    def _config_param(configs: List[Any], accession: str) -> Any:
-        """The first value any configuration declares for ``accession``."""
-        for config in configs:
-            params = getattr(config, "param_by_accession", None)
-            if isinstance(params, dict) and accession in params:
-                return params[accession]
-        return None
-
-    def _instrument_model(self, configs: List[Any]) -> Optional[str]:
-        """The declared instrument model, from the shape the exporter chose.
-
-        Vendors write the model two ways: generic ``MS:1000031 instrument
-        model`` carrying the name as free text, or the model's own child term
-        as a valueless flag (``MS:1001549 solariX``, ``MS:1003124 timsTOF
-        fleX``).  The explicit value wins; a known model accession resolves
-        through the shipped ontology table; and a term newer than the table is
-        still usable when its *name* identifies a family.
-        """
-        value = self._config_param(configs, "MS:1000031")
-        if isinstance(value, str) and value.strip():
-            return value.strip()
-
-        for config in configs:
-            params = getattr(config, "param_by_accession", None)
-            if not isinstance(params, dict):
-                continue
-            for accession in params:
-                if accession in _MODEL_FAMILIES:
-                    return ONTOLOGY.terms[accession][0]
-
-        for config in configs:
-            params = getattr(config, "param_by_name", None)
-            if not isinstance(params, dict):
-                continue
-            for name, value in params.items():
-                if (
-                    isinstance(name, str)
-                    and value is True
-                    and _family_from_model_text(name) is not None
-                ):
-                    return name
-
-        return None
-
-    @staticmethod
-    def _analyzer_accession(configs: List[Any]) -> Optional[str]:
-        """The highest-priority analyzer term declared on any componentList."""
-        declared: set = set()
-        for config in configs:
-            for component in getattr(config, "components", None) or []:
-                if getattr(component, "type", None) != "analyzer":
-                    continue
-                params = getattr(component, "param_by_accession", None)
-                if isinstance(params, dict):
-                    declared.update(params)
-
-        for accession in _ANALYZER_ACCESSIONS:
-            if accession in declared:
-                return accession
-        return None
-
-    def _analyzer_family(
-        self,
-        configs: List[Any],
-        analyzer_accession: Optional[str],
-        model: Optional[str],
-    ) -> Optional[str]:
-        """Resolve the axis family, preferring the analyzer declaration.
-
-        The analyzer cvParam states the physics outright, so it outranks the
-        model term, which outranks a substring match on free-form model text.
-        A file that declares none of the three resolves to ``None``.
-        """
-        if analyzer_accession in _ANALYZER_FAMILIES:
-            return _ANALYZER_FAMILIES[analyzer_accession]
-        if analyzer_accession is not None:
-            # A recognised analyzer outside the family table (TOF, ion trap)
-            # is a real declaration; do not second-guess it from the model.
-            return None
-
-        for config in configs:
-            params = getattr(config, "param_by_accession", None)
-            if not isinstance(params, dict):
-                continue
-            for accession in params:
-                family = _MODEL_FAMILIES.get(accession)
-                if family is not None:
-                    return family
-
-        if model is not None:
-            return _family_from_model_text(model)
-        return None
-
     def _extract_raw_metadata(self) -> Dict[str, Any]:
         """Extract raw metadata from imzmldict and spectrum cvParams."""
         raw_metadata = {}