AlphaTims

---

<!-- PROJECT LOGO --> <br /> <div align="center"> <img src="release/logos/alpha_logo.png" alt="Logo" height="80"> <h3 align="center">AlphaTims</h3> <p align="center"> <a href="https://doi.org/10.1016/j.mcpro.2021.100149">Publication</a> · <a href="https://github.com/Mannlabs/alphatims/releases/latest">Download</a> · <a href="#installation">Installation</a> · <a href="#usage">Usage</a> · <a href="https://alphatims.readthedocs.io/en/latest/">Documentation</a> · <a href="https://alphapept.org">alphapept.org</a> </p> </div>

AlphaTims is an open-source Python package that provides fast accession and visualization of unprocessed LC-TIMS-Q-TOF data from Bruker’s timsTOF Pro instruments. It indexes the data such that it can easily be sliced along all five dimensions: LC, TIMS, QUADRUPOLE, TOF and DETECTOR. It was developed by the Mann Labs at the Max Planck Institute of Biochemistry as a modular tool of the AlphaPept ecosystem. To enable all hyperlinks in this document, please view it at GitHub.

---

About

High-resolution quadrupole time-of-flight (Q-TOF) tandem mass spectrometry can be coupled to several other analytical techniques such as liquid chromatography (LC) and trapped ion mobility spectrometry (TIMS). LC-TIMS-Q-TOF has gained considerable interest since the introduction of the Parallel Accumulation–Serial Fragmentation (PASEF) method in both data-dependent (DDA) and data-independent acquisition (DIA). With this setup, ion intensity values are acquired as a function of the chromatographic retention time, ion mobility, quadrupole mass to charge and TOF mass to charge. As these five-dimensional data points are detected at GHz rates, datasets often contain billions of data points which makes them impractical and slow to access. Raw data are therefore frequently binned for faster data analysis or visualization. In contrast, AlphaTims is a Python package that provides fast accession and visualization of unprocessed raw data. By recognizing that all measurements are ultimately arrival times linked to intensity values, it constructs an efficient set of indices such that raw data can be interpreted as a sparse five-dimensional matrix. On a modern laptop, this indexing takes less than half a minute for raw datasets of more than two billion datapoints. Following this step, interactive visualization of the same dataset can also be done in milliseconds. AlphaTims is freely available, open-source and available on all major Operating Systems. It can be used with a graphical user interface (GUI), a command-line interface (CLI) or as a regular Python package.

---

Installation

AlphaTims can be installed and used on all major operating systems (Windows, macOS and Linux). There are different types of installation possible:

• One-click GUI installation: Choose this installation if you only want the GUI and/or keep things as simple as possible.
• Pip installation: Choose this installation if you want to use AlphaTims as a Python package in an existing Python 3.8 environment (e.g. a Jupyter notebook). If needed, the GUI and CLI can be installed with pip as well.
• Developer installation: Choose this installation if you are familiar with CLI tools, conda and Python. This installation allows access to all available features of AlphaTims and even allows to modify its source code directly. Generally, the developer version of AlphaTims outperforms the precompiled versions which makes this the installation of choice for high-throughput experiments.
• Docker installation: Choose this installation if you want to use AlphaTims without any changes to your system.

IMPORTANT: While AlphaTims is mostly platform independent, some calibration functions require Bruker libraries which are only available on Windows and Linux.

One-click GUI installation

The GUI of AlphaTims is a completely stand-alone tool that requires no knowledge of Python or CLI tools.

You can download the latest release of AlphaTims here.

IMPORTANT: Please refer to the GUI manual for detailed instructions on the installation, troubleshooting and usage of the stand-alone AlphaTims GUI.

Windows

Download the latest alphatims-X.Y.Z-windows-amd64.exe build and double click it to install. If you receive a warning during installation click Run anyway. Important note: always install AlphaTims into a new folder, as the installer will not properly overwrite existing installations.

Linux

Download the latest alphatims-X.Y.Z-linux-x64.deb build and install it via dpkg -i alphatims-X.Y.Z-linux-x64.deb.

MacOS

Download the latest build suitable for your chip architecture (can be looked up by clicking on the Apple Symbol > About this Mac > Chip ("M1", "M2", "M3" -> arm64, "Intel" -> x64), alphatims-X.Y.Z-macos-darwin-arm64.pkg or alphatims-X.Y.Z-macos-darwin-x64.pkg. Open the parent folder of the downloaded file in Finder, right-click and select open. If you receive a warning during installation click Open.

In newer MacOS versions, additional steps are required to enable installation of unverified software. This is indicated by a dialog telling you “alphatims. ... .pkg” Not Opened.

1. Close this dialog by clicking Done.
2. Choose Apple menu > System Settings, then Privacy & Security in the sidebar. (You may need to scroll down.)
3. Go to Security, locate the line "alphatims.pkg was blocked to protect your Mac" then click Open Anyway.
4. In the dialog windows, click Open Anyway.

Older releases remain available on the release page, but no backwards compatibility is guaranteed.

Pip installation

AlphaTims can be installed in an existing Python environment with a single bash command. This bash command can also be run directly from within a Jupyter notebook by prepending it with a !:

pip install alphatims

Installing AlphaTims like this avoids conflicts when integrating it in other tools, as this does not enforce strict versioning of dependencies. However, if new versions of dependencies are released, they are not guaranteed to be fully compatible with AlphaTims. This should only occur in rare cases where dependencies are not backwards compatible.

You can always force AlphaTims to use dependency versions which are known to be compatible with:

pip install "alphatims[stable]"

It is also possible to directly install any branch (e.g. some-branch) from GitHub with

pip install "git+https://github.com/MannLabs/alphatims.git@some-branch#egg=alphatims[stable,development-stable]"

Alternatively, some basic plotting functions can be installed with the following command:

pip install "alphatims[plotting]"

While the above command does allow usage of the full GUI, there are some known compatability issues with newer versions of bokeh. As such, it is generally advised to not use loose plotting dependancies and force a stable installation with:

pip install "alphatims[plotting-stable]"

When older samples need to be analyzed, it might be essential to install the legacy version as well (See also the troubleshooting section):

pip install "alphatims[legacy]"

Developer installation

AlphaTims can also be installed in "editable" mode. This allows to fully customize the software and even modify the source code to your specific needs.

First, clone the AlphaTims repository from GitHub to a new directory

mkdir -p ~/alphatims/project/folder && cd ~/alphatims/project/folder
git clone https://github.com/MannLabs/alphatims.git && cd alphatims

Next, it is highly recommended to use a separate conda virtual environment, as otherwise dependency conflicts can occur with already existing packages

conda create --name alphatims python=3.9 -y
conda activate alphatims

Finally, AlphaTims and all its dependencies need to be installed. To take advantage of all features and allow development (with the -e flag), this is best done by also installing the development dependencies instead of only the core dependencies: