Package {postvocs}

Add Compound_Name and Annotation_Source columns to abundance data

Description

Add Compound_Name and Annotation_Source columns to abundance data

Usage

add_compound_name(ab, annotation)

Annotate CAS numbers with chemical information

Description

This function takes a set of CAS numbers (from an abundance matrix) and retrieves chemical names and properties from user-provided libraries or from online databases (via 'webchem'). It supports caching and automatic rate-limiting to comply with PubChem API constraints.

Usage

annotate_compounds(
  abundance_data,
  lib_source = c("auto", "user", "webchem"),
  user_lib = NULL,
  webchem_config = list(rate_limit = 5, chunk_size = 100, cache_file = NULL),
  use_cache = FALSE,
  force_retrieve = FALSE
)

Arguments

Details

The function automatically determines the batch strategy based on the number of CAS to query:

• 1-50: direct individual queries (no chunking).

• 51-1000: chunked queries using 'chunk_size'.

• 1001-5000: chunked queries with smaller chunk size (200) and extra delay.

• > 5000: a warning is issued recommending the PubChem PUG Download service; the function will still attempt chunked queries but may be slow or rate-limited.

A persistent cache is stored at the location given by 'cache_file' (or the default user cache directory) only when 'use_cache = TRUE'. The cache is a named list where each key is a CAS number and the value is a list of chemical properties, including a 'status' field ('"success"' or '"not_found"'). Cache is updated after each query when enabled.

The 'Annotation_Source' column indicates the origin of the compound name:

• '"user_lib"' - from the user‑provided library.

• '"web"' - newly queried from webchem in this session.

• '"web(cache)"' - retrieved from the cache (previous webchem query).

CAS numbers are automatically cleaned before processing: leading/trailing single quotes are removed and all spaces are stripped.

Value

A list with two components:

Examples

# Create a small abundance matrix
ab <- data.frame(
  CAS = c("64-17-5", "67-64-1", "75-05-8"),
  Sample1 = c(100, 200, 300),
  Sample2 = c(150, 250, 350)
)

# Create a user-provided compound library
user_lib <- data.frame(
  CAS = c("64-17-5", "67-64-1"),
  Name = c("Ethanol", "Acetone"),
  stringsAsFactors = FALSE
)

# Annotate using the user library (no network required)
res <- annotate_compounds(ab, lib_source = "user", user_lib = user_lib)

# View annotation table
head(res$annotation)

# Updated abundance matrix with Compound_Name and Annotation_Source
head(res$abundance_updated)

Batch process GC-MS TXT files in a directory with sample name mapping

Description

Processes all TXT files in a given directory using process_gcms_txt(), maps the raw file names to user-defined sample names via an Excel mapping file, and returns two lists: one containing all PeakTables and one containing all SearchResults, each named by the mapped sample name.

Usage

batch_process_gcms(
  txt_dir,
  sample_file,
  sheet = 1,
  pattern = "\\.txt$",
  encoding = "UTF-8",
  ...
)

Arguments

Value

A list with four components:

Examples

# Get paths to example data
txt_dir <- system.file("extdata/txt", package = "postvocs")
sample_file <- system.file("extdata/SampleID.xlsx", package = "postvocs")

# Process all .txt files in the example folder
result <- batch_process_gcms(
  txt_dir = txt_dir,
  sample_file = sample_file,
  sheet = 1
)

# Access a specific sample's PeakTable
peak_sample <- result$PeakTables[[1]]

# View summary of processing
result$summary

# If you want debug output or different encoding, you can pass them:
result <- batch_process_gcms(txt_dir, sample_file, debug = TRUE)
result <- batch_process_gcms(txt_dir, sample_file, encoding = "GBK")

Build annotation data.frame from cache, user library, and newly queried

Description

Build annotation data.frame from cache, user library, and newly queried

Usage

build_annotation_from_cache_and_user(
  cas_vec,
  cache,
  user_lookup = list(),
  newly_queried = character(0)
)

Build a CAS × Sample abundance matrix from extracted peak areas

Description

Takes a list of extracted CAS–area vectors (as returned by extract_peak_areas) and constructs a matrix where rows are CAS compounds and columns are samples. This is the standard abundance matrix used for subsequent annotation and screening.

Usage

build_cas_abundance(area_list)

Arguments

Details

The function collects all unique CAS numbers from all samples, sorts them, and creates a matrix with CAS as rows and samples as columns. If a sample does not contain a particular CAS, its area is set to 0.

Value

A data frame with the first column "CAS" and subsequent columns for each sample (in the order they appear in area_list). Missing values are filled with 0.

Examples

# Get paths to example data
txt_dir <- system.file("extdata/txt", package = "postvocs")
sample_file <- system.file("extdata/SampleID.xlsx", package = "postvocs")

