% \VignetteIndexEntry{GRANBase overview}
% \VignetteDepends{BiocStyle}
% \VignetteKeywords{reprise}
% \VignettePackage{GRANBase}
\documentclass[10pt]{article}

\title{The GRAN repository system and reproducibility tools}
\author{Gabriel Becker}
\date{\today}


<<<eval = TRUE, echo=FALSE, results=tex>>=
if(requireNamespace("BiocStyle", quietly=TRUE)) {
    BiocStyle::latex()
}
@ 

\newcommand{\gran}{{\tt GRAN }}

\begin{document}
\SweaveOpts{concordance=TRUE}

\maketitle
\tableofcontents
\newpage

\section{Introduction}

\gran is an open source set of tools for testing and deploying \R{} packages 
as package repositories for both general deployment and result
reproduction. It is based on the \tt switchr framework, and allows
users to deploy package manifests as validated repositories.It is centered around the R repository
mechanism for pacakge distribution. \gran provides three major areas of functionality:
\begin{enumerate}
  \item{The ability to create one or more \R{} repositories by pulling and testing packages 
    from diverse locations (scm, local directory), in a manner conducive to continuous integration}
  \item{Tools for recreating specific environments based on sessionInfos, and for creating lightweight 
    virtual repositories which serve the exact package versions specified in the sessoinInfo}
  \item{Tools for assessing the potential impact of upgrading a package, to assist administrators in
    keeping systems up-to-date while protecting reproducibility and comparability of results in
    long-running core applications.}
\end{enumerate}

\section{Creating GRAN repositories}

\gran repositories are based on \textit{package manifests}
(\textbf{PkgManifest} or \textbf{SeedingManifest} objects from the \tt
switchr framework) 


Given a manifest, initial construction and rebuilding of individual \gran repositories (referred to as \textit{subrepositories} because \gran supports a form of branched deployment) is performed via the \Rfunction{makeRepo} function. For example:

<<eval=TRUE,echo=FALSE>>=
suppressPackageStartupMessages(library(GRANBase))
options(error=traceback)
@ 

<<eval=TRUE>>=

testpkgs = list.files(system.file("testpkgs", package = "GRANBase"), full.names = TRUE)
man = PkgManifest(name = basename(testpkgs), 
    url =  testpkgs, type = "local")
repdir = file.path(tempdir(), "repos")
if(!file.exists(repdir))
    dir.create(repdir)
repo = makeRepo(man, repo_name= "stable", basedir = repdir,
    destination = repdir,
    cores = 1L, install_test = FALSE, check_test = FALSE)
@ 

NOTE: In the above code, we disabled the installation and \texttt{R
  CMD check}-related tests due to not playing well with the CRAN build
system. In most cases, these should be \texttt{TRUE} in order to
create a validated package repository. Also note that in the output
below, the \texttt{willfail} package appears in the repository. This
would not be the case if the check test was turned on, as it is
engineered as a test case to fail check.


<<eval=TRUE>>=
available.packages(repo, type="source")
@ 

Note that the repository contains the package \texttt{GRANstable}. This
was generated automatically, and exports a \texttt{defaultGRAN}
function which the  \texttt{switchr} package will use when the package is loaded to encorporate
our package into the set of default repositories.

We refer readers to the documentation for that function regarding the customization options.

\gran represents (sub)repositories as \Rclass{GRANRepository} objects. These objects contain all the information required to build and deploy the repository.

Once a \gran repository is created, its \Rclass{GRANRepository} object 
is saved within the created directory structure as the repo.R file. This allows future builds to be invoked by the simpler syntax of passing a \Rclass{GRANRepository} object or path to a created repository to \Rfunction{makeRepo} directly:


<<eval=FALSE>>=
repo = makeRepo(file.path(repdir, "stable"), cores=1L)
@ 

The \Rfunction{makeRepo} function also accepts a {\tt build\_pkgs} argument, which will cause only the specified packages (and their reverse dependencies) to be rebuilt, regardless of changes in version number.

<<eval=FALSE>>=
repo2  = makeRepo(repo, build_pkgs=basename(testpkgs)[1],
    cores = 1L)
@ 
\newpage
\section{The repository build process}

\gran performs the following steps when creating or updating a repository. At the end of each step, the packages' statuses are updated to reflect the results of that step.

\begin{enumerate}
  \item{Up-to-date copies of package sources are obtained for each package being built, including updating previously checked out versions}
  \item{Packages whose versions have changed since their last successful build, or who are reverse dependencies of such a package, are built without vignettes into a temporary repository via {\tt R CMD build}. }
  \item{Packages which successfully built, along with their \gran, {\tt CRAN}, and \Bioconductor{}-based dependencies, are installed into a temporary library location. }
  \item{Packages which successfully installed are built again, with vignettes, into a staging directory.}
  \item{Remaining packages are tested via {\tt R CMD CHECK}, and their statuses are updated accordingly}
  \item{Packages which meet the requirements set for the repository ({\tt CHECK} warnings and notes can be all owed, or not) are deployed into the final destination repository}
  \item{The \gran manifest is updated to reflect the build results}
  \item{An HTML build report is generated from the updated manifest}
  \item{The manifest and \Rclass{GRANRepository} object are saved}
  \item{The \Rclass{GRANRepsitory} object is returned}
\end{enumerate}

\section{Tools for managing repository stability}

\gran also provides tools to navigate the tension between stability and using the most up-to-date version of packages to have the latest bug fixes available.


The \Rfunction{identifyRisk} function identifies which currently installed packages can be updated, and determines the packages that could possibly be affected by updating the package. In particular, the function allows the user to identify a vector of \textit{important} packages and assesses the risks to each of them (by default, it takes that to be the full set of installed packages).


Risk here has a dual meaning. On the one hand updating a package which an important package depends on incurs the risk of changing the important package's behavior, potentially changing results in a critical application. On the other hand, not updating a such a package may leave important bugfixes un-applied, drawing the results generated when using the important package into question.


\Rfunction{buildRiskReport} builds an HTML report which lists information about each package with an update available in an easy to digest table. It also provides a list of specific risks to each important package (packages with no risks identified are currently omitted).

\begin{figure}[p]
    \centering
    \includegraphics[width=0.8\textwidth]{ReportScreenshot.png}
    \caption{An update risk report}
    \label{fig:risk_report}
\end{figure}
\end{document}
