README.Rmd

---
title: "The **beverstan** package"
author: "Yves Deville"
date: "`r Sys.Date()`" 
output:
  github_document:
        toc: true
---

# Goals

The **beverstan** package for R is a private package funded by
IRSN/Behrig.  It performs the Bayesian inference for some Extreme-Value
models. For now, these are simply "time-varying" models with GEV
margins for block maxima, usually annual maxima. The function
`TVGEVBayes` has an interface which is similar to that of
`NSGEV::TVGEV`. It further allows to use *historical data* via its
argument `timeMAXdata`, see the function help page `?TVGEVBayes` and
the examples therein.

# Requirements

The Bayesian inference relies on MCMC sampling as provided by
[**Stan**](https://mc-stan.org/), used through the
[**rstan**](https://mc-stan.org/users/interfaces/rstan) package
available on the CRAN, including the [**RCpp**
package](https://www.rcpp.org/). The **beverstan** package is an
"Rstan" package with a special structure as can be created thanks to
the [**rstantools**](https://mc-stan.org/rstantools/) package which is
available on the CRAN.

**beverstan** requires compilation. On a Windows platform, the
compilation of the sources requires that the
[**Rtools**](https://cran.r-project.org/bin/windows/Rtools/) are
avilable.

**beverstan** depends on the IRSN packages:
[**NSGEV**](https://github.com/IRSN/NSGEV) (public), and
[**bever**](https://github.com/IRSN/bever) (private), as well as on
public packages available on the CRAN, see the [`DESCRIPION`](./DESCRIPTION) 
file.

# Install on all systems with `devtools`

If you use a Linux, MacOS system or if you are on Windows and have
the **Rtools** installed, you can also install **beverstan** by using
the **devtools** package.

```{r, eval=FALSE}
devtools::install_github("IRSN/beverstan", auth_token = myToken)
```	     
where the `myToken` is a character object containing your
authorisation token. Of course you must keep your token secret. So do
not write it in R programs that could be seen.

Mind the packages embeds a rmarkdown *vignette*, and we recommend to
build it - which is optional. This can be done by using

```{r, eval=FALSE}
devtools::install_github("IRSN/beverstan", auth_token = myToken, build_vignettes = TRUE)
```
A link to the vignette will then be shown in the package help.


# Install a release

The GitHub repos of **bevertan** provides
[releases](https://github.com/IRSN/beverstan/releases/). For each
release precompiled (a.k.a. binary) versions of the package are
provided as files with their name begining by `berverstan_x.y.z` where
`x`, `y`, and `z` are the major, minor and patch numbers in the package
version. The extension of the file corresponds to the (64 bit
architecture) platform

- For **Windows** users the precompiled file is `berverstan_x.y.z.zip`

- For **MacOSX** users the precompiled file is `berverstan_x.y.z.tgz` 

- Finally for **Linux** users the precompiled file is
  `berverstan_x.y.z_R_x_86_64-pc-linux-gnu.tar.gz`

The file extensions should never be changed and neither of these files
should be uncompressed by using the relevant tool (such a unzip) but
either **RStudio** or the R command system. Also mind that although it
has the same file extension as the source tarball, the precompiled
versions for Linux is very different from the tarball file.

In order to install a precompiled version, you can either 

- Use the **RStudio** IDE, menu **`Tools`** then **`Install
Packages...`** or 

- Use the R command `R CMD install` followed by the name of the precompiled
 package file.
 
 Mind that the precompiled versions have been obtained by using the
 latest R version at the release time. See below for a note about R
 versions.


# Install by cloning the sources
  
## Cloning the repository

If you do not have yet a local `beverstan` repository, use `git clone`
to clone the kergp repository

`git clone https://github.com/IRSN/beverstan/`

This will create a `beverstan` subdirectory of the current directory,
i.e. the directory from which the git command was issued.

If you already have cloned the repos, then use the following command
from within the `beverstan` directory
   
`git pull`

This will update your local copy.
        
## Install on Linux and MacOS systems

With these sytems you can install a package from its source. Move to
the parent directory of your cloned repository and use the following
command from a terminal to create a tarball source file

`R CMD build beverstan`

This will produce a source tarball `beverstan_x.y.z.tar.gz` where `x`,
`y` and `z` stand for the *major*, *minor* and *patch* version
numbers. Then you can install from a command line

`R CMD INSTALL beverstan_x.y.z.tar.gz`

Note that you must formerly have installed all the packages required by
`beverstan` installed.


## Install and pre-compile for Windows

### Rtools
	   
In order to install the package from its source, you must have a
suitable Windows plateform with the
[**Rtools**](https://cran.r-project.org/bin/windows/Rtools/)
installed. Then you can proceed as Unix or MacOS users, with a build
step from command line. Note that rather than using a terminal, you
can use the terminal provided by **RStudio**.

If you can not (or do not want to) install the **Rtools** you may get
a trusted binary from a friend or collegue next to you.

### Making a precompiled `.zip` file  with the Rtools
    
If you have the Rtools installed, you can create a precompiled binary
file from the source tarball `beverstan_x.y.z.tar.gz`.  Using a
terminal, move if necessary by using `cd` to the directory containing
the source tarball, and then type

`R CMD INSTALL --build beverstan_x.y.z.tar.gz`

This will create a `.zip` file that can be used on a Windows plateform
which may not be equipped with the **Rtools**. For instance, with
**RStudio** you can use the menu `Tools/Install Packages` and select
`Install from:` to install a precompiled `.zip` file.

### RStudio	 
	 
If you are using the **RStudio** IDE, you can alternatively use menus:
**Install** and **pre-compile for Windows** to install the source
tarball `beverstan_x.y.z.tar.gz`.

If you are planning to modify the package, you can also create a project using
the Menu **New Project...** / **Existing Directory** and then use the
package developpement tools **Build**. By proceeding in this way you
can add new functions or new objects to the package. In thix case you will
find useful to *fork* the repos.
    
## Managing R versions (all systems)

Remind that when the package is compiled with `R-a.b.c` the resulting
binary is intended to be used with R versions having the same major
`a` and the same minor `b` but possibly a different patch number
`c`. So if you want to use the package on several versions of R with different
major or minor, you will have to re-compile it to avoid warnings or errors.