Visualizing xcms data

These helpers take an XcmsExperiment or XCMSnExp (after peak picking and, for feature plots, correspondence) and return ggplot2, patchwork, or ComplexHeatmap objects. Chromatogram overlays take XChromatograms / XChromatogram.

Examples below assume xcms is already processed. They are not evaluated when pkgdown builds this page (no dataset in CI).

library(ggplot2)
library(patchwork)

# xcms: XcmsExperiment or XCMSnExp after findChromPeaks / groupChromPeaks

flowchart TD
  xcms["XcmsExperiment or XCMSnExp"]
  chrom["XChromatograms or XChromatogram"]
  qc["Run QC: TIC, MS1 scan frequency"]
  peaks["Peaks: RT-mz map, scan counts, peak EIC"]
  feats["Features: RT-mz map, heatmap, feature EIC, injection intensity"]
  xic["XIC two-panel"]
  overlay["plot_XChromatograms or mirror"]
  fg["Feature-group EIC or similarity"]
  xcms --> qc
  xcms --> peaks
  xcms --> feats
  xcms --> xic
  xcms --> chrom
  chrom --> overlay
  xcms --> fg
  chrom --> fg

1. Choosing a plotter

Need	Function	Input class / slots	Returns
MS1 TIC overlay by `pData$group`	`plot_xcms_TIC()`	`XcmsExperiment` / `XCMSnExp`	ggplot
MS1 scan frequency vs RT	`plot_xcms_ms1_scan_freq()`	spectra on the xcms object	ggplot
All chromPeaks on the RT–m/z plane	`plot_xcms_peaks_distribution()`	`chromPeaks`	ggplot
MS1 scans overlapping each peak	`plot_xcms_peaks_ms1_scans()`	`chromPeaks` + spectra	ggplot
MS2 scans overlapping each peak	`plot_xcms_peaks_ms2_scans()`	`chromPeaks` + MS2 spectra	ggplot
EIC for one chromPeak	`plot_xcms_peaks_Chromatogram()`	`chromPeaks`	ggplot
Features on the RT–m/z plane	`plot_xcms_features_distribution()`	`featureDefinitions`	ggplot
Feature × sample intensity heatmap	`plot_xcms_features_heatmap()`	`featureValues` + `pData`	Heatmap
EIC for one feature (few samples)	`plot_xcms_feature_chromatogram()`	`featureDefinitions`	ggplot
Feature intensity vs injection order	`plot_xcms_feature_intensity()`	`featureValues` + `pData`	ggplot
Two-panel XIC (EIC + m/z–RT points)	`plot_xcms_xic()`	mz/RT-filtered xcms object	patchwork
Overlay chromatogram matrix	`plot_XChromatograms()`	`XChromatograms` / `MChromatograms`	ggplot
Tidy chromatogram table	`get_chroms_data()`	`XChromatogram` / `XChromatograms`	data.frame
Mirror two traces	`plot_Chromatograph_mirror()`	`XChromatogram` / chromatogram cell	ggplot
Pairwise EIC overlay in a feature group	`plot_xcms_feature_group_EIC_comparasion()`	`featureGroups` + EICs	ggplot
EIC similarity heatmap	`plot_xcms_feature_group_similarity()`	`otherData$EIC_Similarity`	Heatmap

2. Run-level QC

2.1 Total ion chromatogram

plot_xcms_TIC() plots MS1 TIC traces, one line per file, colored by Biobase::pData(xcms)$group. Blank and QC get fixed colors (grey / teal); remaining groups use ggsci::pal_aaas(). Line alpha shrinks when many files are present.

plot_xcms_TIC(xcms, title = "TIC")

2.2 MS1 scan frequency

plot_xcms_ms1_scan_freq() bins MS1 scans in successive rt_window-wide RT windows (default 5 s) per file and plots scan_count / rt_window. Use it to check whether the MS1 cycle is stable across the gradient (drops often mark DDA/MS2-heavy regions or source instability).

plot_xcms_ms1_scan_freq(xcms, rt_window = 5)

3. Chromatographic peaks

These plotters need peak picking (xcms::chromPeaks). Subtitles pull CentWave parameters from processHistory() (ppm, snthresh, prefilter).

3.1 Peak map

plot_xcms_peaks_distribution() draws every (non-merged, width < 60 s) peak on RT vs m/z. Color is log10(maxo); type = "o" uses point size for peak width, type = "l" draws a horizontal segment from rtmin to rtmax.

plot_xcms_peaks_distribution(xcms, type = "o")
plot_xcms_peaks_distribution(xcms, type = "l")

3.2 Scans inside each peak

plot_xcms_peaks_ms1_scans() counts MS1 scans whose RT falls in [rtmin, rtmax]. A horizontal line at 7 scans is a useful CentWave rule of thumb. With many peaks this can be slow; subset files first.

plot_xcms_peaks_ms2_scans() counts MS2 scans whose precursor m/z and RT fall in the peak box, and annotates how many peaks have 0–5 MS2 events. The xcms object must still carry MS2 spectra; an MS1-only XcmsExperiment cannot produce that overlay.

plot_xcms_peaks_ms1_scans(xcms)
plot_xcms_peaks_ms2_scans(xcms)

3.3 Peak EIC

plot_xcms_peaks_Chromatogram() extracts one peak’s EIC via get_xcms_peaks_chromatogram() and fills the [rtmin, rtmax] window.

