% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/02_addMotifAnnotation.R
\name{getMotifAnnotation}
\alias{getMotifAnnotation}
\title{Get motif annotation}
\usage{
getMotifAnnotation(
  motifs,
  motifAnnot,
  annotCats = c("directAnnotation", "inferredBy_MotifSimilarity",
    "inferredBy_Orthology", "inferredBy_MotifSimilarity_n_Orthology"),
  idColumn = "motif",
  returnFormat = c("asCharacter", "subset", "list")[1],
  keepAnnotationCategory = TRUE
)
}
\arguments{
\item{motifs}{Motif IDs}

\item{motifAnnot}{Motif annotation database containing the 
annotations of the motif to genes or transcription factors.}

\item{annotCats}{Annotation categories to be considered:
"directAnnotation" (annotated in the source database),  
"inferredBy_Orthology" (the motif is annotated to an homologous/ortologous 
gene), or inferred based on motif similarity ("inferredBy_MotifSimilarity", 
"inferredBy_MotifSimilarity_n_Orthology").}

\item{idColumn}{Annotation column containing the ID (e.g. motif, accession)}

\item{returnFormat}{Determines the output format. Choose one of the following values:}

\item{keepAnnotationCategory}{Include annotation type in the TF information?
\itemize{
\item \code{asCharacter}: Named vector with the genes or TFs annotated to the given motifs (in the same order, including empty and duplicated values).
\item \code{subset}: Subset of the annotation table (list split by motif)
\item \code{list}: List of TF names (unique values), duplicated motifs or motifs without annotation are not returned.
}}
}
\value{
See argument \code{returnFormat}
}
\description{
Get the genes/transcription factors annotated to the given motifs
}
\examples{

##################################################
# Setup & previous steps in the workflow:

#### Gene sets
# As example, the package includes an Hypoxia gene set:
txtFile <- paste(file.path(system.file('examples', package='RcisTarget')),
                 "hypoxiaGeneSet.txt", sep="/")
geneLists <- list(hypoxia=read.table(txtFile, stringsAsFactors=FALSE)[,1])

#### Databases
## Motif rankings: Select according to organism and distance around TSS
## (See the vignette for URLs to download)
# motifRankings <- importRankings("hg19-500bp-upstream-7species.mc9nr.feather")

## For this example we will use a SUBSET of the ranking/motif databases:
library(RcisTarget.hg19.motifDBs.cisbpOnly.500bp)
data(hg19_500bpUpstream_motifRanking_cispbOnly)
motifRankings <- hg19_500bpUpstream_motifRanking_cispbOnly

## Motif - TF annotation:
data(motifAnnotations_hgnc) # human TFs (for motif collection 9)
motifAnnotation <- motifAnnotations_hgnc

### Run RcisTarget
# Step 1. Calculate AUC
motifs_AUC <- calcAUC(geneLists, motifRankings)

##################################################

### (This step: Step 2)
# Before starting: Setup the paralell computation
library(BiocParallel); register(MulticoreParam(workers = 2)) 
# Select significant motifs, add TF annotation & format as table
motifEnrichmentTable <- addMotifAnnotation(motifs_AUC,
                                           motifAnnot=motifAnnotation)

# Alternative: Modifying some options
motifEnrichment_wIndirect <- addMotifAnnotation(motifs_AUC, nesThreshold=2, 
        motifAnnot=motifAnnotation,
        highlightTFs = "HIF1A", 
        motifAnnot_highConfCat=c("directAnnotation"), 
        motifAnnot_lowConfCat=c("inferredBy_MotifSimilarity",
                                "inferredBy_MotifSimilarity_n_Orthology",
                                "inferredBy_Orthology"),
        digits=3)

# Getting TFs for a given TF:
motifs <- motifEnrichmentTable$motif[1:3]

getMotifAnnotation(motifs, motifAnnot=motifAnnotation)
getMotifAnnotation(motifs, motifAnnot=motifAnnotation, returnFormat="list")

### Exploring the output:
# Number of enriched motifs (Over the given NES threshold)
nrow(motifEnrichmentTable)

# Interactive exploration
motifEnrichmentTable <- addLogo(motifEnrichmentTable)
DT::datatable(motifEnrichmentTable, filter="top", escape=FALSE,
              options=list(pageLength=50))
# Note: If using the fake database, the results of this analysis are meaningless

# The object returned is a data.table (for faster computation),
# which has a diferent syntax from the standard data.frame or matrix
# Feel free to convert it to a data.frame (as.data.frame())
motifEnrichmentTable[,1:6]


##################################################
# Next step (step 3, optional):
\dontrun{
  motifEnrichmentTable_wGenes <- addSignificantGenes(motifEnrichmentTable,
                                                     geneSets=geneLists,
                                                     rankings=motifRankings,
                                                     method="aprox")
}
}
\seealso{
\code{\link{addMotifAnnotation}} add the annotation directly to the motif enrichment results.

See the package vignette for examples and more details:
\code{vignette("RcisTarget")}
}
