# Ptairms

> ptairMS

- Skill: `biomate-ai/ptairms` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/ptairms`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/ptairms/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/ptairms

---


# ptairMS

## Workflows

### Standard Workflow

Preprocess a directory of raw PTR-TOF-MS HDF5 files to calibrate, detect peaks, align samples, impute missing values, annotate VOCs, and export an ExpressionSet.

```r
library(ptairMS)
dirRaw <- system.file("extdata/exhaledAir", package = "ptairData")

# Create ptrSet
exhaledPtrset <- createPtrSet(
  dir = dirRaw, 
  setName = "exhaledPtrset", 
  mzCalibRef = c(21.022, 60.0525), 
  fracMaxTIC = 0.7, 
  saveDir = NULL
)

# Detect peaks
exhaledPtrset <- detectPeak(exhaledPtrset)

# Align samples
exhaledEset <- alignSamples(exhaledPtrset, group = "individual", fracGroup = 1, fracExp = 1/6)

# Impute missing values
exhaledEset <- ptairMS::impute(exhaledEset, exhaledPtrset)

# Annotate VOCs
exhaledEset <- annotateVOC(exhaledEset)

# Export
writeEset(exhaledEset, dirC = file.path(getwd(), "processed_dataset"))
```
*Note: Inputs are a directory containing raw HDF5 files (.h5); the output is an ExpressionSet object and exported TSV files.*

### Single Raw File Processing

This package implements a suite of methods to preprocess data from PTR-TOF-MS instruments (HDF5 form

**Steps:**
1. Read the raw file using readRaw (exactly as documented)
2. Perform calibration on the single raw object
3. Determine time limits (expiration/headspace limits)
4. Write named output files for the meaningful results

```r
library(ptairMS)
dirRaw <- system.file("extdata/exhaledAir", package = "ptairData")
samplePath <- getFileNames(createPtrSet(dir = dirRaw, setName = "temp", mzCalibRef = c(21.022, 60.0525), saveDir = NULL), fullNames = TRUE)[1]

# 1. Read the raw file
sampleRaw <- readRaw(samplePath, calib = FALSE)

# 2. Perform calibration (done during readRaw or via calibration on ptrSet)
# 3. Determine time limits
expirationLimit <- timeLimits(sampleRaw, fracMaxTIC = 0.5, plotDel = TRUE, mzBreathTracer = 60.05)
```
*Note: Inputs are a path to a single raw HDF5 file; the output is the determined time limits of expiration or headspace duration.*

## When to Use
- To process raw PTR-TOF-MS data in HDF5 format (`.h5` extension) using `createPtrSet()`.
- To perform mass axis calibration using reference masses with `calibration()`.
- To detect and quantify peaks in PTR-TOF-MS spectra using `detectPeak()`.
- To align peaks across multiple samples and generate an `ExpressionSet` using `alignSamples()`.
- To impute missing values by returning to the raw data using `impute()`.
- To annotate features using the Human Breathomics Database via `annotateVOC()`.

## When NOT to Use
- For general LC-MS or GC-MS metabolomics preprocessing; use `xcms` instead.
- For general proteomics mass spectrometry data processing; use `MSnbase` or `Spectra` instead.

## Data Requirements
- Raw PTR-TOF-MS data files in HDF5 format (`.h5`).
- Reference calibration masses (e.g., `c(21.022, 60.0525)`).

## Key Parameters
- **mzCalibRef**: Numeric vector of reference masses used for mass axis calibration.
- **fracMaxTIC** (`0.7`): Fraction of maximum Total Ion Chromatogram (TIC) used to determine expiration or headspace time limits.
- **mzBreathTracer**: Mass used to trace expiration phases (e.g., `60.05` for acetone).
- **calibrationPeriod** (`60`): Time interval in seconds for periodic calibration to correct mass drift.
- **group**: Column name in sample metadata used for grouping during sample alignment.
- **fracGroup**: Minimum fraction of samples in at least one group where a peak must be detected to be retained.
- **fracExp**: Minimum fraction of samples where a peak must be significantly higher than background to be retained.
- **pValGreaterThres**: p-value threshold for comparing expiration/headspace phases to background.

## Best Practices
- Use `plot(ptrSet)` to check calibration errors (in ppm), resolution, and primary ion isotope intensity over time.
- Use `plotCalib()` to inspect the average total ion spectrum around reference masses if calibration errors are high.
- Use `plotTIC()` with `showLimits = TRUE` and `baselineRm = TRUE` to verify the detected expiration or headspace time limits.
- Use `plotRaw()` or `plotFeatures()` to visualize raw spectra and check the robustness of potential markers.
- Perform log2 transformation on the resulting `ExpressionSet` intensities using `log2(exprs(eset))` to stabilize variance before statistical analysis.

## Common Pitfalls
- Calibration drift due to temperature changes. Fix by setting an appropriate `calibrationPeriod` (default 60 seconds) to perform periodic calibration.
- Incorrect expiration or headspace detection. Fix by adjusting `fracMaxTIC` or specifying a specific `mzBreathTracer` in `changeTimeLimits()`.
- Modifying row names of sample metadata during external editing. Fix by ensuring row names always match the exact raw file names when using `importSampleMetadata()`.

## Alternatives
- `xcms` for comprehensive preprocessing of LC-MS and GC-MS data.
- `MSnbase` for general mass spectrometry data container and processing.
- `Spectra` for low-level mass spectrometry raw data representation.

## Citations
- Roquencourt et al. (2026), ptairMS: Processing and analysis of PTR-TOF-MS data.
- Blake et al. (2009), Proton Transfer Reaction Mass Spectrometry.

## References
- Homepage: bioconductor.org/packages/ptairms
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/ptairms/inst/doc/ptairMS.html