equivalentGOProfiles: Are two lists of genes equivalent in terms of their Gene Ontology profiles?

Description

Performs an equivalence test based on the squared Euclidean distance between the Gene Ontology profiles of two lists of genes. Equivalence is declared if the upper limit d.sup of a one-sided confidence interval [0, d.sup] for the distance is lesser than the equivalence limit d0.

Usage

equivalentGOProfiles(goObject, ...)
"equivalentGOProfiles"(goObject, equivEpsilon = 0.05, d0 = NULL, confidence = NULL, ...)
"equivalentGOProfiles"(goObject, ...)
"equivalentGOProfiles"(goObject, qm=NULL, pqn0=NULL, n = ngenes(goObject), m = ngenes(qm), n0 = ngenes(pqn0), confidence = 0.95, equivEpsilon = 0.05, d0 = NULL, simplify = FALSE, ...)
"equivalentGOProfiles"(goObject, ...)

Arguments

goObject

an object related to GO profiles or comparisons between them

an expanded GO profile, i.e. and object of class 'ExpandedGOProfile'

pqn0

an expanded GO profile, i.e. and object of class 'ExpandedGOProfile'

a numeric vector with the number of genes profiled in each column of goObject. This parameter is included to allow the possibility of exploring the consequences of varying sample sizes, other than the true sample size in goObject.

a numeric vector with the number of genes profiled in each column of qm.

a numeric vector with the number of genes profiled in each column of pqn0.

confidence

the nominal confidence level of the one-sided confidence interval on the distance

a positive value specifying the equivalence limit

equivEpsilon

a positive value used to compute 'd0' if it is not directly available

simplify

should the result be simplified, if possible? See the 'Details' section

...

further arguments, tipically the same than to 'compareGOProfiles'

Value

statistic: test statistic, (distance - d0) / se
parameter: d0 and the sample sizes (number of genes) n and m
p.value: associated p-value to test the null hypothesis of profiles inequivalence
conf.int: asymptotic one-sided confidence interval for the squared euclidean distance. Its attribute "conf.level" contains its nominal confidence level.
estimate: squared euclidean distance between the contracted profiles. Its attribute "se" contains its standard error estimate
data.name: a character string giving the names of the data
alternative: a character string describing the alternative hypothesis (always 'Equivalence or similarity, true squared Euclidean distance between the contracted profiles is less than d0'

Details

An object of S3 class "ExpandedGOProfile" is, essentially, a "data.frame" object with each column representing the relative frequencies in all observed node combinations, resulting from profiling a set of genes, for a given and fixed ontology. The 'row.names' attribute codifies the node combinations and each "data.frame" column (say, each profile) has an attribute, 'ngenes', indicating the number of profiled genes. In the 'ExpandedGOProfile' interface, the arguments 'goObject', 'qm' and 'pqn0' are compared in a column by column wise, recycling columns, if necessary, in order to perform max(ncol(goObject),ncol(qm),ncol(pqn0)) equivalence tests (each test resulting in an object of class 'htest'). In order to be properly tested, these arguments are expanded by row, according to their row names. That is, the data arguments can have unequal row numbers. Then, they are expanded adding rows with zero frequencies, in order to make them comparable. In the i-th comparison (i from 1 to max(ncol(goObject),ncol(qm),ncol(pqn0))), the parameters n, m and n0 are included to allow the possibility of exploring the consequences of varying sample sizes, other than the true sample sizes included as an attribute in goObject, qm and pqn0. When qm = NULL, the genes profiled in goObject are compared with a subsample of them, those profiled in pqn0 (is there equivalence between a set of genes and a restricted subset, e.g. those overexpressed under a disease, in terms of their profiles?). When pqn0 = NULL, an equivalence test between two profiles with no genes in common is performed. In the 'GOProfileHtest' interface, the one-sided confidence interval for the squared Euclidean distance is computed from the distance and its standard error stored in the corresponding fields of the argument goObject, itself typically an object of class 'GOProfileHtest' resulting from a call to 'compareGOProfiles' with simplify=T. In the 'list' interface, the argument goObject is intended to be a list of objects of class 'GOProfileHtest' typically resulting from a call to 'compareGOProfiles' with simplify=F. The call to the method is iterated along the list, and the one-sided confidence interval for the squared Euclidean distance is computed from the distance and its standard error stored in the corresponding fields of all the members of the list. In the default interface, the 'goObject' argument is previously converted into an object of class 'ExpandedGOProfile' and then this interface is used. If the argument 'd0' is not provided it is computed as $d0 <- s * equivEpsilon^2$, where 's' stands for the number of non empty GO nodes in any of the GO profiles being compared.

Examples

Run this code


data(prostateIds)
expandedWelsh <- expandedProfile(welsh01EntrezIDs[1:100], onto="MF",
                        level=2, orgPackage="org.Hs.eg.db")
expandedSingh <- expandedProfile(singh01EntrezIDs[1:100], onto="MF",
                        level=2, orgPackage="org.Hs.eg.db")
commonGenes <- intersect(welsh01EntrezIDs[1:100], singh01EntrezIDs[1:100])
commonExpanded <- expandedProfile(commonGenes, onto="MF", level=2, orgPackage="org.Hs.eg.db")

equivMF <-equivalentGOProfiles (expandedWelsh[['MF']], 
                          qm  = expandedSingh[['MF']], 
                          pqn0= commonExpanded[['MF']])

print(equivSummary(equivMF, decs=5))