GO_analyse: Identifies gene ontologies clustering samples according to...

Description Usage Arguments Details Value Warning Author(s) See Also Examples

View source: R/analysis.R

Description

Combines gene expression data with Gene Ontology (GO) annotations to rank and visualise genes and GO terms enriched for genes best clustering predefined groups of samples based on gene expression levels.

This methods semi-automatically retrieves the latest information from Ensembl using the biomaRt package, except if custom GO annotations are provided. Custom GO annotations have two main benefits: firstly they allow the analysis of species not supported in the Ensembl BioMart server, and secondly they save time skipping calls to the Ensembl BioMart server for species that are supported. The latter also presents the possiblity of using an older release of the Ensembl annotations, for example.

Using default settings, a random forest analysis is performed to evaluate the ability of each gene to cluster samples according to a predefined grouping factor (one-way ANOVA available as an alteranative). Each GO term is scored and ranked according to the average rank (alternatively, average power) of all associated genes to cluster the samples according to the factor. The ranked list of GO terms is returned, with tools allowing to visualise the statistics on a gene- and ontology-basis.

Usage

1
2
3
4
5
GO_analyse(
    eSet, f, subset=NULL, biomart_dataset="", microarray="",
    method="randomForest", rank.by="rank", do.trace=100, ntree=1000,
    mtry=ceiling(2*sqrt(nrow(eSet))), GO_genes=NULL, all_GO=NULL,
    all_genes=NULL, FUN.GO=mean, ...)

Arguments

eSet

ExpressionSet of the Biobase package including a gene-by-sample expression matrix in the AssayData slot, and a phenotypic information data-frame in the phenodate slot. In the expression matrix, row names are identifiers of expressed features, and column names are identifiers of the individual samples. In the phenotypic data-frame, row names are sample idenfifiers, column names are grouping factors and phenotypic traits usable for statistical tests and visualisation methods.

f

A column name in phenodata used as the grouping factor for the analysis.

subset

A named list to subset eSet for the analysis. Names must be column names existing in colnames(pData(eSet)). Values must be vectors of values existing in the corresponding column of pData(eSet). The original ExpressionSet will be left unchanged.

biomart_dataset

The Ensembl BioMart dataset identifier corresponding to the species studied. If not specified and no custom annotations were provided, the method will attempt to automatically identify the adequate dataset from the first feature identifier in the dataset. Use data(prefix2dataset) to access a table listing valid choices.

microarray

The identifier in the Ensembl BioMart corresponding to the microarray platform used. If not specified and no custom annotations were provided, the method will attempt to automatically identify the platform used from the first feature identifier in the dataset. Use data(microarray2dataset) to access a table listing valid choices.

method

The statistical framework to score genes and gene ontologies. Either "randomForest" or "rf" to use the random forest algorithm, or alternatively either of "anova" or "a" to use the one-way ANOVA model. Default is "randomForest".

rank.by

Either of "rank" or "score" to chose the metric used to order the gene and GO term result tables. Default to 'rank'.

do.trace

Only used if method="randomForest". If set to TRUE, gives a more verbose output as randomForest is run. If set to some integer, then running output is printed for every do.trace trees. Default is 100.

ntree

Only used if method="randomForest". Number of trees to grow. This should be set to a number large enough to ensure that every input row gets predicted at least a few times

mtry

Only used if method="randomForest". Number of features randomly sampled as candidates at each split. Default value is 2*sqrt(gene_count) which is approximately 220 genes for a dataset of 12,000 genes.

GO_genes

Custom annotations associating features present in the expression dataset to gene ontology identifiers. This must be provided as a data-frame of two columns, named gene_id and go_id. If provided, no call to the Ensembl BioMart server will be done, and arguments all_GO and all_genes should be provided as well, to enable all downstream features of GOexpress. An example is provided in AlvMac_GOgenes.

all_GO

Custom annotations used to annotate each GO identifier present in GO_genes with the ontology name (e.g. "apoptotic process") and namespace (i.e. "biological_process", "molecular_function", or "cellular_component"). This must be provided as a data-frame containing at least one column named go_id, and preferably two more columns named name_1006 and namespace_1003 for consistency with the Ensembl BioMart. Supported alternative column headers are name and namespace. Respectively, name should be used to provide the description of the GO term, and namespace should contain one of "biological_process", "molecular_function" and "cellular_component". name is used to generate the title of ontology-based figured, and namespace is important to enable subsequent filtering of results by their corresponding value. An example is provided in data(AlvMac_allGO).

all_genes

