Perform Fold Change Analysis on Preprocessed Peak Data

Performs pairwise fold change analysis on preprocessed metabolomics or proteomics peak data. The function calculates fold changes and log2 fold changes between all possible group pairs while excluding quality control (QC) samples. The analysis uses group means for comparison and includes options for custom group ordering and result sorting.

perform_FoldChange(
  data,
  arrangeLevels = NULL,
  sortFC = TRUE,
  qc_patterns = c("SQC", "EQC", "QC"),
  min_samples_per_group = 2,
  epsilon = 1e-08
)

Arguments

data

List. A preprocessed data object returned by perform_PreprocessingPeakData() or similar preprocessing functions. Must contain:

  • $data_scaledPCA_rsdFiltered_varFiltered: Numeric matrix/data.frame of peak data

  • $Metadata: Data.frame with at least a 'Group' column

arrangeLevels

Character vector. Optional custom ordering for group levels. Must contain all unique group names present in the data (excluding QC samples). If NULL (default), groups are sorted alphabetically.

sortFC

Logical. If TRUE (default), sorts results by fold change values in descending order within each comparison.

qc_patterns

Character vector. Patterns to identify QC samples in the Group column. Default is c("SQC", "EQC", "QC").

min_samples_per_group

Integer. Minimum number of samples required per group for analysis. Default is 2.

epsilon

Numeric. Small value added to prevent log2(0) issues when data contains zeros or negative values. Default is 1e-8.

Value

A list containing:

FunctionOrigin

Character. Function name for traceability

data_shifted

Data.frame. Adjusted data with minimum value shifted to 1

group_summary

Data.frame. Summary of groups and sample counts

comparison_matrix

Matrix. All pairwise comparisons performed

data_combined_GROUP1 vs. GROUP2

Data.frame. Fold change results for each comparison

Details

The function performs the following steps:

  1. Validates input data structure and parameters

  2. Filters out QC samples based on specified patterns

  3. Checks for sufficient samples per group

  4. Handles zero/negative values by adding appropriate shift

  5. Performs all pairwise group comparisons

  6. Calculates fold changes as mean(group1)/mean(group2)

  7. Computes log2 fold changes

  8. Optionally sorts results by fold change magnitude

Warning

The function assumes that higher values indicate higher abundance/expression. Ensure your data is appropriately normalized before analysis.

Author

John Lennon L. Calorio

Examples

if (FALSE) { # \dontrun{
# Basic usage with default parameters
fc_results <- perform_FoldChange(preprocessed_data)

# Custom group ordering and no sorting
fc_results <- perform_FoldChange(
  data = preprocessed_data,
  arrangeLevels = c("Control", "Treatment1", "Treatment2"),
  sortFC = FALSE
)

# Custom QC patterns
fc_results <- perform_FoldChange(
  data = preprocessed_data,
  qc_patterns = c("QC", "Blank", "POOL")
)
} # }