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
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.zarrSee the Tutorial for a full walkthrough, including the published example dataset (10.5281/zenodo.18326569).
- 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)
- 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
pip install thyra# 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-resampleThyra 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.
from thyra import convert_msi
success = convert_msi("data/sample.imzML", "output/sample.zarr")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}")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 JSONSee Metadata Schema.
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
| Input | Extension | Status |
|---|---|---|
| ImzML | .imzML |
Full support |
| Bruker | .d |
Full support (timsTOF + Rapiflex) |
| Waters | .raw |
Full support |
| PHI SmartSoft-TOF | .raw |
Full support |
| Shimadzu | .imdx, .kbd |
In development (workaround: imzML export from IMAGEREVEAL MS) |
Output: SpatialData/Zarr -- cloud-ready, efficient, standardized
git clone https://github.com/M4i-Imaging-Mass-Spectrometry/thyra.git
cd thyra
uv sync
uv run pre-commit install
uv run pytestSee CONTRIBUTING.md for guidelines.
MIT -- see LICENSE.
@software{thyra2024,
title = {Thyra: Modern Mass Spectrometry Imaging Data Conversion},
author = {Visvikis, Theodoros},
year = {2024},
url = {https://github.com/M4i-Imaging-Mass-Spectrometry/thyra}
}- Built with SpatialData ecosystem
- Powered by Zarr for efficient storage
- Uses pyimzML for ImzML parsing
Logomark and logotype designed by Nepsis Scriptorium.
