%\VignetteDepends{codetoolsBioC, RUnit, GenomicFeatures}
%\VignetteIndexEntry{Building Packages}
%\VignettePackage{AdvancedR}


\documentclass{beamer}
%\usepackage{Sweave}
\usepackage{Bioconductor}
\SweaveOpts{keep.source=TRUE}

\title{Building Packages}
\author{Chao-Jen Wong, Nishant Gopalakrishnan, Marc Carson, and Patrick Aboyoun}
\institute[FHCRC]{Fred Hutchinson Cancer Research Center}
\date{20-21 May, 2010}


\begin{document}

<<setup, echo=FALSE>>=
options(width = 40)
@ 

\frame{\titlepage}

\section[Outline]{}
\frame{\tableofcontents}


\section{R Packages}
\subsection{Package Concept}
\begin{frame}{Package Concept}
  \begin{block}{\texttt{R} packages}
    A collection of source code allows the user to attach
    to R session when calling \Rfunction{library()} or \Rfunction{require()}.
  \end{block}

  \begin{block}{Why write a package?}
    \begin{itemize}
      \item Better way to organize your code.
      \item Ability to share software as \texttt{R} packages.
      \item Provide reliable access.
      \item Provide communication channel between the users and authors.
      %\item Control what other packages you use and what you want to make
      %  public (via namespaces).
    \end{itemize}
  \end{block}
\end{frame}

\subsection{Creating R packages}
\begin{frame}[fragile]{Creating a Package}
  \begin{block}{Initialize a new package}
    % do demo on R session
<<skeleton, eval=FALSE>>=
package.skeleton()
@
    
  \end{block}
  
  \begin{block}{Source package}
    \begin{itemize}
      \item Special files
        \begin{itemize}
          \item Essential: \alert{\texttt{DESCRIPTION}} and
            \alert{\texttt{NAMESPACE}}. 
          \item Others: \texttt{configure}, \texttt{LICENSE},
            \texttt{COPYING}, \texttt{INDEX}  and \texttt{NEWS}. 
        \end{itemize}
      \item Subdirectories containing source code, documentation and other
        material.
    \end{itemize}
  \end{block}
% DESCRIPTION: contains basic information about the package
% NAMESPACE: Control what other packages you use and what you want to make
%  public (via namespaces).
  
\end{frame}

\begin{frame}[fragile]{Creating a Package}
  \begin{block}{Subdirectories}
    \vspace{0.2 in}
      \begin{tabular}{|l|l|}
        \hline
        {\bf Directory}& {\bf Content} \\ \hline
        \texttt{R}     & source files (.R) \\ 
        \hline
        \texttt{data}  & files of data objects to be loaded by
                         \Rfunction{data()}  \\ \hline
        \texttt{inst}  & content copied to the installed packages' directory \\
                       & \texttt{doc} -- Sweave document (.Rnw) \\
                       & \texttt{extdata} -- misc. data objects (ASCII) \\
                       & \texttt{unitTest} -- unit testing functions \\
                         \hline
        \texttt{man}   & \Robject{Rd} documentation \\ 
        \hline
        \texttt{src}   & source code in \texttt{C}, \texttt{FORTRAN} or
                       \texttt{C++} \\  \hline 
        \texttt{tests} & test code in \R{} \\ 
        \hline
    \end{tabular}
  \end{block}
\end{frame}


\subsection{Package Tools}
\begin{frame}[fragile]{Package Tools}
  \begin{block}{\texttt{R} shell tools}
    \begin{itemize}
      \item Used to manage packages (build, check and etc.).
      \item Can be accessed from a command shell.
    \end{itemize}
  \end{block}

  \begin{block}{Shell commends}  
    Take the form: \texttt{R CMD} \textit{operation}
    \begin{verbatim}
      $R CMD build package
      $R CMD check package  
      $R CMD check --help
      $R CMD INSTALL package
      $R CMD REMOVE package
      ...
    \end{verbatim}
  \end{block}
\end{frame}

