thyra 1.15.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), Waters (.raw 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

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

# Waters data
thyra data.raw output.zarr

# 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
Waters	.raw	Waters MassLynx imaging 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