greta (version 0.1.7)

greta-distributions: greta probability distributions

Description

These functions can be used to define random variables in a greta model. They return a greta array object that can be combined with other greta arrays to construct a model. All of these functions construct random variables with prior distributions, except for free(), which creates 'free' parameters, so can be used for frequentist analyses.

Usage

free(lower = -Inf, upper = Inf, dim = 1)
uniform(min, max, dim = NULL)
normal(mean, sd, dim = NULL)
lognormal(meanlog, sdlog, dim = NULL)
bernoulli(prob, dim = NULL)
binomial(size, prob, dim = NULL)
negative_binomial(size, prob, dim = NULL)
poisson(lambda, dim = NULL)
gamma(shape, rate, dim = NULL)
exponential(rate, dim = NULL)
student(df, location, scale, dim = NULL)
beta(shape1, shape2, dim = NULL)
multivariate_normal(mean, Sigma, dim = 1)
wishart(df, Sigma)

Arguments

lower, upper

scalar values giving optional limits to free parameters. These must be specified as numerics, they cannot be greta arrays (though see details for a workaround). They can be set to -Inf (lower) or Inf (upper), though lower must always be less than upper.

dim

the dimensions of the variable, either a scalar or a vector of positive integers. See details.

min, max

scalar values giving optional limits to uniform variables. Like lower and upper, these must be specified as numerics, they cannot be greta arrays (though see details for a workaround). Unlike lower and upper, they must be finite. min must always be less than max.

mean, meanlog, location

unconstrained parameters

sd, sdlog, size, lambda, shape, rate, df, scale, shape1, shape2

positive parameters

prob

probability parameter (0 < prob < 1)

Sigma

positive definite variance-covariance matrix parameter

Details

The discrete probability distributions (bernoulli, binomial, negative_binomial, poisson) can be used when they have fixed values (e.g. defined as a likelihood using distribution, but not as unknown variables.

For free(), dim gives the dimension of the greta array to create as a free parameter. All elements of that array will have the same constraints (lower and upper). For univariate distributions dim also gives the dimensions of the greta array to create. Each element of the greta array will be (independently) distributed according to the distribution. dim can also be left at its default of NULL, in which case the dimension will be detected from the dimensions of the parameters (provided they are compatible with one another).

For multivariate_normal(), dim must be a scalar giving the number of rows in the resulting greta array, each row being (independently) distributed according to the multivariate normal distribution. The number of columns will always be the dimension of the distribution, determined from the parameters specified. wishart() always returns a single square, 2D greta array, with dimension determined from the parameter Sigma.

The parameters of both free and uniform must be fixed, not greta variables. This ensures these values can always be transformed to a continuous scale to run the samplers efficiently. However, a hierarchical uniform or free parameter can always be created by defining a free or uniform variable constrained between 0 and 1, and then transforming it to the required scale. I.e. min + u * (max - min), where u is e.g. uniform(0, 1). See below for an example.

Wherever possible, the parameterisation of these distributions matches the those in the stats package. E.g. for the parameterisation of negative_binomial(), see dnbinom. student() is an exception, since the https://en.wikipedia.org/wiki/Student%27s_t-distribution#In_terms_of_scaling_parameter_.CF.83.2C_or_.CF.832 we use is more useful, and widely used, for statistical modelling than the noncentral version implemented in stats

Examples

# an unconstrained and prior-free parameter (e.g. for a frequentist model)
alpha = free()

# positive prior-free parameter (could also do: sigma = exp(free()) )
sigma = free(lower = 0)

# a prior-free parameter constrained to be less that -1
neg_alpha = free(upper = -1)

# a prior-free parameter constrained to be between 0 and 1
psi = free(lower = 0, upper = 1)

# a uniform parameter constrained to be between 0 and 1
phi = uniform(min = 0, max = 1)

# create a hierarchical uniform, constrained between alpha and alpha + sigma,
eta = alpha + uniform(0, 1) * sigma

# an unconstrained parameter with standard normal prior
mu = normal(0, 1)

# a hierarchical distribution
theta = normal(mu, lognormal(0, 1))

# a vector of 3 variables drawn from the same hierarchical distribution
thetas = normal(mu, sigma, dim = 3)

# a matrix of 12 variables drawn from the same hierarchical distribution
thetas = normal(mu, sigma, dim = c(3, 4))

# a multivariate normal variable, with correlation between two elements
Sig <- diag(4)
Sig[3, 4] <- Sig[4, 3] <- 0.6
theta = multivariate_normal(rep(mu, 4), Sig)

# 10 independent replicates of that
theta = multivariate_normal(rep(mu, 4), Sig, dim = 10)

# a Wishart variable with the same covariance parameter
theta = wishart(df = 5, Sigma = Sig)