PANTHER Over-Representation or Enrichment Analysis

Use PANTHER services to perform over-representation enrichment analysis. You can either provide a character vector of gene IDs for over-representation analysis, or a data frame of gene IDs and expression analysis.
Please refer to the details section for more information on the statistical analysis.

Usage

rba_panther_enrich(
  genes,
  organism,
  annot_dataset,
  test_type = NULL,
  correction = "FDR",
  cutoff = NULL,
  ref_genes = NULL,
  ref_organism = NULL,
  request_mapped_genes = "input",
  ...
)

Arguments

genes

Character or Data frame: A vector or data frame. Depending on this parameter, the analysis type is determined.

Character vector:: If a character vector is supplied, over-representation analysis will be performed using either Fisher's exact test (default), or binomial.
Data frame:: If a data.frame is supplied, statistical enrichment test is performed using Mann-Whitney U (Wilcoxon Rank-Sum) test. The data frame should have two columns: the first column is a character vector with gene identifiers and the second column is a numerical vector with expression values.

In both cases, a maximum of 100,000 identifiers can be supplied. The gene identifiers can be any of: Ensembl gene ID, Ensembl protein ID, Ensembl transcript ID, Entrez gene ID, gene symbol, NCBI GI, HGNC ID, International protein index ID, NCBI UniGene ID, UniProt accession or UniProt ID.

organism

Numeric: NCBI taxon ID. run rba_panther_info with argument 'what = "organisms"' to get a list of PANTHER's supported organisms.

annot_dataset

Character: A PANTHER dataset ID to test your input against it. run rba_panther_info with argument 'what = "datasets"' to get a list of PANTHER's supported datasets. Note that you should enter the "id" of the dataset, not its label (e.g. entering "biological_process" is incorrect, you should rather enter "GO:0008150").

test_type

Character: (optional) Statistical test type used to calculate p-values.

If performing over-representation analysis (i.e. `genes` is a character vector), valid values are "FISHER" (default if NULL) or "BINOMIAL".
If performing statistical enrichment analysis (i.e. `genes` is a data frame), the only valid value is "Mann-Whitney" (default if NULL).

correction

Character: (default = "FDR") p value correction method. either "FDR" (default), "BONFERRONI" or "NONE".

cutoff

Numeric: (optional) a threshold to filter the results. if correction is "FDR", the threshold will be applied to fdr column's values; if otherwise, the threshold will be applied to p value column.

ref_genes

Character or Numeric: (optional) (only valid if genes is a character vector) A vector of genes that will be used as the test's background (reference/universe) gene set. If no value is supplied, all of the genes in the specified organism will be used. The maximum length and supported IDs are the same as the 'genes' argument.

ref_organism

Numeric: (optional) (only valid if genes is a character vector) if 'ref_genes' is used, you can specify the organisms which correspond to your supplied IDs in 'ref_genes' argument. see 'organism' argument for supported values.

request_mapped_genes

Character: (default = "input") (only used if genes is a character vector, hence Over-representation test is requested) Which mapped genes should be returned for each result term. One of "input" (default), "reference", or "none". Requesting "reference" without supplying 'ref_genes' may produce a large response because all genes in the specified organism are used as the reference list.

...

rbioapi option(s). See rba_options's arguments manual for more information on available options.

Value

For a successful analysis, a list. The "result" element is a data frame with one row per returned annotation term and columns describing the term, observed counts, enrichment direction, and statistical significance. The remaining elements contain input and reference mapping summaries, when applicable, and PANTHER analysis and release metadata.

Details

Over-representation Test: It assesses whether specific gene sets are represented in your input gene list differently from what is expected by chance. It uses Fisher's exact test or Binomial test to calculate p-values. Fisher's exact test determines the probability of observing the gene counts in a category based on a hypergeometric distribution; the binomial test compares the observed proportion of genes in a category to the expected proportion based on the reference list. A significant p-value indicates over-representation or under-representation of a gene set.

Statistical Enrichment Test: The statistical enrichment test uses the Mann-Whitney U (Wilcoxon Rank-Sum) test to assess if the expression values associated with genes in a specific category differ significantly from the overall distribution in the input list. This non-parametric test first ranks the numerical values and computes whether the expression values were randomly drawn from the overall distribution of values. A small p-value indicates that the numerical values for the genes in the category are significantly different from the background distribution, thus non-random patterns.

Please note that starting from rbioapi version 0.8.2, you can supply a gene expression data frame to perform statistical enrichment analysis. In earlier versions, only a character vector of gene IDs was possible, thus only over-representation analysis.

Corresponding API Resources

"POST https://www.pantherdb.org/services/oai/pantherdb/enrich/overrep"
"POST https://www.pantherdb.org/services/oai/pantherdb/enrich/statenrich"

References

Thomas PD, Ebert D, Muruganujan A, Mushayahama T, Albou L-P, Mi H. (2022) PANTHER: Making genome-scale phylogenetics accessible to all. Protein Science, 31(1), 8–22. https://doi.org/10.1002/pro.4218
Mi H, Muruganujan A, Huang X, Ebert D, Mills C, Guo X, Thomas PD. (2019) Protocol Update for large-scale genome and gene function analysis with the PANTHER classification system (v.14.0). Nature Protocols, 14, 703–721. https://doi.org/10.1038/s41596-019-0128-8
PANTHER Services Details
Citations note on PANTHER website

Examples

# \donttest{
rba_panther_enrich(
  genes = c("TP53", "BRCA1", "CDK2", "Q99835", "CDC42"),
  organism = 9606, annot_dataset = "GO:0008150",
  cutoff = 0.01
  )
# }

# \donttest{
expression_df <- data.frame(
  genes = c("TP53", "BRCA1", "CDK2", "CDC42", "CDK1"),
  expr = c(10, 8, 6, 4, 2)
  )

rba_panther_enrich(
  genes = expression_df,
  organism = 9606,
  annot_dataset = "GO:0008150"
  )
# }