Ion Mobility Mass Spec Dashboard
The Ion Mobility Mass Spec Dashboard is designed to allow scientists to generate results from raw Ion Mobility-Mass Spectrometry data without requiring assistance from an engineer or bioinformatician. This dashboard links four sequential command line tools into a single user-friendly application which communicates with Docker Desktop to dynamically spin up docker containers and manage the filesystem. Each tool has been dockerized and together they perform the following steps: quality control data processing, file type conversion (from proprietary to an open-source format), detection of unique features, and calculation of collision-cross section (CCS).
IMS-MS Background
Mass Spectrometry (MS) is used to identify and differentiate unknown molecules by comparing intensities and mass-to-charge-ratio (m/z). This is important in clinical research and drug development, however, this method stuggles with identifying small molecules, isomers, and enantiomers. To increase the accuracy of molecular identification, MS can be paired with Ion Mobility Spectrometry (IMS). IMS generates an additional descriptive variable called the “collision cross section”, or CCS, which is used to further differentiate between unknown molecules.
Drift Tube Ion Mobility Spectrometry
DTIMS seperates ions by collision cross section. This works by accelerating ions through a straight tube filled with an inert buffer gas, as the ions pass through the tube, they bump into buffer gas molecules and are slowed down. Drift (retention) time is used as a predictor of CCS. Ions with a greater CCS collide with and are slowed down more by buffer molecules, the inverse is true with small molecules. Single field DTIMS uses a single electrical field to accelerate ions through the tube. This differs from stepped field DTIMS which uses an alternating electrical curent to propel ions though the tube. An increase in the length of drift tube increases resolution and both methods of DTIMS are limited by instrument space.
Structures for Lossless Ion Manipulations
SLIM uses the same principal as single field DTIMS without the limitation of drift tube length. This technology allows the ions to be pushed around corners without colliding with path walls; this allows for significantly longer paths resulting in much greater resolution of ion CCS values.
How to install
Two applications are required to run workflows: Docker Desktop, and Ion_Mob_PC.exe (or UI_V2).
Restart computer
First open Docker Desktop, and then Ion_Mob_PC.exe.
Run Overview
Workflow choice will be dictated by which type of experiment you are running. The option to run any individual tool is also available.
Depending on which workflow you’d like to run,a set of files and folders must be prepared ahead of time.
Enter parameter values and use a unique experiment name. Avoid spaces or any special characters in this name.
Double check parameter inputs, files, then run the experiment.
If AutoCCS was performed, you will be able to view a preview of the results. If this does not appear, the experiment may have failed.
Save results to folder. Do not use a duplicate folder name. Once results are saved, they will be removed from the application workspace.
First - Run PNNL PreProcessor
Select your Workflow
There are three types of workflows to run. Each mode has separate needs for input files, but runs a combination of the modules depicted below.
DTIMS Single field
Drift tube ion mobility mass spectrometry requires knowledge of experiments and a table of calibration ions.
A Note on Proteowizard: For the single tool option, this application will convert all (.d) files to mzML. For the Single-Field workflow, this application will filter out all files suspected to come from multi-field data - this will be determined by the PNNL PreProcessor naming suffix. If a file suffix contains any number greater than (filename)1.d, it will be removed. For example, (filename)2.d would be removed from this workflow.
DTIMS Stepped field
Drift tube ion mobility mass spectrometry that requires specific known targets and their masses.
A Note on AutoCCS: For the stepped-field experiment, autoCCS does not generate a (hidden) metadata file. Instead, it extracts the ionization from the file name (POS or NEG). As such, any Feature files and Ims_Metadata files run through stepped-field AutoCCS must include POS or NEG in their names.
Single Tool Option
This option is selected to run tools individually.
Select which tool you would like to run. Grey boxes are unavailable, white boxes are available, and the orange box indicates which is selected.
If AutoCCS is selected, choose single field, stepped field, or SLIM depending on your experiment.
Prepare your Files
Examples of each data type can be found under test data in the github repository.
Upload your files
Prior to uploading files, please sort each file type into their own folder, then select the folder by clicking “Browse”. For example, all Raw data files should be placed in a single folder without any other files. This includes data types such as Agilent (.d) which are folders themselves - ie: select the encompassing folder/directory which holds one or more raw data types, not the data files themselves.
Individual File uploads do not require folders and may be selected directly. These include: Calibrant File, Target List File, and Metadata File.
Once files are uploaded, select the Run tab.
Run Experiment
Prior to selecting “Run Experiment”, Docker Desktop must be open.
Please confirm all variables and path locations before running experiment.
When running experiment, do not exit the application or Docker. Doing so may result in temporary files (such as .tar files in data folders) not being deleted. If exited early, please ensure no temporary files exist in experimental folders before running again.
Viewing and Saving Results
After an experiment is completed, a “Save Results” button should appear. Select this button to find a folder to save results at.
If CCS Values were generated, a summary graph or PDF will be available to preview depending on the experiment type.
Running Additional Experiments
To clear all parameters and results, select the “Clear Experiment” button and confirm. Save results before clearing or they will be lost.
Errors and Troubleshooting
The most common connectivity timeout error may occur when the computer logs out or enters sleep mode partway through a run. This issue becomes more frequent when Docker Desktop is not restarted between runs.
The first time the application uses a tool, the container is pulled from dockerhub (which is updated via github). This first pull event may be slow but afterwards, it will be faster. One issue that may occur here is once a container is pulled, it will not automatically update to the latest version. To update to the latest version, you must navigate to the “Images” tab in Docker Desktop, then “clean up” or remove images. Once the application is run again, it will automatically update to the latest version.
Two docker containers with the same name can not be run at the same time, ensure that all files have unique names and no docker containers are running or stopped before starting an experiment (these must be deleted).
DEIMos is a very efficient and accurate tool that also outperforms mzMine in terms of speed. However, the current version is not entirely compatible with usage in a docker container and as such, it runs slower than expected and may run into memory issues. We hope this can be resolved in future versions of this application. We also hope to incorporate additional DEIMos functions in the future.
Available Tools
Currently we have enabled the use of the following tools.
ProteoWizard Tool
Docker image and script to run ProteoWizard tool
MZMine Tool
Docker image and script to run MZMine Java Program.
AutoCCS Tool
Docker image and script to run AutoCCS Python script.
Ion_Mob_PC.exe (or UI_V2)
This is the GUI for the dashboard.