%\VignetteIndexEntry{01. Introduction}
%\VignettePackage{useR2013}


\section{Introduction}

This workshop introduces use of \R{} and \Bioconductor{} for analysis
of high-throughput sequence data. The workshop is structured as a
series of short remarks followed by group exercises. The exercises
explore the diversity of tasks for which \R{} / \Bioconductor{} are
appropriate, but are far from comprehensive.

The goals of the workshop are to: (1) develop familiarity with \R{} /
\Bioconductor{} software for high-throughput analysis; (2) expose key
statistical issues in the analysis of sequence data; and (3) provide
inspiration and a framework for further independent exploration.  An
approximate schedule is shown in Table \ref{tab:sched}.

\begin{table}
  \begin{center}
    \begin{minipage}[h]{\textwidth}
      \caption{Schedule.}
      \label{tab:sched}
      \medskip\par
      \hrule
      \begin{description}[topsep=3pt]
      \item[Introduction] \software{Rstudio} and the AMI; \R{}
        packages and help; \Bioconductor.
      \item[Sequences and ranges] Representing and manipulating
        biological sequences; working with genomic coordinates.
      \item [Reads and alignments] High-throughput sequence reads
        (fastq files) and their aligned representation (bam files).
      \item [RNA-seq] A post-alignment workflow for differential
        representation.
      \item [ChIP-seq] Working with multiple ChIP-seq experiments
      \item [Annotation] Resources for annotation of gene and genomes;
        working the variants (VCF files).
      \hrule
      \end{description}
    \end{minipage}
  \end{center}
\end{table}

\subsection{\software{Rstudio}}

\begin{Exercise}
  Log on to the \software{Rstudio} account set up for this course.
  
  Visit the `Packages' tab in the lower right panel, find the
  \Rpackage{useR2013} package, and discover the vignette (i.e., this
  document).
  
  Under the `Files' tab, figure out how to upload and download (small)
  files to the server.
\end{Exercise}
\subsection{\R}

