Retention time mz coordinate mapping

Skill HolobiomicsLab/asb-skill-collections/packs/metabolomics/ion-mobility/skills/retention-time-mz-coordinate-mapping

Curated, evidence-grounded skill and software-tool collections for scientific AI agents, generated by the AgenticScienceBuilder

Install

npx -y skills add HolobiomicsLab/asb-skill-collections --skill retention-time-mz-coordinate-mapping

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when when you have mass-spectrometry data in tabular form (Pandas DataFrame) with columns for m/z, retention time or ion mobility, and intensity, and you need to visualize the 2D distribution of peaks to assess peak separation, detect co-elution, or examine chromatographic and mass resolution.

The file declares its own license as CC-BY-4.0. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

6.7 KB, as published. Nobody here has run it

retention-time-mz-coordinate-mapping

Summary

Map mass-spectrometry data onto a two-dimensional coordinate system using retention time (or ion mobility) as one axis and m/z as the other, enabling interactive or static visualization of peak maps. This skill is essential for visualizing the joint distribution of analytes across time and mass dimensions.

When to use

When you have mass-spectrometry data in tabular form (Pandas DataFrame) with columns for m/z, retention time or ion mobility, and intensity, and you need to visualize the 2D distribution of peaks to assess peak separation, detect co-elution, or examine chromatographic and mass resolution together.

When NOT to use

Input data lacks retention time or ion mobility information—use 1D spectrum visualization instead.
You require 3D visualization with z-axis as a spatial dimension beyond intensity—use peakmap(plot3d=True) with plotly backend instead.
Data is already aggregated to a feature table or intensity matrix without original m/z and time coordinates.

Inputs

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

Outputs

Interactive Bokeh plot object (when backend='ms_bokeh')
Static matplotlib figure object (when backend='matplotlib' or default)
2D peak map visualization with optional marginal plots

How to apply

Load mass-spectrometry data into a Pandas DataFrame with required columns: m/z, retention time (or ion mobility), and intensity. Set the Pandas plotting backend to 'ms_bokeh' (for interactive Bokeh plots) or keep matplotlib default (for static plots) using pd.set_option(). Call the DataFrame.plot() method with x and y parameters specifying the column names for m/z and retention time, kind='peakmap', and backend='ms_bokeh' (or omit backend for matplotlib). Optionally enable marginal plots by setting add_marginals=True to display marginal chromatograms and spectra on the axes. The resulting plot renders intensity as a third dimension (typically color or z-axis height) to create a 2D peak map visualization.

Related tools

pyOpenMS-viz (Primary library providing the plotting API and peakmap visualization kind for Pandas DataFrames) — https://github.com/OpenMS/pyopenms_viz
Pandas (Data structure (DataFrame) that holds m/z, retention time, and intensity columns; provides plot() method interface)
bokeh (Interactive plotting backend for rendering 2D peak maps with hover tooltips and zoom/pan interactions)
matplotlib (Static plotting backend alternative for rendering 2D peak maps as raster images)

Examples

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

Evaluation signals

Verify that the resulting plot displays both m/z on one axis and retention time (or ion mobility) on the other axis with correct column labels.
Check that intensity is encoded as a visual third dimension (e.g., color intensity or contour height) and matches expected peak magnitudes from the input DataFrame.
If add_marginals=True, confirm that marginal plots on the axes correctly represent 1D chromatograms and spectra derived from projecting the 2D data.
For interactive plots, test that hover tooltips reveal m/z, retention time, and intensity values for individual peaks.
Confirm that peak positions in the 2D plot correspond to non-zero intensity rows in the input DataFrame and that no rows are dropped or misaligned.

Limitations

The peakmap plot requires exactly three dimensions (x, y, z); missing retention time or m/z will raise an error.
3D peakmap visualization (plot3d=True) is not supported by the bokeh backend—use plotly backend instead.
Marginal plots (add_marginals=True) may reduce clarity when the 2D peak map is already dense; consider filtering or downsampling large datasets before visualization.
Column names must be explicitly specified; the function does not auto-detect standard MS column names.

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)"