nlmm {nlmm}

Fitting Generalized Laplace Mixed-Effects Models

Description

nlmm is used to fit mixed-effects models based on the generalized Laplace distribution.

Usage

nlmm(fixed, random, group, covariance = "pdDiag", data = sys.frame(sys.parent()),
subset, weights = NULL, na.action = na.fail, control = list(), contrasts = NULL,
fit = TRUE)

Arguments

fixed

an object of class formula for fixed effects: a symbolic description of the model to be fitted.

random

a one-sided formula of the form ~x1 + x2 + ... + xn for random effects: a symbolic description of the model to be fitted.

group

grouping factor.

covariance

variance–covariance matrix of the random effects. Default is pdDiag (see details)

data

an optional data frame containing the variables named in fixed, random, group, and weights. By default the variables are taken from the environment from which nlmm is called.

subset

an optional vector specifying a subset of observations to be used in the fitting process.

weights

an optional varFunc object or one-sided formula describing the within-group heteroscedasticity structure. If given as a formula, it is used as the argument to varFixed, corresponding to fixed variance weights. See the documentation on varClasses in nlme package for a description of the available varFunc classes. Defaults to NULL, corresponding to homoscedastic within-group errors.

na.action

a function that indicates what should happen when the data contain NAs. The default action (na.fail) causes nlmm to print an error message and terminate if there are any incomplete observations.

control

list of control parameters of the fitting process. See nlmmControl.

contrasts

not yet implemented.

fit

logical flag. If FALSE the function returns a list of objects used for fitting.

Details

The function fits a generalized Laplace mixed-effects model conditional on the covariates, as specified by the formula argument, and on random effects, as specified by the random argument. The predictor is assumed to be linear. The function maximizes the (log)likelihood of the generalized Laplace regression as proposed by Geraci and Farcomeni (2020). The likelihood is numerically integrated via Gaussian quadrature techniques. The optimization algorithm can be either optim (Nelder-Mead by default) or nlminb. See nlmmControl for more details.

By default, the function fits a mixed-effects model where both random effects and error term follow a generalized Laplace distribution (GenLaplace). This is a family of distributions that includes the normal and the Laplace distributions as special cases. Constrained fitting can be controlled via the arguments alpha.index and alpha in nlmmControl. For example, if alpha.index = 0, the model is Normal-Normal if alpha = c(0,0), Normal-Laplace if alpha = c(0,1), Laplace-Normal if alpha = c(1,0), and Laplace-Laplace if alpha = c(1,1). But any value of alpha between 0 (normal distribution) and 1 (Laplace distribution) is allowed.

Different standard types of positive–definite matrices for the random effects can be specified: pdIdent multiple of an identity; pdCompSymm compound symmetry structure (constant diagonal and constant off–diagonal elements); pdDiag diagonal; pdSymm general positive–definite matrix, with no additional structure.

Within-group heteroscedasticity can be modeled via the weights argument using varClasses in the nlme packages.

Value

nlmm returns an object of class nlmm.

The function summary is used to obtain and print a summary of the results.

An object of class nlmm is a list containing the following components:

theta

a vector containing (in this order) fixed regression coefficients, parameters of the variance–covariance matrix of the random effects, shape parameter, scale parameter, and (optional) within-group variance function parameters. All parameters are unconstrained. See VarCorr.nlmm to extract the variance–covariance of the random effects from an "nlmm" object.

theta_x, theta_z

partition of theta: fixed regression coefficients (theta_x) and unique variance–covariance unconstrained parameters (theta_z).

tau

unconstrained shape parameter.

alpha

constrained shape parameter.

phi

unconstrained scale parameter.

sigma

constrained scale parameter.

vf

(fitted) within-group variance function of class varFunc. S3 methods (summary.varFunc, varWeights.varFunc, coef.varFunc) can be applied.

value

negative log–likelihood.

call

the matched call.

nn

column names of mmf.

mm

column names of mmr.

nobs

the number of observations.

dim_theta

the number of columns in mmf and mmr.

dim_theta_z

the length of theta_z.

mmf

the model matrix – fixed effects.

mmr

the model matrix – random effects.

y

the model response.

revOrder

original order of observations (now ordered according to group).

group

the grouping factor.

ngroups

the number of groups.

InitialPar

starting values for theta, included the fitted lme or lm object from where starting values have been taken.

control

list of control parameters used for optimization (see nlmmControl).

cov_name

class of variance-covariance matrix for the random effects.

mfArgs

arguments for model.frame to return the full data frame.

sc

model's distribution. "Generalized Laplace" if unconstrained estimation, or one of four special case for specific values of alpha ("Normal-Normal", "Normal-Laplace", "Laplace-Normal", "Laplace-Laplace").

Author(s)

Marco Geraci

References

Geraci M (2017). Mixed-effects models using the normal and the Laplace distributions: A 2 x 2 convolution scheme for applied research. arXiv:1712.07216v1 [stat.ME]. URL: https://arxiv.org/abs/1712.07216v1.

Geraci, M. and Farcomeni A. (2020). A family of linear mixed-effects models using the generalized Laplace distribution. Statistical Methods in Medical Research, 29(9), 2665-2682.

See Also

summary.nlmm, fixef.nlmm, ranef.nlmm, VarCorr.nlmm, predict.nlmm, residuals.nlmm, nlmmControl

Examples

data(rats)

nlmm(y ~ trt*time, random = ~ 1, group = id, data = rats,
control = nlmmControl(multistart = FALSE))