Repository files navigation

TheRcpp package provides a C++ library to make it easier to use C++ with R. R and Rcpp provide functions for a variety of statistical distributions. Several R packages make functions available to R for additional statistical distributions. However, to access these functions from C++ code, a costly call to the R functions must be made.

RcppDist provides a header-only C++ library with functions for additional statistical distributions that can be called from C++ when writing code using Rcpp orRcppArmadillo. Functions are available that return NumericVectors as well as doubles, and for multivariate or matrix distributions, Armadillo vectors and matrices.

RcppDist provides functions for the following distributions:

• The four parameter beta distribution
• The Laplace distribution
• The location-scale t distribution
• The truncated normal distribution
• The truncated t distribution
• A truncated location-scale t distribution
• The triangular distribution
• The multivariate normal distribution
• The multivariate t distribution
• The Wishart distribution
• The inverse Wishart distribution

You can install RcppDist from CRAN via

install.packages("RcppDist")

Or, you can install the development version from GitHub via

remotes::install_github("duckmayr/RcppDist")

You can use RcppDist in standalone C++ files using

#include<RcppDist.h>// [[Rcpp::depends(RcppArmadillo, RcppDist)]]

If you would prefer to use Rcpp butnot RcppArmadillo (i.e. include the Rcpp headers but not the RcppArmadillo headers), instead use

#defineRCPPDIST_DONT_USE_ARMA#include<RcppDist.h>// [[Rcpp::depends(RcppDist)]]

though be aware that without Armadillo, the multivariate normal, multivariate t, Wishart, and inverse Wishart distributions will be unavailable.

To use RcppDist in a package that links to RcppArmadillo, you must

• Set up your package to useRcppArmadillo, such as viaRcppArmadillo::RcppArmadillo.package.skeleton(your_package)
• Add RcppDist to the LinkingTo field of your DESCRIPTION file.
• In any C++ file that calls aRcppDist function, add#include <RcppDist.h>

To use RcppDist in a package that does not link to RcppArmadillo, you must

• Set up your package to useRcpp, such as viaRcpp::Rcpp.package.skeleton(your_package) ordevtools::use_rcpp(your_package).
• Add RcppDist to the LinkingTo field of your DESCRIPTION file.
• In any C++ file that calls aRcppDist function, add#include <RcppDist.h>.
• Use#define RCPPDIST_DONT_USE_ARMA before any include ofRcppDist.h.

Much like distributions in R, functions are prefixed by d, p, q, and r to mean density, distribution, quantile, and random number generating functions respectively. Functions that return a double rather than, say, a NumericVector are instead prefixed by d_, p_, q_, and r_. For example,

d4beta(x,2.0,2.0, -5.0,5.0)

gives the density of the four-parameter beta distribution with shape values 2 and 2 defined on the interval [-5, 5] at the values in theRcpp::NumericVector x (the function's return value is also aRcpp::NumericVector), while

d_4beta(x, 2.0, 2.0, -5.0, 5.0)

gives the density of the four-parameter beta distribution with shape values 2 and 2 defined on the interval [-5, 5] at the value in thedouble x (the function's return value is also adouble).

Definitions and descriptions of the C++ functions provided by RcppDist, as well as more information on including RcppDist headers (such as using headers for only one or more specific distributions), are given in the vignette, which you can access from R using

vignette("RcppDist")

An example of using RcppDist's multivariate normal generator can be seen in thebayeslm() R-facing function; its code is displayed in the help file for it, accessible via

help("bayeslm")

The distributions above were selected for inclusion because I already had occasion to generate C++ code for use with Rcpp (or RcppArmadillo) for these distributions, but I am open to requests to expand the package to include additional distributions -- just open an issue with the requested feature, or feel free to contribute the code yourself and open a pull request; before contributing, please consult the contributing guidelines in CONTRIBUTING.md.

GPL (>= 2)