%\VignetteIndexEntry{06. Annotation}
%\VignettePackage{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}.
\begin{Schunk}
\begin{Sinput}
> cols(org.Dm.eg.db)
\end{Sinput}
\begin{Soutput}
 [1] "ENTREZID"     "ACCNUM"       "ALIAS"        "CHR"          "CHRLOC"      
 [6] "CHRLOCEND"    "ENZYME"       "MAP"          "PATH"         "PMID"        
[11] "REFSEQ"       "SYMBOL"       "UNIGENE"      "ENSEMBL"      "ENSEMBLPROT" 
[16] "ENSEMBLTRANS" "GENENAME"     "UNIPROT"      "GO"           "EVIDENCE"    
[21] "ONTOLOGY"     "GOALL"        "EVIDENCEALL"  "ONTOLOGYALL"  "FLYBASE"     
[26] "FLYBASECG"    "FLYBASEPROT" 
\end{Soutput}
\begin{Sinput}
> keytypes(org.Dm.eg.db)
\end{Sinput}
\begin{Soutput}
 [1] "ENTREZID"     "ACCNUM"       "ALIAS"        "CHR"          "CHRLOC"      
 [6] "CHRLOCEND"    "ENZYME"       "MAP"          "PATH"         "PMID"        
[11] "REFSEQ"       "SYMBOL"       "UNIGENE"      "ENSEMBL"      "ENSEMBLPROT" 
[16] "ENSEMBLTRANS" "GENENAME"     "UNIPROT"      "GO"           "EVIDENCE"    
[21] "ONTOLOGY"     "GOALL"        "EVIDENCEALL"  "ONTOLOGYALL"  "FLYBASE"     
[26] "FLYBASECG"    "FLYBASEPROT" 
\end{Soutput}
\begin{Sinput}
> uniprotKeys <- head(keys(org.Dm.eg.db, keytype="UNIPROT"))
> cols <- c("SYMBOL", "PATH")
> select(org.Dm.eg.db, keys=uniprotKeys, cols=cols, keytype="UNIPROT")
\end{Sinput}
\begin{Soutput}
  UNIPROT  SYMBOL  PATH
1  Q8IRZ0  CG3038  <NA>
2  Q95RP8  CG3038  <NA>
3  Q95RU8     G9a 00310
4  Q9W5H1 CG13377  <NA>
5  P39205     cin  <NA>
6  Q24312     ewg  <NA>
\end{Soutput}
\end{Schunk}
Selecting UNIPROT and SYMBOL ids of KEGG pathway \texttt{00310} is
very similar:
\begin{Schunk}
\begin{Sinput}
> kegg <- select(org.Dm.eg.db, "00310", c("UNIPROT", "SYMBOL"), "PATH")
> nrow(kegg)
\end{Sinput}
\begin{Soutput}
[1] 32
\end{Soutput}
\begin{Sinput}
> head(kegg, 3)
\end{Sinput}
\begin{Soutput}
   PATH UNIPROT  SYMBOL
1 00310  Q95RU8     G9a
2 00310  Q9W5E0 Hmt4-20
3 00310  Q9W3N9 CG10932
\end{Soutput}
\end{Schunk}
\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.
\begin{Schunk}
\begin{Sinput}
> stamFile <- system.file("data", "stam.Rda", package="useR2013")
> load(stamFile)
\end{Sinput}
\end{Schunk}
  Identify the rows of \Robject{stam} that have non-zero counts for
  all cell lines, and extract the corresponding ranges:
\begin{Schunk}
\begin{Sinput}
> ridx <- rowSums(assays(stam)[["Tags"]] > 0) == ncol(stam)
> peak <- rowData(stam)[ridx]
\end{Sinput}
\end{Schunk}
  Select the center of the ranges of these peaks, as a proxy for the
  ChIP binding site:
\begin{Schunk}
\begin{Sinput}
> peak <- resize(peak, width=1, fix="center")
\end{Sinput}
\end{Schunk}

  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?