The following should be familiar to you. \R{} has a number of standard
data types that represent \Rcode{integer}, \Rcode{numeric} (floating
point), \Rcode{complex}, \Rcode{character}, \Rcode{logical} (boolean),
and \Rcode{raw} (byte) data. It is possible to convert between data
types, and to discover the class (e.g., \Rfunction{class}) of a
variable. All of the vectors mentioned so far are homogenous,
consisting of a single type of element. A \Rcode{list} can contain a
collection of different types of elements and, like all vectors, these
elements can be named to create a key-value association. A
\Rcode{data.frame} is a list of equal-length vectors, representing a
rectangular data structure not unlike a spread sheet. Each column of
the data frame is a vector, so data types must be homogenous within a
column. A \Rcode{data.frame} can be subset by row or column, and
columns can be accessed with \Rcode{\$} or \Rcode{[[}. A \Rcode{matrix}
    is also a rectangular data structure, but subject to the
    constraint that all elements are the same type.

\R{} has \emph{object-oriented} ways of representing complicated data
objects; \Bioconductor{} makes extensive use of `S4' objects. Objects
are often created by functions (e.g., \Rfunction{GRanges}, below) with
parts of the object extracted or assigned using \emph{accessor}
functions. Many operations on classes are implemented as
\emph{methods} that specialize a \emph{generic} function for the
particular class of objects used to invoke the function. For instance,
\Rfunction{countOverlaps} is a generic that counts the number of times
elements of its \Rcode{query} argument overlaps elements of its
\Rcode{subject}; there are methods with slightly different behaviors
when the arguments are \Rclass{IRange} instances or \Rclass{GRanges}
instances (in the latter case, the \Rfunction{countOverlaps} method
pays attention to whether ranges are on the same strand and
chromosome, for instance).

Packages provide functionality beyond that available in base \R. There
are more than 500 \Bioconductor{} packages. Packages are contributed
by diverse members of the community; they vary in quality (many are
excellent) and sometimes contain idiosyncratic aspects to their
implementation. New packages (e.g., \Biocpkg{ShortRead},
\Biocpkg{VariantAnnotation} packages and their dependencies) can be
added to an \R{} installation using
\begin{Schunk}
\begin{Sinput}
> source("http://bioconductor.org/biocLite.R")
> biocLite(c("ShortRead", "VariantAnnotation")) # new packages
> biocLite()                                    # update packages
\end{Sinput}
\end{Schunk}
%% 
A package is installed only once per
\R{} installation, but needs to be loaded (with \Rfunction{library})
in each session in which it is used.

Find help using the \R{} help system. Start a web browser with
\begin{Schunk}
\begin{Sinput}
> help.start()
\end{Sinput}
\end{Schunk}
%% 
The `Search Engine and Keywords' link is helpful in day-to-day use.
Use manual pages to find detailed descriptions of the arguments and
return values of functions, and the structure and methods of classes.
Find help within an \R{} session using \Rcode{?}; the package defining
the help page must have been loaded (with \Rfunction{library}).
\begin{Schunk}
\begin{Sinput}
> library(ShortRead)
> ?readFastq
\end{Sinput}
\end{Schunk}
S4 classes and generics can be discovered with syntax like the
following for the \Rfunction{complement} generic in the
\Biocpkg{Biostrings} package:
\begin{Schunk}
\begin{Sinput}
> library(Biostrings)
> showMethods(complement)
\end{Sinput}
\begin{Soutput}
Function: complement (package Biostrings)
x="DNAString"
x="DNAStringSet"
x="MaskedDNAString"
x="MaskedRNAString"
x="RNAString"
x="RNAStringSet"
x="XStringViews"
\end{Soutput}
\end{Schunk}
Methods defined on the \Rfunction{DNAStringSet} class of
\Biocpkg{Biostrings} can be found with
\begin{Schunk}
\begin{Sinput}
> showMethods(class="DNAStringSet", where=getNamespace("Biostrings"))
\end{Sinput}
\end{Schunk}
Obtaining help on S4 classes and methods requires syntax such as
\begin{Schunk}
\begin{Sinput}
> class ? DNAStringSet
> method ? "complement,DNAStringSet"
\end{Sinput}
\end{Schunk}

Vignettes, especially in \Bioconductor{} packages, provide an
extensive narrative describing overall package functionality. Use
\begin{Schunk}
\begin{Sinput}
> vignette(package="useR2013")
\end{Sinput}
\end{Schunk}
%
to see a list of vignettes available in the \Rpackage{useR2013}
package. Vignettes usually consist of text with embedded \R{} code, a
form of literate programming.  The vignette can be read as a PDF
document, while the \R{} source code is present as a script file
ending with extension \texttt{.R}. The script file can be sourced or
copied into an \R{} session to evaluate exactly the commands used in
the vignette.

\subsection{\Bioconductor}

\Bioconductor{} is a collection of \R{} packages for the analysis and
comprehension of high-throughput genomic data. \Bioconductor{} started
more than 10 years ago. It gained credibility for its statistically
rigorous approach to microarray pre-preprocessing and analysis of
designed experiments, and integrative and reproducible approaches to
bioinformatic tasks. There are now more than 500 \Bioconductor{}
packages for expression and other microarrays, sequence analysis, flow
cytometry, imaging, and other domains.  The \Bioconductor{}
\href{http://bioconductor.org}{web site} provides installation,
package repository, help, and other documentation.

The \Bioconductor{} web site is at \url{bioconductor.org}. Features
include:
\begin{itemize} \itemsep0pt\parskip0pt
\item Introductory \href{http://bioconductor.org/help/workflows/}{work
  flows}.
\item A manifest of
  \href{http://bioconductor.org/packages/release/bioc/}{\Bioconductor{}
    packages} arranged in
  \href{http://bioconductor.org/packages/release/BiocViews.html}{BiocViews}.
\item
  \href{http://bioconductor.org/packages/release/data/annotation/}{Annotation}
  (data bases of relevant genomic information, e.g., Entrez gene ids
  in model organisms, KEGG pathways) and
  \href{http://bioconductor.org/packages/release/data/experiment/}{experiment
    data} (containing relatively comprehensive data sets and their
  analysis) packages.
\item
  \href{http://bioconductor.org/help/mailing-list/}{Mailing lists},
  including searchable archives, as the primary source of help.
\item \href{http://bioconductor.org/help/course-materials/}{Course and
  conference} information, including extensive reference material.
\item \href{http://bioconductor.org/about/}{General information} about
  the project.
\item
  \href{http://bioconductor.org/developers/}{Package developer}
  resources, including guidelines for creating and submitting new
  packages.
\end{itemize}

\paragraph{High-throughput sequence analysis}

Table \ref{tab:bioc-sequence-pkgs} enumerates many of the packages
available for sequence analysis. The table includes packages for
representing sequence-related data (e.g., \Biocpkg{GenomicRanges},
\Biocpkg{Biostrings}), as well as domain-specific analysis such as
RNA-seq (e.g., \Biocpkg{edgeR}, \Biocpkg{DEXSeq}), ChIP-seq
(e.g,. \Biocpkg{ChIPpeakAnno}, \Biocpkg{DiffBind}), and SNPs and copy
number variation (e.g., \Biocpkg{genoset}, \Biocpkg{ggtools},
\Biocpkg{VariantAnnotation}).

\begin{table}
  \centering
  \caption{Selected \Bioconductor{} packages for high-throughput
    sequence analysis.}
  \label{tab:bioc-sequence-pkgs}
  \begin{tabular}{lp{.7\textwidth}}
    Concept & Packages\\
    \hline

    Data representation & \Biocpkg{IRanges}, \Biocpkg{GenomicRanges},
    \Biocpkg{GenomicFeatures}, \Biocpkg{Biostrings},
    \Biocpkg{BSgenome}, \Biocpkg{girafe}.\\

    Input / output & \Biocpkg{ShortRead} (fastq), \Biocpkg{Rsamtools}
    (bam), \Biocpkg{rtracklayer} (gff, wig, bed),
    \Biocpkg{VariantAnnotation} (vcf), \Biocpkg{R453Plus1Toolbox}
    (454).\\

    Annotation & \Biocpkg{GenomicFeatures}, \Biocpkg{ChIPpeakAnno},
    \Biocpkg{VariantAnnotation}, \Biocpkg{ensemblVEP}.\\

    Alignment & \Biocpkg{Rsubread}, \Biocpkg{Biostrings}.\\

    Visualization & \Biocpkg{ggbio}, \Biocpkg{Gviz}.\\

    Quality assessment & \Biocpkg{qrqc}, \Biocpkg{seqbias},
    \Biocpkg{ReQON}, \Biocpkg{htSeqTools}, \Biocpkg{TEQC}, 
    \Biocpkg{ShortRead}.\\

    RNA-seq & \Biocpkg{BitSeq}, \Biocpkg{cqn}, \Biocpkg{cummeRbund},
    \Biocpkg{DESeq2}, \Biocpkg{DEXSeq}, \Biocpkg{EDASeq},
    \Biocpkg{edgeR}, \Biocpkg{gage}, \Biocpkg{goseq},
    \Biocpkg{iASeq}, \Biocpkg{tweeDEseq}.\\

    ChIP-seq, etc. & \Biocpkg{DiffBind}, \Biocpkg{BayesPeak}, 
    \Biocpkg{baySeq}, \Biocpkg{ChIPpeakAnno}, \Biocpkg{chipseq}, 
    \Biocpkg{ChIPseqR}, \Biocpkg{ChIPsim}, \Biocpkg{CSAR}, 
    \Biocpkg{MEDIPS}, \Biocpkg{mosaics}, \Biocpkg{NarrowPeaks},
    \Biocpkg{nucleR}, \Biocpkg{PICS}, \Biocpkg{PING},
    \Biocpkg{REDseq}, \Biocpkg{Repitools}, \Biocpkg{TSSi}.\\

    Motifs & \Biocpkg{MotifDb}, \Biocpkg{BCRANK}, \Biocpkg{cosmo}, 
    \Biocpkg{cosmoGUI}, \Biocpkg{MotIV}, \Biocpkg{seqLogo}, 
    \Biocpkg{rGADEM}.\\

    3C, etc. & \Biocpkg{HiTC}, \Biocpkg{r3Cseq}.\\

    Copy number & \Biocpkg{cn.mops}, \Biocpkg{CNAnorm},
    \Biocpkg{exomeCopy}, \Biocpkg{seqmentSeq}.\\

    Microbiome & \Biocpkg{phyloseq}, \Biocpkg{DirichletMultinomial},
    \Biocpkg{clstutils}, \Biocpkg{manta}, \Biocpkg{mcaGUI}.\\

    Work flows & \Biocpkg{Quasr}, \Biocpkg{ArrayExpressHTS}, 
    \Biocpkg{easyRNASeq}, \Biocpkg{oneChannelGUI},
    \Biocpkg{rnaSeqMap}.\\

    Database & \Biocpkg{SRAdb}.\\

    \hline
  \end{tabular}
\end{table}

\begin{Exercise}
  Scavenger hunt. Spend five minutes tracking down the following
  information.
  \begin{enumerate}
  \item The package containing the \Rfunction{readFastq} function.
  \item The author of the \Rfunction{alphabetFrequency} function,
    defined in the \Biocpkg{Biostrings} package.
  \item A description of the \Rclass{GappedAlignments} class.
  \item The number of vignettes in the \Rpackage{GenomicRanges}
    package.
  \item From the \Bioconductor{} web site, instructions for installing
    or updating \Bioconductor{} packages.
  \item A list of all packages in the current release of
    \Bioconductor{}.
  \item The URL of the \Bioconductor{} mailing list subscription page.
  \end{enumerate}
\end{Exercise}

\begin{Solution}
  Possible solutions are found with the following \R{} commands
\begin{Schunk}
\begin{Sinput}
> ??readFastq
> library(Biostrings)
> ?alphabetFrequency
> class?GappedAlignments
> vignette(package="GenomicRanges")
\end{Sinput}
\end{Schunk}
%%
and by visiting the \Bioconductor{} web site, e.g., installation
instructions\footnote{\url{http://bioconductor.org/install/}} current
software
packages\footnote{\url{http://bioconductor.org/packages/release/bioc/}},
and mailing
lists\footnote{\url{http://bioconductor.org/help/mailing-list/}}.
\end{Solution}

\subsection{Resources}

Dalgaard \cite{R:Dalgaard:2008} provides an introduction to
statistical analysis with \R. Matloff \cite{Matloff2011} introduces
\R{} programming concepts. Chambers \cite{R:Chambers:2008} provides
more advanced insights into \R. Gentleman \cite{R:Gentleman:2008b}
emphasizes use of \R{} for bioinformatic programming tasks. The
\href{http://r-project.org}{\R{} web site} enumerates additional
publications from the user community.
