# Interactive Plot Generation

> Use when you have loaded m/z and intensity arrays from an MZA file (via mzapy) and need to inspect a mass spectrum, extracted ion chromatogram (XIC), or arrival time distribution (ATD) visually, either for QC purposes, method development, or publication-ready output.

- Skill: `holobiomicslab/interactive-plot-generation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/interactive-plot-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/interactive-plot-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/interactive-plot-generation

---


# interactive-plot-generation

## Summary

Generate interactive matplotlib visualizations of mass spectrometry data (spectrum plots, chromatograms, mobility distributions) from HDF5-stored m/z and intensity arrays in MZA format. This skill enables rapid visual inspection and customization of multidimensional MS data before downstream analysis.

## When to use

Apply this skill when you have loaded m/z and intensity arrays from an MZA file (via mzapy) and need to inspect a mass spectrum, extracted ion chromatogram (XIC), or arrival time distribution (ATD) visually, either for QC purposes, method development, or publication-ready output. Use it when you want to overlay multiple spectra, apply m/z range filters, or export figures to disk.

## When NOT to use

- Input arrays are not paired or have mismatched lengths — validate array shape consistency before calling.
- Data has not yet been extracted from the MZA file or is still in HDF5 dataset form — use mzapy data collection methods (collect_ms1_arrays_by_rt, collect_xic_arrays_by_mz, etc.) first.
- You need statistical peak detection or quantification, not visual inspection — use mzapy.peaks.find_peaks_1d_localmax or find_peaks_1d_gauss instead.

## Inputs

- m/z array (1D numpy array of mass-to-charge ratios)
- intensity array (1D numpy array of signal intensities)
- optional m/z range window (tuple: [min_mz, max_mz])
- optional matplotlib axis object (ax)
- optional plot parameters (color, label, figsize)

## Outputs

- matplotlib axis object (ax) with plotted spectrum
- interactive display (if figname='show')
- saved figure file (if figname contains a file path)

## How to apply

Accept paired 1D input arrays: m/z values and corresponding intensity values (optionally filtered by a user-specified m/z range window). Initialize a matplotlib figure and axis, optionally accepting a pre-existing axis for subplot integration. Plot intensity as a line or stem plot against m/z using matplotlib.pyplot, respecting the specified m/z range bounds. Apply customizations including line color, axis labels, plot title or legend (if a label is provided). Return the axis object to enable further manipulation, display the plot interactively (figname='show'), or persist to disk via plt.savefig(figname) if a file path is provided. The decorator _setup_and_save_or_show_plot abstracts these display/save decisions.

## Related tools

- **matplotlib** (Core rendering engine for figure creation, axis setup, line/stem plotting, and interactive/file-based display control)
- **numpy** (Array manipulation and filtering (e.g., boolean indexing for m/z range windowing))
- **mzapy** (Data loading and array extraction from MZA HDF5 files (collect_ms1_arrays_by_rt, collect_xic_arrays_by_mz, collect_atd_arrays_by_rt_mz)) — https://github.com/PNNL-m-q/mzapy
- **h5py** (Low-level HDF5 file access (wrapped by mzapy but may be used directly for custom data retrieval))

## Examples

```
from mzapy.view import plot_spectrum; import numpy as np; mz_arr = np.array([400.1, 401.2, 450.5, 500.3]); intensity_arr = np.array([1000, 5000, 3000, 2000]); ax = plot_spectrum(mz_arr, intensity_arr, mz_range=[400, 510], color='blue', label='MS1 Scan 100', figname='spectrum.png')
```

## Evaluation signals

- Axis object is returned and contains a plotted line or stem series with non-zero data points corresponding to input m/z and intensity arrays.
- If m/z range filtering is applied, verify that all plotted points fall within [min_mz, max_mz] bounds and that points outside this range are absent.
- If figname='show', plot appears in an interactive window; if figname is a file path, the file is created and is valid (file size > 0, format matches expected suffix).
- Axis labels, legend (if label provided), and color customizations are correctly applied and visible in the rendered output.
- Multiple invocations on the same axis (passed as parameter) correctly overlay spectra without clearing previous data; single invocation with no ax parameter creates a new figure.

## Limitations

- Performance degrades for very large arrays (>>100k points); consider downsampling or subsampling m/z windows for real-time interaction.
- stem plots can become visually cluttered when m/z ranges are very wide; narrow the m/z range window or switch to line plots for dense spectra.
- Interactive display (figname='show') requires a display environment (X11, GUI backend); will fail in headless contexts unless redirected to file output.
- No built-in mass accuracy validation or unit conversion; assumes input m/z values are in Daltons and intensity in arbitrary units as stored in MZA.
- Overlay of multiple spectra on the same axis requires manual loop and axis reuse; no built-in spectral alignment or normalization.

## Evidence

- [other] 1. Accept input arrays (m/z values, intensity values) and optional parameters (m/z range, color, label, figsize). 2. Initialize matplotlib figure and axis using _setup_and_save_or_show_plot decorator or accept existing ax.: "Accept input arrays (m/z values, intensity values) and optional parameters (m/z range, color, label, figsize). 2. Initialize matplotlib figure and axis using _setup_and_save_or_show_plot decorator or"
- [other] 3. Plot intensity as a line or stem plot against m/z values using matplotlib.pyplot, respecting the specified m/z range window.: "Plot intensity as a line or stem plot against m/z values using matplotlib.pyplot, respecting the specified m/z range window."
- [other] 4. Customize plot appearance (color, label, axis labels) and conditionally add legend if label is provided. 5. Return ax for further customization, display interactively if figname='show', or save to file if figname contains a path using plt.savefig.: "Customize plot appearance (color, label, axis labels) and conditionally add legend if label is provided. 5. Return ax for further customization, display interactively if figname='show', or save to"
- [other] A Python package that provides an interface to unprocessed MS data in the MZA format, with matplotlib as a dependency for visualization operations.: "mzapy provides a Python interface to unprocessed MS data in the MZA format, with matplotlib as a dependency for visualization operations."
- [readme] Spectra are stored omitting zero-intensity values and as two jagged arrays, one in each corresponding group and named as the "Scan" value in the metadata table: * Arrays_intensity (HDF5 group): contains 1D arrays with intensity values. * Arrays_mz (HDF5 group): contains 1D arrays with mass-to-charge (m/z) values.: "Spectra are stored omitting zero-intensity values and as two jagged arrays, one in each corresponding group: Arrays_intensity (HDF5 group): contains 1D arrays with intensity values. Arrays_mz (HDF5"