%------------------------- section 2
\section{Package Dependencies and Namespaces}
\begin{frame}[fragile, shrink=18]{Dependencies in DESCRIPTION}
  \begin{block}{The \texttt{DESCRIPTION} file}
    \begin{verbatim}
Package: affy
Version: 1.25.2
Title: Methods for Affymetrix Oligonucleotide Arrays
Author: Rafael A. Irizarry <rafa@jhu.edu>, Laurent Gautier
        ...
Maintainer: Rafael A. Irizarry <rafa@jhu.edu>
Depends: R (>= 2.8.0), Biobase (>= 2.5.5)
Imports: affyio (>= 1.13.3), Biobase (>= 2.5.5), graphics, 
         grDevices, methods, preprocessCore, stats, utils
Suggests: tkWidgets (>= 1.19.0), affydata
Description: The package contains functions for exploratory
             ...
License: LGPL (>= 2.0)
Collate: ProgressBarText.R ppset.ttest.R ppsetApply.R expressoWidget.R
        getCDFenv.R AffyRNAdeg.R avdiff.R barplot.ProbeSet.R ...

     \end{verbatim}
  \end{block}
  
\end{frame}

\begin{frame}[fragile]{Dependencies in DESCRIPTION}
%why is it important
  \begin{itemize}
    \item Declare what packages are required to run your package.
    \item Clarify the relationship between your package and other packages.
    \item Give clear and reliable definition of the package's behavior
      (namespaces).
  \end{itemize}
\end{frame}

\begin{frame}[fragile]{Dependencies in DESCRIPTION}
      % explain the attach/load mechanism
      \begin{block}{Depends}

          %\item Packages in the Depends field are attached to the search path
          %  prior to the package is loaded
           Packages expected to be attached 

      \end{block}
      \begin{block}{Imports}
        \begin{itemize}
          \item Only a few functions or objects are used by this package.
          \item Not necessarily needed to be attached.
          \item Avoid the cost in time and space of accessing the unused
            functions. 
        \end{itemize}
      \end{block}

  \begin{block}{Suggests}
    \begin{itemize}
      \item Used in examples or vignettes.
      \item Introduce special functionality. % example: having require() in
                                % your package
    \end{itemize}
  \end{block}

\end{frame}


\begin{frame}[fragile]{Namespace}
  \begin{block}{Why give your package a namespace}
    \begin{itemize}
      \item Avoid conflicts and confusion from multiple functions (from
        attached packages) with the same names.
        % result could be potentially disastrous
      % \item Clarify package dependencies.
      \item Control what are public (exported) and private. 
      %\item More efficient loading of the package.
        
    \end{itemize}
  \end{block}
  
\end{frame}

% Namespace mechanism
\begin{frame}[fragile]{Namespace}
  
  \begin{itemize}
    \item Declare in the \texttt{NAMESPACE} file. 
    \item Required being explicit about what is exported and imported.
    \item 'import' -- entire package or specific objects, classes and methods.
      \begin{verbatim}
     import(Biobase)
or
     importFrom(Biobase, openVignettes)
       \end{verbatim}
    \item 'export' -- explicit list of objects, methods and classes.
      \begin{verbatim}
     exportPattern("^[^\\.]")
     export(...)
     exportClass(...)
     exportMethods(...)
       \end{verbatim}
      
    \item Sealed once the package is installed. 
      Non-exported functions can be addressed by the \Rfunction{:::} operator. 
  \end{itemize}
  
  % case study? show good example: GenomicFeatures
  % packages both in Imports and Depends fields?
  
\end{frame}

% codetoolsBioc
\begin{frame}[fragile]{Useful Tool: codetoolsBioC}
<<codetoolsBioC>>=
library(codetoolsBioC)
ls(2)
@ 
\begin{block}{writeNamespaceImports}
  Writes imports statements that can be included in a package's
  \texttt{NAMESPACE} file.
\end{block}
<<use writeNamespaceImports, eval=FALSE>>=
library(GenomicFeatures)
writeNamespaceImports("GenomicFeatures")
@ 

\end{frame}


%-----------------------------------------------

