seas {sparrow} | R Documentation

## Performs a plethora of set enrichment analyses over varied inputs.

### Description

This is a wrapper function that delegates GSEA analyses to different "workers", each of which implements the flavor of GSEA of your choosing. The particular analyses that are performed are specified by the `methods` argument, and these methods are fine tuned by passing their arguments down through the `...` of this wrapper function.

### Usage

    seas(
      x,
      gsd,
      methods = NULL,
      design = NULL,
      contrast = NULL,
      use.treat = FALSE,
      feature.min.logFC = if (use.treat) log2(1.25) else 1,
      feature.max.padj = 0.1,
      trim = 0.1,
      verbose = FALSE,
      ...,
      score.by = c("t", "logFC", "pval"),
      rank_by = NULL,
      rank_order = c("ordered", "descending", "ascending"),
      xmeta. = NULL,
      BPPARAM = BiocParallel::SerialParam()
    )

### Arguments

`x` | An object to run enrichment analyses over. This can be an ExpressoinSet-like object that you can differential expression over (for roast, fry, camera), a named (by feature_id) vector of scores to run ranked-based GSEA, a data.frame with feature_id's, ranks, scores, etc.
`gsd` | The `GeneSetDb()` that defines the gene sets of interest.
`methods` | A character vector indicating the GSEA methods you want to run. Refer to the GSEA Methods section for more details. If no methods are specified, only differential gene expression and geneset level statistics for the contrast are computed.
`design` | A design matrix for the study
`contrast` | The contrast of interest to analyze. This can be a column name of `design`, or a contrast vector which performs "coefficient arithmetic" over the columns of `design`. The `design` and `contrast` parameters are interpreted in exactly the same way as the same parameters in limma's `limma::camera()` and `limma::roast()` methods.
`use.treat` | should we use limma/edgeR's "treat" functionality for the gene-level differential expression analysis?
`feature.min.logFC` | The minimum logFC required for an individual feature (not geneset) to be considered differentialy expressed. Used in conjunction with `feature.max.padj` primarily for summarization of genesets (by `geneSetsStats()`, but can also be used by GSEA methods that require differential expression calls at the individual feature level, like `goseq()`.
`feature.max.padj` | The maximum adjusted pvalue used to consider an individual feature (not geneset) to be differentially expressed. Used in conjunction with `feature.min.logFC`.
`trim` | The amount to trim when calculated trimmed `t` and `logFC` statistics for each geneset. This is passed down to the `geneSetsStats()` function.
`verbose` | make some noise during execution?
`...` | The arguments are passed down into `calculateIndividualLogFC()` and the various geneset analysis functions.
`score.by` | this was the original `rank_by`. We need to reconcile the two. `score.by` is a parameter that is passed down into the do.* functions, and `rank_by` and other `underscored_variables` tend to be ones that are consumed by high-level/front facing function, like the difference between `do.ora()` and `ora()`.
`rank_by` | the name of a column that should be used to rank the features in `x` for pre-ranked gsea tests like cameraPR or fgsea. Only works when `x` is a data.frame-like input. `rank_by` overrides `score.by`
`rank_order` | specify how the features in `x` should be used to rank the features in `x` using the `rank_by` column. Accepted values are: `"ordered"` (default) means that the rows in `x` are pre-ranked already. `"descendeing"`, and `"ascending"`. Only used when `x` is a data.frame-like input.
`xmeta.` | A hack to support data.frame inputs for `x`. End users should not use this.
`BPPARAM` | a BiocParallel parameter definition, like one generated from `BiocParallel::MulticoreParam()`, or `BiocParallel::BatchtoolsParam()`, for instance, which is passed down to BiocParallel::bplapply()]. Default is set to `BiocParallel::SerialParam()`

### Details

Set enrichment analyses can either be performed over an expression object, which requires the specification of the experiment design and contrast of interest, or over a set of features to rank (stored as a data.frame or vector).

Note that we are currently in the middle of a refactor to accept and fully take advantage of `data.frame` as inputs for `x`, which will be used for preranked type of GSEA methods. See the following issue for more details: https://github.com/lianos/multiGSEA/issues/24

