imzy

imzy: A simple reader interface to imzML, Bruker (.tdf/.tsf) file formats

Getting started

Install using pip

pip install imzy

Analyse your data

import numpy as np
from imzy import get_reader

PATH_TO_FILE = "path/to/file"

# we currently support imzML, Bruker .d (.tsf/.tdf) formats
reader = get_reader(PATH_TO_FILE)
# will extract mass spectrum for pixel index '0'
mz_x, mz_y = reader.get_mass_spectrum(0)
# will extract summed mass spectrum for pixel indices 0-100
mz_x, mz_y = reader.get_summed_spectrum(np.arange(100))
# iterate over all mass spectra in the dataset
for mz_x, mz_y in reader.spectra_iter():
  ...
# get tic array
tic = reader.get_tic()
# this array is 1d so needs to be reshaped to 2d if you want to view it as an image
tic = reader.reshape(tic)
# will extract the 885.549 ion image with 10 ppm window around it
image = reader.get_ion_image(885.549, ppm=10)
# you can also extract multiple images at the same time (which is much more efficient since the spectra
# only need to be loaded into memory once)
mzs = [...] # list of m/zs to extract
images = reader.get_ion_images(mzs, tol=0.05)

Supported formats

• imzML on Windows, macOS and Linux
• Bruker (.tdf/.tsf) on Windows and Linux

Plugins

It is now possible to create your own readers by implementing the imzy.hookspec interface. This allows you to create your own readers for any format you want. You can then register your reader with imzy by adding the following to your setup.py or pyproject.toml or setup.cfg file:

If you have project named your_project_name, you could add a file imzy.py to your project with the following code:

from imzy import BaseReader
from imzy.hookspec import hook_impl

class YourReader(BaseReader):
  """Your reader class."""
  

@hook_impl
def imzy_reader(path: str, **kwargs) -> ty.Optional[YourReader]:
    """Return YourReader if path is valid."""
    ...

In the pyproject.toml file, please define the interface:

[options.entry_points."imzy.plugins"]
your_project_name = "your_project_name.imzy"

Your reader will be automatically detected when the ImzyPluginManager is initialized, which happens when the get_reader function is called. You can then use your reader as follows:

Planned features

• add functionality to readers
• improve performance
• improve tests
• add better caching support
• add support for Waters (.raw) files
• add support for Thermo (.raw) files

Contributing

Initialize your code

1. Initialize git inside your repo:

cd imzy && git init

2. Create conda environment. We are using imzy as its name.

conda create -n imzy python=3.9

3. Initialize and install pre-commit hooks:

make develop
make pre-commit-install

4. Run the codestyle:

make codestyle

5. Upload initial code to GitHub:

git add .
git commit -m ":tada: Initial commit"
git branch -M main
git remote add origin https://github.com/imzy/imzy.git
git push -u origin main

🛡 License

This project is licensed under the terms of the BSD-3 license. See LICENSE for more details.

📃 Citation

@misc{imzy,
  author = {imzy},
  title = {imzy: A new reader/writer interface to imzML and other imaging mass spectrometry formats.},
  year = {2022},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/imzy/imzy}}
}