clmm {ordinal}

Cumulative Link Mixed Models

Description

Fits Cumulative Link Mixed Models with one or more random effects via the Laplace approximation or quadrature methods

Usage

clmm(formula, data, weights, start, subset, na.action, contrasts, Hess =
TRUE, model = TRUE, link = c("logit", "probit", "cloglog", "loglog",
"cauchit"), doFit = TRUE, control = list(), nAGQ = 1L,
threshold = c("flexible", "symmetric", "symmetric2", "equidistant"), ...)

Arguments

formula

a two-sided linear formula object describing the fixed-effects part of the model, with the response on the left of a ~ operator and the terms, separated by + operators, on the right. The vertical bar character "|" separates an expression for a model matrix and a grouping factor.

data

an optional data frame in which to interpret the variables occurring in the formula.

weights

optional case weights in fitting. Defaults to 1.

start

optional initial values for the parameters in the format c(alpha, beta, tau), where alpha are the threshold parameters, beta are the fixed regression parameters and tau are variance parameters for the random effects on the log scale.

subset

expression saying which subset of the rows of the data should be used in the fit. All observations are included by default.

na.action

a function to filter missing data.

contrasts

a list of contrasts to be used for some or all of the factors appearing as variables in the model formula.

Hess

logical for whether the Hessian (the inverse of the observed information matrix) should be computed. Use Hess = TRUE if you intend to call summary or vcov on the fit and Hess = FALSE in all other instances to save computing time.

model

logical for whether the model frames should be part of the returned object.

link

link function, i.e. the type of location-scale distribution assumed for the latent distribution. The default "logit" link gives the proportional odds mixed model.

doFit

logical for whether the model should be fit or the model environment should be returned.

control

a call to clmm.control

nAGQ

integer; the number of quadrature points to use in the adaptive Gauss-Hermite quadrature approximation to the likelihood function. The default (1) gives the Laplace approximation. Higher values generally provide higher precision at the expense of longer computation times, and values between 5 and 10 generally provide accurate maximum likelihood estimates. Negative values give the non-adaptive Gauss-Hermite quadrature approximation, which is generally faster but less accurate than the adaptive version. See the references for further details. Quadrature methods are only available with a single random effects term; the Laplace approximation is always available.

threshold

specifies a potential structure for the thresholds (cut-points). "flexible" provides the standard unstructured thresholds, "symmetric" restricts the distance between the thresholds to be symmetric around the central one or two thresholds for odd or equal numbers or thresholds respectively, "symmetric2" restricts the latent mean in the reference group to zero; this means that the central threshold (even no. response levels) is zero or that the two central thresholds are equal apart from their sign (uneven no. response levels), and "equidistant" restricts the distance between consecutive thresholds to be of the same size.

...

additional arguments are passed on to clm.control.

Details

This is a new (as of August 2011) improved implementation of CLMMs. The old implementation is available in clmm2. Some features are not yet available in clmm; for instance scale effects, nominal effects and flexible link functions are currently only available in clmm2. clmm is expected to take over clmm2 at some point.

There are standard print, summary and anova methods implemented for "clmm" objects.

Value

a list containing

alpha

threshold parameters.

beta

fixed effect regression parameters.

stDev

standard deviation of the random effect terms.

tau

log(stDev) - the scale at which the log-likelihood function is optimized.

coefficients

the estimated model parameters = c(alpha, beta, tau).

control

List of control parameters as generated by clm.control.

Hessian

Hessian of the model coefficients.

edf

the estimated degrees of freedom used by the model = length(coefficients).

nobs

sum(weights).

n

length(y).

fitted.values

fitted values evaluated with the random effects at their conditional modes.

df.residual

residual degrees of freedom; length(y) - sum(weights)

tJac

Jacobian of the threshold function corresponding to the mapping from standard flexible thresholds to those used in the model.

terms

the terms object for the fixed effects.

contrasts

contrasts applied to the fixed model terms.

na.action

the function used to filter missing data.

call

the matched call.

logLik

value of the log-likelihood function for the model at the optimum.

Niter

number of Newton iterations in the inner loop update of the conditional modes of the random effects.

optRes

list of results from the optimizer.

ranef

list of the conditional modes of the random effects.

condVar

list of the conditional variance of the random effects at their conditional modes.

Author(s)

Rune Haubo B Christensen

Examples

## Cumulative link model with one random term:	
fmm1 <- clmm(rating ~ temp + contact + (1|judge), data = wine)	
summary(fmm1)	
	
## Not run:  	
## May take a couple of seconds to run this.	

## Cumulative link mixed model with two random terms:
mm1 <- clmm(SURENESS ~ PROD + (1|RESP) + (1|RESP:PROD), data = soup,
            link = "probit", threshold = "equidistant")
mm1
summary(mm1)

## test random effect:
mm2 <- clmm(SURENESS ~ PROD + (1|RESP), data = soup,
            link = "probit", threshold = "equidistant")
anova(mm1, mm2)

## End(Not run)