Yves Deville 2023-12-28
- Goals
- Requirements
- Install on all systems
with
devtools - Install a release
- Install by cloning the sources
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.
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.
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.
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
ToolsthenInstall Packages...or -
Use the R command
R CMD installfollowed 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.
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.
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.
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.
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.
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.
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.