# Batch process example files and extract peak areas
batch <- batch_process_gcms(txt_dir, sample_file)
areas <- extract_peak_areas(batch)

# Build abundance matrix (CAS as rows, samples as columns)
abund <- build_cas_abundance(areas)

# View first few rows and columns
head(abund[, 1:5])

Extract CAS and total peak areas from GC-MS results

Description

This function extracts CAS numbers and their corresponding total peak areas from GC-MS PeakTable and SearchResults data. It supports three input types:

• A list from process_gcms_txt() (single sample)

• A list from batch_process_gcms() (multiple samples)

• A folder path containing PeakTable and SearchResults files (CSV or Excel)

Usage

extract_peak_areas(x, ...)

Arguments

Details

The function automatically detects the input type:

• If x is a character path to an existing folder, it scans for files containing "PeakTable" and "SearchResults" in their names, pairs them by common prefix, and processes all samples.

• If x is a list containing PeakTable and SearchResults, it processes as a single sample and returns a list with one element.

• If x is a list containing PeakTables and SearchResults, it processes all samples in batch.

Value

A named list. Each element is a named numeric vector with CAS as names and total peak area as values. The list names are sample names.

Examples

# Get paths to example data
txt_file <- system.file("extdata/txt/sample1.txt", package = "postvocs")
txt_dir <- system.file("extdata/txt", package = "postvocs")
sample_file <- system.file("extdata/SampleID.xlsx", package = "postvocs")

# 1. From process_gcms_txt result (single sample)
res <- process_gcms_txt(txt_file)
result_single <- extract_peak_areas(res)
# result_single is a list with one element named "sample1"

# 2. From batch_process_gcms result (multiple samples)
batch <- batch_process_gcms(txt_dir, sample_file)
results_batch <- extract_peak_areas(batch)
# results_batch is a list with elements named by mapped sample names
# e.g., "Site1_TreatA_1", "Site1_TreatA_2", ...

# 3. From a folder containing PeakTable and SearchResults CSV files
# (This requires you to have saved the results from save_gcms_results first)
# For example:
save_gcms_results(res, tempdir(), format = "csv")
results_folder <- extract_peak_areas(tempdir())

Filter compounds by occurrence frequency across samples and treatment groups

Description

This function performs a two‑step filtering of compounds from an abundance matrix. It removes compounds detected in blank samples, then retains compounds based on occurrence frequency across all samples and within treatment groups. It returns a detailed summary table with flags for each compound.

Usage

filter_by_frequency(
  abundance_data,
  sample_group_file,
  sheet = 1,
  group_col = "Combined_Treatment",
  threshold_total = 0.25,
  threshold_treatment = 0.25,
  blank_indicators = c("Species", "Treatment", "Combined_Treatment")
)

Arguments

Details

The function expects the abundance matrix to contain at least two columns: 'CAS' and 'Compound_Name'. The 'Compound_Name' column should have been added by 'annotate_compounds()'; if missing, a warning is issued and 'Compound_Name' is filled with 'NA'.

Blank samples (identified by 'blank_indicators' all equal "0") are used to remove contaminant compounds, but are excluded from frequency calculations. Compounds that appear (area > 0) in any blank sample are removed entirely and flagged in the summary table.

Frequency is calculated as the proportion of samples (or samples within a treatment group) where the compound area is strictly greater than zero.

The filtering proceeds in two rounds:

1. Compounds with total frequency >= 'threshold_total' are kept.

2. For compounds not kept in round 1, those with frequency >= 'threshold_treatment' in at least one treatment group are additionally kept.

Value

A list with five components:

summary

A data frame with filtering statistics.

abundance

The full abundance matrix with added frequency columns.

round1

Data frame of compounds kept in round 1.

round2

Data frame of compounds kept in round 2.

summary_table

A comprehensive table for all original compounds with flags.

Examples

# Load pre-annotated example data (generated by the package maintainer)
annotated <- readRDS(system.file("extdata/annotated_example.rds", package = "postvocs"))

# Path to sample grouping file
sample_file <- system.file("extdata/SampleID.xlsx", package = "postvocs")

# Run frequency-based filtering
result <- filter_by_frequency(
  abundance_data = annotated,
  sample_group_file = sample_file,
  group_col = "Combined_Factor",
  blank_indicators = c("Factor1", "Factor2", "Combined_Factor")
)

# View summary
result$summary

Parse a single GC-MS exported TXT file

Description

Extracts the [MC Peak Table] and [MS Similarity Search Results for Spectrum Process Table] from a Shimadzu GC-MS workstation text export. The function returns the two tables as data frames in a list, with element names derived from the input file name. No files are written to disk.

Usage

process_gcms_txt(txt_file, debug = FALSE, encoding = "UTF-8")

Arguments

Details

