Polya Gamma Distribution Sampler • pg

The goal of pg is to provide both R and C++ header access to the Polya Gamma distribution sampling routine.

Installation

You can install the development version of pg from GitHub with:

# install.packages("devtools")
devtools::install_github("tmsalab/pg")

Usage

Let X be a Polya Gamma Distribution denoted by PG(h, z), where h is the “shape” parameter and z is the “scale” parameter. Presently, the following sampling cases are enabled:

h > 170: Normal approximation method
h <= 170 and h > 13: Saddlepoint method
h = 1 or h = 2: Devroye method
h > 0: Sum of gammas method.
h < 0: Result is automatically set to zero.

Not implemented:

h <= 13 and h > 1: Alternative method (waiting for verification)

The package structure allows for the sampling routines to be accessed either via C++ or through R. The return type can be either a single value or a vector. When repeat sampling is needed with the same b and c, please use the vectorized sampler.

Sampling with C++

Using the sampling routine in C++ through a standalone .cpp file requires either the rpg_scalar_hybrid(), rpg_vector_hybrid(), or rpg_hybrid() function to be accessed in the pg C++ namespace. Each of these functions will automatically select the appropriate algorithm based on criteria discussed previously.

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

// [[Rcpp::export]]
double rpg_scalar(const double h, const double z) {
  return pg::rpg_scalar_hybrid(h, z);
}

// [[Rcpp::export]]
arma::vec rpg_hybrid(const arma::vec& h, const arma::vec& z) {
  return pg::rpg_hybrid(h, z);
}

// [[Rcpp::export]]
arma::vec rpg_vector(unsigned int n, const double h, const double z) {
  return pg::rpg_vector_hybrid(n, h, z);
}

For use within an R package, include a the pg package name in the DESCRIPTION file. From there, include the pg.h header in a similar manner to the stand-alone C++ example.

LinkingTo: 
    Rcpp,
    RcppArmadillo
    pg

Sampling with R

For use within an R file, you can do:

# Number of observations to sample
n = 4
# Select the PG(h, z) values
h = 1; z = 0.5

# Set a seed for reproducibility
set.seed(141)

# Sample a single observation
pg::rpg_scalar(h, z)
#> [1] 0.05752942

# Set a seed for reproducibility
set.seed(141)

# Sample a vector of observations
pg::rpg_vector(n, h, z)
#>            [,1]
#> [1,] 0.05752942
#> [2,] 0.38752679
#> [3,] 0.38710433
#> [4,] 0.18847913

Author

James Balamuta leaning heavily on work done in BayesLogit R package by Nicholas G. Polson, James G. Scott, and Jesse Windle.

Citing the `pg` package

To ensure future development of the package, please cite pg package if used during an analysis or simulation study. Citation information for the package may be acquired by using in R:

citation("pg")

License

GPL (>= 3)

pg