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