%\VignetteIndexEntry{06. Annotation}
%\VignettePackage{useR2013}

\SweaveOpts{keep.source=TRUE, pdf=FALSE, png=TRUE}
<<setup, echo=FALSE>>=
options(width=90)
library(useR2013)
@

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

\Bioconductor{} provides extensive annotation resources, summarized in
Figure \ref{fig:dbtypes}. These can be \emph{gene}-, or
\emph{genome}-centric. Annotations can be provided in packages curated
by \Bioconductor, or obtained from web-based resources. Gene-centric
\Biocpkg{AnnotationDbi} packages include:
\begin{itemize}
  \item Organism level: e.g. \Biocannopkg{org.Mm.eg.db}.
  \item Platform level: e.g. \Biocannopkg{hgu133plus2.db},
        \Biocannopkg{hgu133plus2.probes}, \Biocannopkg{hgu133plus2.cdf}.
  \item Homology level: e.g. \Biocannopkg{hom.Dm.inp.db}.
  \item System biology level: \Biocpkg{GO.db}, \Biocpkg{KEGG.db},
    \Biocpkg{Reactome.db}.
\end{itemize}
Examples of genome-centric packages include:
\begin{itemize}
  \item \Biocpkg{GenomicFeatures}, to represent genomic features,
    including constructing reproducible feature or transcript data
    bases from file or web resources.
  \item Pre-built transcriptome packages,
    e.g. \Biocannopkg{TxDb.Hsapiens.UCSC.hg19.knownGene} based on the
    \Hsap{} UCSC hg19 knownGenes track.
  \item \Biocpkg{BSgenome} for whole genome sequence representation
    and manipulation.
  \item Pre-built genomes, e.g.,
    \Biocannopkg{BSgenome.Hsapiens.UCSC.hg19} based on the \Hsap{}
    UCSC hg19 build.
