---
vignette: >
  %\VignetteIndexEntry{Seroincidence package installation manual}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}

title: "Seroincidence package installation manual"
author: "European Centre for Disease Prevention and Control (ECDC)"
date: "`r Sys.Date()`"
output: 
  pdf_document:
    toc: yes
header-includes:
- \setkeys{Gin}{height=3.5in, keepaspectratio}
---


```{r, echo = FALSE}
# Grab package version and date from DESCRIPTION file
pkgVersion <- packageDescription("seroincidence")$Version
pkgDate <- packageDescription("seroincidence")$Date
pkgBaseFileName <- paste("seroincidence", pkgVersion, sep = "_")
pkgUrl <- gsub("\n", "", packageDescription("seroincidence")$URL)
pkgPath <- "http://ecdc.europa.eu/en/data-tools/seroincidence-calculator-tool/Documents"
library("knitr")
```

# 1. Introduction

Package **seroincidence** is written in programming language R and end user must have
access to a working installation of R interpreter. This document describes the most 
common setup with R installed locally on the user's computer. The screenshots refer to 
the classical R interface, but the package can also be opened in other Graphical User 
Interfaces fo R like e.g. [RStudio](http://www.rstudio.com/products/RStudio/).

# 2. Installation steps

R is a free software and can be downloaded from [http://cran.r-project.org/](http://cran.r-project.org/).
Latest version as of writing this document is **R 3.1.3**.
Once the appropriate, operating system dependent, version is downloaded, install it on your computer following the
standard procedure applicable to the operating system. For Windows the file to be downloaded
is the so-called *base* distribution: [http://cran.r-project.org/bin/windows/base/](http://cran.r-project.org/bin/windows/base/).

\pagebreak

## 2.1. Installing R

Start the R installer and follow the presented steps:

![R installer - step 1](fig/setup1.png)

It is advised to have R installed in folder that does not contain spaces, therefore
please adjust the destination location accordingly:

![R installer - step 2](fig/setup2.png)

\pagebreak

The **seroincidence** package is compatible with both the 32-bit and the 64-bit version of R. 
Choose the preferred platform (or both). If unsure install the 32-bit version only, however
on compatible platforms the 64-bit version may provide better performance:

![R installer - step 3](fig/setup3.png)

It is advised to select *Registry entries* in the next step for best experience:

![R installer - step 4](fig/setup4.png)

\pagebreak

R interpreter, when installed on Windows, can be invoked from the start menu folder named **R**.

![Windows start menu](fig/startMenu.png)

Start the preferred version of R (if both the 32-bit: *R i386* and the 64-bit: *x64* are installed).
Graphical user interface for R interpreter will start in a new window:

![R Graphical User Interface - welcome screen](fig/RGui1.png)

\pagebreak

## 2.2. Installing *seroincidence* package

Since this is a new installation of R, the **seroincidence** package must be installed 
before first use. The package can be installed either through a menu option in the 
graphical user interface (GUI) or with a command executed in the R console. 
Both options are presented:

### 2.2.1. Package installation from the graphical user interface

Download the seroincidence calculator package from ECDC website: [`r pkgUrl`](`r pkgUrl`). 
Two versions of the package are made available:

* Windows binary package (seroincidence_[version].zip)
* Source package (seroincidence_[version].tar.gz)

If your operating system is Windows then it is best to download the Windows binary package.

Go to menu *Packages* and select command *Install package(s) from local zip files...*:

![R GUI - install package menu](fig/RGui2.png)

\pagebreak

Select the package file and click "Open":

![R GUI - select package file](fig/RGui3.png)

Post-installation message should appear:

![R GUI - welcome screen](fig/RGui4.png)

The package is now installed in R. 

### 2.2.2. Package installation from R console

Alternatively, installation of the package can also be performed 
by executing one of the following commands in the *R console*:
```{r, include=FALSE, tidy=FALSE}
chunkTemplate <- "```{r, eval = FALSE}
# OPTION A
# Install Windows binary package \"seroincidence\" directly from internet location:
install.packages(
    pkgs = \"{{pkgPath}}/
                {{pkgBaseFileName}}.zip\",
    repos = NULL, type = \"win.binary\")

# OPTION B
# Install source package directly from internet location:
install.packages(
    pkgs = \"{{pkgPath}}/
                {{pkgBaseFileName}}.tar.gz\",
    repos = NULL, type = \"source\")

# OPTION C
# Install Windows binary package from a local file:
#   install.packages(\"[PATH/TO/FILE/]seroincidence_[version].zip\", 
#                       repos = NULL, type = \"win.binary\")
# For instance:
install.packages(pkgs = \"C:/{{pkgBaseFileName}}.zip\", repos = NULL, type = \"win.binary\")

# OPTION D
# Install source package from a local file:
install.packages(pkgs = \"C:/{{pkgBaseFileName}}.tar.gz\", repos = NULL, type = \"source\")
```"

chunkSource <- knit_expand(text = chunkTemplate, pkgBaseFileName = pkgBaseFileName)
```

`r knit(text = chunkSource)`

# 3. Post-installation

Successful installation can be confirmed by loading the package into the workspace 
and exploring help files and manuals distributed with the package:
```{r, eval=FALSE}
# Load package "seroincidence"
library(seroincidence)

# Show R help for the package
?seroincidence

# Show tutorial for the package
vignette(topic = "tutorial", package = "seroincidence")
```

Additionally, most package details can be found when executing the following commands:
```{r}
# Description
packageDescription("seroincidence")

# Citation
citation("seroincidence")
```
