\name{associateTranscriptionFactors}
 \alias{associateTranscriptionFactors,MotifList-method}
 \alias{associateTranscriptionFactors}
 \title{associateTranscriptionFactors}
 \description{
 In the analysis of, or exploration of gene regulatory networks, one
 often creates a data.frame of possible genomic regulatory sites, genomic
 locations where a TF binding motif matches some DNA sequence.  A common
 next step is to associate each of these motifs with its related
 transcription factor/s.     We provide two sources for those
 relationships.  When you specify the "MotifDb" source, we return
 the motif/TF relationships provided by each of the constituent
 public MotifDb sources.  When you specify the "TFClass" source,
 transcription factor family memberships (described in
 \url{https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4383905/}) are -
 sometimes expansively - provided for each motif you supply.
 
 This method uses, and therefore expects, different columns of the incoming data.frame
 to be used with each method.  The MotifDb source uses the "motifName" column of
 the incoming data.frame.  The TFClass source expects a "shortName"
 column in the incoming database.
 
 A new column, "geneSymbol", is added to the incoming data.frame.  This
 new column identifies the transcription factor associated with the motif
 for each row in the data.frame.
 
 }
 \usage{
 \S4method{associateTranscriptionFactors}{MotifList}(object, tbl.withMotifs, source, expand.rows)
 }
 \arguments{
   \item{object}{a \code{MotifList} object.}
   \item{tbl.withMotifs}{a \code{data.frame}}
   \item{source}{a \code{character} string, either 'MotifDb' or "TFClass' (case insensitive)}
     \item{expand.rows}{a \code{logical} value, recommended especially for the TFClass source,
       in which sometimes many TFs are mapped to the same motif}
 }
 
 \value{
   A data.frame with one column ("geneSymbol") and possibly multiple rows added
 }
 \author{Paul Shannon}
 
 \examples{
   tbl.tfClassExample <- data.frame(motifName=c("MA0006.1", "MA0042.2", "MA0043.2"),
                                    chrom=c("chr1", "chr1", "chr1"),
                                    start=c(1000005, 1000085, 1000105),
                                    start=c(1000013, 1000092, 1000123),
                                    score=c(0.85, 0.92, 0.98),
                                    stringsAsFactors=FALSE)
       # here we illustrate how to add a column with the required name:
   tbl.tfClassExample$shortMotif <- tbl.tfClassExample$motifName
   tbl.out <- associateTranscriptionFactors(MotifDb, tbl.tfClassExample, source="TFClass",
                                            expand.rows=TRUE)
   dim(tbl.out)   #    MANY tfs mapped, mostly FOX family genes
   tbl.motifDbExample <- data.frame(motifName=c("Mmusculus-jaspar2016-Ahr::Arnt-MA0006.1",
                                                "Hsapiens-jaspar2016-FOXI1-MA0042.2",
                                                "Hsapiens-jaspar2016-HLF-MA0043.2"),
                                     chrom=c("chr1", "chr1", "chr1"),
                                     start=c(1000005, 1000085, 1000105),
                                     start=c(1000013, 1000092, 1000123),
                                     score=c(0.85, 0.92, 0.98),
                                     stringsAsFactors=FALSE)
 
    tbl.out <- associateTranscriptionFactors(MotifDb, tbl.motifDbExample, source="MotifDb",
                                             expand.rows=TRUE)
    dim(tbl.out)   # one new column ("geneSymbol"), no new rows
 }
 \seealso{
   MotifDb,
   geneToMotif,
   motifToGene,
   subset,
   query
 }
 
 \keyword{utilities}