Thyra (from Greek thyra, meaning "door" or "portal") -- a modern Python library for converting Mass Spectrometry Imaging (MSI) data into the standardized SpatialData/Zarr format, serving as your portal to spatial omics analysis workflows.
Read the documentation | Getting Started | Tutorial | CLI Reference | API Reference
Try it without any data
pip install thyra
thyra-example-data example_data/synthetic_brain.imzML # generates a small synthetic dataset
thyra example_data/synthetic_brain.imzML example_data/synthetic_brain.zarr
See the Tutorial for a full walkthrough, including the published example dataset (10.5281/zenodo.18326569).
Features
- 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
- Multi-Region Support: Handles slides with multiple tissue sections
- Resampling: Physics-aware mass axis resampling (on by default in the CLI; opt-in from the Python API)
- Ion Mobility and MS/MS: TIMS acquisitions keep their mass-mobility heatmap and can carry a mobility-resolved sibling table; scheduled PASEF MS/MS acquisitions are written split apart by precursor by default. The defaults and the measurements behind them are recorded in the design decisions
- Validated Metadata: Versioned, ontology-mapped metadata schema (PSI-MS, NCBITaxon, UBERON, CHEBI) with
thyra validateand one-command METASPACE export - 3D Support: Process volume data or treat as 2D slices
- Cross-Platform: Windows, macOS, and Linux
Installation
pip install thyra
Quick Start
Command Line
# Basic conversion (resampling enabled by default)
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.
Python API
from thyra import convert_msi
success = convert_msi("data/sample.imzML", "output/sample.zarr")
Working with the Output
import spatialdata as sd
sdata = sd.read_zarr("output/sample.zarr")
msi_table = sdata.tables["msi_dataset_z0"]
print(f"Shape: {msi_table.shape}") # (pixels, m/z bins)
print(f"m/z range: {msi_table.var['mz'].min():.1f} -- {msi_table.var['mz'].max():.1f}")
Metadata
Every converted store carries a versioned, ontology-mapped metadata block
(uns["msi_metadata"]), auto-populated from the source file:
thyra validate output.zarr # schema + ontology checks
thyra export-metaspace output.zarr --merge sample.json # METASPACE submission JSON
See Metadata Schema.
Documentation
Full documentation: M4i-Imaging-Mass-Spectrometry.github.io/thyra
- Getting Started -- installation, first conversion, common workflows
- CLI Reference -- all command-line options
- Output Format -- understanding the zarr structure
- Metadata Schema -- the validated, ontology-mapped metadata block and METASPACE export
- Coordinate Systems -- the
"global"contract Thyra writes for downstream consumers - API Reference -- Python API documentation
Supported Formats
| Input | Extension | Status |
|---|---|---|
| ImzML | .imzML |
Full support |
| Bruker | .d |
Full support (timsTOF + solariX + Rapiflex) |
| Waters | .raw directory |
Full support |
| PHI SmartSoft-TOF | .raw file |
Full support (nanoTOF, ToF-SIMS) |
| mzPeak | .mzpeak |
Experimental (HUPO-PSI v0.9 draft, read-only) |
| Shimadzu | .imdx, .kbd |
In development (workaround: imzML export from IMAGEREVEAL MS) |
PHI mosaic, MS/MS and depth-profiling acquisitions are implemented but so far tested only against synthetic files -- real data in those modes is very welcome.
Output: SpatialData/Zarr -- cloud-ready, efficient, standardized
Development
git clone https://github.com/M4i-Imaging-Mass-Spectrometry/thyra.git
cd thyra
uv sync
uv run pre-commit install
uv run pytest
Contributing
See CONTRIBUTING.md for guidelines.
License
MIT -- see LICENSE.
Citation
@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 ecosystem
- Powered by Zarr for efficient storage
- Uses pyimzML for ImzML parsing
Visual identity
Logomark and logotype designed by Nepsis Scriptorium.
1 maintainer
Metadata
1 maintainer
Release files for thyra 3.23.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| thyra-3.23.0.tar.gz | 11.8 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| thyra-3.23.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 23.7 MB
Release files / thyra-3.23.0.tar.gz
| Download URL | thyra-3.23.0.tar.gz |
|---|---|
| Size | 11.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e8ca7857d0919ff8a6b3051f772dbcf589f7e3d55615e8b2924c8a673bfc7c1
|
|
BLAKE2b-256 checksum How to use checksums |
079cfce90e86f882560a6eb1f33968b27d901a78d17014c4612866a14ed58c00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency logRelease files / thyra-3.23.0-py3-none-any.whl
| Download URL | thyra-3.23.0-py3-none-any.whl |
|---|---|
| Size | 11.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57eb085f2b42246ccbfa7ee933bb412c58bfbe8ddea7265fd6bfbe0dd90aebcd
|
|
BLAKE2b-256 checksum How to use checksums |
b02924567158c0388e6c0f0957184ee1b8533b4fceb754f62507cdeb5053e632
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2026.
Transparency log
