Matplotlib Static Figure Generation

---
name: matplotlib-static-figure-generation
description: Use when you have mass spectrometry data in a pandas DataFrame with retention
  time (rt) and intensity columns, and need to produce a static figure for publication,
  presentation, or archival.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3441
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3520
  tools:
  - pyOpenMS-viz
  - matplotlib
  - pandas
  techniques:
  - mass-spectrometry
  license_tier: open
  provenance_tier: literature
derived_from:
- doi: 10.1021/acs.jproteome.4c00873
  title: pyopenmsviz
evidence_spans:
- Chromatograms can be plotted using kind = chromatogram
- pyOpenMS-Viz is a visualization package for mass spectrometry data directly from
  pandas dataframes
- These plots can be generated by setting the `backend='ms_matplotlib'`. Matplotlib
  is useful for generating static publication quality plots.
- Multiple backends supported including matplotlib, bokeh, and plotly
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_pyopenmsviz_cq
    doi: 10.1021/acs.jproteome.4c00873
    title: pyopenmsviz
  dedup_kept_from: coll_pyopenmsviz_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1021/acs.jproteome.4c00873
  all_source_dois:
  - 10.1021/acs.jproteome.4c00873
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# matplotlib-static-figure-generation

## Summary

Generate publication-ready static visualizations of mass spectrometry data (chromatograms, spectra, peak maps) by leveraging pyOpenMS-viz's matplotlib backend integration with pandas DataFrames. This skill enables reproducible export of MS figures as PNG or other raster formats suitable for journals and archival.

## When to use

Use this skill when you have mass spectrometry data in a pandas DataFrame with retention time (rt) and intensity columns, and need to produce a static figure for publication, presentation, or archival. Matplotlib is the preferred backend when you do not require interactivity (contrast with bokeh or plotly) and need deterministic, reproducible output suitable for peer-reviewed manuscripts.

## When NOT to use

- When the analysis requires interactive exploration (zoom, pan, hover tooltips) — use bokeh or plotly backends instead.
- When the input data is not structured as a pandas DataFrame with clearly named rt and intensity columns — pre-process or reshape first.
- When the output must be embedded in a web application or dashboard — use plotly or bokeh for client-side rendering capability.

## Inputs

- pandas.DataFrame with columns: retention_time (rt) and intensity
- optional: mass-to-charge (m/z) column for multi-trace separation
- optional: mzML or CSV file path to be read into DataFrame

## Outputs

- static PNG or raster image file (savefig output)
- matplotlib Figure object (in-memory)
- matplotlib Axes object with rendered chromatogram/spectrum/peakmap

## How to apply

Load MS data into a pandas DataFrame from a deposited CSV or mzML file containing retention time (rt) and intensity columns. Set the pandas plotting backend to 'ms_matplotlib' using pd.set_option('plotting.backend', 'ms_matplotlib'). Call the .plot() method on the DataFrame with parameters x='rt', y='intensity', and kind='chromatogram' (or 'spectrum', 'peakmap' for other MS data types). Optionally use the 'by' parameter to separate different mass-to-charge (m/z) traces if multiple ion channels are present. Save the resulting figure using matplotlib's savefig() method with desired DPI and format (PNG recommended for compatibility). Verify the output by checking file existence, size > 0 bytes, and visual inspection of axis labels, data traces, and legend.

## Related tools

- **pyOpenMS-viz** (provides the pandas plotting backend ('ms_matplotlib') that abstracts matplotlib rendering for MS data types (chromatogram, spectrum, peakmap)) — https://github.com/OpenMS/pyopenms_viz
- **pandas** (DataFrame container and .plot() interface for triggering backend rendering)
- **matplotlib** (underlying static plotting library that renders figures to raster output (PNG, PDF, etc.))

## Examples

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

## Evaluation signals

- Output PNG file exists and has non-zero file size on disk.
- Figure contains correct axis labels (x='rt', y='intensity') and title corresponding to plot kind (e.g., 'chromatogram').
- Data traces are rendered without clipping or NaN propagation; all intensity values within DataFrame bounds appear on plot.
- When 'by' parameter is used for multi-trace plots, each unique m/z value is rendered as a separate subplot or trace with distinct legend entry.
- savefig() completes without exception; figure is readable by standard image viewers and importable by downstream tools (e.g., Pillow, ImageMagick).

## Limitations

- Static matplotlib output cannot be modified interactively post-generation (e.g., no zoom or pan without regeneration).
- Large datasets (>100k data points) may result in slow rendering or large file sizes; consider downsampling or aggregation before plotting.
- matplotlib backend does not support 3D peak maps; use plotly with plot3d=True for three-dimensional visualizations.
- Column naming must exactly match 'rt' and 'intensity' (or be explicitly mapped via x/y parameters); misnamed columns will cause KeyError or silent incorrect rendering.

## Evidence

- [other] Load mass spectrometry data into a pandas DataFrame from a deposited CSV or mzML file containing 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 the pandas plotting backend to 'ms_matplotlib' using pd.set_option('plotting.backend', 'ms_matplotlib').: "Set the pandas plotting backend to 'ms_matplotlib' using pd.set_option('plotting.backend', 'ms_matplotlib')."
- [other] Call the .plot() method on the DataFrame with parameters x='rt', y='intensity', kind='chromatogram' to generate a chromatogram plot.: "Call the .plot() method on the DataFrame with parameters x='rt', y='intensity', kind='chromatogram' to generate a chromatogram plot."
- [other] Save the resulting static figure as a PNG file using matplotlib's savefig() method for publication or archival.: "Save the resulting static figure as a PNG file using matplotlib's savefig() method for publication or archival."
- [readme] Support for multiple plotting backends: matplotlib (static), bokeh and plotly (interactive): "Support for multiple plotting backends: matplotlib (static), bokeh and plotly (interactive)"
- [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"