R/DAVIDGODag-class.R

In RDAVIDWebService: An R Package for retrieving data from DAVID into R objects using Web Services API.

#' class "DAVIDGODag" 
#'
#' This concrete class represents an induced GO DAG generated by the DAVID
#' Functional Annotation Chart report a.k.a a DAVIDFunctionalAnnotationChart
#' object. 
#'
#' @section Type:
#' This class is a "\code{Concrete}" one.
#'
#' @section Extends:
#' \itemize{
#'  \item \emph{GOHyperGResult} directly, in order to reuse GOstats
#'  functionalities.
#' }
#'
#' @section Slots: the ones inherited from GOHyperGResult
#'
#' @section Methods:
#' \describe{
#' \item{\code{show}}{\code{signature(object="DAVIDGODag")}: basic
#'  console output.}
#' \item{\code{summary}}{\code{signature(object="DAVIDGODag", ...)}: basic
#'  summary console output.}
#' \item{\code{initialize}}{\code{signature(object="DAVIDGODag",
#' fileName="character")}: basic cluster report file parser.}
#' \item{\code{DAVIDGODag}}{\code{signature(object="DAVIDGODag",
#' fileName="character")}: high level constructor to parse the file report.}
#' \item{\code{universeMappedCount, universeCounts, counts}}{\code{signature(
#' object="DAVIDGODag")}: modifications to the corresponding GOstats/Category
#' library functions, to keep the same behavior, for DAVIDGODag object.}
#' \item{\code{fdrs, benjaminis, bonferronis}}{\code{ signature(
#' object="DAVIDGODag")}: Adjusted method specific p-values for the
#' corresponding nodes/terms.}
#' \item{\code{terms}}{\code{signature(object="DAVIDGODag")}: character vector
#' with GO node names.}
#' \item{\code{popTotals, popHits, listTotals}}{\code{signature(
#' object="DAVIDGODag")}: integer vector with the number of ids, to use in the
#' EASE score calculations, when building the 2x2 contingency table.}
#' \item{\code{percentages}}{\code{signature(object="DAVIDGODag")}: numeric
#' vector with the percentage of the gene list ids present in the term.}
#' \item{\code{foldEnrichments}}{\code{signature(object="DAVIDGODag")}:numeric
#' vector with the ratio of the two proportions for each node/term. For
#' example, if 40/400 (i.e. 10\%) of your input genes involved in "kinase
#' activity" and the background information is 300/30000 genes (i.e. 1\%)
#' associating with "kinase activity", roughly 10\%/1\%=10 fold enrichment.}
#' }
#'
#' @author Cristobal Fresno and Elmer A Fernandez
#' 
#' @references 
#' \enumerate{
#'  \item The Database for Annotation, Visualization and Integrated Discovery 
#'  (david.abcc.ncifcrf.gov)
#'  \item Huang, D. W.; Sherman, B. T.; Tan, Q.; Kir, J.; Liu, D.; Bryant, D.; 
#'  Guo, Y.; Stephens, R.; Baseler, M. W.; Lane, H. C. & Lempicki, R. A. DAVID
#'  Bioinformatics Resources: expanded annotation database and novel algorithms
#'  to better extract biology from large gene lists. Nucleic Acids Res,
#'  Laboratory of Immunopathogenesis and Bioinformatics, SAIC-Frederick, Inc.,
#'  National Cancer Institute at Frederick, MD 21702, USA., 2007, 35, W169-W175
#'  \item Falcon, S; Gentleman, R.; Using GOstats to test gene lists for GO term
#'  association, Bioinformatics 23 (2007) 257-258.
#' }
#'
#' @docType class
#' @keywords classes 
#' @family DAVIDGODag
#' @name DAVIDGODag-class
#' @importClassesFrom GOstats GOHyperGResult
#' @rdname DAVIDGODag-class
#' @exportClass DAVIDGODag
#' @examples
#' {
#' ##Load the Functional Annotation Chart file report for the input demo 
#' ##file 2, using data function. Then, create a DAVIDGODag object using
#' ##Molecular Function main category of DAVIDFunctionalAnnotationChart object,
#' ##obtained from the loaded data.frame funChart2. In addition, we have
#' ##selected a threshold pvalue of 0.001 and removed unattached nodes, in case
#' ##DAVID/GO.db database are not using the same version.
#' data(funChart2)
#' davidGODag<-DAVIDGODag(DAVIDFunctionalAnnotationChart(funChart2), type="MF",
#'   pvalueCutoff=0.001, removeUnattached=TRUE)
#' 
#' ##Now, we can inspect the enrichment GO DAG using GOstats functionalities:
#' ##counts, pvalues, sigCategories, universeCounts, geneMappedCount, etc.
#' ##However, oddsRatios, expectedCounts and universeMappedCount are not
#' ##available because these results are not available on DAVID's Functional
#' ##Annotation Chart report. In addition geneIdUniverse are not the ones of
#' ##the universe but the ids on the category (geneIdsByCategory).
#' davidGODag
#' counts(davidGODag)
#' pvalues(davidGODag)
#' sigCategories(davidGODag, p=0.0001)
#' universeCounts(davidGODag)
#' geneMappedCount(davidGODag)
#' geneIdsByCategory(davidGODag)
#' summary(davidGODag) 
#' 
#' ##In addition, the new nodeData attributes (term, listTotal, popHit,
#' ##popTotal, foldEnrichment, bonferroni, benjamini, fdr) can be retrieved.
#' terms(davidGODag)
#' listTotals(davidGODag)
#' popHits(davidGODag)
#' popTotals(davidGODag)
#' foldEnrichments(davidGODag)
#' bonferronis(davidGODag)
#' benjaminis(davidGODag)
#' fdrs(davidGODag)
#' 
#' ##The user can even plot the enrichment GO DAG if Rgraphviz package is
#' ##available.
#'  plotGOTermGraph(g=goDag(davidGODag), r=davidGODag, max.nchar=30,
#'    node.shape="ellipse")
#' }
#'
setClass("DAVIDGODag", 
    contains ="GOHyperGResult", 
    prototype=prototype(
      conditional=FALSE,
      annotation="DAVID.website", 
      testName=as.character(c("GO","BP")), 
      testDirection="over",
      pvalueCutoff=0.1,
      geneIds=character(0),
      pvalue.order=integer(0)
    )
)