getMotifAnnotation {RcisTarget} | R Documentation

## Get motif annotation

### Description

Get the genes/transcription factors annotated to the given motifs

### 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

`motifs` | Motif IDs
`motifAnnot` | Motif annotation database containing the annotations of the motif to genes or transcription factors.
`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").
`idColumn` | Annotation column containing the ID (e.g. motif, accession)
`returnFormat` | Determines the output format. Choose one of the following values:
`keepAnnotationCategory` | Include annotation type in the TF information? `asCharacter`: Named vector with the genes or TFs annotated to the given motifs (in the same order, including empty and duplicated values). `subset`: Subset of the annotation table (list split by motif) `list`: List of TF names (unique values), duplicated motifs or motifs without annotation are not returned.

### Value

See argument `returnFormat`

### See Also

`addMotifAnnotation` add the annotation directly to the motif enrichment results.

See the package vignette for examples and more details: `vignette("RcisTarget")`

### 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):
    ## Not run:
      motifEnrichmentTable_wGenes <- addSignificantGenes(motifEnrichmentTable,
                                                         geneSets=geneLists,
                                                         rankings=motifRankings,
                                                         method="aprox")

    ## End(Not run)

[Package RcisTarget version 1.14.0 Index]