xmris is an xarray-based toolkit for Magnetic Resonance Imaging and Spectroscopy (MRIS).
If you have ever processed MR data in Python, you have likely written dozens of for loops to iterate over voxels, coils, or time points, all while carefully keeping track of raw numpy array dimensions in your head. This is what xmris tries to solve.
By keeping your multi-dimensional data permanently linked to its named dimensions (like "time" or "frequency"), physical coordinates, and metadata (like the spectrometer frequency), you can process entire datasets simultaneously — no loops, no positional axis indexing.
⚡ Quick Start: A Minimal Working Example¶
Because xmris functions return standard xarray objects, you can chain methods together to build readable, N-dimensional processing pipelines without writing a single for loop:
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 × 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={"b0_field": 7.0, "reference_frequency": 300.15},
)
# 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()
)
# 3. Fit the time-domain data using the pyAMARES integration
fit_dataset = mrsi_data.xmr.fit_amares(prior_knowledge_file="pk.csv")🧠 How it Works: xarray + xmris¶
By simply importing xmris, standard xarray DataArrays instantly gain specialized MRIS functionality. You put an xarray in, apply a method, and get a processed xarray out.
What is xarray?
xarray is a Python library that builds labeled, N-dimensional arrays on top of numpy.
DataArray: The workhorse. It is a single, N-dimensional array just like anumpyarray, but it has named dimensions (e.g.,["voxel", "time"]), physical coordinate values, and metadata attached directly to it.Dataset: A dictionary-like container that holds multiple alignedDataArrayobjects. For example,xmrisfitting operations return aDatasetcontaining your raw data, the fitted model, and the residuals all perfectly synced together!
What exactly is an accessor?
An accessor is how xarray lets external packages attach custom methods directly to standard xarray objects. Conceptually, the division of labor looks like this:
Native xarray handles data wrangling:
da.mean(),da.sel(voxel=2),da.plot(), ...xmris handles the physics:
da.xmr.to_spectrum(),da.xmr.autophase(), ...
It is the exact same data object, meaning you never have to switch contexts or convert data types.
Here is a conceptual look at how your raw data might be structured and processed through the xmris pipeline:
🏗️ Want to Understand the Design?¶
If you are curious about why xmris is built this way — why metadata lives in .attrs, why dimensions are flexible but attributes are strictly guarded, or what the @requires_attrs decorator does — read the architecture guide:
🧭 Where do I start?¶
We recommend going through the example notebooks. They are designed to be read more or less chronologically :)