The bulk of the GSEA methods currently available in this package come from edgeR/limma, however others are included (and are being added), as well. GSEA Methods and GSEA Method Parameterization sections for more details.

In addition to performing GSEA, this function also internally orchestrates a differential expression analysis, which can be tweaked by identifying the parameters in the `calculateIndividualLogFC()` function, and passing them down through `...` here. The results of the differential expression analysis (ie. the `limma::topTable()`) are accessible by calling the `logFC()` function on the `SparrowResult()` object returned from this function call.

Please Note: be sure to cite the original GSEA method when using results generated from this function.

### Value

A `SparrowResult()` which holds the results of all the analyses specified in the `methods` parameter.

### GSEA Methods

You can choose the methods you would like to run by providing a character vector of GSEA method names to the `methods` parameter. Valid methods you can select from include:

- `"camera"`: from `limma::camera()` (*)

- `"cameraPR"`: from `limma::cameraPR()`

- `"ora"`: overrepresentation analysis optionally accounting for bias (`ora()`). This method is a wrapper function that makes the functionality in `limma::kegga()` available to an arbitrary GeneSetDb.

- `"roast"`: from `limma::roast()` (*)

- `"fry"`: from `limma::fry()` (*)

- `"romer"`: from `limma::romer()` (*)

- `"geneSetTest"`: from `limma::geneSetTest()`

- `"goseq"`: from `goseq::goseq()`

- `"fgsea"`: from `fgsea::fgsea()`

Methods annotated with a `(*)` indicate that these methods require a complete expression object, a valid design matrix, and a contrast specification in order to run. These are all of the same things you need to provide when performing a vanilla differential gene expression analysis.

Methods missing a `(*)` can be run on a feature-named input vector of gene level statistics which will be used for ranking (ie. a named vector of logFC's or t-statistics for genes). They can also be run by providing an expression, design, and contrast vector, and the appropriate statistics vector will be generated internally from the t-statistics, p-values, or log-fold-changes, depending on the value provided in the `score.by` parameter.

The worker functions that execute these GSEA methods are functions named `do.METHOD` within this package. These functions are not meant to be executed directly by the user, and are therefore not exported. Look at the respective method's help page (ie. if you are running `"camera"`, look at the `limma::camera()` help page for full details. The formal parameters that these methods take can be passed to them via the `...` in this `seas()` function.

### GSEA Method Parameterization

Each GSEA method can be tweaked via a custom set of parameters. We leave the documentation of these parameters and how they affect their respective GSEA methods to the documentation available in the packages where they are defined. The `seas()` call simply has to pass these parameters down into the `...` parameters here. The `seas` function will then pass these along to their worker functions.

What happens when two different GSEA methods have parameters with the same name?

Unfortunately you currently cannot provide different values for these parameters. An upcoming version version of sparrow will support this feature via slightly different calling semantics. This will also allow the caller to call the same GSEA method with different parameterizations so that even these can be compared against each other.

### Differential Gene Expression

When the `seas()` call is given an expression matrix, design, and contrast, it will also internally orchestrate a gene level differential expression analysis. Depending on the type of expression object passed in via `x`, this function will guess on the best method to use for this analysis.

If `x` is a `DGEList`, then ensure that you have already called `edgeR::estimateDisp()` on `x` and edgeR's quasilikelihood framework will be used, otherwise we'll use limma (note that `x` can be an `EList` run through `voom()`, `voomWithQuailityWeights()`, or when where you have leveraged limma's `limma::duplicateCorrelation()` functionality, even.

The parameters of this differential expression analysis can also be customized. Please refer to the `calculateIndividualLogFC()` function for more information. The `use.treat`, `feature.min.logFC`, `feature.max.padj`, as well as the `...` parameters from this function are passed down to that funciton.

### Examples

    vm <- exampleExpressionSet()
    gdb <- exampleGeneSetDb()
    mg <- seas(vm, gdb, c('camera', 'fry'),
               design = vm$design, contrast = 'tumor',
               # customzie camera parameter:
               inter.gene.cor = 0.04)
    resultNames(mg)
    res.camera <- result(mg, 'camera')
    res.fry <- result(mg, 'fry')
    res.all <- results(mg)

[Package sparrow version 1.0.3 Index]