Test pathway association with AES-PCA

Given a supervised OmicsPath object (one of OmicsSurv, OmicsReg, or OmicsCateg), extract the first $k$ adaptive, elastic-net, sparse principal components (PCs) from each pathway-subset of the features in the -Omics assay design matrix, test their association with the response matrix, and return a data frame of the adjusted $p$-values for each pathway.

AESPCA_pVals(
  object,
  numPCs = 1,
  numReps = 0L,
  parallel = FALSE,
  numCores = NULL,
  asPCA = FALSE,
  adjustpValues = TRUE,
  adjustment = c("Bonferroni", "Holm", "Hochberg", "SidakSS", "SidakSD", "BH", "BY",
    "ABH", "TSBH"),
  ...
)

# S4 method for OmicsPathway
AESPCA_pVals(
  object,
  numPCs = 1,
  numReps = 1000,
  parallel = FALSE,
  numCores = NULL,
  asPCA = FALSE,
  adjustpValues = TRUE,
  adjustment = c("Bonferroni", "Holm", "Hochberg", "SidakSS", "SidakSD", "BH", "BY",
    "ABH", "TSBH"),
  ...
)

Arguments

object	An object of class `OmicsPathway` with a response matrix or vector.
numPCs	The number of PCs to extract from each pathway. Defaults to 1.
numReps	How many permutations to estimate the $p$-value? Defaults to 0 (that is, to estimate the $p$-value parametrically). If `numReps` > 0, then the non-parametric, permutation $p$-value will be returned based on the number of random samples specified.
parallel	Should the computation be completed in parallel? Defaults to `FALSE`.
numCores	If `parallel = TRUE`, how many cores should be used for computation? Internally defaults to the number of available cores minus 1.
asPCA	Should the computation return the eigenvectors and eigenvalues instead of the adaptive, elastic-net, sparse principal components and their corresponding loadings. Defaults to `FALSE`; this should be used for diagnostic or comparative purposes only.
adjustpValues	Should you adjust the $p$-values for multiple comparisons? Defaults to TRUE.
adjustment	Character vector of procedures. The returned data frame will be sorted in ascending order by the first procedure in this vector, with ties broken by the unadjusted $p$-value. If only one procedure is selected, then it is necessarily the first procedure. See the documentation for the `ControlFDR` function for the adjustment procedure definitions and citations.
...	Dots for additional internal arguments.

Value

A results list with class aespcOut. This list has three components: a data frame of pathway details, pathway $p$-values, and potential adjustments to those values (pVals_df); a list of the first numPCs score vectors for each pathway (PCs_ls); and a list of the first numPCs feature loading vectors for each pathway (loadings_ls). The $p$-value data frame has columns:

pathways : The names of the pathways in the Omics* object (given in object@trimPathwayCollection$pathways.)
setsize : The number of genes in each of the original pathways (given in the object@trimPathwayCollection$setsize object).
n_tested : The number of genes in each of the trimmed pathways (given in the object@trimPathwayCollection$n_tested object).
terms : The pathway description, as given in the object@trimPathwayCollection$TERMS object.
rawp : The unadjusted $p$-values of each pathway.
... : Additional columns of adjusted $p$-values as specified through the adjustment argument.

The data frame will be sorted in ascending order by the method specified first in the adjustment argument. If adjustpValues = FALSE, then the data frame will be sorted by the raw $p$-values. If you have the suggested tidyverse package suite loaded, then this data frame will print as a tibble. Otherwise, it will print as a data frame.

Details

This is a wrapper function for the ExtractAESPCs, PermTestSurv, PermTestReg, and PermTestCateg functions.

Please see our Quickstart Guide for this package: https://gabrielodom.github.io/pathwayPCA/articles/Supplement1-Quickstart_Guide.html

Examples

  ###  Load the Example Data  ###
  data("colonSurv_df")
  data("colon_pathwayCollection")

  ###  Create an OmicsSurv Object  ###
  colon_Omics <- CreateOmics(
    assayData_df = colonSurv_df[, -(2:3)],
    pathwayCollection_ls = colon_pathwayCollection,
    response = colonSurv_df[, 1:3],
    respType = "surv"
  )
#> 
#>   ======  Creating object of class OmicsSurv  =======
#> The input pathway database included 676 unique features.
#> The input assay dataset included 656 features.
#> Only pathways with at least 3 or more features included in the assay dataset are
#>   tested (specified by minPathSize parameter). There are 15 pathways which meet
#>   this criterion.
#> Because pathwayPCA is a self-contained test (PMID: 17303618), only features in
#>   both assay data and pathway database are considered for analysis. There are 615
#>   such features shared by the input assay and pathway database.

  ###  Calculate Pathway p-Values  ###
  colonSurv_aespc <- AESPCA_pVals(
    object = colon_Omics,
    numReps = 0,
    parallel = TRUE,
    numCores = 2,
    adjustpValues = TRUE,
    adjustment = c("Hoch", "SidakSD")
  )
#> Part 1: Calculate Pathway AES-PCs
#> Initializing Computing Cluster: 
#> DONE
#> Extracting Pathway PCs in Parallel: 
#> DONE
#> 
#> Part 2: Calculate Pathway p-Values
#> Initializing Computing Cluster: 
#> DONE
#> Extracting Pathway p-Values in Parallel: 
#> DONE
#> 
#> Part 3: Adjusting p-Values and Sorting Pathway p-Value Data Frame
#> DONE

Arguments

Value

Details

See also

Examples

Contents