Post-Processing Tools for GC-MS Volatile Organic Compound Data

Provides functions for processing Shimadzu gas chromatography-mass spectrometry (GC-MS) exported text files, extracting Chemical Abstracts Service (CAS) numbers and peak areas, building abundance matrices, annotating compounds, and screening based on occurrence frequency. The package is designed for organizing, identifying, and screening volatile compounds in metabolomics and environmental studies.

postvocs

Overview

postvocs is an R package designed for automated post-processing of Shimadzu GC-MS volatile organic compound (VOC) data.

The package provides a complete workflow for transforming raw GC-MS export files into analyzable compound abundance matrices. It automates:

• parsing GC-MS text exports;
• extracting peak information and mass spectral identification results;
• constructing CAS number × sample abundance matrices;
• annotating compounds using chemical databases or user-provided libraries;
• performing frequency-based compound screening;
• exporting processed results without requiring intermediate files.

The workflow is fully modular, allowing users to perform individual processing steps or run the complete pipeline from raw GC-MS files to final VOC screening results.

Installation

The development version can be installed from GitHub using:

# install.packages("devtools")

devtools::install_github("HanXT97/postvocs")

Load the package:

library(postvocs)

Workflow

The postvocs workflow converts raw GC-MS exports into processed VOC analysis results:

1. Parse GC-MS exports
   • Single file: process_gcms_txt()
   • Batch: batch_process_gcms()
2. Extract peak areas → extract_peak_areas()
3. Build abundance matrix → build_cas_abundance()
4. Annotate compounds → annotate_compounds()
5. Frequency screening → filter_by_frequency()
6. Export results
   • Analysis results: save_postvocs_results()
   • Raw parsing: save_gcms_results()

Quick Start

1. Batch process GC-MS text files

Parse all Shimadzu GC-MS exported .txt files and map raw filenames to sample names.

batch <- batch_process_gcms(
  txt_dir = "data-raw/txt",
  sample_file = "data-raw/SampleID.xlsx"
)

2. Extract peak areas

Extract CAS numbers and total peak areas from parsed GC-MS results.

areas <- extract_peak_areas(batch)

3. Build abundance matrix

Construct a CAS × sample abundance matrix.

abund <- build_cas_abundance(areas)

4. Annotate compounds

Annotate compounds using either a user-provided library or chemical databases.

Example using webchem:

annotated <- annotate_compounds(
  abund,
  lib_source = "webchem"
)

5. Frequency-based screening

Remove unreliable compounds based on blank contamination and occurrence frequency.

result <- filter_by_frequency(
  abundance_data = annotated,
  sample_group_file = "data-raw/sample_groups.xlsx",
  group_col = "Combined_Treatment"
)

6. Export results

Save processed VOC results.

save_postvocs_results(
  result,
  output_dir = "results",
  format = "xlsx"
)

Main Functions

Key Features

Flexible Input

postvocs accepts multiple input formats:

• R data frames;
• CSV files;
• Excel files;
• outputs generated by previous workflow steps.

This allows users to integrate the package into different GC-MS analysis pipelines.

CAS Number Protection

The package automatically protects CAS numbers during export by adding single quotes when necessary. It checks whether a leading quote already exists before adding one, avoiding duplication.

This prevents Excel from automatically converting CAS identifiers into dates or other unintended formats.

Compound Annotation

annotate_compounds() supports:

• user-provided compound libraries;
• automatic annotation through chemical databases;
• cached queries to improve efficiency.

API-Friendly Database Query

When using online annotation services:

• queries are cached locally;
• repeated requests are avoided;
• API rate limits are respected.

Multi-sheet Export

Results can be exported as Excel workbooks containing multiple related tables, including:

• processed abundance matrices;
• compound annotations;
• screening summaries.

Screening Summary

filter_by_frequency() provides detailed tracking information:

• compounds removed during blank filtering;
• compounds removed during first-round frequency screening;
• compounds recovered during second-round screening.

Documentation

Detailed documentation is available through R help:

library(postvocs)

?process_gcms_txt
?batch_process_gcms
?extract_peak_areas
?build_cas_abundance
?annotate_compounds
?filter_by_frequency
?save_postvocs_results
?save_gcms_results

Example Data

Example datasets and workflows will be provided in future releases.

A typical analysis requires:

project/
|
├── data-raw/
│   ├── txt/
│   │   ├── sample1.txt
│   │   ├── sample2.txt
│   │
│   ├── SampleID.xlsx
│
└── results/

SampleID.xlsx contains sample identification and grouping information with columns:

This file is used for both sample name mapping in batch_process_gcms() and frequency screening in filter_by_frequency().

Contributing

Contributions, bug reports, and feature requests are welcome.

Please submit issues or pull requests through GitHub:

https://github.com/HanXT97/postvocs

License

GPL-3 © Xiaotao Han