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."
1---2name: ion-mobility-feature-classification3description: Use when 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.4license: CC-BY-4.05---67# ion-mobility-feature-classification89## Summary1011Assigns 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.1213## When to use1415You 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.1617## When NOT to use1819- Input is already a validated, identified feature table (features linked to known compounds via database or MS/MS); classification adds no value.20- You require species-level identification (e.g., which specific lipid species) rather than class-level categorization (e.g., 'lipid' vs. 'protein').21- Data lacks both arrival time and m/z values, or arrival time is corrupted; the algorithm requires both physico-chemical dimensions.2223## Inputs2425- TWIM-MS experimental data in RawDT format (raw arrival time and m/z from ion mobility mass spectrometry instrument files)26- TWIM-MS experimental data in UserDT format (processed arrival time and m/z values in tabular form)27- Feature list with m/z and arrival time columns (one row per observed feature)2829## Outputs3031- Feature table indexed by feature identifier with assigned biomolecular class labels32- Class-indexed feature assignments (one row per feature, columns for feature ID and class)33- Feature-to-class mapping suitable for downstream class-specific CCS calculations3435## How to apply3637Load 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.3839## Related tools4041- **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/MOCCal42- **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/deimos4344## Examples4546```47python MOCCal.py --input_file experimental_features.csv --input_format UserDT --output_dir ./Output48```4950## Evaluation signals5152- Every feature in the input dataset receives exactly one class label in the output (completeness).53- Class distribution is consistent with expected multi-omic composition (e.g., lipids represent majority in lipid-rich samples, proteins in proteomic samples).54- 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).55- Output table schema matches expected format: one row per feature, with feature ID and class columns; no missing or null class assignments.56- Class assignments remain stable across repeated runs on the same input data (reproducibility).5758## Limitations5960- Class assignment algorithm does not identify specific compounds or species; it stratifies only by broad biomolecular class (e.g., lipid, protein, carbohydrate, metabolite).61- 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.62- Algorithm assumes features conform to physico-chemical property distributions of the training class set; unusual or heavily modified molecules may be misclassified.63- No changelog available, making it unclear which algorithm versions correspond to published benchmarks.6465## Evidence6667- [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."68- [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"69- [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"70- [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)."71- [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."
HolobiomicsLab