Ion mobility feature classification

ion-mobility-feature-classification

Summary

Assigns biomolecular class labels (e.g., lipid, protein, carbohydrate) to TWIM-MS features based on their physico-chemical properties (arrival time and m/z) without requiring prior feature identification. This enables immediate class-stratified analysis and class-specific CCS calibration on unidentified experimental data.

When to use

You have raw or processed TWIM-MS data (arrival time and m/z pairs) from multiple lipid, protein, or metabolite classes and need to classify features by biomolecular type before—or instead of—performing feature identification. Use this when you want to perform class-specific CCS calibration or generate class-indexed feature tables without external database lookups or prior peak annotation.

When NOT to use

• Input is already a validated, identified feature table (features linked to known compounds via database or MS/MS); classification adds no value.
• You require species-level identification (e.g., which specific lipid species) rather than class-level categorization (e.g., 'lipid' vs. 'protein').
• Data lacks both arrival time and m/z values, or arrival time is corrupted; the algorithm requires both physico-chemical dimensions.

Inputs

• TWIM-MS experimental data in RawDT format (raw arrival time and m/z from ion mobility mass spectrometry instrument files)
• TWIM-MS experimental data in UserDT format (processed arrival time and m/z values in tabular form)
• Feature list with m/z and arrival time columns (one row per observed feature)

Outputs

• Feature table indexed by feature identifier with assigned biomolecular class labels
• Class-indexed feature assignments (one row per feature, columns for feature ID and class)
• Feature-to-class mapping suitable for downstream class-specific CCS calculations

How to apply

Load your TWIM-MS experimental data in either RawDT format (raw instrument files requiring DEIMoS preprocessing) or UserDT format (pre-processed arrival time and m/z tables). Execute MOCCal's biomolecular class-assignment algorithm, which classifies each feature by analyzing its physico-chemical properties (arrival time, m/z, and intrinsic physical characteristics that correlate with molecular class). The algorithm assigns a discrete class label to each feature. Compile the results into a tabular output indexed by feature identifier, with one row per feature and columns for feature ID and assigned class label. The class assignments enable downstream workflows such as class-specific CCS calibration or stratified statistical analysis without requiring prior MS/MS identification or database matching.

Related tools

• MOCCal (Core application that implements biomolecular class assignment algorithm and performs CCS calibration; available as both Python script and standalone executable) — https://github.com/HinesLab/MOCCal
• DEIMoS (PNNL preprocessing tool required for RawDT workflow; converts raw ion mobility mass spectrometry data to arrival time and m/z format) — http://github.com/pnnl/deimos

Examples

python MOCCal.py --input_file experimental_features.csv --input_format UserDT --output_dir ./Output

Evaluation signals

• Every feature in the input dataset receives exactly one class label in the output (completeness).
• Class distribution is consistent with expected multi-omic composition (e.g., lipids represent majority in lipid-rich samples, proteins in proteomic samples).
• Assigned classes correlate visually with m/z and arrival time ranges (e.g., high m/z features predominate in lipid or protein classes; small metabolites cluster separately).
• Output table schema matches expected format: one row per feature, with feature ID and class columns; no missing or null class assignments.
• Class assignments remain stable across repeated runs on the same input data (reproducibility).

Limitations

• Class assignment algorithm does not identify specific compounds or species; it stratifies only by broad biomolecular class (e.g., lipid, protein, carbohydrate, metabolite).
• Accuracy depends on arrival time measurement quality; TWIM instruments record arrival time (ion reaches detector) rather than true drift time (ion residence in mobility cell), and this distinction may affect some assignments.
• Algorithm assumes features conform to physico-chemical property distributions of the training class set; unusual or heavily modified molecules may be misclassified.
• No changelog available, making it unclear which algorithm versions correspond to published benchmarks.

Evidence

• [other] MOCCal performs experimental data biomolecular class assignment as a core functionality alongside CCS calibration and class-specific CCS calculations.: "MOCCal performs experimental data biomolecular class assignment as a core functionality alongside CCS calibration and class-specific CCS calculations."
• [other] Load experimental TWIM-MS data (arrival time and m/z values) from RawDT or UserDT input format. Execute MOCCal's biomolecular class-assignment algorithm to classify each feature based on its physico-chemical properties. Compile assigned class labels into a tabular output indexed by feature identifier, with one row per feature and columns for feature ID and assigned class.: "Load experimental TWIM-MS data (arrival time and m/z values) from RawDT or UserDT input format. Execute MOCCal's biomolecular class-assignment algorithm to classify each feature based on its"
• [intro] MOCCal offers class assignment and CCS calculations without need for identifying the features first: "MOCCal offers class assignment and CCS calculations without need for identifying the features first"
• [readme] TWIM platforms record the time at which the ion reaches the detector (arrival time) rather than the time an ion spends within the TWIM cell (drift time).: "TWIM platforms record the time at which the ion reaches the detector (arrival time) rather than the time an ion spends within the TWIM cell (drift time)."
• [readme] After DEIMoS is set up, you can then run MOCCal_RawDT.py in the DEIMoS virtual environment.: "After DEIMoS is set up, you can then run MOCCal_RawDT.py in the DEIMoS virtual environment."