Interactive plot embedding

interactive-plot-embedding

Summary

Generate embeddable static spectrum plot images (PNG/SVG) with embedded URLs or QR codes that link to interactive spectrum visualization endpoints, enabling publication-ready figures with clickable access to full spectral data. This skill bridges publication media (static images) with web-based interactivity for metabolomics and proteomics data.

When to use

You have resolved USI (Unified Spectrum Identifier) spectrum data from a supported repository (GNPS, MassBank, MetaboLights, Metabolomics Workbench, ProteoXchange, or MS2LDA) and need to create a figure suitable for journal publication or supplementary materials that retains a link to the full, explorable spectrum in a web browser. Use this when your goal is to enable readers to click or scan a figure in a PDF or HTML article to access interactive peak annotation, m/z filtering, and intensity scaling tools.

When NOT to use

• The spectrum source is not in a supported repository or cannot be resolved to a valid USI (e.g., proprietary local format without a public accession).
• The use case requires real-time, live spectrum data updates; static images capture a snapshot and do not auto-refresh.
• Your publication or distribution channel does not support hyperlinks or QR code scanning (e.g., some print-only journals); in this case, consider caption text with manual URL entry instead.

Inputs

• Resolved USI (Unified Spectrum Identifier) in the format mzspec:<source>:<identifier path>:<scan|accession>:<value>
• Spectrum source type (GNPS, MassBank, MetaboLights, Metabolomics Workbench, ProteoXchange, MS2LDA)
• Optional rendering parameters: m/z range, intensity scaling, peak annotation list, plot title, grid/annotation toggles

Outputs

• Static spectrum plot image (PNG or SVG) with embedded URL or QR code
• Embeddable image file suitable for PDF, HTML, or journal manuscript
• Interactive spectrum viewer URL or QR code artifact

How to apply

Resolve the USI identifier using the MetabolomicsSpectrumResolver to retrieve the spectrum's m/z values, intensities, and metadata. Render a static spectrum plot (bar/stick plot with baseline) as a raster or vector image using the resolver's /svg/ or /png/ endpoint, specifying optional parameters such as m/z range (mz_min, mz_max), intensity ceiling (max_intensity), peak annotations (annotate_peaks), grid display, and title. Generate a corresponding URL to the interactive viewer endpoint (e.g., https://metabolomics-usi.ucsd.edu/spectrum/?usi=<USI>) or QR code pointing to that URL. Embed this link as metadata within the image file or as a visible QR code overlaid on or adjacent to the static plot. Save the final embeddable image; verify that clicking or scanning the embedded link resolves to the interactive spectrum viewer for the same USI.

Related tools

• MetabolomicsSpectrumResolver (Resolves USI identifiers and generates static plot images (/svg/, /png/ endpoints) and interactive spectrum URLs; core engine for this skill) — https://github.com/mwang87/MetabolomicsSpectrumResolver
• GNPS Molecular Networking (Spectrum data source for clustered spectra USI resolution)
• MassBank (Library spectrum data source for USI resolution)
• MetaboLights (Dataset repository spectrum data source for USI resolution)
• Metabolomics Workbench (Dataset repository spectrum data source for USI resolution)
• ProteoXchange Repository (Proteomics repository spectrum data source for USI resolution)
• MS2LDA (Reference motif and spectrum data source for USI resolution)

Examples

https://metabolomics-usi.ucsd.edu/svg/?usi=mzspec:GNPS:TASK-c95481f0c53d42e78a61bf899e9f9adb-spectra/specs_ms.mgf:scan:1943&mz_min=550&mz_max=800&annotate_peaks=[[463.297,708.463,816.474]]

Evaluation signals

• The generated image file is a valid PNG or SVG raster/vector image and can be opened in standard image viewers and PDF readers.
• The embedded URL or QR code, when clicked or scanned, resolves to an interactive spectrum viewer endpoint displaying the same USI and spectrum data as the static plot.
• The static plot accurately represents the resolved spectrum's peak positions (m/z values) and relative intensities from the source repository.
• Optional parameters (m/z range, peak annotations, intensity ceiling, title) are correctly applied to the rendered image; e.g., peaks outside mz_min/mz_max are not displayed.
• The image can be embedded in a PDF, HTML article, or supplementary material without corruption and retains its hyperlink or QR code functionality.

Limitations

• USI identifiers are based on draft specifications (currently using 'mzdraft' instead of 'mzspec' prefix) and are subject to change; identifiers may break or require migration in future versions.
• The skill depends on the stability and availability of the underlying spectrum repository APIs (GNPS, MassBank, MetaboLights, etc.); if a repository is offline or removes a spectrum, the embedded link will fail.
• Static images do not auto-update if the underlying spectrum metadata or annotations in the source repository are revised after the image is generated.
• QR code embedding adds visual complexity and may not be suitable for high-resolution or print-heavy figure layouts; URL embedding as metadata may be preferable for some publication formats.
• Mirror-match plots (comparing two spectra) are supported but require two valid USI identifiers; single-spectrum and dual-spectrum rendering paths have separate parameter schemas.

Evidence

• [readme] Enable creation of embeddable images in publications that will link out to viewable/interactable spectrum plots.: "Enable creation of embeddable images in publications that will link out to viewable/interactable spectrum plots."
• [readme] 3rd party embedding for visualization of spectra that exist in repositories (e.g. MassIVE, PRIDE, PeptideAtlas). 3rd party embedding of QR code.: "3rd party embedding for visualization of spectra that exist in repositories (e.g. MassIVE, PRIDE, PeptideAtlas). 3rd party embedding of QR code."
• [other] Load resolved spectrum data; render static spectrum plot; generate/embed URL or QR code pointing to interactive viewer; save embeddable image.: "1. Load the resolved spectrum data (m/z values, intensities, metadata) from the USI resolver output. 2. Render a static spectrum plot (peaks and baseline) as a raster image (PNG or SVG) using a"
• [readme] Supported sources include GNPS Molecular Networking, GNPS Spectral Libraries, ProteoXchange, MS2LDA, MassBank, MetaboLights, and Metabolomics Workbench.: "Supported USI Types: 1. GNPS Molecular Networking Clustered Spectra 2. GNPS Spectral Libraries 3. ProteoXchange Repository Data 4. MS2LDA Reference Motifs 5. MassBank Library Spectra 6. MetaboLights"
• [readme] The resolver provides /svg/ and /png/ endpoints with optional rendering parameters including mz_min, mz_max, annotate_peaks, plot_title, and grid display.: "1. /png/ 1. /svg/ ... ## Plotting Parameters - mz_min: Minimum m/z value. - mz_max: Maximum m/z value. - annotate_peaks: ... - plot_title: Custom plot title, omit to use default"
• [readme] USI identifiers are currently in draft status and may be subject to change.: "These identifiers are based on draft USI and draft Metabolomics USI identifiers. Thus, they are subject to change, and so for the moment, they will be specified as mzdraft instead of mzspec"