HolobiomicsLab mass-spectrometry-data-formatting
Summary
Transform raw GC-MS CSV output into a searchable, nested data structure indexed by compound identity and analytical features. This skill prepares mass spectrometry data for downstream sorting, aggregation, and cheminformatics queries by integrating retention time, m/z peaks, and published chemical metadata.
When to use
Apply this skill when you have raw GC-MS output exported as CSV (containing columns: Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name) and need to enable intelligent filtering by retention time and mass, cross-sample aggregation, or lookup of published chemical synonyms and structural properties before downstream analysis or curation.
When NOT to use
- Input CSV lacks any of the six required column names (Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name) — preprocessing or reformatting is required before calling spreadOut().
- Compound names are already standardized identifiers or ChEBI/PubChem CIDs — webchem metadata lookup will fail or be redundant.
- Data is already in a preprocessed spread/matrix format — skip directly to mzExacto() or categorate().
Inputs
- CSV file with columns: Component.RT, Base.Peak.MZ, Component.Area, Compound.Name, Match.Factor, File.Name
Outputs
- R list object (standard_spread) containing reshaped matrices and nested metadata list (webInfo)
- RDS serialized file for persistence and downstream function compatibility
How to apply
Load the raw CSV using R's read.csv() and pass it to spreadOut(), which internally: (1) extracts and reshapes the six required columns into separate matrices with samples as columns; (2) queries webchem to retrieve published metadata (all synonyms, top m/z peaks, exact molecular mass, retention time ranges) for each unique Compound.Name; (3) constructs unique identifiers by concatenating retention time and exact mass (rtBYmass); (4) assembles a nested list (webInfo) keyed by compound name, storing all aliases and spectral/physical properties; (5) aggregates all matrices and metadata into a single R list object (standard_spread) and serializes as RDS. This transformation enables subsequent filtering by Match.Factor threshold, sorting by retention times and published masses, and aggregation across sample replicates using all published names and top m/z peaks.
Related tools
- webchem (Retrieves published chemical metadata (synonyms, m/z peaks, molecular mass, retention time ranges) for each detected compound name via PubChem and related chemical databases) — https://cran.r-project.org/web/packages/webchem/index.html
- ChemmineR (Provides cheminformatics utilities for structural and property-based queries on the aggregated chemical library) — https://www.bioconductor.org/packages/release/bioc/html/ChemmineR.html
- R (Programming language and runtime environment for executing spreadOut() and serializing the output as RDS)
- Agilent Unknowns Analysis (Recommended software for generating the input CSV in the default format with correct column names and data types) — https://www.agilent.com/cs/library/usermanuals/public/G3335-901
Examples
input_dat = read.csv('your/gcms/dataset.csv'); input_spread = spreadOut(input_dat)
Evaluation signals
- Verify the output standard_spread list contains exactly six named matrix elements (one per input column) with consistent dimensions: samples as columns, entries as rows.
- Check that webInfo nested list is keyed by unique Compound.Name values and each entry contains published synonyms, top m/z peaks, exact molecular mass, and retention time ranges (non-null).
- Confirm rtBYmass identifiers are unique and follow the format 'retention_time_exact_mass' for each sample–compound combination.
- Validate that the RDS file is readable by R's readRDS() and recreates the standard_spread structure without loss or corruption.
- Spot-check one or two Compound.Name entries in webInfo against PubChem directly to confirm webchem successfully retrieved published data.
Limitations
- Requires exact or near-exact Compound.Name matching during webchem lookup; poorly formatted or ambiguous chemical names will fail to retrieve metadata or return incorrect entries.
- Depends on external database availability (PubChem, LOTUS, KEGG, FEMA, FDA/SPL); network failures or database downtime will interrupt metadata collection.
- Retention time prediction and m/z peak lists are taken from published databases and may not match the specific GC-MS instrument, column, or method used to generate the input data.
- Large CSV files with hundreds of unique compounds may incur significant API call overhead and latency during webchem metadata retrieval.
Evidence
- [other] spreadOut() prepares the read-in CSV for intelligent sorting by retention times and published masses, followed by aggregation using all published names and top m/z peaks: "spreadOut() prepares the read in .CSV for intelligent sorting (using retention times and published masses) then aggregation (using all published names and top m/z peaks)"
- [readme] The input CSV must have specific column names in no particular order: "The column names MUST include: 'Component.RT', 'Component.Area', 'Base.Peak.MZ', 'File.Name', 'Compound.Name', and 'Match.Factor' in no particular order."
- [methods] webchem package is used to query published chemical databases for metadata: "webchem"
- [other] The output is a nested list indexed by compound name storing metadata: "Build a nested list (webInfo) indexed by compound name, storing all published names, top m/z peaks, exact mass, and published retention time ranges."
- [other] Output is serialized as RDS for downstream function compatibility: "Aggregate all matrices and the nested metadata list into a single R list object (standard_spread) and serialize as an RDS file."