thyra 1.11.0

A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics

Thyra

Thyra (from Greek θύρα, 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.

Features

• Multiple Input Formats: ImzML, Bruker (.d directories)
• SpatialData Output: Modern, cloud-ready format with Zarr backend
• Memory Efficient: Handles large datasets (100+ GB) through streaming processing
• Metadata Preservation: Extracts and maintains all acquisition parameters
• 3D Support: Process volume data or treat as 2D slices
• Cross-Platform: Windows, macOS, and Linux support

Installation

Via pip (Recommended)

pip install thyra

Via conda

conda install -c conda-forge thyra

From source

git clone https://github.com/Tomatokeftes/thyra.git
cd thyra
poetry install

Quick Start

Command Line Interface

# Basic conversion
thyra input.imzML output.zarr

# With custom parameters
thyra data.d output.zarr --pixel-size 50 --dataset-id "experiment_001"

# 3D volume processing
thyra volume.imzML output.zarr --handle-3d

Python API

from thyra import convert_msi

# Simple conversion
success = convert_msi(
    input_path="data/sample.imzML",
    output_path="output/sample.zarr",
    pixel_size_um=25.0
)

# Advanced usage with custom parameters
success = convert_msi(
    input_path="data/experiment.d",
    output_path="output/experiment.zarr",
    dataset_id="exp_001",
    pixel_size_um=10.0,
    handle_3d=True
)

Supported Formats

Input Formats

Format	Extension	Description	Status
ImzML	.imzML	Open standard for MS imaging	✅ Full support
Bruker	.d	Bruker proprietary format	✅ Full support

Output Formats

Format	Description	Benefits
SpatialData/Zarr	Modern spatial omics standard	Cloud-ready, efficient, standardized

Advanced Usage

Configuration Options

# All available options
thyra input.imzML output.zarr \
    --pixel-size 25 \
    --dataset-id "my_experiment" \
    --handle-3d \
    --optimize-chunks \
    --log-level DEBUG \
    --log-file conversion.log

Batch Processing

import glob
from thyra import convert_msi

# Process multiple files
for input_file in glob.glob("data/*.imzML"):
    output_file = input_file.replace(".imzML", ".zarr")
    convert_msi(input_file, output_file)

Working with SpatialData

import spatialdata as sd

# Load converted data
sdata = sd.read_zarr("output/sample.zarr")

# Access the MSI data
msi_data = sdata.tables["msi_dataset"]
print(f"Shape: {msi_data.shape}")
print(f"Mass channels: {msi_data.var.index}")

Development

Setup Development Environment

# Clone repository
git clone https://github.com/Tomatokeftes/thyra.git
cd thyra

# Install with development dependencies
poetry install

# Install pre-commit hooks
poetry run pre-commit install

Running Tests

# Unit tests only
poetry run pytest -m "not integration"

# All tests
poetry run pytest

# With coverage
poetry run pytest --cov=thyra

Code Quality

# Format code
poetry run black .
poetry run isort .

# Run linting
poetry run flake8

# Run all checks
poetry run pre-commit run --all-files

Documentation

• API Documentation: Auto-generated docs
• Contributing Guide: CONTRIBUTING.md
• Architecture Overview: docs/architecture.md
• Changelog: CHANGELOG.md

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Quick Contribution Steps

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run the test suite (poetry run pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

Citation

If you use Thyra in your research, please cite:

@software{thyra2024,
  title = {Thyra: Modern Mass Spectrometry Imaging Data Conversion - Portal to Spatial Omics},
  author = {Visvikis, Theodoros},
  year = {2024},
  url = {https://github.com/Tomatokeftes/thyra}
}

Acknowledgments

• Built with SpatialData ecosystem
• Powered by Zarr for efficient storage
• Uses pyimzML for ImzML parsing

---

Thyra - Your portal from traditional MSI formats to modern spatial omics workflows