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"
1---2name: pandas-accessor-integration3description: 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='...4license: CC-BY-4.05---67# pandas-accessor-integration89## Summary1011Integrate 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).1213## When to use1415You 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.1617## When NOT to use1819- You are visualizing non-mass-spectrometry data; use standard pandas.plotting instead.20- You need custom plot kinds not in the supported set (spectrum, chromatogram, mobilogram, peakmap); extend the base classes first.21- Your data is already in a format other than Pandas DataFrame; convert to DataFrame first before using the accessor.2223## Inputs2425- pandas.DataFrame with mass-spectrometry columns (m/z, intensity, retention time, mobility, etc.)26- kind parameter (string: 'spectrum', 'chromatogram', 'mobilogram', 'peakmap')27- backend parameter (string: 'matplotlib', 'bokeh', or 'plotly')28- x, y, z column names (strings)29- optional configuration object (SpectrumConfig, ChromatogramConfig, MobilogramConfig, PeakMapConfig)3031## Outputs3233- plot object (matplotlib Figure, bokeh Figure, or plotly Figure)34- interactive or static visualization rendered to display or file3536## How to apply3738Register 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.3940## Related tools4142- **Pandas** (Provides the DataFrame object and accessor registration pattern; used for data manipulation and as the entry point for plot dispatch) — https://pandas.pydata.org43- **matplotlib** (Backend for static plot rendering; instantiated via MATPLOTLIBPlot and concrete subclasses (MATPLOTLIBSpectrumPlot, MATPLOTLIBChromatogramPlot, etc.))44- **bokeh** (Backend for interactive plot rendering; instantiated via BOKEHPlot and concrete subclasses (BOKEHSpectrumPlot, BOKEHChromatogramPlot, etc.))45- **plotly** (Backend for interactive plot rendering; instantiated via PLOTLYPlot and concrete subclasses (PLOTLYSpectrumPlot, PLOTLYChromatogramPlot, etc.))46- **pyOpenMS-viz** (Implements the accessor integration, class hierarchy, and kind-dispatch mechanism for mass-spectrometry visualization) — https://github.com/OpenMS/pyopenms_viz4748## Examples4950```51ms_data.plot(x="m/z", y="intensity", kind="spectrum", backend="bokeh")52```5354## Evaluation signals5556- Verify that `df.plot(kind='spectrum')` returns a plot object of the expected backend type without raising AttributeError or NotImplementedError.57- 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).58- Check that invalid `kind` values raise a clear ValueError identifying supported plot kinds.59- 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.).60- Ensure that the accessor does not conflict with pandas' native `.plot()` method by testing backward compatibility on standard plot kinds (line, scatter, bar).6162## Limitations6364- The accessor pattern requires explicit registration and may conflict with other custom accessors on the same DataFrame class.65- All plot kinds must be predefined in the concrete subclass hierarchy; dynamic or ad-hoc plot kinds cannot be added via the accessor alone.66- Performance may degrade for very large DataFrames if data is not pre-filtered or aggregated before passing to the accessor.67- 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.6869## Evidence7071- [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"72- [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"73- [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)"74- [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"75- [other] Plot directly from a pandas dataframe object: "Plot directly from a pandas dataframe object"
HolobiomicsLab