# Peakmap Visualization Generation

> Use when you have mass spectrometry data loaded into a Pandas DataFrame with columns for m/z, retention time (or ion mobility), and intensity, and you need to visualize the complete 2D peak map landscape to identify co-eluting features, assess data quality, or explore retention time and.

- Skill: `holobiomicslab/peakmap-visualization-generation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/peakmap-visualization-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/peakmap-visualization-generation/raw
- Safety review: pending
- 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/peakmap-visualization-generation

---


# peakmap-visualization-generation

## Summary

Generate interactive or static 2D and 3D peak map visualizations of mass spectrometry data from Pandas DataFrames using pyOpenMS-viz with multiple plotting backends. This skill enables researchers to render retention time (or ion mobility) versus m/z intensity maps, with optional marginal chromatograms and spectra.

## When to use

Use this skill when you have mass spectrometry data loaded into a Pandas DataFrame with columns for m/z, retention time (or ion mobility), and intensity, and you need to visualize the complete 2D peak map landscape to identify co-eluting features, assess data quality, or explore retention time and mass-to-charge patterns interactively across multiple backends (matplotlib for static output, bokeh or plotly for interactive exploration).

## When NOT to use

- Input data is not a Pandas DataFrame or lacks required m/z, retention time, and intensity columns.
- You need to visualize only 1D data (single spectrum or chromatogram); use spectrum or chromatogram plot kinds instead.
- You require 3D visualization using the bokeh backend; bokeh does not support the plot3d=True parameter for peak maps.

## Inputs

- Pandas DataFrame with columns for m/z (x-axis)
- Pandas DataFrame with columns for retention time or ion mobility (y-axis)
- Pandas DataFrame with columns for intensity (z-axis, color scale)

## Outputs

- 2D peak map plot (matplotlib, bokeh, or plotly object)
- 3D peak map plot (matplotlib or plotly object, with plot3d=True)
- Interactive peak map with optional marginal chromatogram and spectrum plots

## How to apply

Load mass spectrometry data into a Pandas DataFrame with m/z, retention time (or ion mobility), and intensity columns. Set the Pandas plotting backend to the desired backend ('ms_matplotlib', 'ms_bokeh', or 'ms_plotly') using pd.set_option(). Call the DataFrame.plot() method with x and y parameters specifying the m/z and retention time column names, kind='peakmap', and backend parameter matching your chosen backend. Optionally enable marginal plots by setting add_marginals=True to display marginal chromatograms and spectra alongside the main 2D peak map. For 3D visualization, add plot3d=True (supported in matplotlib and plotly but not bokeh). Render and display the resulting plot object. The consistent API across backends allows seamless switching between static publication-quality plots and interactive web-based visualizations.

## Related tools

- **pyOpenMS-viz** (Primary visualization library providing the peakmap plot kind and multi-backend plotting interface for mass spectrometry data) — https://github.com/OpenMS/pyopenms_viz
- **Pandas** (Data container and manipulation library; DataFrames hold the m/z, retention time, and intensity data passed to the plotting API)
- **matplotlib** (Static plotting backend for generating publication-ready peak map visualizations)
- **bokeh** (Interactive plotting backend for browser-based, web-friendly peak map exploration with hover tooltips and pan/zoom)
- **plotly** (Interactive plotting backend supporting both 2D and 3D peak map visualizations with interactive controls)

## Examples

```
ms_data.plot(x="m/z", y="rt", z="intensity", kind="peakmap", backend="ms_bokeh", add_marginals=True)
```

## Evaluation signals

- Peak map renders without errors and displays m/z on x-axis, retention time (or ion mobility) on y-axis, and intensity encoded as color scale.
- If add_marginals=True is set, verify that marginal chromatogram and spectrum plots appear alongside the main 2D peak map.
- For 3D peak maps (plot3d=True), confirm that the plot is generated in matplotlib or plotly backend and displays as a 3D surface or scatter; verify it is not attempted in bokeh.
- Interactive features (zoom, pan, hover tooltips) function correctly when using bokeh or plotly backends; static image renders cleanly when using matplotlib.
- The plot integrates seamlessly with the Pandas plotting API using the consistent syntax: df.plot(x='m/z', y='rt', kind='peakmap', backend='ms_<backend>', add_marginals=True/False).

## Limitations

- Bokeh backend does not support 3D peak map visualization (plot3d=True parameter is ignored or raises an error).
- The skill requires mass spectrometry data to be pre-loaded and pre-formatted into a Pandas DataFrame; raw mass spectrometry file formats (mzML, mzXML, etc.) must be converted to DataFrame form prior to visualization.
- Performance may degrade with very large DataFrames (millions of data points) when using interactive backends; consider data subsampling or aggregation for real-time exploration.
- Marginal plots (add_marginals=True) require properly aligned retention time and m/z binning; irregular or sparse data may produce uninformative marginal visualizations.

## Evidence

- [other] Load mass spectrometry data into a Pandas DataFrame with columns for m/z, retention time (or ion mobility), and intensity: "Load mass spectrometry data into a Pandas DataFrame with columns for m/z, retention time (or ion mobility), and intensity."
- [other] Call the DataFrame.plot() method with x and y parameters specifying the m/z and retention time column names, kind='peakmap', and backend='ms_bokeh': "Call the DataFrame.plot() method with x and y parameters specifying the m/z and retention time column names, kind='peakmap', and backend='ms_bokeh'."
- [other] Optionally enable marginal plots by setting add_marginals=True to display marginal chromatograms and spectra: "Optionally enable marginal plots by setting add_marginals=True to display marginal chromatograms and spectra."
- [readme] Visualization of various mass spectrometry data types, including 1D chromatograms, spectra, and 2D peak maps: "Visualization of various mass spectrometry data types, including 1D chromatograms, spectra, and 2D peak maps"
- [readme] Support for multiple plotting backends: matplotlib (static), bokeh and plotly (interactive): "Support for multiple plotting backends: matplotlib (static), bokeh and plotly (interactive)"
- [readme] Consistent API across different plotting backends for easy switching between static and interactive plots: "Consistent API across different plotting backends for easy switching between static and interactive plots"