---
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=2.8in, keepaspectratio}
  \DeclareUnicodeCharacter{2010}{-}
vignette: >
  %\VignetteIndexEntry{Seroincidence package installation manual}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{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")
```

\newpage

# 1. Introduction

Package **seroincidence** is written in programming language R and end user must have access to a 
working installation of R engine. 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.5.0**. 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/).

## 2.1. Installing R

Start the R installer and follow the presented steps:

```{r echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("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 echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("fig/setup2.png")
```

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 echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("fig/setup3.png")
```

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

```{r echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("fig/setup4.png")
```

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

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 echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("fig/RGui1.png")
```

## 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:

* binary package (seroincidence_[version].zip) - Microsoft Windows compatible
* Source package (seroincidence_[version].tar.gz) - cross-platform compatible (MS Windows, Linux, 
  MacOS)

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 files...*:

```{r echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("fig/RGui2.png")
```

Select the package file and click "Open":

```{r echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("fig/RGui3.png")
```

Post-installation message should appear:

```{r echo=FALSE, fig.pos="!h", fig.align='center'}
include_graphics("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 ECDC website:
install.packages(
    pkgs = \"{{pkgPath}}/
                {{pkgBaseFileName}}.zip\",
    repos = NULL, type = \"win.binary\")

# OPTION B
# Install source package directly from internet CRAN repository:
install.packages(\"seroincidence\")

# 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}
# Show description.
packageDescription("seroincidence")

# Show citation.
citation("seroincidence")
```
