# Chromatogram Retention Time Visualization

> Use when you have mass spectrometry data loaded as a pandas DataFrame with at minimum two numeric columns representing retention time and intensity values, and you need to generate a chromatogram visualization for exploratory analysis, quality control, or publication.

- Skill: `holobiomicslab/chromatogram-retention-time-visualization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/chromatogram-retention-time-visualization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/chromatogram-retention-time-visualization/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/chromatogram-retention-time-visualization

---


# chromatogram-retention-time-visualization

## Summary

Generate static or interactive chromatogram plots from mass spectrometry data by mapping retention time (RT) to the x-axis and intensity to the y-axis using pyOpenMS-viz with a specified plotting backend. This skill enables publication-ready visualization of 1D chromatographic traces across multiple plotting backends (matplotlib, bokeh, plotly) while leveraging pandas DataFrames for flexible column mapping.

## When to use

Apply this skill when you have mass spectrometry data loaded as a pandas DataFrame with at minimum two numeric columns representing retention time and intensity values, and you need to generate a chromatogram visualization for exploratory analysis, quality control, or publication. Trigger conditions include: (1) data is already in or convertible to a pandas DataFrame from CSV, mzML, or similar MS data formats; (2) you want to inspect peak patterns across the retention time dimension; (3) you need to produce static (matplotlib) or interactive (bokeh/plotly) output suitable for notebooks or web applications.

## When NOT to use

- Input data lacks retention time or intensity dimensions — use spectrum or peakmap visualization instead.
- You need 2D or 3D mass spectrometry heatmap output (m/z vs. RT vs. intensity) — use peakmap kind instead.
- Your data is already pre-aggregated into a static image or bitmap — visualization skill is not needed.

## Inputs

- pandas DataFrame with numeric 'rt' (retention time) and 'intensity' columns
- mzML file (converted to pandas DataFrame via pyOpenMS or similar loader)
- CSV file with retention time and intensity traces (loaded as pandas DataFrame)

## Outputs

- static chromatogram figure (matplotlib.figure.Figure or saved PNG/PDF)
- interactive chromatogram visualization (bokeh Plot or plotly Figure object)
- saved chromatogram file (PNG, PDF, or HTML depending on backend)

## How to apply

First, load your mass spectrometry data into a pandas DataFrame, ensuring columns named or mapped to 'rt' (retention time) and 'intensity' exist. Second, select your target plotting backend and configure it via `pd.set_option('plotting.backend', 'ms_matplotlib')` or the equivalent for bokeh/plotly. Third, call `.plot(x='rt', y='intensity', kind='chromatogram')` on the DataFrame, optionally using the 'by' parameter to facet by mass-to-charge (m/z) value if multiple traces are present. Fourth, verify the resulting figure displays a line or area plot with retention time on the x-axis and intensity on the y-axis, with peaks corresponding to known compound elution times. Fifth, save the figure as PNG or vector format using matplotlib's `savefig()` or the backend's equivalent export method. The rationale is that pyOpenMS-viz abstracts backend differences into a unified pandas plotting API, avoiding boilerplate matplotlib/bokeh/plotly code while ensuring column names map correctly to MS semantics.

## Related tools

- **pyOpenMS-viz** (Primary visualization library providing unified pandas plotting API for chromatogram rendering across matplotlib, bokeh, and plotly backends) — https://github.com/OpenMS/pyopenms_viz
- **pandas** (DataFrame container and manipulation library; .plot() method dispatches to pyOpenMS-viz backend)
- **matplotlib** (Static chromatogram rendering backend; handles figure generation and file export (PNG, PDF))
- **bokeh** (Interactive chromatogram rendering backend; enables hover tooltips and browser-based exploration)
- **plotly** (Interactive chromatogram rendering backend; supports both static and interactive output including 3D variants)

## Examples

```
import pandas as pd; ms_data = pd.read_csv('chromatogram.csv'); pd.set_option('plotting.backend', 'ms_matplotlib'); ms_data.plot(x='rt', y='intensity', kind='chromatogram'); plt.savefig('chromatogram.png', dpi=300)
```

## Evaluation signals

- Output figure displays a line or area plot with retention time values on x-axis and corresponding intensity values on y-axis
- Peak positions in the chromatogram align with expected retention times for known compounds in the sample
- When 'by' parameter is used, faceted subplots correctly separate traces by m/z or other grouping column without data loss
- Figure dimensions, axis labels, and title are readable and conform to publication standards (e.g., high DPI, legible fonts)
- Saved file format (PNG/PDF/HTML) is correct and opens without corruption; file size is appropriate for backend choice

## Limitations

- Requires retention time and intensity columns to be present and numeric; missing or null values may cause plot errors or distorted visualization.
- The 'by' parameter assumes a discrete grouping column (e.g., m/z); continuous variables will not facet meaningfully.
- Interactive backends (bokeh, plotly) have limited support for certain advanced matplotlib customizations (e.g., custom colormaps, complex annotations).
- Large datasets (millions of RT-intensity points) may render slowly or consume significant memory in interactive backends; consider downsampling or aggregation.
- Consistent axis scaling and labeling depend on correct column naming; typos or case mismatches will cause KeyError exceptions.

## Evidence

- [other] Load mass spectrometry data into pandas DataFrame with retention time (rt) and intensity columns: "Load mass spectrometry data into a pandas DataFrame from a deposited CSV or mzML file containing retention time (rt) and intensity columns."
- [other] Set pandas plotting backend and call .plot() with chromatogram kind parameter: "Set the pandas plotting backend to 'ms_matplotlib' using pd.set_option('plotting.backend', 'ms_matplotlib'). 3. Call the .plot() method on the DataFrame with parameters x='rt', y='intensity',"
- [other] Use 'by' parameter to facet by mass-to-charge when multiple traces present: "Optionally use the 'by' parameter to separate different mass traces if multiple mass-to-charge values are present in the data."
- [other] Save figure using matplotlib savefig for publication and archival: "Save the resulting static figure as a PNG file using matplotlib's savefig() method for publication or archival."
- [readme] pyOpenMS-viz supports multiple plotting backends for static and interactive chromatogram visualization: "Support for multiple plotting backends: matplotlib (static), bokeh and plotly (interactive)"
- [readme] Chromatogram is a supported plot type requiring x and y dimensions: "Chromatogram    | x, y                    | chromatogram                                              | ✓              | ✓         | ✓"
- [intro] pyOpenMS-viz integrates seamlessly with plotting backends and leverages pandas: "integrates seamlessly with various plotting library backends (matpotlib, bokeh and plotly) and leverages the power of Pandas for data manipulation and representation"