The function expects the TXT file to have the following structure:

• A header line starting with "Data File Name" (used only for debug and not for naming).

• After [MC Peak Table], a line like # of Peaks\t38 or # of Peaks,38 giving the number of peaks.

• The column name line of the peak table must start with "Peak#" (e.g., Peak#\tRet.Time\tArea... or Peak#,Ret.Time,Area...).

• The mass spectral search results section starts with [MS Similarity Search Results ...], and its column name line must start with "Spectrum#".

The delimiter (tab or comma) is auto-detected from the column name line of each table and used for parsing all rows of that table. The two tables may use different delimiters.

Value

A list with two data frames, named as "<basename>_PeakTable" and "<basename>_SearchResults", where <basename> is the input file name without extension.

• PeakTable: The extracted peak table from [MC Peak Table], containing columns like Peak#, Ret.Time, Area, etc.

• SearchResults: The extracted similarity search results from [MS Similarity Search Results ...], containing columns like Spectrum#, CAS#, Name, etc. CAS numbers are cleaned by removing all spaces.

Examples

# Get path to the example data directory
txt_dir <- system.file("extdata/txt", package = "postvocs")

# Construct the full path to a sample TXT file
txt_file <- file.path(txt_dir, "sample1.txt")

# Process the file (default encoding UTF-8)
res <- process_gcms_txt(txt_file, debug = TRUE)

# If encountering encoding warnings, try GBK
res <- process_gcms_txt(txt_file, encoding = "GBK")

# Access the two tables using dynamically generated names
peak_table <- res[["sample1_PeakTable"]]
search_results <- res[["sample1_SearchResults"]]

# See all names
names(res)

Save GC-MS parsing results to CSV or Excel files

Description

Saves the data frames from process_gcms_txt() or batch_process_gcms() to individual files. For SearchResults data frames, the CAS column is prefixed with a single quote to prevent Excel from interpreting CAS numbers as dates.

Usage

save_gcms_results(results, output_dir, format = c("csv", "xlsx"), ...)

Arguments

Details

The function detects data frames that contain CAS-related columns (based on the data frame name containing "SearchResults") and adds a single quote prefix to the CAS column to avoid Excel date conversion. For PeakTable data frames, no modification is applied.

If format = "xlsx", the openxlsx package is required. If not installed, the function will prompt to install it.

Value

Invisibly, a character vector of saved file paths.

Examples

# Get paths to example data
txt_dir <- system.file("extdata/txt", package = "postvocs")
txt_file <- file.path(txt_dir, "sample1.txt")
sample_file <- system.file("extdata/SampleID.xlsx", package = "postvocs")

# (1) Process a single file and save as CSV
res <- process_gcms_txt(txt_file)
save_gcms_results(res, output_dir = tempdir(), format = "csv")

# (2) Batch process and save as Excel (all in one file)
batch <- batch_process_gcms(txt_dir, sample_file)
save_gcms_results(batch, output_dir = tempdir(), format = "xlsx")

# (3) Save only PeakTables (custom extraction)
save_gcms_results(batch$PeakTables, output_dir = tempdir(), format = "csv")

Save postvocs results to CSV or Excel files

Description

This function saves the results from 'build_cas_abundance()', 'annotate_compounds()', or 'filter_by_frequency()' to CSV or Excel files. It automatically adds a single quote prefix to CAS columns to prevent Excel date conversion. It checks whether the CAS column already contains a leading single quote; if so, it does not add another one.

Usage

save_postvocs_results(
  x,
  output_dir,
  prefix = NULL,
  format = c("csv", "xlsx"),
  what = NULL,
  ...
)

Arguments

Details

For Excel output ('format = "xlsx"'), if the input is a list containing multiple data frames (e.g., from 'filter_by_frequency()' or 'annotate_compounds()'), all tables are saved as separate worksheets in a single Excel file. For CSV output, each table is saved as an independent file.

For data.frames that contain a column named "CAS", the function adds a single quote prefix to each CAS value to prevent Excel from interpreting them as dates. It does not add a second quote if the value already starts with a single quote.

If 'format = "xlsx"', the 'openxlsx' package is required.

Value

Invisibly, a character vector of saved file paths.

Examples

# Load pre-annotated example data
annotated <- readRDS(system.file("extdata/annotated_example.rds", package = "postvocs"))

# Path to sample grouping file
sample_file <- system.file("extdata/SampleID.xlsx", package = "postvocs")

# Perform frequency-based screening (if needed)
result <- filter_by_frequency(
  abundance_data = annotated,
  sample_group_file = sample_file,
  group_col = "Combined_Factor",
  blank_indicators = c("Factor1", "Factor2", "Combined_Factor")
)

# Save results
save_postvocs_results(result, output_dir = tempdir(), format = "csv")