%%Quality of code has to be constantly verified
%% especially true for interpreted languages like R
%% where there is no compiler checking  
%Isolate each part of the program 
%show that the individual parts are correct.  
%Finds problems early in the developmental cycle

% provided by RUnit
\section{Unit Testing}
\begin{frame}[fragile, shrink=10]{What is a unit test?}
 \vspace{0.5 in}

  \begin{columns}
    \column{0.5\textwidth}
    A function myFun
    \begin{verbatim}
library(RUnit)

myFun <- function(a) {
  # input checking
  if(!is.numeric(a))
    stop("'a' should be of 
         type 'numeric(1)'")
  if(length(a) != 1)
    stop("'a' should be of 
            length 1")

  # calc factorial
  factorial(a)
}
    \end{verbatim}

    \column{0.5\textwidth}
    \vspace{0.1 in}
    Unit test for myFun
      \begin{verbatim}
test_myFun <- function() {
  target <- 6
  current <- myFun(3)
  checkIdentical(target,current)
                
  checkException(myFun("A"))

  checkException(myFun(1:8))
}
      \end{verbatim}
  \end{columns}
\end{frame}

%-----------------------------------------------
% facilitates code changes/refactoring -  I better not touch this
%% piece of code 
%% testing parts of the program first and then sum of its parts
%% makes integration easier
%% test cases become a living documentation of the system
\begin{frame}[fragile]{ Why Unit tests ?}
\begin{itemize}
\item Interface specification
\item Ensures code correctness, e.g., when \R{} changes
\item Allows refactoring without breaking existing code
\item Encourages writing simple, working code chunks that can be
  integrated into larger components
\item Encourages collaboration -- tests describe what is supposed to
  happen
\item Helps describe bugs -- `this test fails'
\item Documentation for developer -- what code is intended to do
\end{itemize}
\end{frame}

%-----------------------------------------------

\begin{frame}[fragile]{The \Rpackage{RUnit} package}
    \begin{itemize} 
      \item Framework for test case execution
        \begin{itemize}
            \item create a series of test functions
            \item define a test suite (defineTestSuite)
            \item run the tests (runTestSuite)
            \item summarize results (printTextProtocol, printHTMLProtocol)
        \end{itemize}
      % the last three steps can be accomplished by writeRUnitRunner
      \item Hint: use \Rfunction{writeRUnitRunner} from the
        \Rpackage{codetoolsBioC} package

      %\item Tools for code coverage inspection
  \end{itemize}
\end{frame}

%-----------------------------------------------
%%Demonstrate by going through the folders of the GenomicFeatures package

\begin{frame}[fragile]{Adding Unit tests to your package}
\begin{itemize}
\item Create test functions 
   \begin{itemize}
    \item save in inst/unitTests folder of your package
    \end{itemize}
    %demo: open GenomicFeatures/inst/unitTest, show how it looks like...
\item Function to create test suite, run tests, summarize results
  % define your test suite, run the unitTest and summarize results...
    \begin{itemize}
        \item use \Rfunction{writeRUnitRunner} to create the file
          containing the \Rfunction{.test} function
        \item save in R folder of your package 
    \end{itemize} % just like internal private functions
\item Function to call the \Rfunction{.test} function
    \begin{itemize}
        \item save in the tests folder of your package
        % allows R CMD check to run .test or pkg:::.test
    \end{itemize}
 
\item Add \Rpackage{RUnit} to the Suggests field in DESCRIPTION
\end{itemize}
\end{frame}

%-----------------------------------------------
%% say how the .test is an internal function, useful to access
%% and test code after making some changes to your package without
%% running R CMD check.     USE ::: to access an internal function

% avoid calling up R CMD check...
\begin{frame}[fragile]{Running a unit tests}
  % show nidemo demo on my screen
  
  % how to run with R CMD check
% an alternative way to run unit testing for your package ...
% if don't want to run R CMD check, just want to run unit testing
<<nidemo-demo, eval=FALSE>>=
library(nidemo)
nidemo:::.test()
@   
\end{frame}

%-----------------------------------------------

%% expections, .Rd, vignette, Sweave, Stangle,
\section{Documentation}

\begin{frame}
  \frametitle{Documentation Types}
\begin{block}{Manual pages}
  \begin{itemize}
    \item Reference pages for \R{} objects (functions, data sets, etc.)
    \item Written in ``R documentation" (Rd) format
    \item Thoroughly checked during R CMD check
    \item Templates created by \Rfunction{prompt*} family of functions
  \end{itemize}
\end{block}
\begin{block}{Vignettes}
  \begin{itemize}
    \item A task-oriented description of package functionality
    \item Contain simple "HowTo"s that are built with the package
    \item Written in Sweave (.Rnw) format, which integrates R code into
      \LaTeX{} documents
    \item Required component of a Bioconductor package
  \end{itemize}
\end{block}
  Details provided in \textit{Writing R Extensions} manual.
\end{frame}

\subsection{Manual Pages}

%-----------------------------------------------
\begin{frame}[fragile]
  \frametitle{Manual Pages (A Simple Example)}
{\small
\begin{verbatim}
\name{name}
\alias{alternate name}
\title{name of manual page}
\description{Brief description of what this does.}
\usage{
  myfun(arg1, arg2 = FALSE)
}
\arguments{
  \item{arg1}{\code{arg1} is required}
  \item{arg2}{\code{arg2} is optional}
}
\details{Important details on how it does it.}
\value{Return type}
\seealso{\code{\link[pkg:pkgfun]{pkgfun}}}
\author{Your name here}
\examples{## R code to demo this}
\keyword{names from KEYWORDS file in R doc dir}
\end{verbatim}
}
\end{frame}

%-----------------------------------------------
\begin{frame}
  \frametitle{Manual Pages (Tips)}
  \begin{itemize}
    \item Flip through ``Writing R documentation files" chapter of
      \textit{Writing R Extensions} manual
    \item Change manual page when when underlying \R{} object changes
    \item Make examples run fast and be robust to changes in
      annotations and web resources
    \item Run R CMD check on modified packages
  \end{itemize}
\end{frame}


\subsection{Vignettes}

%-----------------------------------------------
\begin{frame}[fragile]
  \frametitle{Vignette (Skeleton)}
{\footnotesize
\begin{verbatim}
%\VignetteIndexEntry{Descriptive Title}
%\VignetteKeywords{words}
%\VignettePackage{Package Name}

\documentclass[11pt]{article}

\usepackagege{Sweave}

\newcommand{\Rfunction}[1]{{\texttt{#1}}}
\newcommand{\Robject}[1]{{\texttt{#1}}}
\newcommand{\Rpackage}[1]{{\textit{#1}}}
\newcommand{\Rclass}[1]{{\textit{#1}}}

\title{Descriptive Title}
\author{your name}
 \SweaveOpts{keep.source=TRUE}

\begin{document}
\maketitle

\end{document}
\end{verbatim}
}
\end{frame}

%-----------------------------------------------
\begin{frame}[fragile]
  \frametitle{Vignette (Body)}
{\small
\begin{verbatim}
\begin{document}
\maketitle

\section{Introduction}
The \Rpackage{foo} is great.

\subsection{Getting Started}
First load the \Rpackage{foo} package and then execute
function \Rfunction{foo}.

 <<code-block>>=
 library(foo)
 foo()
 @

\end{document}
\end{verbatim}
}
\end{frame}

%-----------------------------------------------
\begin{frame}[fragile]
  \frametitle{Vignette (Code Blocks)}
{\small
\begin{verbatim}
 <<UnevaluatedCode, eval=FALSE>>=
 longRunningFunction(bigDataObject)
 @
 <<UnseenCodeAndOutput, echo=FALSE>>=
 options(width = 60)
 @
 <<UnseenMessages, results=hide>>=
 library(Biobase)
 @
 <<IncludeGraphic, fig=TRUE>>=
 plot(1:10)
 @
 <<KeepMyFormat, keep.source=TRUE>>=
 loveMyFormat(arg1 = "first",
              arg2 = "second")
 @
\end{verbatim}
}
\end{frame}

%-----------------------------------------------
\begin{frame}[t,fragile]
  \frametitle{Sweave and Stangle Commands}
  \Rfunction{Sweave} -- creates a post-(code block)-processed \LaTeX{} file \\
  \Rfunction{Stangle} -- creates an R script from code blocks \\
\begin{block}{R commands}
{\small
<<code-block,eval=FALSE>>=
library(tools)
Sweave("foo.Rnw")
texi2dvi("foo.tex", pdf=TRUE, clean=TRUE)
Stangle("foo.Rnw")
@
}
\end{block}
\begin{block}{Shell commands}
{\small
\begin{verbatim}
  R CMD Sweave foo.Rnw
  R CMD texi2dvi --pdf --clean foo.tex
  R CMD Stangle foo.Rnw
\end{verbatim}
}
\end{block}
\end{frame}


%-----------------------------------------------

%----------- Nishant's input -------------
\section{Tools of the trade}

\subsection{Version Control}
\begin{frame}[fragile]{Need for Version Control}
Problems
  \begin{itemize}
   \item Projects consist of multiple files
   \item We add/remove/change content
   \item Multiple people editing same file -> merge changes
   \item Multiple machines/operating systems -> merge changes
   \item Go back to a previous snapshot
  \end{itemize}

The wrong way
  \begin{itemize}
    \item proj1.R, proj2.R, proj3.R
    \item User managed backups
  \end{itemize}
\end{frame}

%-----------------------------------------------
% Distributed vs. Centralized Version Control
% Distributed vc: clients hosts the repositories, merge based on what?
\begin{frame}[fragile]{Version control software}
\begin{itemize}
   \item svn % centralized server: has a central server that host the repository
   \item Mercurial % distributed
   \item git % distributed
   \end{itemize}
\end{frame}

%-----------------------------------------------

\begin{frame}[fragile]{Bioconductor svn}
\begin{itemize}
\item Devel Branch
    \begin{itemize}
        \item \url{https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks}
    \end{itemize}
\item 2.6 Release Branch
    \begin{itemize}
        \item \url{https://hedgehog.fhcrc.org/bioconductor/branches/RELEASE\_2\_6/
              madman/Rpacks}
    \end{itemize}
\item username:readonly password:readonly
\end{itemize}

Reference Book:\textit{ Version Control with Subversion}
\url{http://svnbook.red-bean.com/}
\end{frame}

%-----------------------------------------------

\begin{frame}[fragile]{Useful svn commands: svn checkout}
svn co https://hedgehog.fhcrc.org/bioconductor/trunk/madman/Rpacks/
BiocCaseStudies/ --username readonly --password readonly
    \begin{figure}
    \includegraphics[width=3in]{packs/svnCo.png}
    \end{figure}
\end{frame}

%-----------------------------------------------

\begin{frame}[fragile]{Useful svn commands: svn log}
svn log NAMESPACE | more
    \begin{figure}
    \includegraphics[width=3.5in]{packs/svnLog.png}
    \end{figure}

\begin{itemize}
\item Logs are useful only if useful commit messages are provided.
\item Commit once conceptual change at a time.
\end{itemize}
\end{frame}

%-----------------------------------------------

%\begin{frame}[fragile]{Useful svn commands: svn update}
%   svn update -r28929 NAMESPACE
%    \begin{figure}
%    \includegraphics[width=3.5in]{packs/svnUpdate.png}
%    \end{figure}
%\end{frame}

%-----------------------------------------------
% + : added; -: removed
%\begin{frame}[fragile]{Useful svn commands: svn diff}
%    svn diff NAMESPACE -r29576 
%    \begin{figure}
%    \includegraphics[width=3.5in]{packs/svnDiff.png}
%    \end{figure}
%\end{frame}

%-----------------------------------------------
%
%\begin{frame}[fragile]{Useful svn commands: svn export}
%    svn export BiocCaseStudies/ \~/proj/packages/BiocCaseStudies --force
%    \begin{figure}
%    \includegraphics[width=3.5in]{packs/svnExport.png}
%    \end{figure}
%\end{frame}

%-----------------------------------------------

\begin{frame}[fragile]{Useful svn commands}
\begin{itemize}
  \item svn checkout
  \item svn add
  \item svn checkin
  \item svn update
  \item svn status
  \item svn log -v 
  \item ...
\end{itemize}
\end{frame}

%-----------------------------------------------

\subsection{Efficient Editing}

\begin{frame}[fragile]{Efficient Editing}
  \framesubtitle{Editing from the command line}
\begin{itemize}
\item history()
\item savehistory("foo")
\item loadhistory("foo")
\item reverse search on unix using \texttt{Ctrl-R}
\end{itemize}
\end{frame}

%-----------------------------------------------
% R-mode

\begin{frame}[fragile]{Code editors}
    \begin{itemize}
        \item Eclipse(StatET) \url{http://www.walware.de/goto/statet}
        \item Emacs(ESS) \url{http://ess.r-project.org/}
        \item vim(Vim-R-plugin2) \url{http://www.vim.org/scripts/script.php?script_id=2628}
        \item Tinn-R
        \item Notepad++(NppToR) \url{http://sourceforge.net/projects/npptor/}
    \end{itemize}
Advantages
\begin{itemize}
    \item{syntax highlighting}
    \item{auto indent code}
    \item{send code/functions to R console}
\end{itemize}
\end{frame}

\begin{frame}[fragile]{Efficient work flows}
  Editing without building documentation or configure
  \begin{verbatim}
    R CMD check --no-vigenttes --no-examples pkgs
    R CMD INTSALL --no-docs pkgs
    R CMD INSTALL --no-configure pkgs
    R CMD INSTALL --help
  \end{verbatim}
\end{frame}
%-----------------------------------------------

%\begin{frame}[fragile]{Accessing functions not available in the namespace}
%\begin{itemize}
%\item :: operator to access functions that are exported from a package
%namespace 
%\item ::: operator to access internal functions not exported from the package 
%namespace
%\end{itemize}
%\end{frame}

%-----------------------------------------------
% explain what is .Rfile

% example: sourcing biocLite.R
\begin{frame}[fragile, shrink=10]{.Rprofile}
%\begin{verbatim}
%dir.create(Sys.getenv("R_LIBS_USER"),
%                   recursive = TRUE,
%                   showWarnings = FALSE)
%
%options(repos="http://cran.fhcrc.org")

\begin{verbatim}

.First <- function() {cat("\n Hello! \n\n")}

if (interactive()) {
    tryCatch({
         source("http://bioconductor.org/biocLite.R")
    }, error=function(e) invisible(NULL),
       warning=function(w) message("Not connected to the net"))
}

reload_pkg <- function(p) {
    detach(paste("package", p, sep = ":"), unload = TRUE,
            character.only = TRUE)
    library(p, character.only = TRUE)
}

\end{verbatim}
\end{frame}

%-----------------------------------------------
% detach your package and reload it again
% useful when you change your package and want to re-install
%\begin{frame}[fragile]{.Rprofile - reload an R package}
%\begin{verbatim}
%reload_pkg <- function(p) {
%    detach(paste("package", p, sep = ":"), unload = TRUE,
%            character.only = TRUE)
%    library(p, character.only = TRUE)
%}
%\end{verbatim}
%\end{frame}
 
%-----------------------------------------------
\section{Resources}

\begin{frame}{Resources}
  \begin{itemize}
    \item John Chambers. \emph{Software for Data Analysis}.  Springer, New
      York, 2008. 
    \item \emph{Writing R Extensions} manual, \\
      \url{http://cran.r-project.org/doc/manuals/R-exts.html}
    \item \emph{Version Control with Subversion}, \\
      \url{http://svnbook.red-bean.com/} 
    \item \emph{Sweave User Manual}, \\
      \url{http://www.stat.uni-muenchen.de/~leisch/Sweave}
  \end{itemize}
\end{frame}


\end{document}
