%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{11 BestPractices -- Slides}

\documentclass[xcolor=dvipsnames]{beamer}

\usepackage{BioconductorSlides}
\hypersetup{colorlinks,linkcolor=,urlcolor=Blue}
\AtBeginSection[]
{
  \begin{frame}<beamer>{Outline}
    \tableofcontents[currentsection]
  \end{frame}
}

\begin{document}

<<knitr-settings, echo=FALSE>>=
library(knitr)
opts_chunk$set(tidy=FALSE)
@ 

\title{Best Practices}
\author{Martin Morgan (\href{mailto:mtmorgan@fhcrc.org}{mtmorgan@fhcrc.org}) \\
  Fred Hutchinson Cancer Research Center \\
  Seattle, WA}
\date{7 February 2014}
\maketitle

\begin{frame}[fragile]{Best practices}
  \begin{enumerate}
  \item Write organized, consistent \R{} code
  \item Use version control
  \item Document functions
  \item Write tests
  \item Write vignettes
  \item Create a package (!)
  \item What about \software{Rstudio}? Makes this easy!
  \end{enumerate}
  Example: utilities for working with \Rclass{GRanges}, e.g.,
  \Rfunction{isSimpleVariant}. See
<<GRangesUtilities-tar, eval=FALSE>>=
system.file(package="SummerX", "GRangesUtilities.tar.gz")
@ 
\end{frame}

\begin{frame}[fragile]{Writing organized, consistent \R{} code}
  \begin{itemize}
  \item Organize frequently used commands into not-too-complicated
    functions
  \item Adopt consistent
    \href{http://bioconductor.org/developers/how-to/coding-style/}{coding
      conventions}
    \begin{itemize}
    \item Function and variable names
    \item Indentation
    \item Line lengths
    \item \ldots
    \end{itemize}
  \item Organize functions into files, e.g., one-function-per-file
\begin{verbatim}
|-- GRangesUtilities
    |-- R
        |-- isSimpleVariant.R
        |-- stickFigure.R
    |-- vignettes
        |-- UsingGRangesUtilities.Rmd
\end{verbatim}
  \end{itemize}
\end{frame}

\begin{frame}{Using version control}
  \begin{itemize}
  \item Easily keep track of changes as your documents develop,
    without using confusing file-naming or other conventions.
  \end{itemize}
  Software
  \begin{itemize}
  \item \software{git} -- modern, flexible, easy to use locally (no server required)
  \item \software{subversion} (\software{svn}) -- used by
    \Bioconductor{}, requires central server
  \end{itemize}
  Sharing with others
  \begin{itemize}
  \item Use \href{http://github.com}{github}, or\ldots
  \item Get your IT guys to set up a \software{git} or \software{svn}
    server for your group's use
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Using version control -- \software{git}}
  \begin{itemize}
  \item Change into the directory where you've started your project
\begin{verbatim}
$ cd GRangesUtilities
\end{verbatim}
  \item Initialize a \software{git} repository and check the status
\begin{verbatim}
$ git init
$ git status
\end{verbatim}
  \item Create / edit files, directories\ldots; track in git
\begin{verbatim}
$ git add R/isSimpleVariant.R
$ git status
\end{verbatim}
  \item Commit the changes
\begin{verbatim}
$ git commit 
\end{verbatim}
    \item See the commit log
\begin{verbatim}
$ git log
\end{verbatim}
  \end{itemize}
\end{frame}

\begin{frame}{Document functions}
  \begin{itemize}
  \item Purpose: document how to use \emph{function}
  \item \texttt{man} directory with `\texttt{Rd}' files, organized
    like \texttt{R} files, e.g., \texttt{isSimpleVariant.Rd}
  \item Alternative: use \Rpackage{roxygen2} package to add
    `annotations', e.g., to \R{} code.
  \end{itemize}
\end{frame}

\begin{frame}{Write tests}
  \href{http://bioconductor.org/developers/how-to/unitTesting-guidelines/}{Unit tests}
  \begin{itemize}
  \item Short tests of specific parts of each function, implemented in
    a \texttt{tests} directory
  \item \Rpackage{testthat} framework
  \item \Rpackage{RUnit} framework, used in \Bioconductor{}
  \end{itemize}
  Test-driven development
  \begin{itemize}
  \item Write unit tests that describe expected functionality
    \emph{before} implementing the code.
  \end{itemize}
\end{frame}

\begin{frame}{Write vignettes}
  Why?
  \begin{itemize}
  \item Purpose: document how to use several functions in an
    integrated way
  \item `Literate' programming: Text, figures, tables surrounding \R{}
    script
  \end{itemize}
  How?
  \begin{itemize}
  \item Write documents in a directory \texttt{vignettes}
  \item \texttt{Rmd}: `markdown' and \R{} -- easy
  \item \texttt{Rnw}: `Sweave' combines \LaTeX{} and \R{} to produce
    PDF documents -- flexible
  \end{itemize}
\end{frame}

\begin{frame}{Create a package}
  \begin{itemize}
  \item Why? Easy to re-use, share with others (e.g., lab members)
  \item How? -- \Rcode{RShowDoc("R-exts")}
  \end{itemize}
  From what we've already done\ldots
  \begin{itemize}
  \item Add a \texttt{DESCRIPTION} file
  \item Arrange for tests to be run when the package is checked
  \end{itemize}
  Additional (optional) steps
  \begin{itemize}
  \item \texttt{data} directory of \R{} data objects
  \item \texttt{inst/script} of \R{} scripts
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Making a package available to your colleagues}
\Rpackage{roxygen2}-ize to create NAMESPACE, \texttt{man} pages
\begin{verbatim}
  $ R -e "roxygen2::roxygenize('GRangesUtilities')"
\end{verbatim}
Build, check, and install the package
\begin{verbatim}
  $ R CMD build GRangesUtilities
  $ R CMD check GRangesUtilities_0.0.1.tar.gz
  $ R CMD INSTALL GRangesUtilities_0.0.1.tar.gz
\end{verbatim}
Final step within \R:
\begin{verbatim}
  install.package("GRangesUtilities_0.0.1.tar.gz", 
      repos=NULL)
\end{verbatim}

Windows: create a \texttt{.zip} file for easy installation
\begin{verbatim}
  $ R CMD INSTALL --build GRangesUtilities_0.0.1.tar.gz
\end{verbatim}
\end{frame}

\begin{frame}[fagile]{Use it!}
<<GRangesUtilities, eval=FALSE>>=
library(GRangesUtilities)

?isSimpleVariant

vignette("UsingGRangesUtilities")

example(isSimpleVariant)
@ 
\end{frame}

\end{document}