Pandas Dataframe Column Specification

pandas-dataframe-column-specification

Summary

Specify and map Pandas DataFrame columns to mass spectrometry visualization dimensions (x, y, z axes) to enable flexible adaptation of diverse data formats to pyOpenMS-viz plotting functions. This skill decouples the plotting API from rigid column naming conventions, allowing reuse across different MS data schemas.

When to use

When you have mass spectrometry data in a Pandas DataFrame with column names that do not match pyOpenMS-viz's default expectations (e.g., 'm/z' vs 'mz' or 'retention_time' vs 'rt'), or when your data uses domain-specific column labels (e.g., 'mass_to_charge', 'scan_time', 'peak_intensity'). Use this skill before calling DataFrame.plot() with kind='spectrum', 'chromatogram', 'mobilogram', or 'peakmap' to ensure the plotting function can locate and correctly interpret your x, y, and z dimensions.

When NOT to use

• Your DataFrame columns are already named according to pyOpenMS-viz conventions ('m/z', 'rt', 'intensity') and you are not switching between multiple data sources with different schemas.
• You are working with data that has already been preprocessed and reshaped by another tool—verify column names first before applying this skill.
• The visualization does not require explicit column selection (e.g., simple plots with only x and y where column order is unambiguous).

Inputs

• Pandas DataFrame with columns for m/z, retention time (or ion mobility), and intensity values

Outputs

• Column name mappings (string identifiers) ready for use in DataFrame.plot() method calls
• Validated x, y, z parameter assignments passed to plotting functions

How to apply

Identify the column names in your DataFrame that correspond to the required dimensions for your chosen plot type. For 1D plots (spectrum, chromatogram, mobilogram), you need x and y columns; for 2D plots (peakmap), you need x, y, and z. Pass these column names explicitly as parameters to the DataFrame.plot() method using the x, y, and z arguments—do not rely on implicit column order or naming conventions. For example, if your DataFrame has columns named 'mass_to_charge', 'retention_time', and 'intensity', specify these explicitly when calling plot(x='mass_to_charge', y='retention_time', z='intensity', kind='peakmap'). This mapping isolates your data schema from the visualization backend, allowing seamless switching between matplotlib, bokeh, and plotly backends without rewriting column references.

Related tools

• Pandas (Provides DataFrame structure and plot() method interface for column-aware visualization)
• pyOpenMS-viz (Accepts column name parameters (x, y, z) in plotting backend to map DataFrame columns to visualization dimensions) — https://github.com/OpenMS/pyopenms_viz
• bokeh (Interactive plotting backend that receives and renders column-specified data)
• matplotlib (Static plotting backend that receives and renders column-specified data)
• plotly (Interactive plotting backend that receives and renders column-specified data)

Examples

ms_data.plot(x="mass_to_charge", y="retention_time", z="peak_intensity", kind="peakmap", backend="bokeh")

Evaluation signals

• Column names passed to x, y, z parameters match exactly (case-sensitive) to existing DataFrame column names; no KeyError is raised when plot() is called.
• The resulting plot displays data on the correct axes—verify that m/z values appear on the expected axis (typically x for spectrum plots), retention time on the expected axis (typically x for chromatograms), and intensity on the y-axis.
• The plot renders without data corruption or axis label misalignment; visual inspection should show sensible ranges and scale.
• The same DataFrame can be re-plotted with different column specifications for different plot kinds (e.g., spectrum vs. chromatogram) without manual data transformation.
• Column specification successfully enables switching between plotting backends (matplotlib, bokeh, plotly) without changing the x, y, z parameter values.

Limitations

• Column names are case-sensitive and must match exactly; misspellings or case mismatches will result in KeyError exceptions.
• The skill assumes columns are present in the DataFrame before plotting; it does not handle missing or NaN-filled columns gracefully.
• Z-column (intensity) specification is required for 2D peakmap plots but optional or absent for 1D plots; ensure you provide the correct number of dimensions for your chosen plot kind.
• Column selection does not validate data types or ranges; if a column contains non-numeric or malformed data, the plotting backend may fail or produce incorrect visualizations.
• Multi-index DataFrames or hierarchical column names may require additional handling not covered by simple x, y, z string parameters.

Evidence

• [readme] Versatile column selection for easy adaptation to different data formats: "Versatile column selection for easy adaptation to different data formats"
• [other] Call the DataFrame.plot() method with x and y parameters specifying the m/z and retention time column names: "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'"
• [readme] Flexible plotting API that interfaces directly with Pandas DataFrames: "Flexible plotting API that interfaces directly with Pandas DataFrames"
• [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"