Skip to contents

The beverstan package

Yves Deville 2023-12-28

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, used through the rstan package available on the CRAN, including the RCpp package. The beverstan package is an “Rstan” package with a special structure as can be created thanks to the rstantools package which is available on the CRAN.

beverstan requires compilation. On a Windows platform, the compilation of the sources requires that the Rtools are avilable.

beverstan depends on the IRSN packages: NSGEV (public), and bever (private), as well as on public packages available on the CRAN, see the DESCRIPION 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.

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

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. 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 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.