thyra 4.0.0__tar.gz → 4.2.0__tar.gz

thyra-4.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: thyra
+Version: 4.2.0
+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
+Project-URL: Documentation, https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/
+Project-URL: Bug Tracker, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/issues
+Project-URL: Discussions, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/discussions
+Project-URL: Changelog, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CHANGELOG.md
+Project-URL: Contributing, https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/contributing/
+Author-email: Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>
+Maintainer-email: Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,bruker,data-conversion,imaging,imzml,mass-spectrometry,msi,omics,scientific-computing,spatial-omics,spatialdata,zarr
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: File Formats
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.12
+Requires-Dist: anndata<0.14,>=0.13.2
+Requires-Dist: click<9,>=8.1
+Requires-Dist: dask<2026.8,>=2026.3.0
+Requires-Dist: defusedxml>=0.7.1
+Requires-Dist: geopandas>=0.9.0
+Requires-Dist: imagecodecs>=2024.1.1
+Requires-Dist: numpy<3,>=2.0.0
+Requires-Dist: ome-zarr<0.19,>=0.16.0
+Requires-Dist: pandas<4,>=2.0.0
+Requires-Dist: pillow>=10.1
+Requires-Dist: psutil>=5.0.0
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyimzml>=1.4.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: shapely>=2.0.0
+Requires-Dist: spatialdata<0.9,>=0.8.0
+Requires-Dist: tifffile>=2026.5.2
+Requires-Dist: tqdm>=4.50.0
+Requires-Dist: xarray>=2024.10.0
+Requires-Dist: zarr<3.5,>=3.4.0
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/thyra-logotype.svg" alt="Thyra" width="420">
+</p>
+
+[![Tests](https://img.shields.io/github/actions/workflow/status/M4i-Imaging-Mass-Spectrometry/thyra/tests.yml?branch=main&logo=github)](https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/thyra?logo=pypi&logoColor=white)](https://pypi.org/project/thyra/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/notebooks/Thyra_Validation_Workflow.ipynb)
+
+**Thyra converts imaging mass spectrometry data into one open format.** It
+reads the files your instrument writes (Bruker, Waters, PHI, or imzML from any
+vendor) and saves them in [SpatialData](https://spatialdata.scverse.org/),
+which analysis and viewing tools can read. You do not need to know how to
+program.
+
+**[Documentation](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)** | [Install](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/install/) | [Your first conversion](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/getting-started/) | [Tutorial](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/tutorial/) | [Technical reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/technical-reference/)
+
+![The total ion current and two ion images of a sagittal mouse brain section, converted with Thyra](docs/assets/mouse-brain-ion-images.webp)
+
+<sub>A sagittal mouse brain section converted with Thyra: the total ion current
+and two ion images. MALDI-MSI data from
+[10.5281/zenodo.18326569](https://doi.org/10.5281/zenodo.18326569),
+CC-BY-4.0.</sub>
+
+## Quick start
+
+```bash
+uv tool install --python 3.13 thyra                     # or: pip install thyra (Python 3.12 to 3.14)
+thyra-example-data example_data/synthetic_brain.imzML   # makes a small example dataset
+thyra example_data/synthetic_brain.imzML example_data/synthetic_brain.zarr
+```
+
+New to the terminal or to uv? The
+[Install](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/install/) page
+walks you through every step. To try Thyra with nothing installed, open the
+[notebook in Google Colab](https://colab.research.google.com/github/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/notebooks/Thyra_Validation_Workflow.ipynb).
+The [Tutorial](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/tutorial/)
+also converts the published example dataset
+([10.5281/zenodo.18326569](https://doi.org/10.5281/zenodo.18326569)).
+
+## What you can convert
+
+| Your instrument | Point Thyra at |
+|---|---|
+| Bruker timsTOF or solariX | the folder ending in `.d` |
+| Bruker rapifleX | the acquisition folder |
+| Waters (MassLynx) | the folder ending in `.raw` |
+| PHI nanoTOF (ToF-SIMS) | the file ending in `.raw` |
+| Any instrument that exports imzML | the `.imzML` file, with its `.ibd` file next to it |
+| mzPeak (experimental) | the `.mzpeak` file |
+
+Thyra reads timsTOF and Waters data on Windows and Linux; everything else
+also works on macOS. Shimadzu support is in development: until then, export
+imzML from IMAGEREVEAL MS.
+
+PHI mosaic, MS/MS and depth-profiling acquisitions have so far been tested
+only on synthetic files. If you have real data in those modes, please get in
+touch.
+
+## What you get
+
+One folder ending in `.zarr`, holding:
+
+- the spectrum of every pixel, on one shared m/z axis
+- an image of the total ion current (TIC)
+- the optical image of the slide, when the acquisition has one
+- ion mobility and MS/MS data from Bruker timsTOF, when the acquisition has them
+- a validated description of the acquisition, ready for METASPACE
+
+Thyra handles datasets larger than your computer's memory, slides with
+several regions, and 3D data.
+
+## From Python
+
+```python
+from thyra import convert_msi
+import spatialdata as sd
+
+convert_msi("data/sample.imzML", "output/sample.zarr")
+
+sdata = sd.read_zarr("output/sample.zarr")
+table = sdata.tables["msi_dataset_z0"]  # one row per pixel, one column per m/z bin
+```
+
+The acquisition description has its own commands:
+
+```bash
+thyra metadata raw_data.d                                # describe a dataset without converting it
+thyra validate output.zarr                               # check a result against the schema
+thyra export-metaspace output.zarr --merge sample.json   # METASPACE submission file
+```
+
+Every option, format and output detail is in the
+[Technical reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/technical-reference/).
+
+## Development
+
+```bash
+git clone https://github.com/M4i-Imaging-Mass-Spectrometry/thyra.git
+cd thyra
+uv sync
+uv run pre-commit install
+uv run pytest
+```
+
+CI runs the same hooks on every pull request. Installing them locally shows
+you a failure before you push.
+
+## Contributing
+
+See [CONTRIBUTING.md](docs/contributing.md) for guidelines.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).
+
+## Citation
+
+```bibtex
+@software{thyra2024,
+  title = {Thyra: Modern Mass Spectrometry Imaging Data Conversion},
+  author = {Visvikis, Theodoros},
+  year = {2024},
+  url = {https://github.com/M4i-Imaging-Mass-Spectrometry/thyra}
+}
+```
+
+## Acknowledgments
+
+- Built with [SpatialData](https://spatialdata.scverse.org/) ecosystem
+- Powered by [Zarr](https://zarr.readthedocs.io/) for efficient storage
+- Uses [pyimzML](https://github.com/alexandrovteam/pyimzML) for ImzML parsing
+
+### Visual identity
+
+Logomark and logotype designed by **Nepsis Scriptorium**.
+
+[![Instagram @nepsis.scriptorium](https://img.shields.io/badge/Instagram-%40nepsis.scriptorium-E4405F?logo=instagram&logoColor=white)](https://www.instagram.com/nepsis.scriptorium/)
+[![Email nepsisscriptorium@gmail.com](https://img.shields.io/badge/Email-nepsisscriptorium%40gmail.com-EA4335?logo=gmail&logoColor=white)](mailto:nepsisscriptorium@gmail.com)

thyra-4.2.0/README.md

@@ -0,0 +1,142 @@
+<p align="center">
+  <img src="docs/assets/thyra-logotype.svg" alt="Thyra" width="420">
+</p>
+
+[![Tests](https://img.shields.io/github/actions/workflow/status/M4i-Imaging-Mass-Spectrometry/thyra/tests.yml?branch=main&logo=github)](https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/thyra?logo=pypi&logoColor=white)](https://pypi.org/project/thyra/)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/notebooks/Thyra_Validation_Workflow.ipynb)
+
+**Thyra converts imaging mass spectrometry data into one open format.** It
+reads the files your instrument writes (Bruker, Waters, PHI, or imzML from any
+vendor) and saves them in [SpatialData](https://spatialdata.scverse.org/),
+which analysis and viewing tools can read. You do not need to know how to
+program.
+
+**[Documentation](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)** | [Install](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/install/) | [Your first conversion](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/getting-started/) | [Tutorial](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/tutorial/) | [Technical reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/technical-reference/)
+
+![The total ion current and two ion images of a sagittal mouse brain section, converted with Thyra](docs/assets/mouse-brain-ion-images.webp)
+
+<sub>A sagittal mouse brain section converted with Thyra: the total ion current
+and two ion images. MALDI-MSI data from
+[10.5281/zenodo.18326569](https://doi.org/10.5281/zenodo.18326569),
+CC-BY-4.0.</sub>
+
+## Quick start
+
+```bash
+uv tool install --python 3.13 thyra                     # or: pip install thyra (Python 3.12 to 3.14)
+thyra-example-data example_data/synthetic_brain.imzML   # makes a small example dataset
+thyra example_data/synthetic_brain.imzML example_data/synthetic_brain.zarr
+```
+
+New to the terminal or to uv? The
+[Install](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/install/) page
+walks you through every step. To try Thyra with nothing installed, open the
+[notebook in Google Colab](https://colab.research.google.com/github/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/notebooks/Thyra_Validation_Workflow.ipynb).
+The [Tutorial](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/tutorial/)
+also converts the published example dataset
+([10.5281/zenodo.18326569](https://doi.org/10.5281/zenodo.18326569)).
+
+## What you can convert
+
+| Your instrument | Point Thyra at |
+|---|---|
+| Bruker timsTOF or solariX | the folder ending in `.d` |
+| Bruker rapifleX | the acquisition folder |
+| Waters (MassLynx) | the folder ending in `.raw` |
+| PHI nanoTOF (ToF-SIMS) | the file ending in `.raw` |
+| Any instrument that exports imzML | the `.imzML` file, with its `.ibd` file next to it |
+| mzPeak (experimental) | the `.mzpeak` file |
+
+Thyra reads timsTOF and Waters data on Windows and Linux; everything else
+also works on macOS. Shimadzu support is in development: until then, export
+imzML from IMAGEREVEAL MS.
+
+PHI mosaic, MS/MS and depth-profiling acquisitions have so far been tested
+only on synthetic files. If you have real data in those modes, please get in
+touch.
+
+## What you get
+
+One folder ending in `.zarr`, holding:
+
+- the spectrum of every pixel, on one shared m/z axis
+- an image of the total ion current (TIC)
+- the optical image of the slide, when the acquisition has one
+- ion mobility and MS/MS data from Bruker timsTOF, when the acquisition has them
+- a validated description of the acquisition, ready for METASPACE
+
+Thyra handles datasets larger than your computer's memory, slides with
+several regions, and 3D data.
+
+## From Python
+
+```python
+from thyra import convert_msi
+import spatialdata as sd
+
+convert_msi("data/sample.imzML", "output/sample.zarr")
+
+sdata = sd.read_zarr("output/sample.zarr")
+table = sdata.tables["msi_dataset_z0"]  # one row per pixel, one column per m/z bin
+```
+
+The acquisition description has its own commands:
+
+```bash
+thyra metadata raw_data.d                                # describe a dataset without converting it
+thyra validate output.zarr                               # check a result against the schema
+thyra export-metaspace output.zarr --merge sample.json   # METASPACE submission file
+```
+
+Every option, format and output detail is in the
+[Technical reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/technical-reference/).
+
+## Development
+
+```bash
+git clone https://github.com/M4i-Imaging-Mass-Spectrometry/thyra.git
+cd thyra
+uv sync
+uv run pre-commit install
+uv run pytest
+```
+
+CI runs the same hooks on every pull request. Installing them locally shows
+you a failure before you push.
+
+## Contributing
+
+See [CONTRIBUTING.md](docs/contributing.md) for guidelines.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).
+
+## Citation
+
+```bibtex
+@software{thyra2024,
+  title = {Thyra: Modern Mass Spectrometry Imaging Data Conversion},
+  author = {Visvikis, Theodoros},
+  year = {2024},
+  url = {https://github.com/M4i-Imaging-Mass-Spectrometry/thyra}
+}
+```
+
+## Acknowledgments
+
+- Built with [SpatialData](https://spatialdata.scverse.org/) ecosystem
+- Powered by [Zarr](https://zarr.readthedocs.io/) for efficient storage
+- Uses [pyimzML](https://github.com/alexandrovteam/pyimzML) for ImzML parsing
+
+### Visual identity
+
+Logomark and logotype designed by **Nepsis Scriptorium**.
+
+[![Instagram @nepsis.scriptorium](https://img.shields.io/badge/Instagram-%40nepsis.scriptorium-E4405F?logo=instagram&logoColor=white)](https://www.instagram.com/nepsis.scriptorium/)
+[![Email nepsisscriptorium@gmail.com](https://img.shields.io/badge/Email-nepsisscriptorium%40gmail.com-EA4335?logo=gmail&logoColor=white)](mailto:nepsisscriptorium@gmail.com)

{thyra-4.0.0 → thyra-4.2.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thyra"
-version = "4.0.0"
+version = "4.2.0"
 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" }]
 license = "MIT"
 license-files = ["LICENSE"]
 readme = "README.md"
-requires-python = ">=3.12, <3.14"
+requires-python = ">=3.12, <3.15"
 keywords = [
     "mass-spectrometry",
     "imaging",
@@ -34,6 +34,7 @@ classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Bio-Informatics",
     "Topic :: Scientific/Engineering :: Information Analysis",
     "Topic :: Scientific/Engineering :: Medical Science Apps.",
@@ -329,7 +330,7 @@ dev = [
 ]
 docs = [
     "mkdocs>=1.6, <2",
-    "mkdocs-material>=9.5",
+    "mkdocs-material>=9.7",           # navigation.path, content.tooltips
     "mkdocs-jupyter>=0.25, <1",       # renders docs/*.ipynb as site pages
     "mkdocstrings[python]>=0.27",
 ]
@@ -480,6 +481,12 @@ module = [
 ignore_missing_imports = true
 
 
+[tool.black]
+# Black otherwise infers every version in `requires-python` and, whenever the
+# newest is above the interpreter running it, prints a warning on each run.
+# Formatting follows the oldest target either way, so this changes no output.
+target-version = ["py312"]
+
 [tool.isort]
 profile = "black"
 multi_line_output = 3

thyra-4.2.0/thyra/__init__.py

@@ -0,0 +1,110 @@
+"""MSIConverter - Convert Mass Spectrometry Imaging data to SpatialData/Zarr format.
+
+This package provides tools for converting MSI data from various formats
+(ImzML, Bruker) into the modern SpatialData/Zarr format with automatic
+pixel size detection.
+
+**Nothing heavy is imported here** (issue #381). This module used to import
+the reader and converter packages for their registration side effects and
+bind the public API eagerly, which cost 3.5 s and 3,580 modules --
+``spatialdata``, ``dask`` and ``anndata`` among them -- before any caller
+did any work. A parent package always initialises first, so that was also
+the price of ``import thyra.metadata.schema``: the metadata layer depends
+on none of it in source (every reference from ``thyra/metadata/`` to the
+converter is ``TYPE_CHECKING``-guarded) and could not be used without it.
+
+Two changes replaced it. The registry imports a format's module the first
+time that format is looked up, from the table in
+:mod:`thyra.core.registry`, so registration no longer needs a front door.
+The public names below resolve on first attribute access (:pep:`562`), so
+``thyra.convert_msi`` and ``from thyra import preview_msi`` still work and
+still cost what they always did -- paid by the caller who asks for them.
+
+``__version__`` stays an ordinary module attribute rather than joining
+them. It is what ``python-semantic-release`` rewrites at release
+(``version_variables`` in ``pyproject.toml``), and
+``thyra.metadata.schema.builder`` reads it through ``from thyra import
+__version__`` while building a document -- which is only affordable
+because reaching this module is now free.
+
+**Where a broken install now fails.** Issue #310 made ``spatialdata`` and
+``defusedxml`` abort ``import thyra``, because both had been treated as
+optional and the branch that fired swallowed the cause: the user's first
+sign of trouble was ``No converter for format 'spatialdata'. Available:
+[]``, naming no package and no reason. The swallowing is still gone and
+nothing rewrites either ImportError; what moved is where it surfaces.
+``spatialdata`` is imported by :mod:`thyra.converters`, which a conversion
+reaches while resolving its output format, before it opens the input;
+``defusedxml`` by ``thyra.readers.bruker.mis_parser``, which every Bruker
+path reaches during format detection. Each raises at its own import with
+its own traceback. Checking for them here instead would have cost the
+metadata layer the very thing #381 is for: an implementation that only
+writes the document would have to have ``spatialdata`` installed to import
+the schema.
+"""
+
+# Suppress known warnings from dependencies
+import importlib
+import warnings
+from typing import TYPE_CHECKING, Any, List
+
+if TYPE_CHECKING:  # pragma: no cover - for type checkers, not at runtime
+    from .convert import convert_msi
+    from .converters.spatialdata.converter import SpatialDataConverter
+    from .metadata.document import read_metadata_document
+    from .preview import MsiPreview, preview_msi
+
+# Suppress remaining dependency warnings
+warnings.filterwarnings("ignore", category=FutureWarning, module="dask")
+warnings.filterwarnings("ignore", category=FutureWarning, module="spatialdata")
+warnings.filterwarnings("ignore", category=RuntimeWarning, module="numba")
+warnings.filterwarnings(
+    "ignore", message="pkg_resources is deprecated", category=UserWarning
+)
+warnings.filterwarnings(
+    "ignore",
+    message="The legacy Dask DataFrame implementation is deprecated",
+    category=FutureWarning,
+)
+
+__version__ = "4.2.0"
+
+#: Public name -> the module that defines it, imported on first access.
+_LAZY_ATTRS = {
+    "MsiPreview": ".preview",
+    "SpatialDataConverter": ".converters.spatialdata.converter",
+    "convert_msi": ".convert",
+    "preview_msi": ".preview",
+    "read_metadata_document": ".metadata.document",
+}
+
+#: Subpackages ``import thyra`` used to bind as attributes on its way to
+#: registering their contents. Kept reachable as ``thyra.readers`` and
+#: ``thyra.converters`` for code that never imported them by name.
+_LAZY_SUBMODULES = ("converters", "readers")
+
+# Expose main API
+__all__ = [
+    "__version__",
+    "convert_msi",
+    "preview_msi",
+    "read_metadata_document",
+    "MsiPreview",
+    "SpatialDataConverter",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Resolve a public name by importing the module that defines it."""
+    if name in _LAZY_SUBMODULES:
+        return importlib.import_module(f".{name}", __name__)
+    module_path = _LAZY_ATTRS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(module_path, __name__), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> List[str]:
+    return sorted(set(globals()) | set(__all__) | set(_LAZY_SUBMODULES))

{thyra-4.0.0 → thyra-4.2.0}/thyra/__main__.py

@@ -16,6 +16,15 @@ The import block is ordered deliberately and carries ``# noqa: E402``: the
 dependency warning configuration has to run before the libraries that emit
 those warnings are imported, so the usual "imports first" rule is
 inverted on purpose here.
+
+**What it does not import at module scope is ``thyra.convert``** (issue
+#381). Binding ``convert_msi`` here meant every invocation paid for the
+converter, ``pandas`` and ``spatialdata`` before click had parsed a single
+argument -- including ``thyra --version`` and the two subcommands,
+``validate`` and ``metadata``, that never reach a converter at all. The
+conversion command imports it where it calls it. Tests that replace the
+conversion patch ``thyra.convert.convert_msi``, which is the function
+rather than a second name for it.
 """
 
 # Configure dependencies to suppress warnings BEFORE any imports
@@ -30,12 +39,6 @@ from uuid import uuid4  # noqa: E402
 import click  # noqa: E402
 
 from thyra import __version__  # noqa: E402
-from thyra.convert import (  # noqa: E402
-    convert_msi,
-    dataset_id_problem,
-    quarantine_partial_output,
-)
-from thyra.core.registry import detect_format  # noqa: E402
 from thyra.resampling.mobility_grid import MOBILITY_CHANNELS  # noqa: E402
 from thyra.utils.logging_config import setup_logging  # noqa: E402
 
@@ -80,6 +83,8 @@ def _validate_basic_params(pixel_size: Optional[float], dataset_id: str) -> None
         raise click.BadParameter(
             "Pixel size must be a finite positive number", param_hint="pixel_size"
         )
+    from thyra.convert import dataset_id_problem
+
     # Emptiness used to be the whole check, so an id with a space or a
     # slash was refused by SpatialData only at the write, after both
     # passes over the source (issue #250).
@@ -207,6 +212,8 @@ def _validate_input_path(input: Path) -> None:
                 f"found: {ibd_path}"
             )
     elif input.is_dir() and input.suffix.lower() == ".d":
+        from thyra.core.registry import detect_format
+
         # Several Bruker formats share the .d extension (timsTOF via
         # analysis.tsf/.tdf, solariX via peaks.sqlite), so delegate to the
         # registry's detection rather than duplicating the marker files
@@ -335,7 +342,11 @@ def _display_calibration_info(input: Path, use_recalibrated: bool) -> None:
     else:
         click.echo("\nUsing original calibration (--no-recalibrated flag set)")
 
-    click.echo("\nNote: Interactive selection not yet available. See GitHub issue #54.")
+    click.echo(
+        "\nNote: this lists the states only; one cannot be chosen here. "
+        "Thyra uses the active state, or the original calibration with "
+        "--no-recalibrated."
+    )
     click.echo("=" * 60 + "\n")
 
 
@@ -563,6 +574,8 @@ def _quarantine_partial_output(output: Path) -> None:
     store already moved aside does not exist here, so this returns
     immediately.
     """
+    from thyra.convert import quarantine_partial_output
+
     quarantine_partial_output(output)
 
 
@@ -1048,9 +1061,10 @@ def main(
     INPUT: Path to input MSI file or directory
     OUTPUT: Path for output file
 
-    Subcommands (each has its own --help): 'thyra validate PATH'
-    validates MSI metadata against the schema; 'thyra export-metaspace
-    PATH' writes the METASPACE submission JSON.
+    Subcommands (each has its own --help): 'thyra metadata INPUT'
+    writes a raw source's metadata document without converting it;
+    'thyra validate PATH' validates MSI metadata against the schema;
+    'thyra export-metaspace PATH' writes the METASPACE submission JSON.
     """
     # Validate all parameters
     _validate_basic_params(pixel_size, dataset_id)
@@ -1090,6 +1104,9 @@ def main(
     # If input folder has multiple .d datasets, let the user choose
     input = _select_bruker_dataset(input)
 
+    from thyra.convert import convert_msi
+    from thyra.core.registry import detect_format
+
     # Before any work: say which of the given options this source ignores.
     # Detection failures are left to the conversion, which reports them
     # with the guidance the registry writes for each format.
@@ -1178,9 +1195,9 @@ def cli() -> None:
     """Console-script entry point: dispatch subcommands, else convert.
 
     ``thyra INPUT OUTPUT`` converts exactly as it always has; the
-    metadata subcommands (``thyra validate``, ``thyra
-    export-metaspace``) are picked off by their first argument before
-    click sees it.  Dispatch is hand-rolled rather than a
+    metadata subcommands (``thyra metadata``, ``thyra validate``,
+    ``thyra export-metaspace``) are picked off by their first argument
+    before click sees it.  Dispatch is hand-rolled rather than a
     ``click.Group`` because a group cannot carry the two positional
     arguments the conversion interface is documented with.
     """

thyra-4.2.0/thyra/converters/__init__.py

@@ -0,0 +1,26 @@
+"""Converter plugins for MSI data output formats.
+
+Importing this package is what pulls in ``spatialdata``, and through it
+``dask`` and ``anndata``. It used to happen during ``import thyra``, for
+the ``@register_converter`` side effect; the registry now imports
+:mod:`thyra.converters.spatialdata.converter` the first time the
+``spatialdata`` output format is resolved (issue #381), so this runs when
+a conversion is actually being set up.
+
+The Dask configuration below moved here from ``thyra/__init__.py`` for the
+same reason: reading it there meant importing ``dask`` to silence a
+``dask`` warning, on every import of anything under ``thyra``. It has to
+be set before ``dask.dataframe`` is first imported, which is why it comes
+before the subpackage import rather than after.
+"""
+
+try:
+    import dask
+
+    # Configure Dask to use new query planning (silences legacy DataFrame
+    # warning)
+    dask.config.set({"dataframe.query-planning": True})
+except ImportError:
+    pass
+
+from . import spatialdata  # noqa: E402,F401