gen {mcmcsae}

Create a model component object for a generic random effects component in the linear predictor

Description

This function is intended to be used on the right hand side of the formula argument to create_sampler or generate_data.

Usage

gen(
  formula = ~1,
  factor = NULL,
  remove.redundant = FALSE,
  drop.empty.levels = FALSE,
  X = NULL,
  var = NULL,
  prior = NULL,
  Q0 = NULL,
  PX = NULL,
  GMRFmats = NULL,
  priorA = NULL,
  Leroux = FALSE,
  R0 = NULL,
  RA = NULL,
  constr = NULL,
  S0 = NULL,
  SA = NULL,
  formula.gl = NULL,
  a = 1000,
  name = "",
  sparse = NULL,
  control = gen_control(),
  debug = FALSE
)

Arguments

formula

a model formula specifying the effects that vary over the levels of the factor variable(s) specified by argument factor. Defaults to ~1, corresponding to random intercepts. If X is specified formula is ignored. Variable names are looked up in the data frame passed as data argument to create_sampler or generate_data, or in environment(formula).

factor

a formula with factors by which the effects specified in the formula argument vary. Often only one such factor is needed but multiple factors are allowed so that interaction terms can be modeled conveniently. The formula must take the form ~ f1(fac1, ...) * f2(fac2, ...) ..., where fac1, fac2 are factor variables and f1, f2 determine the correlation structure assumed between levels of each factor, and the ... indicate that for some correlation types further arguments can be passed. Correlation structures currently supported include iid for independent identically distributed effects, RW1 and RW2 for random walks of first or second order over the factor levels, AR1 for first-order autoregressive effects, season for seasonal effects, spatial for spatial (CAR) effects and custom for supplying a custom precision matrix corresponding to the levels of the factor. For further details about the correlation structures, and further arguments that can be passed, see correlation. Argument factor is ignored if X is specified. The factor variables are looked up in the data frame passed as data argument to create_sampler or generate_data, or in environment(formula).

remove.redundant

whether redundant columns should be removed from the model matrix associated with formula. Default is FALSE.

drop.empty.levels

whether to remove factor levels without observations.

X

A (possibly sparse) design matrix. This can be used instead of formula and factor.

var

the (co)variance structure among the varying effects defined by formula over the levels of the factors defined by factor. The default is "unstructured", meaning that a full covariance matrix parameterization is used. For uncorrelated effects with unequal variances use var="diagonal". For uncorrelated effects with equal variances use var="scalar". In the case of a single varying effect there is no difference between these choices.

prior

the prior specification for the variance parameters of the random effects. These can currently be specified by a call to pr_invwishart in case var="unstructured" or by a call to pr_invchisq otherwise. See the documentation of those prior specification functions for more details.

Q0

precision matrix associated with formula. This can only be used in combination with var="scalar".

PX

whether parameter expansion should be used. Default is TRUE, which applies parameter expansion with default options. The only exception is that for gamma sampling distributions the default is FALSE, i.e. no parameter expansion. Alternative options can be specified by supplying a list with one or more of the following components:

prior

prior for the multiplicative expansion parameter. Defaults to a normal prior with mean 0 and standard deviation 1, unless the sampling distribution is gamma in which case the default is a Multivariate Log inverse Gamma prior. The default parameters can be changed using functions pr_normal or pr_MLiG.

vector

whether a redundant multiplicative expansion parameter is used for each varying effect specified by formula. The default is TRUE except when var="scalar". If FALSE a single redundant multiplicative parameter is used.

data.scale

whether the data level scale is used as a variance factor for the expansion parameters. Default is TRUE.

GMRFmats

list of incidence/precision/constraint matrices. This can be specified as an alternative to factor. It should be a list such as that returned by compute_GMRF_matrices. Can be used together with argument X as a flexible alternative to formula and factor.

priorA

prior distribution for scale factors at the variance scale associated with QA. In case of IGMRF models the scale factors correspond to the innovations. The default NULL means not to use any local scale factors. A prior can currently be specified using pr_invchisq or pr_exp.

Leroux

