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:

Parse GC-MS exports
- Single file: process_gcms_txt()
- Batch: batch_process_gcms()
Extract peak areas → extract_peak_areas()
Build abundance matrix → build_cas_abundance()
Annotate compounds → annotate_compounds()
Frequency screening → filter_by_frequency()
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

Function	Description
`process_gcms_txt()`	Parse a single GC-MS exported `.txt` file
`batch_process_gcms()`	Batch process multiple GC-MS files with sample name mapping
`extract_peak_areas()`	Extract CAS numbers and peak area information
`build_cas_abundance()`	Generate CAS × sample abundance matrix
`annotate_compounds()`	Annotate compounds using databases or custom libraries
`filter_by_frequency()`	Perform frequency-based VOC screening with blank removal
`save_postvocs_results()`	Export processed VOC results as CSV/XLSX
`save_gcms_results()`	Save raw parsing outputs including peak tables and search results

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:

Column	Description
`SampleID`	Sample identifier (e.g., 01, 02, …)
`SampleName`	User-defined sample name
`Factor1`	First grouping factor (e.g., Species)
`Factor2`	Second grouping factor (e.g., Treatment)
`Combined_Factor`	Combined grouping factor for analysis (e.g., Species_Treatment)

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