A Python package to index Bruker TimsTOF raw data for fast and easy accession and visualization
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.
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.
AlphaTims was developed by the Mann Labs at the Max Planck Institute of Biochemistry and is freely available with an Apache License. Since AlphaTims uses Bruker libraries (available in the alphatims/ext folder) additional third-party licenses are applicable. External Python packages (available in the requirements folder) have their own licenses, which can be consulted on their respective websites.
AlphaTims can be installed and used on all major operating systems (Windows, macOS and Linux). There are three different types of installation possible:
IMPORTANT: While AlphaTims is mostly platform independent, some calibration functions require Bruker libraries which are only available on Windows and Linux.
The GUI of AlphaTims is a completely stand-alone tool that requires no knowledge of Python or CLI tools. Click on one of the links below to download the latest release for:
IMPORTANT: Please refer to the GUI manual for detailed instructions on the installation, troubleshooting and usage of the stand-alone AlphaTims GUI.
Older releases remain available on the release page, but no backwards compatibility is guaranteed.
AlphaTims can be installed in an existing Python 3.8 environment with a single bash command. This bash command can also be run directly from within a Jupyter notebook by prepending it with a !. The lightweight version of AlphaTims that purely focuses on data accession (no plotting without additional packages) can be installed with:
pip install alphatims
Installing AlphaTims like this avoids conflicts when integrating it in other tools, as this does not enforce strict versioning of dependancies. However, if new versions of dependancies are released, they are not guaranteed to be fully compatible with AlphaTims. While this should only occur in rare cases where dependencies are not backwards compatible, you can always force AlphaTims to use dependancy versions which are known to be compatible with:
pip install "alphatims[stable]"
NOTE: You might need to run pip install pip==21.0 before installing AlphaTims like this. Also note the double quotes ".
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]"
When a new version of AlphaTims becomes available, the old version can easily be upgraded by running e.g. the command again with an additional --upgrade flag:
pip install "alphatims[plotting,legacy,stable]" --upgrade
The following extra options are available:
stableplottingplotting-stablelegacylegacy-stabledevelopmentdevelopment-stableNOTE: Multiple dependancy packs can be installed by comma-separation. Note however that this only works without spaces!
AlphaTims can also be installed in editable (i.e. developer) mode with a few bash commands. This allows to fully customize the software and even modify the source code to your specific needs. When an editable Python package is installed, its source code is stored in a transparent location of your choice. While optional, it is advised to first (create and) navigate to e.g. a general software folder:
mkdir ~/folder/where/to/install/software
cd ~/folder/where/to/install/software
The following commands assume you do not perform any additional cd commands anymore.
Next, download the AlphaTims repository from GitHub either directly or with a git command. This creates a new AlphaTims subfolder in your current directory.
git clone https://github.com/MannLabs/alphatims.git
For any Python package, it is highly recommended to use a conda virtual environment. The best way to install an editable version of AlphaTims is to use AlphaTims' pre-built conda development environment (note that the --force flag overwrites an already existing AlphaTims environment):
conda env create --force --name alphatims --file alphatims/misc/conda_development_environment.yaml
conda activate alphatims
Alternatively, a new conda environment can manually be created or AlphaTims can be installed in an already existing environment. Note that dependancy conflicts can occur with already existing packages in the latter case! Once a conda environment is activated, AlphaTims and all its dependancies need to be installed. To take advantage of all features and allow development (with the -e flag), this is best done by installing both the plotting dependencies and development dependencies instead of only the core dependencies:
conda create -n alphatims python=3.8 -y
conda activate alphatims
pip install -e "./alphatims[plotting-stable,development]"
By using the editable flag -e, all modifications to the AlphaTims source code folder are directly reflected when running AlphaTims. Note that the AlphaTims folder cannot be moved and/or renamed if an editable version is installed.
The following steps are optional, but make working with AlphaTims slightly more convenient:
conda activate alphatims and conda deactivate every time AlphaTims is used, the binary execution (which still reflects all modifications to the source code) can be added as an alias. On linux and MacOS, this can be done with e.g.:
conda activate alphatims
alphatims_bin="$(which alphatims)"
echo "alias alphatims='"${alphatims_bin}"'" >> ~/.bashrc
conda deactivate
zsh is the default terminal instead of bash, replace ~/.bashrc with ~/.zshrc. On Windows, the command where alphatims can be used to find the location of the binary executable. This path can then be (permanently) added to Windows' path variable.conda install nb_conda_kernels in the conda base environment. Hereafter, running a jupyter notebook from the conda base environment should have a python [conda env: alphatims] kernel available, in addition to all other conda kernels in which the command conda install ipykernel was run.(WIP)
docker pull ghcr://MannLabs/alphatims:latest
See the general troubleshooting section.
AlphaTims is compatible with both ddaPASEF and diaPASEF.
A test sample of human cervical cancer cells (HeLa, S3, ATCC) is provided for AlphaTims. These cells were cultured in Dulbecco's modified Eagle's medium (all Life Technologies Ltd., UK). Subsequently, the cells were collected, washed, flash-frozen, and stored at -80 °C. Following the previously published in-StageTip protocol, cell lysis, reduction, and alkylation with chloroacetamide were carried out simultaneously in a lysis buffer (PreOmics, Germany). The resultant dried peptides were reconstituted in water comprising 2 vol% acetonitrile and 0.1% vol% trifluoroacetic acid, yielding a 200 ng/µL solution. This solution was further diluted with water containing 0.1% vol% formic acid. The manufacturer's instructions were followed to load approximately 200ng peptides onto Evotips (Evosep, Denmark).
Single-run LC-MS analysis was executed via an Evosep One LC system (Evosep). This was coupled online with a hybrid TIMS quadrupole TOF mass spectrometer (Bruker timsTOF Pro, Germany). A silica emitter (Bruker) was placed inside a nano-electrospray ion source (Captive spray source, Bruker) and connected to an 8 cm x 150 µm reverse phase column to perform LC. The column was packed with 1.5 µm C18-beads (Pepsep, Denmark). Mobile phases were water and acetonitrile, buffered with 0.1% formic acid. The samples were separated with a predefined 60 samples per day method (Evosep).
A ddaPASEF dataset is available for download from the release page. Each topN acquisition cycle consisted of 10 PASEF MS/MS scans, and the accumulation and ramp times were set to 100 ms. Single-charged precursors were excluded using a polygon filter in the m/z-ion mobility plane. Furthermore, all precursors, which reached the target value of 20000, were excluded for 0.4 min from the acquisition. Precursors were isolated with a quadrupole window of 2 Th for m/z <700 and 3 Th for m/z >700.
The same sample was acquired with diaPASEF and is also available for download from the release page. The "high-speed" method (mass range: m/z 400 to 1000, 1/K0: 0.6 – 1.6 Vs cm- 2, diaPASEF windows: 8 x 25 Th) was used, as described in Meier et al.
There are three ways to use AlphaTims:
NOTE: The first time you use a fresh installation of AlphaTims, it is often quite slow because some functions might still need compilation on your local operating system and architecture. Subsequent use should be a lot faster.
Please refer to the GUI manual for detailed instructions on the installation, troubleshooting and usage of the stand-alone AlphaTims GUI.
If the GUI was not installed through a one-click GUI installer, it can be activate with the following bash command:
alphatims gui
Note that this needs to be prepended with a ! when you want to run this from within a Jupyter notebook. When the command is run directly from the command-line, make sure you use the right environment (activate it with e.g. conda activate alphatims or set an alias to the binary executable).
The CLI can be run with the following command (after activating the conda environment with conda activate alphatims or if an alias was set to the alphatims executable):
alphatims -h
It is possible to get help about each function and their (required) parameters by using the -h flag. For instance, the command alphatims export hdf -h will produce the following output:
************************
* AlphaTims 0.0.210310 *
************************
Usage: alphatims export hdf [OPTIONS] BRUKER_D_FOLDER
Export BRUKER_D_FOLDER as hdf file.
Options:
--disable_overwrite Disable overwriting of existing files.
--enable_compression Enable compression of hdf files. If set, this
roughly halves files sizes (on-disk), at the
cost of taking 2-10 longer accession times.
-o, --output_folder DIRECTORY A directory for all output (blank means
`input_file` root is used).
-l, --log_file PATH Save all log data to a file (blank means
'log_[date].txt' with date format
yymmddhhmmss in 'log' folder of AlphaTims
directory). [default: ]
-t, --threads INTEGER The number of threads to use (0 means all,
negative means how many threads to leave
available). [default: -1]
-s, --disable_log_stream Disable streaming of log data.
-p, --parameter_file FILE A .json file with (non-required) parameters
(blank means default parameters are used).
NOTE: Parameters defined herein override all
default and given CLI parameters.
-e, --export_parameters FILE Save currently selected parameters to a
parameter file.
-h, --help Show this message and exit.
For this particular command, the line Usage: alphatims export hdf [OPTIONS] BRUKER_D_FOLDER shows that you always need to provide a path to a BRUKER_D_FOLDER and that all other options are optional (indicated by the brackets in [OPTIONS]). Each option can be called with a double dash -- followed by a long name, while common options also can be called with a single dash - followed by their short name. It is indicated what type of parameter is expected, e.g. a DIRECTORY for --output_folder or nothing for enable/disable flags. Defaults are also shown and all parameters will be saved in a log file. Alternatively, all used parameters can be exported with the --export_parameters option and the non-required ones can be reused with the --parameter_file.
IMPORTANT: Please refer to the CLI manual for detailed instructions on the usage and troubleshooting of the stand-alone AlphaTims CLI.
AlphaTims can be imported as a Python package into any Python script or notebook with the command import alphatims. Documentation for all functions is available in the Read the Docs API.
A brief Jupyter notebook tutorial on how to use the API is also present in the nbs folder. When running locally it provides interactive plots, which are not rendered on GitHub. Instead, they are available as individual html pages in the nbs folder.
Performance can be measured in function of speed or RAM usage.
Typical time performance statistics on data in-/output and slicing of standard HeLa datasets are available in the performance notebook. All result can be summarized as follows:
On average, RAM usage is twice the size of a raw Bruker .d folder. Since most .d folders have file sizes of less than 10 Gb, a modern computer with 32 Gb RAM suffices to explore most datasets with ease.
Common installation/usage issues include:
conda activate alphatims. If this fails, make sure you have installed conda and have created an AlphaTims environment with conda create -n alphatims python=3.8.git command. Make sure git is installed. In a notebook !conda install git -y might work.python --version (or !python --version in a notebook). If not, reinstall the AlphaTims environment with conda create -n alphatims python=3.8.pip install pip==20.2 or pip install pip==21.0 (before running pip install alphatims) could solve dependancy conflicts../ (e.g. pip install "./alphatims"). On some systems, installation specifically requires (not) to use single quotes ' around the AlphaTims folder, e.g. pip install "./alphatims[plotting-stable,development]".-e flag when using pip install -e alphatims.numpy==1.19.4 has some issues. After installing AlphaTims, downgrade NumPy with pip install numpy==1.19.3.conda install -c conda-forge firefox geckodriver in the AlphaTims conda environment. Alternatively, a file can be exported as html and opened in a browser. From the browser there is a save as png button available.pip install "alphatims[legacy]" or pip install "alphatims[legacy]" --upgrade if already pre-installed.pip, the GUI cannot be started. Make sure you install AlphaTims with pip install "alphatims[plotting-stable]" to include the GUI with stable dependancies. If this was done and it still fails to run the GUI, a possible fix might be to run pip install panel==0.10.3 after AlphaTims was installed.OSError: libgomp.so.1: cannot open shared object file: No such file or directory. This can be solved by installing those manually, e.g. on Linux: apt-get install libgomp1.The basic workflow of AlphaTims looks as follows:
.d folder.Also checkout:
Bruker stores TimsTOF raw data in a .d folder. The two main files in this folder are analysis.tdf and analysis.tdf_bin.
The analysis.tdf file is an SQL database, in which all metadata are stored together with summarised information. This includes the Frames table, wherein information about each individual TIMS cycle is summarised including the retention time, the number of scans (i.e. a single TOF push is related to a single ion mobility value), the summed intensity and the total number of ions that have hit the detector. More details about individual scans of the frames are available in the PasefFrameMSMSInfo (for PASEF acquisition) or DiaFrameMsMsWindows (for diaPASEF acquisition) tables. This includes quadrupole and collision settings of the frame/scan combinations.
The analysis.tdf_bin file is a binary file that contains the number of detected ions per individual scan, all detector arrival times and their intensity values. These values are grouped and compressed per frame (i.e. TIMS cycle), thereby allowing fast appendage during online acquisition.
AlphaTims first reads relevant metadata from the analysis.tdf SQL database and creates a Python object of the bruker.TimsTOF class. Next, AlphaTims reads the summary information from the Frames table and creates three empty arrays:
tof_indices array, in which all TOF arrival times of each individual detector hit will be stored. Its size is determined by summing the number of detector hits for all frames.intensities array of the same size, in which all intensity values of each individual detector hit will be stored.tof_indptr array, that will store the number of detector hits per scan. Its size is equal to (frame_max_index + 1) * scans_max_index + 1. It includes one additional frame to compensate for the fact that Bruker arrays are 1-indexed, while Python uses 0-indexing. The final +1 is because this array will be converted to an offset array, similar to the index pointer array of a compressed sparse row matrix. Typical values are scans_max_index = 1000 and frame_max_index = gradient_length_in_seconds * 10, resulting in approximately len(tof_indptr) = 10000 * gradient_length_in_seconds.After reading the PasefFrameMSMSInfo or DiaFrameMsMsWindows table from the analysis.tdf SQL database, four arrays are created:
quad_indptr array that indexes the tof_indptr array. Each element points to an index of the tof_indptr where the voltage on the quadrupole and collision cell is adjusted. For PASEF acquisitions, this is typically 20 times per MSMS frame (turning on and off a value for 10 precursor selections) and once per change from an MS (precursor) frame to an MSMS (fragment) frame. For diaPASEF, this is typically twice to 10 times per frame and with a repetitive pattern over the frame cycle. This results in an array of approximately len(quad_indptr) = 100 * gradient_length_in_seconds. As with the tof_indptr array, this array is converted to an offset array with size +1.quad_low_values array of len(quad_indptr) - 1. This array stores the lower m/z boundary that is selected with the quadrupole. For precursors without quadrupole selection, this value is set to -1.quad_high_values array, similar to quad_low_values.precursor_indices array of len(quad_indptr) - 1. For PASEF this array stores the index of the selected precursor. For diaPASEF, this array stores the WindowGroup of the fragment frame. A value of 0 indicates an MS1 ion (i.e. precursor) without quadrupole selection.After processing this summarising information from the analysis.tdf SQL database, the actual raw data from the analysis.tdf_bin binary file is read and stored in the empty tof_indices, intensities and tof_indptr arrays.
Finally, three arrays are defined that allow quick translation of frame_, scan_ and tof_indices to rt_values, mobility_values and mz_values arrays.
rt_values array is read read directly from the Frames table in analysis.tdf and has a length equal to frame_max_index + 1. Note that an empty zeroth frame with rt = 0 is created to make Python's 0-indexing compatible with Bruker's 1-indexing.mobility_values array is defined by using the function tims_scannum_to_oneoverk0 from timsdata.dll on the first frame and typically has a length of 1000.mz_values array is defined by using the function tims_index_to_mz from timsdata.dll on the first frame. Typically this has a length of 400000.All these arrays can be loaded into memory, taking up roughly twice as much RAM as the .d folder on disk. This increase in RAM memory is mainly due to the compression used in the analysis.tdf_bin file. The HDF5 file can also be compressed so that its size is roughly halved and thereby has the same size as the Bruker .d folder, but (de)compression reduces accession times by 3-6 fold.
Once a Python TimsTOF object is available, it can be loaded into memory for ultrafast accession. Accession of the data object is done by simple Python slicing such as e.g. selected_ion_indices = data[frame_selection, scan_selection, quad_selection, tof_selection]. This slicing returns a pd.DataFrame for subsequent analysis. The columns of this dataframe contain all information for all selected ions, i.e. frame, scan, precursor and tof indices and rt, mobility, quad_low, quad_high, mz and intensity values. See the tutorial jupyter notebook for usage examples.
Check out the paper.
If you like AlphaTims you can give us a star to boost our visibility! All direct contributions are also welcome. Feel free to post a new issue or clone the repository and create a pull request with a new branch. For an even more interactive participation, check out the discussions. For more information see the Contributors License Agreement.
The following changes were introduced in the following versions of AlphaTims. Download the latest version in the installation section.
alphatims.utils.set_threads.alphatims.bruker.indptr_lookup.pip install "alphatims[stable]". NOTE: This option is not guaranteed to be maintained. Future AlphaTims versions might opt for an intermediate solution with semi-strict dependancy versioning.FAQs
A Python package to index Bruker TimsTOF raw data for fast and easy accession and visualization
We found that alphatims demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.