clmm: Cumulative Link Mixed Models
In ordinal: Regression Models for Ordinal Data

Description Usage Arguments Details Value Author(s) Examples

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

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"), ...)

`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`.

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.

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.

Rune Haubo B Christensen

## 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)