# Ccs Calibration Polynomial Fitting

> Use when you have acquired tunemix or reference standard data in ion mobility spectrometry with known m/z, drift time, and CCS values, and you need to establish a drift-time-to-CCS mapping for a specific instrument, ionization mode (positive or negative), and buffer gas.

- Skill: `holobiomicslab/ccs-calibration-polynomial-fitting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/ccs-calibration-polynomial-fitting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/ccs-calibration-polynomial-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/ccs-calibration-polynomial-fitting

---


# ccs-calibration-polynomial-fitting

## Summary

Fit a polynomial calibration model to convert ion mobility drift times and reference m/z values into collision cross section (CCS) coefficients using the single-field calibration equation. This skill produces calibration coefficients (beta and tfix) that enable downstream CCS prediction for unknown ions in positive- or negative-mode ion mobility spectrometry.

## When to use

Apply this skill when you have acquired tunemix or reference standard data in ion mobility spectrometry with known m/z, drift time, and CCS values, and you need to establish a drift-time-to-CCS mapping for a specific instrument, ionization mode (positive or negative), and buffer gas. The skill is necessary as the first step in any CCS-based feature characterization workflow.

## When NOT to use

- Do not use this skill if reference CCS standards are not available or not accurately characterized; the calibration will be unreliable.
- Do not use this skill if drift time and m/z data have not been properly preprocessed (e.g., baseline-subtracted, aligned) or contain significant instrumental noise; garbage input produces garbage calibration.
- Do not use this skill if switching between ionization modes or buffer gases without recalibrating; calibration coefficients are mode- and gas-specific.

## Inputs

- tunemix reference m/z values (numpy array or pandas Series)
- tunemix experimental drift times (numpy array or pandas Series, units: milliseconds)
- known CCS values for reference standards (numpy array, units: Ų)
- charge states (integer array or scalar)
- buffer gas mass (float, atomic mass units)
- calibration mode identifier (string: 'positive' or 'negative')

## Outputs

- calibration coefficient beta (float)
- calibration coefficient tfix (float)
- R-squared goodness-of-fit metric (float, range 0–1)
- fitted calibration model object (DEIMoS calibration model)

## How to apply

Load reference tunemix data (m/z, drift_time, known CCS values, charge states) from an HDF5 file using deimos.load(). Call deimos.calibration.calibrate_ccs() with the reference m/z and drift_time arrays, specifying the calibration mode (positive or negative), known CCS standards, and buffer gas mass. The function applies the single-field calibration equation (Stow et al. 2017) to solve for calibration coefficients beta and tfix. Extract the returned R-squared metric and polynomial coefficients. Validate that the R-squared value meets the threshold of ≥0.9999; values below this indicate poor model fit and may signal data quality issues, incorrect reference standards, or instrument miscalibration.

## Related tools

- **DEIMoS** (Python API providing calibrate_ccs() function and load() utility for HDF5 file I/O; applies single-field calibration equation to compute beta and tfix coefficients) — https://github.com/pnnl/deimos
- **numpy** (Numerical array operations for m/z, drift_time, and CCS value handling during calibration)
- **Python** (Execution environment and scripting language for DEIMoS API calls and calibration workflow)

## Examples

```
tune_pos = deimos.load('example_tune_pos.h5', key='ms1'); calibration = deimos.calibration.calibrate_ccs(tune_pos['mz'].values, tune_pos['drift_time'].values, known_ccs, charges, buffer_gas_mass, mode='positive')
```

## Evaluation signals

- R-squared metric ≥ 0.9999 (threshold from paper validation examples; values <0.99 indicate poor fit)
- Returned beta and tfix coefficients are finite, positive numbers and match expected physical ranges for the instrument and buffer gas
- Calibration model can be applied to independent test m/z and drift_time pairs and produce CCS predictions within ±5% of known standard values (typical IMS accuracy)
- Residual plot of predicted vs. observed drift times shows random scatter around zero with no systematic bias across m/z or drift_time ranges
- Model coefficients are reproducible when recalibrated with the same reference data (deterministic function)

## Limitations

- Calibration is specific to a single ionization mode (positive or negative) and buffer gas; switching modes requires recalibration.
- Accuracy depends critically on the quality and accuracy of reference CCS standards; contaminated or mislabeled standards will corrupt the model.
- The single-field calibration equation assumes ideal gas behavior and may not account for instrumental nonlinearities or space-charge effects at high ion currents.
- Extrapolation beyond the m/z and drift_time ranges covered by reference standards is not reliable; predictions are most trustworthy within the calibration domain.

## 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: "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"
- [other] yielding calibration model fit with r-squared of 0.9999784552958134: "yielding calibration model fit with r-squared of 0.9999784552958134"
- [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()"
- [other] 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)"
- [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"
- [readme] algorithm implementations simultaneously utilize all dimensions to (i) offer greater separation between features, thus improving detection sensitivity: "algorithm implementations simultaneously utilize all dimensions to (i) offer greater separation between features, thus improving detection sensitivity"