\begin{Schunk}
\begin{Sinput}
> library(TxDb.Hsapiens.UCSC.hg19.knownGene)
> tx <- transcripts(TxDb.Hsapiens.UCSC.hg19.knownGene)
> tss <- resize(tx, width=1)
\end{Sinput}
\end{Schunk}
  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
\begin{Schunk}
\begin{Sinput}
> idx <- nearest(peak, tss)
> sgn <- as.integer(ifelse(strand(tss)[idx] == "+", 1, -1))
> dist <- (start(peak) - start(tss)[idx]) * sgn
\end{Sinput}
\end{Schunk}
  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}.
\begin{Schunk}
\begin{Sinput}
> bound <- 1000
> ok <- abs(dist) < bound
> dist <- dist[ok]
> table(sign(dist))
\end{Sinput}
\begin{Soutput}
  -1    0    1 
1262    4  707 
\end{Soutput}
\end{Schunk}
\begin{Schunk}
\begin{Sinput}
> 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"))
\end{Sinput}
\end{Schunk}
%%
  The distance to transcript start site is a useful set of operations,
  so let's make it a re-usable function
\begin{Schunk}
\begin{Sinput}
> 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{Sinput}
\end{Schunk}
\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.
\begin{Schunk}
\begin{Sinput}
> 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)
\end{Sinput}
\begin{Soutput}
  A DNAStringSet instance of length 3
    width seq
[1]   311 CAGGGAGACTTGGGAAGGCTTCACGAAGGAGGGTGCCTG...GTTGTACCCAACTCCTAAGCGTCACACATATAATCCTG
[2]   331 GCTAATAATTTACCATGAAGTAACAACTTTTCACTATGT...TGCTGTTTCCTAGGCAGCGAATTTAAGGGTAATGATCA
[3]   751 GTAAAGAATGGACTGACTTAAAGGCAGATGGAATTTCAC...GCTATAATCAAACAAGACAAAGAATCTTCGTGGCCACA
\end{Soutput}
\end{Schunk}
%%
  \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}).
\begin{Schunk}
\begin{Sinput}
> 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"))
\end{Sinput}
\end{Schunk}
\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:
\begin{Schunk}
\begin{Sinput}
> library(VariantAnnotation)
> fl <- system.file("extdata", "chr22.vcf.gz",
+                   package="VariantAnnotation")
> (hdr <- scanVcfHeader(fl))
\end{Sinput}
\begin{Soutput}
class: VCFHeader 
samples(5): HG00096 HG00097 HG00099 HG00100 HG00101
meta(1): fileformat
fixed(1): ALT
info(22): LDAF AVGPOST ... VT SNPSOURCE
geno(3): GT DS GL
\end{Soutput}
\begin{Sinput}
> info(hdr)[c("VT", "RSQ"),]
\end{Sinput}
\begin{Soutput}
DataFrame with 2 rows and 3 columns
         Number        Type                                        Description
    <character> <character>                                        <character>
VT            1      String indicates what type of variant the line represents
RSQ           1       Float      Genotype imputation quality from MaCH/Thunder
\end{Soutput}
\end{Schunk}
%%
  Input the data and peak at their locations:
\begin{Schunk}
\begin{Sinput}
> (vcf <- readVcf(fl, "hg19"))
\end{Sinput}
\begin{Soutput}
class: CollapsedVCF 
dim: 10376 5 
rowData(vcf):
  GRanges with 5 metadata columns: paramRangeID, REF, ALT, QUAL, FILTER
info(vcf):
  DataFrame with 22 columns: LDAF, AVGPOST, RSQ, ERATE, THETA, CIEND, CIPOS, END, HOML...