\end{itemize}
Web-based resources include
\begin{itemize}
  \item \Biocpkg{biomaRt} to query
    \href{http://www.biomart.org/}{biomart} resource for genes,
    sequence, SNPs, and etc.
  \item \Biocpkg{rtracklayer} for interfacing with browser tracks,
    especially the \href{http:://genome.ucsc.edu}{UCSC} genome browser.
\end{itemize}

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

\subsection{Gene-Centric Annotations with \Biocpkg{AnnotationDbi}}

Organism-level (`org') packages contain mappings between a central
identifier (e.g., Enterz gene ids) and other identifiers (e.g. GenBank
or Uniprot accession number, RefSeq id, etc.).  The name of an org
package is always of the form \emph{org.<Sp>.<id>.db}
(e.g. \Biocannopkg{org.Sc.sgd.db}) where \emph{<Sp>} is a 2-letter
abbreviation of the organism (e.g. \texttt{Sc} for \emph{Saccharomyces
  cerevisiae}) and \emph{<id>} is an abbreviation (in lower-case)
describing the type of central identifier (e.g. \texttt{sgd} for gene
identifiers assigned by the \emph{Saccharomyces} Genome Database, or
\texttt{eg} for Entrez gene ids).  The ``How to use the `.db'
annotation packages'' vignette in the \Biocpkg{AnnotationDbi} package
(org packages are only one type of ``.db'' annotation packages) is a
key reference.  The `.db' and most other \Bioconductor{} annotation
packages are updated every 6 months.

Annotation packages contain an object named after the package itself.
These objects are collectively called \Rclass{AnnotationDb} objects,
with more specific classes named \Rclass{OrgDb}, \Rclass{ChipDb} or
\Rclass{TranscriptDb} objects.  Methods that can be applied to these
objects include \Rfunction{cols}, \Rfunction{keys},
\Rfunction{keytypes} and \Rfunction{select}.

%% select exercise
\begin{Exercise}
  What is the name of the org package for \emph{Drosophila}? Load it.

  Display the \Rclass{OrgDb} object for the \Biocpkg{org.Dm.eg.db} package.

  Use the \Rfunction{cols} method to discover which sorts of
  annotations can be extracted from it.

  Use the \Rfunction{keys} method to extract UNIPROT identifiers and
  then pass those keys in to the \Rfunction{select} method in such a
  way that you extract the SYMBOL (gene symbol) and KEGG pathway
  information for each.

  Use \Rfunction{select} to retrieve the ENTREZ and SYMBOL
  identifiers of all genes in the KEGG pathway \texttt{00310}.
\end{Exercise}
\begin{Solution}
  The \Rclass{OrgDb} object is named \Rcode{org.Dm.eg.db}.
<<select>>=
cols(org.Dm.eg.db)
keytypes(org.Dm.eg.db)
uniprotKeys <- head(keys(org.Dm.eg.db, keytype="UNIPROT"))
cols <- c("SYMBOL", "PATH")
select(org.Dm.eg.db, keys=uniprotKeys, cols=cols, keytype="UNIPROT")
@
Selecting UNIPROT and SYMBOL ids of KEGG pathway \texttt{00310} is
very similar:
<<select-kegg>>=
kegg <- select(org.Dm.eg.db, "00310", c("UNIPROT", "SYMBOL"), "PATH")
nrow(kegg)
head(kegg, 3)
@
\end{Solution}

\begin{Exercise}
  Annotate the top table from the RNA-seq differential expression
  analysis of Section~\ref{sec:rnaseq}.
\end{Exercise}

\subsection{Genome-Centric Annotations with \Biocpkg{GenomicFeatures}}

Genome-centric packages are very useful for annotations involving
genomic coordinates. It is straight-forward, for instance, to discover
the coordinates of coding sequences in regions of interest, and from
these retrieve corresponding DNA or protein coding sequences. Other
examples of the types of operations that are easy to perform with
genome-centric annotations include defining regions of interest for
counting aligned reads in RNA-seq experiments
(Section~\ref{sec:rnaseq}) and retrieving DNA sequences underlying
regions of interest in ChIP-seq analysis (Section \ref{sec:chipseq}),
e.g., for motif characterization.

\begin{Exercise}
  The objective of this exercise is to characterize the distance
  between identified peaks and nearest transcription start site.

  Load the ENCODE summary data, select the peaks found in all samples,
  and use the center of these peaks as a proxy for the true ChIP
  binding site. 
  
  Use the transcript data base for the UCSC Known Genes track of hg19
  as a source for transcripts and transcription start sites (TSS). 
  
  Use \Rcode{nearest} to identify the TSS that is nearest each peak,
  and calculate the distance between the peak and TSS; measure
  distance taking account of the strand of the transcript, so that
  peaks 5' of the TSS have negative distance.  
  
  Summarize the locations of the peaks relative to the TSS.
\end{Exercise}

\begin{Solution}
  Read in the ENCODE ChIP peaks for all cell lines.
<<chipseq-anno-data>>=
stamFile <- system.file("data", "stam.Rda", package="useR2013")
load(stamFile)
@
  Identify the rows of \Robject{stam} that have non-zero counts for
  all cell lines, and extract the corresponding ranges:
<<chipseq-anno-common>>=
ridx <- rowSums(assays(stam)[["Tags"]] > 0) == ncol(stam)
peak <- rowData(stam)[ridx]
@
  Select the center of the ranges of these peaks, as a proxy for the
  ChIP binding site:
<<chipseq-anno-centers>>=
peak <- resize(peak, width=1, fix="center")
@

  Obtain the TSS from the
  \Biocannopkg{TxDb.Hsapiens.UCSC.hg19.knownGene} using the
  \Rfunction{transcripts} function to extract coordinates of each
  transcript, and \Rfunction{resize} to a width of 1 for the TSS; does
  this do the right thing for transcripts on the plus and on the minus
  strand?
<<chipseq-anno-tss>>=
library(TxDb.Hsapiens.UCSC.hg19.knownGene)
tx <- transcripts(TxDb.Hsapiens.UCSC.hg19.knownGene)
tss <- resize(tx, width=1)
@
  The \Rfunction{nearest} function returns the index of the nearest
  \Rcode{subject} to each \Rcode{query} element; the distance
  between peak and nearest TSS is thus
<<chipseq-anno-tss-dist>>=
idx <- nearest(peak, tss)
sgn <- as.integer(ifelse(strand(tss)[idx] == "+", 1, -1))
dist <- (start(peak) - start(tss)[idx]) * sgn
@
  Here we summarize the distances as a simple table and density plot,
  focusing on binding sites within 1000 bases of a transcription start
  site; the density plot is in Figure~\ref{fig:chipseq:disthist}.
<<chipseq-anno-tss-dist>>=
bound <- 1000
ok <- abs(dist) < bound
dist <- dist[ok]
table(sign(dist))
@
<<anno-tss-disthist, fig=TRUE, include=FALSE>>=
griddensityplot <-
    function(...)
    ## 'panel' function to plot a grid underneath density
{
    panel.grid()
    panel.densityplot(...)
}
print(densityplot(dist[ok], plot.points=FALSE,
    panel=griddensityplot,
    xlab="Distance to Nearest TSS"))
@
%%
  The distance to transcript start site is a useful set of operations,
  so let's make it a re-usable function
<<tss-dist-func>>=
distToTss <-
    function(peak, tx)
{
    peak <- resize(peak, width=1, fix="center")
    tss <- resize(tx, width=1)
    idx <- nearest(peak, tss)
    sgn <- as.numeric(ifelse(strand(tss)[idx] == "+", 1, -1))
    (start(peak) - start(tss)[idx]) * sgn
}
@
\end{Solution}
\begin{figure}
  \centering
  \includegraphics[width=.4\textwidth]{Annotation-anno-tss-disthist}
  \caption{Distance to nearest TSS amongst conserved peaks}
  \label{fig:chipseq:disthist}
\end{figure}

\begin{Exercise}
  As an additional exercise, extract the sequences of all conserved
  peaks on `chr6'. Use the \Biocannopkg{BSgenome.Hsapiens.UCSC.hg19}
  package and \Rcode{getSeq} function to do this. Use
  \Rfunction{matchPWM} to find sequences with a strong match to the
  JASPAR CTCF PWM motif, and plot the density of distances to nearest
  transcription start site for those with and without a match.  What
  strategies are available for motif discovery?
\end{Exercise}
\begin{Solution}
  Here we select peaks on chromosome 6, and extract the DNA sequences
  corresponding to these peaks.
<<chipseq-anno-seq>>=
library(BSgenome.Hsapiens.UCSC.hg19)
ridx <- rowSums(assays(stam)[["Tags"]] > 0) == ncol(stam)
ridx <- ridx & (seqnames(rowData(stam)) == "chr6")
pk6 <- rowData(stam)[ridx]
seqs <- getSeq(Hsapiens, pk6)
head(seqs, 3)
@
%%
  \Rfunction{matchPWM} operates on one DNA sequence at a time, so we
  arrange to search for the PWM on each sequence using
  \Rfunction{lapply}. We identify sequences with a match by testing
  the length of the returned object, and use this to create a density
  plot (Figure~\ref{fig:chipseq-tss-dist-2}).
<<chipseq-tss-dist-2, fig=TRUE, include=FALSE>>=
pwm <- useR2013::getJASPAR("MA0139.1")
hits <- lapply(seqs, matchPWM, pwm=pwm)
hasPwmMatch <- sapply(hits, length) > 0
dist <- distToTss(pk6, tx)

ok <- abs(dist) < bound
df <- data.frame(Distance = dist[ok], HasPwmMatch = hasPwmMatch[ok])
print(densityplot(~Distance, group=HasPwmMatch, df,
    plot.points=FALSE, panel=griddensityplot,
    auto.key=list(
      columns=2,
      title="Has Position Weight Matrix?",
      cex.title=1),
    xlab="Distance to Nearest Tss"))
@
\begin{figure}
  \centering
  \includegraphics[width=.4\textwidth]{Annotation-chipseq-tss-dist-2.png}
  \caption{Nearest TSS in sequences with and without a PWM match}
  \label{fig:chipseq-tss-dist-2}
\end{figure}
\end{Solution}

\subsection{Exploring Annotated Variants: \Biocpkg{VariantAnnotation}}

A major product of DNASeq experiments are catalogs of called variants
(e.g., SNPs, indels).  We will use the \Biocpkg{VariantAnnotation}
package to explore this type of data.  Sample data included in the
package are a subset of chromosome 22 from the
\href{ftp://ftp-trace.ncbi.nih.gov/1000genomes/ftp/release/20110521/}{1000
  Genomes} project. Variant Call Format (VCF;
\href{http://www.1000genomes.org/wiki/Analysis/Variant%20Call%20Format/vcf-variant-call-format-version-41}{full
  description}) text files contain meta-information lines, a header
line with column names, data lines with information about a position
in the genome, and optional genotype information on samples for each
position.

Data are read from a VCF file and variants identified according to
region such as \Rcode{coding}, \Rcode{intron}, \Rcode{intergenic},
\Rcode{spliceSite} etc. Amino acid coding changes are computed for the
non-synonymous variants. SIFT and PolyPhen databases provide
predictions of how severely the coding changes affect protein
function.

\begin{Exercise}
  The objective of this exercise is to compare the quality of called
  SNPs that are located in dbSNP, versus those that are novel.

  Locate the sample data in the file system. Explore the metadata
  (information about the content of the file) using
  \Rfunction{scanVcfHeader}. Discover the `info' fields \Rcode{VT}
  (variant type), and \Rcode{RSQ} (genotype imputation quality).

  Input sample data in using \Rfunction{readVcf}. You'll need to
  specify the genome build (\Rcode{genome="hg19"}) on which the
  variants are annotated. Take a peak at the \Rfunction{rowData} to
  see the genomic locations of each variant.

  dbSNP uses abbreviations such as \texttt{ch22} to represent
  chromosome 22, whereas the VCF file uses \texttt{22}. Use
  \Rfunction{rowData} and \Rfunction{renameSeqlevels} to extract the
  row data of the variants, and rename the chromosomes.

  The \Biocannopkg{SNPlocs.Hsapiens.dbSNP.20101109} contains
  information about SNPs in a particular build of dbSNP. Load the
  package, use the \Rfunction{dbSNPFilter} function to create a
  filter, and query the row data of the VCF file for membership.

  Create a data frame containing the dbSNP membership status and
  imputation quality of each SNP. Create a density plot to illustrate
  the results.
\end{Exercise}

\begin{Solution}
%%
  Explore the header:
<<readVcf>>=
library(VariantAnnotation)
fl <- system.file("extdata", "chr22.vcf.gz",
                  package="VariantAnnotation")
(hdr <- scanVcfHeader(fl))
info(hdr)[c("VT", "RSQ"),]
@
%%
  Input the data and peak at their locations:
<<readVcf>>=
(vcf <- readVcf(fl, "hg19"))
head(rowData(vcf), 3)
@
%%
  Rename chromosome levels:
<<renameSeqlevels>>=
rowData(vcf) <- renameSeqlevels(rowData(vcf), c("22"="ch22"))
@
%%
  Discover whether SNPs are located in dbSNP:
<<dbSNP>>=
library(SNPlocs.Hsapiens.dbSNP.20101109)
snpFilt <- useR2013::dbSNPFilter("SNPlocs.Hsapiens.dbSNP.20101109")
inDbSNP <- snpFilt(vcf)
table(inDbSNP)
@
%%
  Create a data frame summarizing SNP quality and dbSNP membership:
<<SNP-quality>>=
metrics <-
    data.frame(inDbSNP=inDbSNP, RSQ=info(vcf)$RSQ)
@
%%
  Finally, visualize the data, e.g., using \Rpackage{ggplot2}
  (Figure~\ref{fig:variant-annotation:RSQ}).
<<RSQ-plot, fig=TRUE, include=FALSE>>=
library(ggplot2)
ggplot(metrics, aes(RSQ, fill=inDbSNP)) +
    geom_density(alpha=0.5) +
    scale_x_continuous(name="MaCH / Thunder Imputation Quality") +
    scale_y_continuous(name="Density") +
    theme(legend.position="top")
@

\begin{figure}
  \centering
  \includegraphics[width=.4\textwidth]{Annotation-RSQ-plot}
  \caption{Quality scores of variants in dbSNP, compared to those not
    in dbSNP.}
  \label{fig:variant-annotation:RSQ}
\end{figure}
\end{Solution}

%% FIXME: \subsection{Resources}
