# Distributions¶

Distribution objects represent probability distributions, they have two principle uses:

1. Samples can be generated from a distribution by passing a distribution object to the sample operator.

2. The logarithm of the probability (or density) that a distribution assigns to a value can be computed using `dist.score(val)`. For example:

```Bernoulli({p: .1}).score(true); // returns Math.log(.1)
```

Several primitive distributions are built into the language. Further distributions are created by performing marginal inference.

## Primitives¶

`Bernoulli`({p: ...})
• p: success probability (real [0, 1])

Distribution over `{true, false}`

Wikipedia entry

`Beta`({a: ..., b: ...})
• a: shape (real (0, Infinity))
• b: shape (real (0, Infinity))

Distribution over `[0, 1]`

Wikipedia entry

`Binomial`({p: ..., n: ...})
• p: success probability (real [0, 1])
• n: number of trials (int (>=1))

Distribution over the number of successes for `n` independent `Bernoulli({p: p})` trials.

Wikipedia entry

`Categorical`({ps: ..., vs: ...})
• ps: probabilities (can be unnormalized) (vector or real array [0, Infinity))
• vs: support (any array)

Distribution over elements of `vs` with `P(vs[i])` proportional to `ps[i]`. `ps` may be omitted, in which case a uniform distribution over `vs` is returned.

Wikipedia entry

`Cauchy`({location: ..., scale: ...})
• location: (real)
• scale: (real (0, Infinity))

Distribution over `[-Infinity, Infinity]`

Wikipedia entry

`Delta`({v: ...})
• v: support element (any)

Discrete distribution that assigns probability one to the single element in its support. This is only useful in special circumstances as sampling from `Delta({v: val})` can be replaced with `val` itself. Furthermore, a `Delta` distribution parameterized by a random choice should not be used with MCMC based inference, as doing so produces incorrect results.

`DiagCovGaussian`({mu: ..., sigma: ...})
• mu: mean (tensor)
• sigma: standard deviations (tensor (0, Infinity))

A distribution over tensors in which each element is independent and Gaussian distributed, with its own mean and standard deviation. i.e. A multivariate Gaussian distribution with diagonal covariance matrix. The distribution is over tensors that have the same shape as the parameters `mu` and `sigma`, which in turn must have the same shape as each other.

`Dirichlet`({alpha: ...})
• alpha: concentration (vector (0, Infinity))

Distribution over probability vectors. If `alpha` has length `d` then the distribution is over probability vectors of length `d`.

Wikipedia entry

`Discrete`({ps: ...})
• ps: probabilities (can be unnormalized) (vector or real array [0, Infinity))

Distribution over `{0,1,...,ps.length-1}` with P(i) proportional to `ps[i]`

Wikipedia entry

`Exponential`({a: ...})
• a: rate (real (0, Infinity))

Distribution over `[0, Infinity]`

Wikipedia entry

`Gamma`({shape: ..., scale: ...})
• shape: (real (0, Infinity))
• scale: (real (0, Infinity))

Distribution over positive reals.

Wikipedia entry

`Gaussian`({mu: ..., sigma: ...})
• mu: mean (real)
• sigma: standard deviation (real (0, Infinity))

Distribution over reals.

Wikipedia entry

`KDE`({data: ..., width: ...})
• data: data array
• width: kernel width

A distribution based on a kernel density estimate of `data`. A Gaussian kernel is used, and both real and vector valued data are supported. When the data are vector valued, `width` should be a vector specifying the kernel width for each dimension of the data. When `width` is omitted, Silverman’s rule of thumb is used to select a kernel width. This rule assumes the data are approximately Gaussian distributed. When this assumption does not hold, a `width` should be specified in order to obtain sensible results.

Wikipedia entry

`Laplace`({location: ..., scale: ...})
• location: (real)
• scale: (real (0, Infinity))

Distribution over `[-Infinity, Infinity]`

Wikipedia entry

`LogisticNormal`({mu: ..., sigma: ...})
• mu: mean (vector)
• sigma: standard deviations (vector (0, Infinity))

A distribution over probability vectors obtained by transforming a random variable drawn from `DiagCovGaussian({mu: mu, sigma: sigma})`. If `mu` and `sigma` have length `d` then the distribution is over probability vectors of length `d+1`.

Wikipedia entry

`LogitNormal`({mu: ..., sigma: ..., a: ..., b: ...})
• mu: location (real)
• sigma: scale (real (0, Infinity))
• a: lower bound (real)
• b: upper bound (>a) (real)

A distribution over `(a,b)` obtained by scaling and shifting a standard logit-normal.

Wikipedia entry

`Mixture`({dists: ..., ps: ...})
• dists: array of component distributions
• ps: component probabilities (can be unnormalized) (vector or real array [0, Infinity))

A finite mixture of distributions. The component distributions should be either all discrete or all continuous. All continuous distributions should share a common support.

`Multinomial`({ps: ..., n: ...})
• ps: probabilities (real array with elements that sum to one)
• n: number of trials (int (>=1))

Distribution over counts for `n` independent `Discrete({ps: ps})` trials.

Wikipedia entry

`MultivariateBernoulli`({ps: ...})
• ps: probabilities (vector [0, 1])

Distribution over a vector of independent Bernoulli variables. Each element of the vector takes on a value in `{0, 1}`. Note that this differs from `Bernoulli` which has support `{true, false}`.

`MultivariateGaussian`({mu: ..., cov: ...})
• mu: mean (vector)
• cov: covariance (positive definite matrix)

Multivariate Gaussian distribution with full covariance matrix. If `mu` has length d and `cov` is a `d`-by-`d` matrix, then the distribution is over vectors of length `d`.

Wikipedia entry

`Poisson`({mu: ...})
• mu: mean (real (0, Infinity))

Distribution over integers.

Wikipedia entry

`RandomInteger`({n: ...})
• n: number of possible values (int (>=1))

Uniform distribution over `{0,1,...,n-1}`

Wikipedia entry

`TensorGaussian`({mu: ..., sigma: ..., dims: ...})
• mu: mean (real)
• sigma: standard deviation (real (0, Infinity))
• dims: dimension of tensor (int (>=1) array)

Distribution over a tensor of independent Gaussian variables.

`TensorLaplace`({location: ..., scale: ..., dims: ...})
• location: (real)
• scale: (real (0, Infinity))
• dims: dimension of tensor (int (>=1) array)

Distribution over a tensor of independent Laplace variables.

`Uniform`({a: ..., b: ...})
• a: lower bound (real)
• b: upper bound (>a) (real)

Continuous uniform distribution over `[a, b]`

Wikipedia entry