# Ion Mobility Calibration Curve Fitting

> Use when you have TWIM-MS experimental data with arrival times and m/z values, and access to calibrant reference standards with known CCS values (typically loaded from a calibration template).

- Skill: `holobiomicslab/ion-mobility-calibration-curve-fitting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ion-mobility-calibration-curve-fitting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ion-mobility-calibration-curve-fitting/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/ion-mobility-calibration-curve-fitting

---


# ion-mobility-calibration-curve-fitting

## Summary

Fit a regression model (linear or polynomial) to drift time vs. collision cross section (CCS) reference standards to establish a calibration curve for converting experimental TWIM-MS arrival times into calibrated CCS values. This is a core step in high-dimensional multi-omic ion mobility mass spectrometry data analysis.

## When to use

You have TWIM-MS experimental data with arrival times and m/z values, and access to calibrant reference standards with known CCS values (typically loaded from a calibration template). You need to convert raw arrival times into calibrated CCS values across the m/z range before downstream biomolecular class assignment or quantification.

## When NOT to use

- Arrival times have already been manually converted to drift times using a different method or instrument calibration—re-fitting may introduce inconsistency.
- Reference calibrant standards are unavailable, unlabeled, or have uncertain CCS values.
- The experimental m/z range extends far beyond the m/z coverage of reference standards, leading to extrapolation beyond the validated calibration domain.

## Inputs

- TWIM-MS arrival times (time at detector) and m/z values from experimental sample
- Instrument-specific time-of-flight offset parameter
- Calibrant reference standards with known CCS values
- Calibration template (data structure defining reference standards and CCS assignments)

## Outputs

- Calibration curve model (linear or polynomial regression coefficients)
- Calibrated CCS values for all ions in experimental dataset
- CCS table with m/z, charge state, drift time, and quality metrics
- Calibration quality report (e.g., residuals, R² goodness-of-fit)

## How to apply

Load calibrant reference standards with known CCS values from the calibration template. Convert experimental arrival times to drift times by subtracting the instrument-specific time-of-flight offset. Fit a linear or polynomial regression model to the calibrant reference standards, mapping drift time to CCS across the m/z range. Apply the resulting calibration function to the experimental drift times to generate calibrated CCS values for all ions. Export the calibrated CCS table with associated m/z, charge state, and quality metrics (e.g., residuals or goodness-of-fit). Validate that calibration residuals are acceptable and that the curve spans the full m/z range of experimental data.

## Related tools

- **MOCCal** (Python application that implements CCS calibration as a core workflow step, including data import, drift time conversion, calibrant loading, and calibration curve fitting for TWIM-MS data) — https://github.com/HinesLab/MOCCal
- **DEIMoS** (Dependency for MOCCal when processing raw (unprocessed) calibration files; version 1.3.2 required for RawDT workflow) — http://github.com/pnnl/deimos

## Evaluation signals

- Calibration curve residuals (difference between fitted and reference CCS values) are within acceptable bounds (typically < 2% relative error for high-quality standards).
- Goodness-of-fit metric (R² or adjusted R²) is ≥ 0.99, indicating the model explains ≥ 99% of variance in reference standards.
- Calibrated CCS values for unknown samples fall within the m/z and drift time range spanned by the reference standards (no extrapolation).
- Quality metrics (charge state, m/z assignment) are correctly propagated to output CCS table and match input experimental data.
- Calibration is reproducible: re-fitting with the same standards and parameters yields identical or near-identical CCS values (bit-identical or within floating-point tolerance).

## Limitations

- TWIM platforms record arrival time (time at detector) rather than drift time (time in TWIM cell), and the conversion requires an accurate instrument-specific time-of-flight offset; incorrect offset propagates systematic error into all calibrated CCS values.
- Linear or polynomial regression assumes a smooth, monotonic relationship between drift time and CCS; non-ideal behavior (e.g., instrument hysteresis or space-charge effects) may violate this assumption and degrade calibration accuracy at extreme m/z or CCS values.
- Reference calibrant standards must cover the m/z and CCS range of experimental data; sparse or unevenly distributed standards lead to poor fit quality or unreliable predictions in sparse regions.
- No changelog provided; version history and known issues are not documented in the repository README.

## Evidence

- [other] Convert arrival times to drift times by accounting for the time-of-flight offset specific to the instrument platform.: "Convert arrival times to drift times by accounting for the time-of-flight offset specific to the instrument platform."
- [other] Load calibrant reference standards with known CCS values from the calibration template.: "Load calibrant reference standards with known CCS values from the calibration template."
- [other] Apply linear or polynomial regression to establish a calibration curve mapping drift time to CCS across the m/z range.: "Apply linear or polynomial regression to establish a calibration curve mapping drift time to CCS across the m/z range."
- [other] Apply the calibration function to experimental arrival times to generate calibrated CCS values for all ions.: "Apply the calibration function to experimental arrival times to generate calibrated CCS values for all ions."
- [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] Functionality includes collision cross section (CCS) calibration, experimental data biomolecular class assignment, and experimental class-specific CCS calculations.: "Functionality includes collision cross section (CCS) calibration, experimental data biomolecular class assignment, and experimental class-specific CCS calculations."