xmris 0.5.0

An xarray-based MRI and MRS toolbox

A modern, N-dimensional, xarray-based toolbox for Magnetic Resonance Imaging and Spectroscopy.

📖 Documentation

Documentation, tutorials, and API reference can be found here.

⚡ Overview

xmris bridges the gap between modern data structures and magnetic resonance research. By building on top of xarray, it provides a robust environment for handling multi-dimensional MRI and MRS data with labeled coordinates, powerful broadcasting, and seamless integration with the scientific Python ecosystem.

Key Features:

• N-Dimensional Data: Native handling of complex MRI/MRS datasets using xarray.
• MRS Integration: Direct compatibility with tools like pyAMARES and nmrglue.
• Modern Tooling: Built for speed and reliability, developed using uv and strictly typed for modern Python environments.

🚀 Installation

Note: xmris requires Python 3.11 or 3.12.

You can install the package directly from PyPI using standard package managers:

# Using pip
pip install xmris

# Using uv (recommended)
uv add xmris

💻 Quick Start

import numpy as np
import xarray as xr
import xmris  # Registers the .xmr accessor!

# 1. Create a dummy N-dimensional FID (e.g., 5 Voxels x 1024 Time points)
time = np.linspace(0, 1, 1024)
data = np.random.randn(5, 1024) + 1j * np.random.randn(5, 1024)

mrsi_data = xr.DataArray(
    data,
    dims=["Voxel", "Time"],
    coords={"Voxel": np.arange(5), "Time": time},
    attrs={"MHz": 120.0, "sw": 10000.0}
)

# 2. Process all voxels simultaneously using the .xmr accessor!
results = (
    mrsi_data
    .xmr.zero_fill(target_points=2048)
    .xmr.apodize_exp(lb=5.0)
    .xmr.to_spectrum()
    .xmr.autophase()
)

---

🛠️ Development

We use uv for lightning-fast dependency management and Ruff for linting/formatting. To set up a local development environment:

1. Fork this repository and then clone your version of this repository.

2. Sync the environment and install dependencies:

uv sync

3. Run tests via pytest (which includes notebook testing via nbmake):

uv run pytest

4. Build the MyST based documentation :

uv run docs

More information can be found in the documentation here

---

⚖️ License & Commercial Use

xmris is licensed under the GNU Affero General Public License v3.0 (AGPLv3).