R: Define a probability distribution object

make.dist

R Documentation

Define a probability distribution object

Description

Defines a probability distribution object for use with compare.samplers.

Usage

make.dist(ndim, name, name.expression=NULL,
          log.density=NULL, grad.log.density=NULL,
          log.density.and.grad=NULL, initial=NULL,
          mean=NULL, cov=NULL, mean.log.dens=NULL)

Arguments

`ndim`	The size of the distribution's state space.
`name`	A human-readable name for the distribution.
`name.expression`	A name for the distribution in `plotmath` notation. Used in preference to `name` in plot functions when available.
`log.density`	A function taking a vector argument that returns the log density of the distribution evaluated at that point.
`grad.log.density`	A function taking a vector argument that returns the gradient of the log density of the distribution evaluated at that point.
`log.density.and.grad`	A function taking a vector argument and a logical that returns a list with two elements, `log.density` and `grad.log.density`. The logical indicates whether the caller wants the gradient; if not, this function may omit the `grad.log.density` element in the return value.
`initial`	A function that returns an overdispersed initial state for an MCMC simulation of this distribution, used by `compare.samplers`. If unset, uniform draws on a unit hypercube are assumed to be acceptable.
`mean`	A vector specifying the true mean of the distribution.
`cov`	A matrix specifying the true covariance of the distribution.
`mean.log.dens`	A scalar specifying the true mean of the log density of the distribution. This will depend on the normalization of the log density function.

Details

Every distribution must have a name and a dimension. The log density and its gradient are optional; they are used by samplers implemented in R. Samplers implemented in other languages could specifically recognize the name of the distribution instead of calling back into R, though there is a mechanism for C functions to call back. The mean and covariance do not affect sampling, only post-sample diagnostics like autocorrelation time.

For many distributions, it is easier to compute the log density and its gradient at the same time than separately; these will generally specify log.density.and.grad and leave log.density and log.density.and.grad as NULL. The returned object will fill those in with calls to log.density.and.grad. Similarly, if it is simpler to compute them separately, log.density.and.grad will be synthesized from log.density and grad.log.density if necessary.

mean, cov, and mean.log.dens values are intended to be used by diagnostic routines. mean and mean.log.dens are currently used by compare.samplers when estimating autocorrelation times.

See make.c.dist for a way to define distributions whose densities are implemented in C instead of R.

Value

A scdist object. It has elements with the same names as the arguments to make.dist.

Examples

  # A one dimensional Gamma(3,2) distribution.

  # So that the density does not return NaN outside the support.
  inflog <- function(x) ifelse(x<=0, -Inf, log(x))

  # Define density; unnormalized densities are fine.

  gamma32.log.density <- function(x) (3-1)*inflog(x) - x/2
  gamma32.grad <- function(x) (3-1)/x - 1/2

  # Use make.dist to define the distribution object.

  gamma32.dist <- make.dist(1, 'Gamma32', 'plain("Gamma")(3,2)',
                            log.density=gamma32.log.density,
                            grad.log.density=gamma32.grad,
                            mean=3*2, cov=as.matrix(3*2^2))

  # Make sure the log density and gradient agree at an arbitrary point.

  check.dist.gradient(gamma32.dist, 17)