---
name: data-visualization-from-tabulated-results
description: Use when after executing a MassQL query that returns a tabulated results DataFrame (e.g., MS1 or MS2 scan metadata, peak intensities, retention times), and you need to produce visual summaries suitable for publication, presentation, or exploratory analysis.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_0337
  edam_topics:
  - http://edamontology.org/topic_3520
  - http://edamontology.org/topic_3375
  tools:
  - MassQL
  - MassQLab
  - pandas.DataFrame.to_csv
  techniques:
  - LC-MS
derived_from:
- doi: 10.1002/rcm.10132
  title: MassQLab
evidence_spans: []
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_massqlab_cq
    doi: 10.1002/rcm.10132
    title: MassQLab
  dedup_kept_from: coll_massqlab_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1002/rcm.10132
  all_source_dois:
  - 10.1002/rcm.10132
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# data-visualization-from-tabulated-results

## Summary

Convert tabulated mass spectrometry query results into publication-ready visualizations by generating plot images (PNG/PDF) from result DataFrames, with parallel export to CSV for data reproducibility. This skill is essential when MassQL query results must be communicated visually to stakeholders or included in reports.

## When to use

After executing a MassQL query that returns a tabulated results DataFrame (e.g., MS1 or MS2 scan metadata, peak intensities, retention times), and you need to produce visual summaries suitable for publication, presentation, or exploratory analysis. Specifically when results must be understood in both tabular form (for downstream analysis or sharing) and graphical form (for pattern recognition or reporting).

## When NOT to use

- Results have already been serialized to both CSV and image formats by a prior workflow step
- The query returned no matches (empty DataFrame) — visualization cannot be meaningfully generated from zero rows
- Output directory is read-only or lacks write permissions — file I/O will fail

## Inputs

- Tabulated query results DataFrame (in-memory pandas.DataFrame or intermediate format from MassQL query execution)
- Result metadata including scan type (MS1 or MS2), query parameters, and file associations

## Outputs

- PNG or PDF raster/vector image file(s) containing visualization(s) of the tabulated results
- CSV file containing the same tabulated results in delimited text format

## How to apply

Load the tabulated query results DataFrame into memory (generated by MassQL query execution). Determine the plot type and structure based on result columns: for MS1 results, generate traces with Gaussian fit overlays; for MS2 results, generate spectral line plots or cluster summaries. Use a plotting library (e.g., matplotlib, plotly) to render the visualization according to the result structure and dimensionality. Save the rendered figure to a raster format (PNG) or vector format (PDF) in the designated output directory. Verify that both the CSV serialization and image file are written with non-zero size and correct formatting before proceeding to downstream analysis or reporting.

## Related tools

- **MassQL** (Executes domain-specific queries on mass spectrometry data to produce tabulated results that serve as input to visualization) — https://github.com/mwang87/MassQueryLanguage
- **MassQLab** (Framework that orchestrates MassQL query execution and implements the complete serialization and visualization pipeline for results) — https://github.com/JohnsonDylan/MassQLab
- **pandas.DataFrame.to_csv** (CSV serialization method used to write tabulated results to persistent storage)

## Examples

```
from massql import msql_engine; results_df = msql_engine.process_query(query_str, filename); results_df.to_csv('output.csv'); import matplotlib.pyplot as plt; plt.figure(); plt.plot(results_df['mz'], results_df['intensity']); plt.savefig('output.png')
```

## Evaluation signals

- Both CSV and image files are present in the designated output directory
- CSV file contains all rows and columns from the results DataFrame with correct delimiters and no truncation
- Image file is non-empty (file size > 0 bytes) and renders without corruption in standard image viewers
- Image dimensions and aspect ratio are appropriate for the result structure (e.g., sufficient height for multi-row traces, sufficient width for full m/z range)
- Metadata in filenames or sidecar files correctly identifies the query name, file source, and timestamp

## Limitations

- Plot type determination relies on heuristic inspection of DataFrame columns — mismatches between result structure and assumed plot type may produce misleading or malformed visualizations
- Large results (many scans or queries) may produce extremely wide or tall images that are difficult to display or print; pagination or faceting strategies may be required
- Visualization parameters (color scheme, font size, axis ranges) are typically fixed by the framework and cannot be customized per query without code modification
- Image format choice (PNG vs. PDF) affects file size and scalability; vector formats (PDF) are preferred for publication but require additional rendering overhead

## Evidence

- [intro] Results are tabulated and saved as images and csv files: "Results are tabulated and saved as images and csv files"
- [other] MassQLab exports via two-format serialization mechanism: "MassQLab exports tabulated query results through a two-format serialization mechanism: results are saved as both images and CSV files."
- [other] CSV serialization uses pandas or equivalent: "Serialize results table to CSV format using a CSV writer (e.g. pandas.DataFrame.to_csv or equivalent)."
- [other] Visualization format and plot type determined by result structure: "Generate visualization image(s) from the tabulated results (format and plot type determined by result structure)."
- [readme] MS1 and MS2 output types include PDF and PNG image files: "ms1_traces.pdf: All Gaussian fits per query/file
- ms1_summary_traces.pdf: Summary of Gaussian fits per query
- ms1_summary_traces_inverse.pdf: Summary of Gaussian fits per file
-"