Perform Area Under the Receiver Operating Characteristic Curve Analysis

Performs comprehensive Area Under the Receiver Operating Characteristic (AUROC) analysis for metabolomics data. This function integrates results from data preprocessing, dimension reduction (OPLS-DA), fold change analysis, and comparative analysis to identify and visualize discriminative metabolic features between different groups. The function automatically filters features based on Variable Importance in Projection (VIP) scores, fold change thresholds, and statistical significance, then generates ROC curves for the most discriminative features.

perform_AUROC(
  data_PP,
  data_DR,
  data_FC,
  data_CA,
  arrangeLevels = NULL,
  VIPmin = 1,
  fcUP = 2,
  fcDown = 0.5,
  adjpvalue = 0.05,
  direction = "auto",
  top_n = 5L,
  plot_iden_met = NULL,
  confidence_level = 0.95,
  min_group_size = 3L
)

Arguments

data_PP

List. Results from the performPreprocessingPeakData function. Must contain $Metadata with $Group column and $data_scaledPCA_rsdFiltered_varFiltered matrix.

data_DR

List. Results from the performDimensionReduction function (OPLS-DA). Must contain VIP score data frames with naming pattern data_VIPScores_[group1] vs. [group2].

data_FC

List. Results from the performFoldChange function. Must contain fold change data frames with naming pattern data_combined_[group1] vs. [group2].

data_CA

List. Results from the performComparativeAnalysis function. Must contain $results data frame with adjusted p-values.

arrangeLevels

Character vector or NULL. Specifies the order of groups for analysis (e.g., c("Control", "Case1", "Case2")). When NULL, groups are sorted alphabetically. It is recommended to arrange from least severe to most severe condition (e.g., "Control", "Mild", "Severe").

VIPmin

Numeric. Minimum Variable Importance in Projection (VIP) score threshold for feature selection. Features with VIP < VIPmin are excluded. Default: 1.0.

fcUP

Numeric. Minimum fold change threshold for up-regulated features. Features with fold change >= fcUP are considered up-regulated. Default: 2.0.

fcDown

Numeric. Maximum fold change threshold for down-regulated features. Features with fold change <= fcDown are considered down-regulated. Default: 0.5.

adjpvalue

Numeric. Adjusted p-value threshold for statistical significance. Features with adjusted p-value >= adjpvalue are excluded. Default: 0.05.

direction

Character. Direction parameter for ROC analysis. Options:

  • "auto": Automatically determines optimal direction

  • ">": Use when predictor values for control group > case group

  • "<": Use when predictor values for control group < case group

See roc for details. Default: "auto".

top_n

Integer. Number of top features (by AUC) to display in ROC plots. Must be positive. Default: 5.

plot_iden_met

Character vector or NULL. Specific metabolite names to plot individually. When provided, generates separate ROC plots for each specified metabolite regardless of filtering criteria. Default: NULL.

confidence_level

Numeric. Confidence level for AUC confidence intervals. Must be between 0 and 1. Default: 0.95.

min_group_size

Integer. Minimum number of samples required per group for ROC analysis. Default: 3.

Value

A list containing the following components:

  • FunctionOrigin: Character indicating the source function

  • data_Merged_[comparison]: Merged data frames for each group comparison

  • data_Filtered_[comparison]: Filtered data matrices for each comparison

  • data_results_[comparison]: AUROC results data frames

  • plots: List of combined ROC plots for top features

  • plots_identifiedMetabolites: Individual plots for specified metabolites (if requested)

  • summary: Overall summary statistics

Details

The function performs the following steps:

  1. Validates input data and parameters

  2. Excludes quality control (QC) samples

  3. Generates all possible pairwise group combinations

  4. For each comparison, merges VIP, fold change, and statistical data

  5. Filters features based on specified thresholds

  6. Computes ROC curves and AUC values with confidence intervals

  7. Generates publication-ready plots

  8. Optionally creates individual plots for specified metabolites

See also

roc, auc, ci

Author

John Lennon L. Calorio

Examples

if (FALSE) { # \dontrun{
# Basic usage
auroc_results <- perform_AUROC(
  data_PP = preprocessing_results,
  data_DR = dimension_reduction_results,
  data_FC = fold_change_results,
  data_CA = comparative_analysis_results
)

# Advanced usage with custom parameters
auroc_results <- perform_AUROC(
  data_PP = preprocessing_results,
  data_DR = dimension_reduction_results,
  data_FC = fold_change_results,
  data_CA = comparative_analysis_results,
  arrangeLevels = c("Control", "Mild", "Severe"),
  VIPmin = 1.5,
  fcUP = 1.5,
  fcDown = 0.67,
  adjpvalue = 0.01,
  top_n = 10,
  plot_iden_met = c("Metabolite1", "Metabolite2")
)
} # }