multi-charge-state-ccs-handling
Summary
Calibrate collision cross section (CCS) values for ions across multiple charge states in TWIM-MS data by establishing separate or unified calibration curves and applying charge-state-aware regression. This skill enables accurate CCS assignment for complex biomolecular mixtures where ions exist in multiple protonation or ionization states.
When to use
Your TWIM-MS dataset contains ions with multiple charge states (e.g., +1, +2, +3 for the same molecular species) and you need CCS values that correctly account for the relationship between drift time, m/z, and charge state. Use this skill when calibrant reference standards are available at multiple charge states, or when your experimental data spans a wide m/z range where charge heterogeneity is expected.
When NOT to use
- Your calibration data or experimental ions are restricted to a single charge state; simpler single-charge calibration workflows are more appropriate.
- You lack reference standards at multiple charge states and cannot validate charge-dependent CCS behavior.
- Your input data are already calibrated CCS values or feature tables; re-calibration would be redundant.
Inputs
- TWIM-MS raw arrival times (list or array)
- Ion m/z values (list or array)
- Ion charge states (list or array)
- Calibrant reference standards with known CCS values and their charge states
- Instrument-specific time-of-flight offset parameter
Outputs
- Calibrated CCS values (numeric array, one per ion)
- Calibration curve coefficients (linear or polynomial, per charge state or unified)
- Quality metrics (residuals, R² values, prediction confidence per charge state)
- CCS table with m/z, charge state, and associated CCS and quality annotations
How to apply
Load TWIM-MS experimental data (arrival times and m/z values) alongside calibrant reference standards with known CCS values at each charge state. Convert arrival times to drift times accounting for time-of-flight offset. Stratify calibration data by charge state (or apply polynomial regression that captures charge-dependent drift-time–CCS relationships across the m/z range). Apply the charge-aware calibration function to map each experimental ion's drift time and m/z to its calibrated CCS, preserving charge state metadata. Export the calibrated CCS table with m/z, charge state, and quality metrics (e.g., residuals from the calibration curve) to enable downstream validation.
Related tools
- MOCCal (Python application for CCS calibration and charge-aware class assignment from TWIM-MS data; executes linear or polynomial regression per charge state and exports calibrated CCS tables) — https://github.com/HinesLab/MOCCal
- DEIMoS (PNNL ion mobility processing toolkit; used by MOCCal (RawDT workflow) for raw calibration file handling and drift-time feature extraction before charge-state stratification) — http://github.com/pnnl/deimos
Evaluation signals
- Calibration curve R² values are ≥0.95 within each charge state stratum; residuals are randomly distributed around zero with magnitude consistent across the m/z range.
- CCS values for the same molecule at different charge states show expected relationships (e.g., CCS increases slightly with charge state due to Coulomb repulsion); literature or external database validation confirms biological plausibility.
- Exported CCS table contains no missing or null charge-state entries; each ion has a paired m/z, charge state, CCS, and quality metric.
- Charge-state-specific calibration curves (if generated separately) show overlapping or smoothly transitional relationships; unified polynomial curves have appropriate degree (typically 2–3) without overfitting.
- Comparison of calibrated CCS against known standards (orthogonal method or literature values) yields average absolute error <2–3% across all charge states.
Limitations
- MOCCal terminology uses 'arrival time' and 'drift time' interchangeably for convenience, but TWIM platforms record arrival time (time to detector) not drift time (time in TWIM cell); users must correctly convert arrival time to true drift time using the instrument-specific offset to avoid systematic bias in CCS values.
- Charge-state-specific calibration requires sufficient calibrant coverage at each charge state; sparse or missing charge states may degrade curve fitting and prediction confidence.
- Linear calibration curves may not capture non-linear drift-time–CCS relationships across very wide m/z or charge-state ranges; polynomial or machine-learning alternatives may be needed.
- No changelog provided; version reproducibility and backward compatibility with older data formats are not documented.
Evidence
- [readme] Charge-state handling in calibration: "Apply linear or polynomial regression to establish a calibration curve mapping drift time to CCS across the m/z range"
- [readme] Arrival vs. drift time distinction: "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)"
- [other] Export of charge-state-associated CCS: "Export the calibrated CCS table with associated m/z, charge state, and quality metrics"
- [intro] Class-specific CCS calculations: "MOCCal enables biomolecular class assignment and class-specific CCS calculations without requiring prior feature identification"
- [readme] Multi-omic multi-charge capability: "MOCCal, or Multi-Omic CCS Calibrator, is a Python application for high-dimensional, multi-omic traveling-wave ion mobility mass spectrometry (TWIM-MS) data analysis"
1---2name: multi-charge-state-ccs-handling3description: Use when your TWIM-MS dataset contains ions with multiple charge states (e.g., +1, +2, +3 for the same molecular species) and you need CCS values that correctly account for the relationship between drift time, m/z, and charge state.4license: CC-BY-4.05---67# multi-charge-state-ccs-handling89## Summary1011Calibrate collision cross section (CCS) values for ions across multiple charge states in TWIM-MS data by establishing separate or unified calibration curves and applying charge-state-aware regression. This skill enables accurate CCS assignment for complex biomolecular mixtures where ions exist in multiple protonation or ionization states.1213## When to use1415Your TWIM-MS dataset contains ions with multiple charge states (e.g., +1, +2, +3 for the same molecular species) and you need CCS values that correctly account for the relationship between drift time, m/z, and charge state. Use this skill when calibrant reference standards are available at multiple charge states, or when your experimental data spans a wide m/z range where charge heterogeneity is expected.1617## When NOT to use1819- Your calibration data or experimental ions are restricted to a single charge state; simpler single-charge calibration workflows are more appropriate.20- You lack reference standards at multiple charge states and cannot validate charge-dependent CCS behavior.21- Your input data are already calibrated CCS values or feature tables; re-calibration would be redundant.2223## Inputs2425- TWIM-MS raw arrival times (list or array)26- Ion m/z values (list or array)27- Ion charge states (list or array)28- Calibrant reference standards with known CCS values and their charge states29- Instrument-specific time-of-flight offset parameter3031## Outputs3233- Calibrated CCS values (numeric array, one per ion)34- Calibration curve coefficients (linear or polynomial, per charge state or unified)35- Quality metrics (residuals, R² values, prediction confidence per charge state)36- CCS table with m/z, charge state, and associated CCS and quality annotations3738## How to apply3940Load TWIM-MS experimental data (arrival times and m/z values) alongside calibrant reference standards with known CCS values at each charge state. Convert arrival times to drift times accounting for time-of-flight offset. Stratify calibration data by charge state (or apply polynomial regression that captures charge-dependent drift-time–CCS relationships across the m/z range). Apply the charge-aware calibration function to map each experimental ion's drift time and m/z to its calibrated CCS, preserving charge state metadata. Export the calibrated CCS table with m/z, charge state, and quality metrics (e.g., residuals from the calibration curve) to enable downstream validation.4142## Related tools4344- **MOCCal** (Python application for CCS calibration and charge-aware class assignment from TWIM-MS data; executes linear or polynomial regression per charge state and exports calibrated CCS tables) — https://github.com/HinesLab/MOCCal45- **DEIMoS** (PNNL ion mobility processing toolkit; used by MOCCal (RawDT workflow) for raw calibration file handling and drift-time feature extraction before charge-state stratification) — http://github.com/pnnl/deimos4647## Evaluation signals4849- Calibration curve R² values are ≥0.95 within each charge state stratum; residuals are randomly distributed around zero with magnitude consistent across the m/z range.50- CCS values for the same molecule at different charge states show expected relationships (e.g., CCS increases slightly with charge state due to Coulomb repulsion); literature or external database validation confirms biological plausibility.51- Exported CCS table contains no missing or null charge-state entries; each ion has a paired m/z, charge state, CCS, and quality metric.52- Charge-state-specific calibration curves (if generated separately) show overlapping or smoothly transitional relationships; unified polynomial curves have appropriate degree (typically 2–3) without overfitting.53- Comparison of calibrated CCS against known standards (orthogonal method or literature values) yields average absolute error <2–3% across all charge states.5455## Limitations5657- MOCCal terminology uses 'arrival time' and 'drift time' interchangeably for convenience, but TWIM platforms record arrival time (time to detector) not drift time (time in TWIM cell); users must correctly convert arrival time to true drift time using the instrument-specific offset to avoid systematic bias in CCS values.58- Charge-state-specific calibration requires sufficient calibrant coverage at each charge state; sparse or missing charge states may degrade curve fitting and prediction confidence.59- Linear calibration curves may not capture non-linear drift-time–CCS relationships across very wide m/z or charge-state ranges; polynomial or machine-learning alternatives may be needed.60- No changelog provided; version reproducibility and backward compatibility with older data formats are not documented.6162## Evidence6364- [readme] Charge-state handling in calibration: "Apply linear or polynomial regression to establish a calibration curve mapping drift time to CCS across the m/z range"65- [readme] Arrival vs. drift time distinction: "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)"66- [other] Export of charge-state-associated CCS: "Export the calibrated CCS table with associated m/z, charge state, and quality metrics"67- [intro] Class-specific CCS calculations: "MOCCal enables biomolecular class assignment and class-specific CCS calculations without requiring prior feature identification"68- [readme] Multi-omic multi-charge capability: "MOCCal, or Multi-Omic CCS Calibrator, is a Python application for high-dimensional, multi-omic traveling-wave ion mobility mass spectrometry (TWIM-MS) data analysis"
HolobiomicsLab