Custom annotations used to annotate each feature identifier in the expression dataset with the gene name or symbol (e.g. "TNF"), and an optional description. This must be provided as a data-frame containing at least a column named gene_id and preferably two more columns named external_gene_name and description for consistency with the Ensembl BioMart. A supported alternative header is name. While external_gene_name is important to enable subsequent visualisation of results by gene symbol, description is only displayed for readability of result tables. An example is provided in data(AlvMac_allgenes).

FUN.GO

Function to summarise the score and rank of all feature associated with each gene ontology. Default is mean function. If using "lambda-like" (anonymous) functions, these must take a list of numeric values as an input, and return a single numeric value as an output.

...

Additional arguments passed on to the randomForest() method, if applicable.

Details

The default scoring functions strongly favor GO terms associated with fewer genes at the top of the ranking. This bias may actually be seen as a valuable feature which enables the user to browse through GO terms of increasing "granularity", i.e. associated with increasingly large sets of genes, although consequently being increasingly vague and blurry (e.g. "protein binding" molecular function associated with over 6,000 genes).

It is suggested to use the subset_scores() function to subsequently filter out GO terms with fewer than 5+ genes associated with it. Indeed, those GO terms are more sensitive to outlier genes as they were scored on the average of a handful of genes.

Additionally, the pValue_GO function may be used to generate a permutation-based P-value indicating the chance of seeing each GO term reaching an equal or higher rank – or score – by chance.

Value

A list containing the results of the analysis. Some elements are specific to the output of each analysis method.

Core elements:

GO

A table ranking all GO terms related to genes in the expression dataset based on the average ability of their related genes to cluster the samples according to the predefined grouping factor.

mapping

The table mapping genes present in the dataset to GO terms.

genes

A table ranking all genes present in the expression dataset based on their ability to cluster the samples according to the predefined grouping factor.

factor

The predefined grouping factor.

method

The statistical framework used.

subset

The filters used to run the analysis only on a subet of the samples. NULL if no filter was applied.

rank.by

The metric used to rank order the genes and gene ontologies.

FUN.GO

The function used to summarise the score and rank of all gene features associated with each gene ontology.

Random Forest additional elements:

ntree

Number of trees grown.

mtry

Number of variables randomly sampled as candidates at each split.

One-way ANOVA does not have additional arguments.

Warning

Make sure that the factor f is an actual factor in the R language meaning. This is important for the underlying statistical framework to identify the groups of samples defined by their level of this factor.

If the column defining the factor (e.g. "Treatment") in phenodata is not an R factor, use pData(targets)$Treatment = factor(pData(targets)$Treatment) to convert the character values into an actual R factor with appropriate levels.

Author(s)

Kevin Rue-Albrecht

See Also

Methods subset_scores, pValue_GO, getBM, randomForest, and oneway.test.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
# Load example data subset
data(AlvMac)
# Load a local copy of annotations obtained from the Ensembl Biomart server
data(AlvMac_GOgenes)
data(AlvMac_allgenes)
data(AlvMac_allGO)

# Run the analysis on factor "Treatment",
# considering only treatments "MB" and "TB" at time-point "48H"
# using a local copy of annotations obtained from the Ensembl BioMart server
AlvMac_results <- GO_analyse(  
    eSet=AlvMac, f="Treatment",
    subset=list(Time=c("48H"), Treatment=c("MB", "TB")),
    GO_genes=AlvMac_GOgenes, all_genes=AlvMac_allgenes, all_GO=AlvMac_allGO
    )

# Valid Ensembl BioMart datasets are listed in the following variable
data(prefix2dataset)

# Valid microarray= values are listed in the following variable
data(microarray2dataset)

## Not run: 
# Other valid but time-consuming examples:

# Run the analysis on factor "Treatment" including all samples
GO_analyse(eSet=AlvMac, f="Treatment")

# Run the analysis on factor "Treatment" using ANOVA method
GO_analyse(eSet=AlvMac, f="Treatment", method="anova")


# Use alternative GO scoring/summarisation functions (Default is: average)

# Named functions
GO_analyse(eSet=AlvMac, f="Treatment", FUN.GO = median)

# Anonymous functions (simple example without scientific value)
GO_analyse(eSet=AlvMac, f="Treatment", FUN.GO = function(x){median(x)/100})


# Syntax examples without actual data:

# To force the use of the Ensembl BioMart for the human species, use:
GO_analyse(eSet, f, biomart_dataset = "hsapiens_gene_ensembl")

# To force use of the bovine affy_bovine microarray annotations use:
GO_analyse(eSet, f, microarray = "affy_bovine")

## End(Not run)

kevinrue/GOexpress-release documentation built on May 20, 2019, 9:08 a.m.