Metadata-Version: 2.4
Name: thyra
Version: 1.20.1
Summary: A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics
License: MIT
License-File: LICENSE
Keywords: mass-spectrometry,imaging,spatialdata,zarr,omics,bioinformatics,msi,imzml,bruker,spatial-omics,data-conversion,scientific-computing
Author: Theodoros Visvikis
Author-email: t.visvikis@maastrichtuniversity.nl
Maintainer: Theodoros Visvikis
Maintainer-email: t.visvikis@maastrichtuniversity.nl
Requires-Python: >=3.11,<3.13
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
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-Dist: Shapely (>=1.8.0)
Requires-Dist: anndata (>=0.11.0)
Requires-Dist: cryptography (>=45.0.5,<46.0.0)
Requires-Dist: dask (>=2023.0.0)
Requires-Dist: geopandas (>=0.9.0)
Requires-Dist: imagecodecs (>=2024.1.1)
Requires-Dist: lxml (>=4.6.0)
Requires-Dist: matplotlib (>=3.10.6,<4.0.0)
Requires-Dist: numpy (>=2.0.0)
Requires-Dist: pandas (>=2.0.0)
Requires-Dist: psutil (>=7.2.1,<8.0.0)
Requires-Dist: pyimzML (>=1.4.0)
Requires-Dist: scipy (>=1.7.0)
Requires-Dist: spatialdata (>=0.6.0)
Requires-Dist: tqdm (>=4.50.0)
Requires-Dist: zarr (>=3.0.0)
Project-URL: Bug Tracker, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/issues
Project-URL: Changelog, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CHANGELOG.md
Project-URL: Contributing, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/blob/main/CONTRIBUTING.md
Project-URL: Documentation, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra#readme
Project-URL: Discussions, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra/discussions
Project-URL: Homepage, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra
Project-URL: Repository, https://github.com/M4i-Imaging-Mass-Spectrometry/thyra
Description-Content-Type: text/markdown

# Thyra

[![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.11+](https://img.shields.io/badge/python-3.11+-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)

**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](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)** | [Getting Started](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/getting-started/) | [CLI Reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/cli/) | [API Reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/api/)

## 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
- **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 (enabled by default)
- **3D Support**: Process volume data or treat as 2D slices
- **Cross-Platform**: Windows, macOS, and Linux

## Installation

```bash
pip install thyra
```

## Quick Start

### Command Line

```bash
# Basic conversion (resampling enabled by default)
thyra input.imzML output.zarr

# Bruker data with verbose logging
thyra data.d output.zarr -v DEBUG

# Disable resampling
thyra input.imzML output.zarr --no-resample
```

### Python API

```python
from thyra import convert_msi

success = convert_msi("data/sample.imzML", "output/sample.zarr")
```

### Working with the Output

```python
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}")
```

## Documentation

Full documentation: **[M4i-Imaging-Mass-Spectrometry.github.io/thyra](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra)**

- [Getting Started](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/getting-started/) -- installation, first conversion, common workflows
- [CLI Reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/cli/) -- all command-line options
- [Output Format](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/output-format/) -- understanding the zarr structure
- [API Reference](https://M4i-Imaging-Mass-Spectrometry.github.io/thyra/api/) -- Python API documentation

## Supported Formats

| Input | Extension | Status |
|-------|-----------|--------|
| ImzML | `.imzML` | Full support |
| Bruker | `.d` | Full support (timsTOF + Rapiflex) |
| Waters | `.raw` | Full support |

Output: **SpatialData/Zarr** -- cloud-ready, efficient, standardized

## Development

```bash
git clone https://github.com/M4i-Imaging-Mass-Spectrometry/thyra.git
cd thyra
poetry install
poetry run pre-commit install
poetry run pytest
```

## 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

