The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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

License

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.