# Pandas Accessor Integration

> Use when you have mass-spectrometry data in a Pandas DataFrame and need to expose plot kinds (spectrum, chromatogram, mobilogram, peakmap) as a `.plot(kind='...

- Skill: `holobiomicslab/pandas-accessor-integration` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/pandas-accessor-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/pandas-accessor-integration/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/pandas-accessor-integration

---


# pandas-accessor-integration

## Summary

Integrate a custom visualization backend into Pandas DataFrames via the accessor pattern, enabling domain-specific plot kinds (spectrum, chromatogram, mobilogram, peakmap) to be called directly on DataFrame objects with a consistent API across multiple plotting backends (matplotlib, bokeh, plotly).

## When to use

You have mass-spectrometry data in a Pandas DataFrame and need to expose plot kinds (spectrum, chromatogram, mobilogram, peakmap) as a `.plot(kind='...')` interface that routes to backend-specific rendering (matplotlib for static, bokeh or plotly for interactive) without requiring users to import backend-specific classes directly.

## When NOT to use

- You are visualizing non-mass-spectrometry data; use standard pandas.plotting instead.
- You need custom plot kinds not in the supported set (spectrum, chromatogram, mobilogram, peakmap); extend the base classes first.
- Your data is already in a format other than Pandas DataFrame; convert to DataFrame first before using the accessor.

## Inputs

- pandas.DataFrame with mass-spectrometry columns (m/z, intensity, retention time, mobility, etc.)
- kind parameter (string: 'spectrum', 'chromatogram', 'mobilogram', 'peakmap')
- backend parameter (string: 'matplotlib', 'bokeh', or 'plotly')
- x, y, z column names (strings)
- optional configuration object (SpectrumConfig, ChromatogramConfig, MobilogramConfig, PeakMapConfig)

## Outputs

- plot object (matplotlib Figure, bokeh Figure, or plotly Figure)
- interactive or static visualization rendered to display or file

## How to apply

Register a custom pandas accessor (e.g., `@pd.api.extensions.register_dataframe_accessor('plot')`) that intercepts the `.plot(kind=...)` call. Inside the accessor's `__call__` or `plot()` method, implement a kind-dispatch mechanism that maps the `kind` argument ('spectrum', 'chromatogram', 'mobilogram', 'peakmap') to the appropriate concrete plot subclass (SpectrumPlot, ChromatogramPlot, MobilogramPlot, PeakMapPlot). Determine the backend from a user-supplied or default parameter (backend='matplotlib'|'bokeh'|'plotly'), then instantiate the corresponding backend-specific subclass (e.g., MATPLOTLIBSpectrumPlot, BOKEHSpectrumPlot) with x, y, and optional z column names and a configuration object (SpectrumConfig, ChromatogramConfig, etc.). Call the backend-specific `generate()` method to produce and return the plot object. This pattern allows users to write `df.plot(x='m/z', y='intensity', kind='spectrum', backend='bokeh')` without knowing the underlying class hierarchy.

## Related tools

- **Pandas** (Provides the DataFrame object and accessor registration pattern; used for data manipulation and as the entry point for plot dispatch) — https://pandas.pydata.org
- **matplotlib** (Backend for static plot rendering; instantiated via MATPLOTLIBPlot and concrete subclasses (MATPLOTLIBSpectrumPlot, MATPLOTLIBChromatogramPlot, etc.))
- **bokeh** (Backend for interactive plot rendering; instantiated via BOKEHPlot and concrete subclasses (BOKEHSpectrumPlot, BOKEHChromatogramPlot, etc.))
- **plotly** (Backend for interactive plot rendering; instantiated via PLOTLYPlot and concrete subclasses (PLOTLYSpectrumPlot, PLOTLYChromatogramPlot, etc.))
- **pyOpenMS-viz** (Implements the accessor integration, class hierarchy, and kind-dispatch mechanism for mass-spectrometry visualization) — https://github.com/OpenMS/pyopenms_viz

## Examples

```
ms_data.plot(x="m/z", y="intensity", kind="spectrum", backend="bokeh")
```

## Evaluation signals

- Verify that `df.plot(kind='spectrum')` returns a plot object of the expected backend type without raising AttributeError or NotImplementedError.
- Confirm that the same DataFrame and parameters produce consistent output when backend is switched from 'matplotlib' to 'bokeh' or 'plotly' (same data mapped to x, y, z axes).
- Check that invalid `kind` values raise a clear ValueError identifying supported plot kinds.
- Validate that configuration objects (SpectrumConfig, ChromatogramConfig, etc.) are passed through to the backend-specific `generate()` method and reflected in plot styling (axes labels, colors, etc.).
- Ensure that the accessor does not conflict with pandas' native `.plot()` method by testing backward compatibility on standard plot kinds (line, scatter, bar).

## Limitations

- The accessor pattern requires explicit registration and may conflict with other custom accessors on the same DataFrame class.
- All plot kinds must be predefined in the concrete subclass hierarchy; dynamic or ad-hoc plot kinds cannot be added via the accessor alone.
- Performance may degrade for very large DataFrames if data is not pre-filtered or aggregated before passing to the accessor.
- The accessor provides a unified API but backend-specific features (e.g., 3D plots in plotly but not bokeh for peakmap) may still require conditional logic or fallback behavior.

## Evidence

- [other] Implement a kind-dispatch mechanism in the pandas plotting backend accessor that routes kind='spectrum', 'chromatogram', 'mobilogram', 'peakmap' to the appropriate concrete plot class constructor based on backend selection.: "Implement a kind-dispatch mechanism in the pandas plotting backend accessor that routes kind='spectrum', 'chromatogram', 'mobilogram', 'peakmap' to the appropriate concrete plot class constructor"
- [readme] pyOpenMS-Viz provides a simple interface for extending the plotting capabilities of Pandas DataFrames for creating static or interactive visualizations of mass spectrometry data.: "provides a simple interface for extending the plotting capabilities of Pandas DataFrames for creating static or interactive visualizations of mass spectrometry data"
- [readme] Flexible plotting API that interfaces directly with Pandas DataFrames; Support for multiple plotting backends: matplotlib (static), bokeh and plotly (interactive): "Flexible plotting API that interfaces directly with Pandas DataFrames; 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"
- [other] Plot directly from a pandas dataframe object: "Plot directly from a pandas dataframe object"