this option alters the precision matrix determined by factor by taking a weighted average of it with the identity matrix. If TRUE the model gains an additional parameter, the 'Leroux' parameter, being the weight of the original, structured, precision matrix in the weighted average. By default a uniform prior for the weight and a uniform Metropolis-Hastings proposal density are employed. This default can be changed by supplying a list with elements a, b, and a.star, b.star, implying a beta(a, b) prior and a beta(a.star, b.star) independence proposal density. A third option is to supply a single number between 0 and 1, which is then used as a fixed value for the Leroux parameter.

R0

an optional equality restriction matrix acting on the coefficients defined by formula, for each level defined by factor. If c is the number of restrictions, R0 is a q0 x c matrix where q0 is the number of columns of the design matrix derived from formula. Together with RA it defines the set of equality constraints to be imposed on the vector of coefficients. Only allowed in combination with var="scalar".

RA

an optional equality restriction matrix acting on the coefficients defined by factor, for each effect defined by formula. If c is the number of restrictions, RA is a l x c matrix where l is the number of levels defined by factor. Together with R0 this defines the set of equality constraints to be imposed on the vector of coefficients. If constr=TRUE, additional constraints are imposed, corresponding to the null-vectors of the singular precision matrix in case of an intrinsic Gaussian Markov Random Field.

constr

whether constraints corresponding to the null-vectors of the precision matrix are to be imposed on the vector of coefficients. By default this is TRUE for improper or intrinsic GMRF model components, i.e. components with a singular precision matrix such as random walks or CAR spatial components.

S0

an optional inequality restriction matrix acting on the coefficients defined by formula, for each level defined by factor. If c is the number of restrictions, S0 is a q0 x c matrix where q0 is the number of columns of the design matrix derived from formula. Together with SA it defines the set of inequality constraints to be imposed on the vector of coefficients.

SA

an optional inequality restriction matrix acting on the coefficients defined by factor, for each effect defined by formula. If c is the number of restrictions, SA is a l x c matrix where l is the number of levels defined by factor. Together with S0 this defines the set of constraints to be imposed on the vector of coefficients.

formula.gl

a formula of the form ~ glreg(...) for group-level predictors around which the random effect component is hierarchically centered. See glreg for details.

a

only used in case the effects are MLiG distributed, such as is assumed in case of a gamma sampling distribution, or for gaussian variance modelling. In those cases a controls how close the effects' prior is to a normal prior, see pr_MLiG.

name

the name of the model component. This name is used in the output of the MCMC simulation function MCMCsim. By default the name will be 'gen' with the number of the model term attached.

sparse

whether the model matrix associated with formula should be sparse. The default is based on a simple heuristic based on storage size.

control

a list with further computational options. These options can be specified using function gen_control.

debug

if TRUE a breakpoint is set at the beginning of the posterior draw function associated with this model component. Mainly intended for developers.

Value

An object with precomputed quantities and functions for sampling from prior or conditional posterior distributions for this model component. Intended for internal use by other package functions.

References

J. Besag and C. Kooperberg (1995). On Conditional and Intrinsic Autoregression. Biometrika 82(4), 733-746.

C.M. Carvalho, N.G. Polson and J.G. Scott (2010). The horseshoe estimator for sparse signals. Biometrika 97(2), 465-480.

L. Fahrmeir, T. Kneib and S. Lang (2004). Penalized Structured Additive Regression for Space-Time Data: a Bayesian Perspective. Statistica Sinica 14, 731-761.

A. Gelman (2006). Prior distributions for variance parameters in hierarchical models. Bayesian Analysis 1(3), 515-533.

A. Gelman, D.A. Van Dyk, Z. Huang and W.J. Boscardin (2008). Using Redundant Parameterizations to Fit Hierarchical Models. Journal of Computational and Graphical Statistics 17(1), 95-122.

B. Leroux, X. Lei and N. Breslow (1999). Estimation of Disease Rates in Small Areas: A New Mixed Model for Spatial Dependence. In M. Halloran and D. Berry (Eds.), Statistical Models in Epidemiology, the Environment and Clinical Trials, 135-178.

T. Park and G. Casella (2008). The Bayesian Lasso. Journal of the American Statistical Association 103(482), 681-686.

H. Rue and L. Held (2005). Gaussian Markov Random Fields. Chapman & Hall/CRC.