info(header(vcf)):
             Number Type    Description                                                 
   LDAF      1      Float   MLE Allele Frequency Accounting for LD                      
   AVGPOST   1      Float   Average posterior probability from MaCH/Thunder             
   RSQ       1      Float   Genotype imputation quality from MaCH/Thunder               
   ERATE     1      Float   Per-marker Mutation rate from MaCH/Thunder                  
   THETA     1      Float   Per-marker Transition rate from MaCH/Thunder                
   CIEND     2      Integer Confidence interval around END for imprecise variants       
   CIPOS     2      Integer Confidence interval around POS for imprecise variants       
   END       1      Integer End position of the variant described in this record        
   HOMLEN    .      Integer Length of base pair identical micro-homology at event bre...
   HOMSEQ    .      String  Sequence of base pair identical micro-homology at event b...
   SVLEN     1      Integer Difference in length between REF and ALT alleles            
   SVTYPE    1      String  Type of structural variant                                  
   AC        .      Integer Alternate Allele Count                                      
   AN        1      Integer Total Allele Count                                          
   AA        1      String  Ancestral Allele, ftp://ftp.1000genomes.ebi.ac.uk/vol1/ft...
   AF        1      Float   Global Allele Frequency based on AC/AN                      
   AMR_AF    1      Float   Allele Frequency for samples from AMR based on AC/AN        
   ASN_AF    1      Float   Allele Frequency for samples from ASN based on AC/AN        
   AFR_AF    1      Float   Allele Frequency for samples from AFR based on AC/AN        
   EUR_AF    1      Float   Allele Frequency for samples from EUR based on AC/AN        
   VT        1      String  indicates what type of variant the line represents          
   SNPSOURCE .      String  indicates if a snp was called when analysing the low cove...
geno(vcf):
  SimpleList of length 3: GT, DS, GL
geno(header(vcf)):
      Number Type   Description                      
   GT 1      String Genotype                         
   DS 1      Float  Genotype dosage from MaCH/Thunder
   GL .      Float  Genotype Likelihoods             
\end{Soutput}
\begin{Sinput}
> head(rowData(vcf), 3)
\end{Sinput}
\begin{Soutput}
GRanges with 3 ranges and 5 metadata columns:
              seqnames               ranges strand | paramRangeID            REF
                 <Rle>            <IRanges>  <Rle> |     <factor> <DNAStringSet>
    rs7410291       22 [50300078, 50300078]      * |         <NA>              A
  rs147922003       22 [50300086, 50300086]      * |         <NA>              C
  rs114143073       22 [50300101, 50300101]      * |         <NA>              G
                             ALT      QUAL      FILTER
              <DNAStringSetList> <numeric> <character>
    rs7410291                  G       100        PASS
  rs147922003                  T       100        PASS
  rs114143073                  A       100        PASS
  ---
  seqlengths:
   22
   NA
\end{Soutput}
\end{Schunk}
%%
  Rename chromosome levels:
\begin{Schunk}
\begin{Sinput}
> rowData(vcf) <- renameSeqlevels(rowData(vcf), c("22"="ch22"))
\end{Sinput}
\end{Schunk}
%%
  Discover whether SNPs are located in dbSNP:
\begin{Schunk}
\begin{Sinput}
> library(SNPlocs.Hsapiens.dbSNP.20101109)
> snpFilt <- useR2013::dbSNPFilter("SNPlocs.Hsapiens.dbSNP.20101109")
> inDbSNP <- snpFilt(vcf)
> table(inDbSNP)
\end{Sinput}
\begin{Soutput}
inDbSNP
FALSE  TRUE 
 6126  4250 
\end{Soutput}
\end{Schunk}
%%
  Create a data frame summarizing SNP quality and dbSNP membership:
\begin{Schunk}
\begin{Sinput}
> metrics <-
+     data.frame(inDbSNP=inDbSNP, RSQ=info(vcf)$RSQ)
\end{Sinput}
\end{Schunk}
%%
  Finally, visualize the data, e.g., using \Rpackage{ggplot2}
  (Figure~\ref{fig:variant-annotation:RSQ}).
\begin{Schunk}
\begin{Sinput}
> 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")
\end{Sinput}
\end{Schunk}

\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}