pids <- rownames(xcms::chromPeaks(xcms))
plot_xcms_peaks_Chromatogram(xcms, peak_id = pids[[1]], rt = "expand")

rt is passed through as rt.range: "expand" (default, ±15 s), "identity" (peak box only), or "all" (full run). Extraction details: Fast chromatogram extraction.

4. Features

These plotters need correspondence (xcms::featureDefinitions).

4.1 Feature map

plot_xcms_features_distribution() is the feature analogue of the peak map: rtmed vs mzmed, color = median maxo, size = peakWidth.

plot_xcms_features_distribution(xcms)

4.2 Feature heatmap

plot_xcms_features_heatmap() draws featureValues as a ComplexHeatmap: rows are features ordered by rtmed, columns are samples ordered by injection time. Cells are log10(maxo); missing peaks are grey. A left bar encodes RT; a top bar encodes sample.type (Blank / QC / Sample) and injection order.

Positive polarity sorts pData$analysis.time.positive; negative uses analysis.time.negative. If those columns are absent, it falls back to analysis.time, then ExpTime, then the current sample order.

plot_xcms_features_heatmap(xcms)

4.3 Feature EIC (inspection)

plot_xcms_feature_chromatogram() builds a shared mz–RT box from that feature’s chromPeaks, extracts chromatograms, and overlays selected samples. If more than five samples are present, it keeps one sample per pData$group (or the first five if group is missing).

fids <- rownames(xcms::featureDefinitions(xcms))
plot_xcms_feature_chromatogram(xcms, feature.id = fids[[1]])

For many features or full-run traces, extract once with get_xcms_feature_chromatogram(), then plot with plot_XChromatograms() (section 6). The inspection helper still calls xcms::chromatogram() internally and is meant for a handful of features.

4.4 Intensity along the injection sequence

plot_xcms_feature_intensity() plots featureValues against injection order. Positive polarity sorts pData$analysis.time.positive; negative uses analysis.time.negative. Points are colored by sample.type (Blank / QC / Sample).

plot_xcms_feature_intensity(xcms, feature_id_to_show = fids[[1]])

5. Two-panel XIC

plot_xcms_xic() is a ggplot2 stand-in for xcms plot(..., type = "XIC"):

Upper panel: extracted-ion chromatogram (intensity vs RT)
Lower panel: centroid points (m/z vs RT, colored by intensity)

Supply an already filtered XcmsExperiment / XCMSnExp plus the same mz/RT windows used for filtering (axis limits).

mzr <- c(760.58, 760.60)
rtr <- c(400, 460)
xcms.filt <- xcms::filterRt(xcms::filterMz(xcms, mz = mzr), rt = rtr)

plot_xcms_xic(
  xcms.filt,
  mzr = mzr,
  rtr = rtr,
  title = "XIC",
  subtitle = sprintf("mz %.4f–%.4f; rt %.0f–%.0f s", mzr[1], mzr[2], rtr[1], rtr[2])
)

Set return.data = TRUE to get the patchwork plus the chromatogram and point data.frames for custom ggplot layers.

6. `XChromatogram` / `XChromatograms`

Extraction and plotting are separate. Convert XChromatograms / MChromatograms / XChromatogram to a tidy table with get_chroms_data() (columns rt, intensity, row, col), or pass the S4 object to plot_XChromatograms().

chroms <- get_xcms_feature_chromatogram(
  xcms, feature.id = fids[1:8], sample = "all", rt = "expand"
)

plot_XChromatograms(chroms, norm = TRUE, move = TRUE, color_by = "column")
plot_XChromatograms(chroms, norm = FALSE, move = FALSE, color_by = "row")

Argument	Effect
`norm = TRUE`	`MSnbase::normalise()` then scale intensities to 0–100
`move = TRUE`	Offset each trace in RT and intensity so overlays do not sit on top of each other
`color_by`	`"column"` = sample; `"row"` = feature / region
`label_df`	Optional `data.frame(x, y, label)` drawn with `ggrepel`

plot_Chromatograph_mirror() compares two traces (XChromatogram, Chromatogram, an XChromatograms cell, or data.frame(rt, intensity)), optionally normalizing each to its own max and flipping the second below zero.

plot_Chromatograph_mirror(
  chroms[1, 1],
  chroms[2, 1],
  labels = c(fids[[1]], fids[[2]])
)

7. Feature-group EIC views

After feature compounding, xcms::featureGroups() labels groups. Pairwise EIC scores (when stored) sit on MsExperiment::otherData(xcms)$EIC_Similarity.

fg <- unique(stats::na.omit(xcms::featureGroups(xcms)))

plot_xcms_feature_group_EIC_comparasion(
  xcms,
  feature_group = fg[[1]],
  expandRt = 2,
  min_width = 20
)

plot_xcms_feature_group_similarity(xcms, order_by = "feature_group")

How groups and the similarity matrix are built: Feature grouping with EicSimilarityParam.

8. Saving figures

Plotters return ggplot / patchwork / Heatmap objects. Save with ggplot2 or the package export helpers:

p <- plot_xcms_TIC(xcms)
ggplot2::ggsave("TIC.pdf", p, width = 8, height = 4)
open_plot_pdf(p, width = 8, height = 4)

Fast chromatogram extraction — get_xcms_chromatogram, get_xcms_peaks_chromatogram, get_xcms_feature_chromatogram
Feature grouping with EicSimilarityParam
Code: R/dev_xcms.R, R/dev_plot.R