# make.dist: Define a probability distribution object In SamplerCompare: A Framework for Comparing the Performance of MCMC Samplers

## Description

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

## Usage

 ```1 2 3 4``` ```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`.

`compare.samplers`, `make.c.dist`, `check.dist.gradient`, “R/C Glue in SamplerCompare” (vignette)

## Examples

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20``` ``` # 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) ```

### Example output

```
```

SamplerCompare documentation built on Oct. 22, 2021, 9:14 a.m.