# Ion Mobility Calibration Validation

> Use when when you have positive- or negative-mode ion mobility spectrometry data with tunemix reference standards (known m/z, drift times, and CCS values) and need to verify that the calibration model accurately captures the relationship between drift time, reference m/z, and collision cross.

- Skill: `holobiomicslab/ion-mobility-calibration-validation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ion-mobility-calibration-validation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ion-mobility-calibration-validation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- 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-validation

---


# ion-mobility-calibration-validation

## Summary

Validates collision cross section (CCS) calibration coefficients derived from ion mobility spectrometry data by applying the single-field calibration equation to reference standards and assessing model fit quality. This skill ensures that drift time and m/z reference measurements convert to reliable CCS calibration coefficients suitable for downstream ion characterization.

## When to use

When you have positive- or negative-mode ion mobility spectrometry data with tunemix reference standards (known m/z, drift times, and CCS values) and need to verify that the calibration model accurately captures the relationship between drift time, reference m/z, and collision cross section before applying it to unknown analytes.

## When NOT to use

- Input drift times or m/z values are missing, corrupted, or fall outside the instrument's valid range — validation cannot proceed without complete, clean reference data.
- Reference CCS values are not independently verified or traceable to published standards — the calibration will be no more reliable than the reference data itself.
- Calibration is intended for a different ion polarity (e.g., negative-mode coefficients applied to positive-mode unknowns) — the single-field equation is polarity-specific and cross-application will yield systematic bias.

## Inputs

- tunemix reference data file (.h5 format)
- reference m/z values (array)
- experimental drift times (array)
- known CCS values for reference standards (array)
- charge states (array)
- buffer gas mass (scalar, e.g., 28.014 for N2)

## Outputs

- calibration coefficient beta (scalar or array)
- calibration coefficient tfix (scalar)
- r-squared goodness-of-fit metric (scalar)
- fitted polynomial coefficients (array)
- calibration model object

## How to apply

Load tunemix reference data (m/z, drift_time, known CCS values, charge states) from .h5 format using deimos.load(). Call deimos.calibration.calibrate_ccs() with the reference m/z and drift-time arrays, specifying calibration mode (positive or negative) and buffer gas mass to compute calibration coefficients beta and tfix using the single-field calibration equation (Stow et al. 2017). Extract the returned r-squared metric and polynomial coefficients. Validate success by confirming r-squared ≥ 0.9999 (typical threshold from published examples); values below this threshold indicate poor calibration fit and warrant investigation of reference standard quality or instrumental drift. Store the validated coefficients for use in CCS prediction on unknowns.

## Related tools

- **DEIMoS** (Python API housing calibrate_ccs() routine and data loading via deimos.load(); performs single-field calibration equation computation and returns r-squared and coefficients) — http://github.com/pnnl/deimos
- **numpy** (Numerical array operations for handling reference m/z, drift_time, and CCS arrays; supports polynomial coefficient storage and arithmetic)
- **h5py / HDF5** (Underlying file format (.h5) for storing and retrieving tunemix reference data)

## Examples

```
tune_pos = deimos.load('example_tune_pos.h5', key='ms1'); calibration = deimos.calibration.calibrate_ccs(tune_pos['mz'], tune_pos['drift_time'], ccs=tune_pos['ccs'], charge=tune_pos['charge'], mode='positive', buffer_gas_mass=28.014); print(f'R-squared: {calibration.r_squared}')
```

## Evaluation signals

- R-squared value ≥ 0.9999 indicates excellent calibration model fit; r-squared < 0.9999 signals potential reference standard quality issues or instrumental drift requiring re-calibration.
- Calibration coefficients (beta, tfix) remain stable and reproducible across repeated calibration runs with the same reference data — instability suggests instrumental or software inconsistency.
- Residuals (observed drift time minus predicted drift time from calibration model) are randomly distributed around zero with no systematic trend; systematic deviation indicates non-linearity or instrumental artifact not captured by single-field model.
- Calibration coefficients produce CCS predictions on independent validation reference standards (not used to fit the model) that agree with published CCS values to within ±2–3% relative error, confirming external validity.
- Coefficient values and r-squared remain consistent when tunemix data are re-acquired on the same instrument under stable operating conditions; large shifts signal instrumental drift or calibration standard degradation.

## Limitations

- Single-field calibration equation assumes a linear relationship between inverse reduced mobility and CCS; deviations at very high or very low m/z or charge state may introduce systematic error.
- Calibration quality depends critically on the accuracy and stability of reference CCS standards; if reference values are incorrect or standards degrade, the fitted model will be unreliable despite high r-squared.
- The method is polarity-specific; separate calibrations must be performed and validated for positive-mode and negative-mode data — cross-polarity application will introduce systematic bias.
- R-squared ≥ 0.9999 is a typical but not absolute criterion; context-specific thresholds may differ based on instrument performance, sample complexity, or downstream analysis requirements.
- No changelog available in the DEIMoS repository — version-specific behavior or bug fixes are not explicitly documented, requiring careful cross-validation when upgrading.

## Evidence

- [other] The calibrate_ccs routine accepts reference m/z values, known CCS values, charge states, experimental drift times, and buffer gas mass, then applies the single-field calibration equation to compute calibration coefficients beta and tfix: "calibrate_ccs routine accepts reference m/z values, known CCS values, charge states, experimental drift times, and buffer gas mass, then applies the single-field calibration equation to compute"
- [other] Validation: confirm the reported R-squared is ≥0.9999 (threshold criterion from paper examples): "confirm the reported R-squared is ≥0.9999 (threshold criterion from paper examples)"
- [other] Load tunemix positive-mode reference data (m/z, drift_time, known CCS values) from example_tune_pos.h5 using deimos.load(): "Load tunemix positive-mode reference data (m/z, drift_time, known CCS values) from example_tune_pos.h5 using deimos.load()"
- [readme] Functionality includes feature detection, feature alignment, collision cross section (CCS) calibration, isotope detection, and MS/MS spectral deconvolution: "Functionality includes feature detection, feature alignment, collision cross section (CCS) calibration, isotope detection, and MS/MS spectral deconvolution"
- [results] r-squared: 0.9999784552958134: "r-squared: 0.9999784552958134"
- [readme] DEIMoS operates on N-dimensional data, largely agnostic to acquisition instrumentation: "DEIMoS operates on N-dimensional data, largely agnostic to acquisition instrumentation"