%\VignetteIndexEntry{05. Annotation}
%\VignettePackage{useR2011}

\SweaveOpts{keep.source=TRUE}
<<setup, echo=FALSE>>=
options(digits=2)
library(useR2011)
library(org.Dm.eg.db)
@ 

\section{Annotation}
\label{sec:annotation}

\subsection{Major types of annotation in \emph{Bioconductor}}

\begin{figure}[ht]
\centering
\includegraphics[width=\textwidth]{databaseTypes.pdf}
\caption{Annotation Packages: the big picture}
\label{fig:dbtypes}
\end{figure}

\noindent Gene centric \Rpackage{AnnotationDbi} packages:
\begin{itemize}
  \item Organism level: e.g. \Rpackage{org.Mm.eg.db}.
  \item Platform level: e.g. \Rpackage{hgu133plus2.db},
        \Rpackage{hgu133plus2.probes}, \Rpackage{hgu133plus2.cdf}.
  \item Homology level: e.g. \Rpackage{hom.Dm.inp.db}.
  \item System-biology level: \Rpackage{GO.db} or \Rpackage{KEGG.db}.
\end{itemize}

\noindent Genome centric \Rpackage{GenomicFeatures} packages:
\begin{itemize}
  \item Transcriptome level: e.g. \Rpackage{TxDb.Hsapiens.UCSC.hg19.knownGene}
  \item Generic genome features: Can generate via \Rpackage{GenomicFeatures}
\end{itemize}

\noindent \Rpackage{biomaRt}:
\begin{itemize}
  \item Query web-based `biomart' resource for genes, sequence,
        SNPs, and etc.
\end{itemize}

\subsection{Organism level packages}

An organism level package (aka ``org package'') is organized around a
central gene id (e.g. Entrez Gene id) and contains a collection of mappings
between this central id and other kinds of ids (e.g. GenBank or Uniprot
accession number, RefSeq id, etc...).
The name of an org package is always of the form \textit{org.<Ab>.<efg>.db}
(e.g. \Rpackage{org.Sc.sgd.db}) where \textit{<Ab>} is a 2-letter
abbreviation of the organism (e.g. \Rpackage{Sc} for Saccharomyces cerevisiae)
and \textit{<efg>} is an abbreviation (in lower-case) describing the type
of central gene id (e.g. \Rpackage{sgd} for gene ids assigned by the
Saccharomyces Genome Database people or \Rpackage{eg} for Entrez Gene ids).

The document of reference for using org packages is the \textit{How to use
the ``.db'' annotation packages} vignette in the \Rpackage{AnnotationDbi}
package (org packages are only one type of ``.db'' annotation packages).

Like almost all the annotation packages in \Bioconductor{}, the ``.db''
annotation packages are updated every 6 months (i.e. at every new
\Bioconductor{} release).

\begin{Exercise}
  What's the name of the org package for Fly? Load it.

  Use \Rcode{ls('package:<pkgname>')} to display the list of all the
  symbols defined in this package. Explore a few of them by looking
  at their man page, at their class, and by extracting a few samples
  from them with \Rcode{sample(map, 5)}.

  Turn a map into a data frame with \Rfunction{toTable} (use
  \Rfunction{head} to only display the first rows).
  What are the left keys? What are the right keys?

  Most maps can be reversed with \Rfunction{revmap}.
  Reverse a map and extract a few samples from the reversed map.

  Note that reversing a map does NOT switch the left and right keys.
  You can check this with the \Rcode{Lkeys} and \Rcode{Rkeys}
  accessors.
\end{Exercise}

\begin{Solution}
<<org.Dm.eg.db>>=
library(org.Dm.eg.db)
ls('package:org.Dm.eg.db')
org.Dm.egUNIPROT
class(org.Dm.egUNIPROT)
sample(org.Dm.egUNIPROT, 5)
head(toTable(org.Dm.egUNIPROT))
@
  The left keys are the Entrez Gene ids and the right keys the Uniprot
  accession numbers. Note that for all the maps in an org package the
  left key is always the central gene id.
<<revmap>>=
revmap(org.Dm.egUNIGENE)
sample(revmap(org.Dm.egUNIGENE), 5)
identical(Lkeys(org.Dm.egUNIGENE), Lkeys(revmap(org.Dm.egUNIGENE)))
@
\end{Solution}

\begin{Exercise}
  For convenience, \Rcode{lrTest}, the \Rclass{DGEGLM} object obtained in
  the previous section with \Rfunction{glmLRT}, has been included to the
  \Rpackage{user2011} package.
  Load it and create again the `top table' of differentially represented
  genes with \Rfunction{topTags}.

  Extract the Flybase gene ids from this table and map them to their
  corresponding Entrez Gene id (create a named character vector with names
  the Flybase gene ids and values the Entrez Gene ids).

  Finally, add 2 columns to the \Rcode{table} component of the
  \Rclass{TopTags} object created previously: one for the Entrez Gene ids
  and one for their corresponding gene symbols.
\end{Exercise}

\begin{Solution}
<<tt-to-eg>>=
library(org.Dm.eg.db)
data(lrTest)
tt <- topTags(lrTest)
@

<<tt-to-eg1>>=
fbids <- rownames(tt$table)
egids <- unlist(mget(fbids, revmap(org.Dm.egFLYBASE), ifnotfound=NA))
egids
@

Because \Rfunction{unlist} can do strange things when the list to unlist
has duplicated names, a better way to do this is:

<<tt-to-eg2>>=
fbids <- rownames(tt$table)
map <- org.Dm.egFLYBASE
fbids <- intersect(mappedRkeys(map), fbids)
egids <- as.character(revmap(map)[fbids])
egids
@

To add the 2 columns to \Rcode{tt\$table}, we proceed in 3 steps:
(1) merge the 2 mappings in a single data frame \Rcode{anno0},
(2) align the rows in \Rcode{anno0} with the rows in \Rcode{tt\$table}
(by redordering them), and (3) cbind \Rcode{tt\$table} with the
2 new columns:
<<<tt-annotate>>=
eg2fb <- toTable(org.Dm.egFLYBASE[egids])
eg2sym <- toTable(org.Dm.egSYMBOL[egids])
(anno0 <- merge(eg2fb, eg2sym))
(anno0 <- anno0[match(rownames(tt$table), anno0$flybase_id), ])
anno <- cbind(tt$table, anno0[ , c("gene_id", "symbol")])
@ 
\end{Solution}

