olmm: Fitting ordinal and nominal two-stage linear mixed models
In vcrpart: Tree-Based Varying Coefficient Regression for Generalized Linear and Ordinal Mixed Models

Description Usage Arguments Details Value Author(s) References See Also Examples

Fits different types of two-stage linear mixed models for longitudinal (or clustered) ordinal (or multinomial) responses. O ne-stage models are also allowed. Random effects are assumed to be multivariate normal distributed with expectation 0. At the time being, cumulative link models with the logit, probit or cauchy link, the baseline-category logit and the adjacent-category logit model are implemented. Coefficients can be category-specific (i.e. non-proportional odds effects) or global (i.e. proportional odds, or parallel effects).

The function solves the score function for coefficients of the marginal likelihood by using Gauss-Hermite quadrature (e.g., Hedeker; 1994). Random effects are predicted by their expectation (see Hartzl et al.; 2001). Standard deviations of parameter estimates are, by default, based on the expected Fisher-information matrix.

cumulative(link = c("logit", "probit", "cauchy"))
adjacent(link = "logit")
baseline(link = "logit")

olmm(formula, data, family = cumulative(), 
     weights, subset, na.action = na.omit,
     offset, contrasts, control = olmm_control(), ...)

`formula`	a symbolic description of the model. This should be something like `y ~ ce(x1) + ge(x2) +re(1 + ge(w2) \| id)` where `ce(x1)` specifies that the predictor `x1` has a category-specific i.e. non-proportional odds effect and `ge(x2)` that the predictor `x2` has global i.e. proportional odds fixed effect, see `ge`, resp. `ce`. Random effects are specified within the `re` term, where the variable `id` above behind the vertical bar `\|` defines the subject i.e. cluster factor. Notice that only one subject factor is allowed. See details.
`data`	an optional data frame with the variables in `formula`. By default the variables are taken from the environment from which `olmm` is called.
`family`	an `family.olmm` object produced by `cumulative`, `adjacent` or `baseline`.
`weights`	a numeric vector of weights with length equal the number of observations. The weights should be constant for subjects.
`offset`	a matrix specifying the offset separately for each predictor equation, of which there are the number of categories of the response minus one.
`subset, na.action, contrasts`	further model specification arguments as in `lm`.
`control`	a list of control parameters produced by `olmm_control`.
`link`	character string. The name of the link function.
`...`	arguments to be passed to `control`.

The function can be used to fit simple ordinal two-stage mixed effect models with up to 3-4 random effects. For models with higher dimensions on random effects, the procedure may not convergence (cf. Tutz; 1996). Coefficients for the adjacent-category logit model are extracted via coefficient transformation (e.g. Agresti; 2010).

The three implemented families are defined as follows: cumulative is defined as the link of the sum of probabilities of lower categories, e.g., for link = "logit", the logit of the sum of probabilities of lower categories. adjacent is defined as the logit of the probability of the lower of two adjacent categories. baseline is defined as the logit of the probability of a category with reference to the highest category. Notice that the estimated coefficients of cumulative models may have the opposite sign those obtained with alternative software.

For alternative fitting functions, see for example the functions clmm of ordinal, nplmt of package mixcat, DPolmm of package DPpackage, lcmm of package lcmm, MCMCglmm of package MCMCglmm or OrdinalBoost of package GMMBoost.

The implementation adopts functions of the packages statmod (Novomestky, 2012) and matrixcalc (Smyth et al., 2014), which is not visible for the user. The authors are grateful for these codes.

The formula argument specifies the model to be fitted. Categorical regression models distinguish between global effects (or proportional-odds effects), which are defined with ge terms, and category-specific effects, which are defined by ce terms. For undefined terms, the function will use ge terms. Notice that this default does not necessarily yield interpretable outputs. For example, for the baseline model you may use only ce terms, which must be specified manually manually. See the example below. For cumulative models at present it is not possible to specifiy ce for the random effects component because the internal, unconstraint integration would yield unusable predictor values.

olmm returns an object of class olmm. cumulative, adjacent and baseline yield an object of class family.olmm. The olmm class is a list containing the following components:

`env`	environment in which the object was built.
`frame`	the model frame.
`call`	the matched call to the function that created the object (class `"call"`).
`control`	a list of class `olmm_control` produced by `olmm_control`.
`formula`	the formula of the call.
`terms`	a list of `terms` of the fitted model.
`family`	an object of class `family.olmm` that specifies that family of the fitted model.
`y`	(ordered) categorical response vector.
`X`	model matrix for the fixed effects.
`W`	model matrix for the random effects.
`subject`	a factor vector with grouping levels.
`subjectName`	variable name of the subject vector.
`weights`	numeric observations weights vector.
`weights_sbj`	numeric weights vector of length N.
`offset`	numeric offset matrix
`xlevels`	(only where relevant) a list of levels of the factors used in fitting.
`contrasts`	(only where relevant) a list of contrasts used.
`dims`	a named integer of dimensions. Some of the dimensions are n is the number of observations, p is the number of fixed effects per predictor and q is the total number of random effects.
`fixef`	a matrix of fixed effects (one column for each predictor).
`ranefCholFac`	a lower triangular matrix. The cholesky decomposition of the covariance matrix of the random effects.
`coefficients`	a numeric vector of several fitted model parameters
`restricted`	a logical vector indicating which elements of the `coefficients` slot are restricted to an initial value at the estimation.
`eta`	a matrix of unconditional linear predictors of the fixed effects without random effects.
`u`	a matrix of orthogonal standardized random effects (one row for each subject level).
`logLik_obs`	a numeric vector of log likelihood value (one value for each observation).
`logLik_sbj`	a numeric vector of log likelihood values (one value for each subject level).
`logLik`	a numeric value. The log likelihood of the model.
`score_obs`	a matrix of observation-wise partial derivates of the marginal log-likelihood equation.
`score_sbj`	a matrix of subject-wise partial derivates of the marginal log-likelihood equation.
`score`	a numeric vector of (total) partial derivates of the log-Likelihood function.
`info`	the information matrix (default is the expected information).
`ghx`	a matrix of quadrature points for the Gauss-Hermite quadrature integration.
`ghw`	a matrix of weights for the Gauss-Hermite quadrature integration.
`ranefElMat`	a transformation matrix
`optim`	a list of arguments for calling the optimizer function.
`control`	a list of used control arguments produced by `olmm_control`.
`output`	the output of the optimizer (class `"list"`).

Reto Buergin

Agresti, A. (2010). Analysis of Ordinal Categorical Data (2 ed.). New Jersey, USA: John Wiley & Sons.

Hartzel, J., A. Agresti and B. Caffo (2001). Multinomial Logit Random Effect Models, Statistical Modelling 1(2), 81–102.

Hedeker, D. and R. Gibbons (1994). A Random-Effects Ordinal Regression Model for Multilevel Analysis, Biometrics 20(4), 933–944.

Tutz, G. and W. Hennevogl (1996). Random Effects in Ordinal Regression Models, Computational Statistics & Data Analysis 22(5), 537–557.

Tutz, G. (2012). Regression for Categorical Data. New York, USA: Cambridge Series in Statistical and Probabilistic Mathematics.

Novomestky, F. (2012). matrixcalc: Collection of Functions for Matrix Calculations. R package version 1.0-3. URL https://CRAN.R-project.org/package=matrixcalc

Smyth, G., Y. Hu, P. Dunn, B. Phipson and Y. Chen (2014). statmod: Statistical Modeling. R package version 1.4.20. URL https://CRAN.R-project.org/package=statmod

olmm-methods, olmm_control, ordered

## ------------------------------------------------------------------- #
## Example 1: Schizophrenia
##
## Estimating the cumulative mixed models of
## Agresti (2010) chapters 10.3.1
## ------------------------------------------------------------------- #

data(schizo)

model.10.3.1 <-
  olmm(imps79o ~ tx + sqrt(week) + re(1|id),
       data = schizo, family = cumulative())

summary(model.10.3.1)

## ------------------------------------------------------------------- #
## Example 2: Movie critics
##
## Estimating three of several adjacent-categories
## mixed models of Hartzl et. al. (2001)
## ------------------------------------------------------------------- #

data(movie)

## model with category-specific effects for "review"
model.24.1 <- olmm(critic ~ ce(review) + re(1|movie, intercept = "ce"),
                   data = movie, family = adjacent())

summary(model.24.1)

Loading required package: parallel
Loading required package: partykit
Loading required package: grid
Linear Mixed Model fit by Marginal Maximum
Likelihood with Gauss-Hermite Quadrature 

 Family: cumulative logit 
Formula: imps79o ~ tx + sqrt(week) + re(1 | id) 
   Data: schizo 

Goodness of fit:
      AIC      BIC    logLik
 3477.593 3509.871 -1732.796

Random effects:
Subject: id 
            Variance StdDev  
(Intercept) 3.413559 1.847582
Number of obs: 1603, subjects: 437

Global fixed effects:
           Estimate Std. Error z value
tx         1.535965   0.240239  6.3935
sqrt(week) 1.647445   0.076427 21.5557

Category-specific fixed effects:
                                                                       Estimate
normal or borderline mentally ill|mildly or moderately ill:(Intercept) -6.77189
mildly or moderately ill|markedly ill:(Intercept)                      -3.88942
markedly ill|severely or among the most extremely ill:(Intercept)      -1.85251
                                                                       Std. Error
normal or borderline mentally ill|mildly or moderately ill:(Intercept)    0.30684
mildly or moderately ill|markedly ill:(Intercept)                         0.24432
markedly ill|severely or among the most extremely ill:(Intercept)         0.21157
                                                                        z value
normal or borderline mentally ill|mildly or moderately ill:(Intercept) -22.0698
mildly or moderately ill|markedly ill:(Intercept)                      -15.9195
markedly ill|severely or among the most extremely ill:(Intercept)       -8.7561
Linear Mixed Model fit by Marginal Maximum
Likelihood with Gauss-Hermite Quadrature 

 Family: adjacent logit 
Formula: critic ~ ce(review) + re(1 | movie, intercept = "ce") 
   Data: movie 

Goodness of fit:
      AIC      BIC    logLik
 732.4361 775.5439 -355.2181

Random effects:
Subject: movie 
                      Variance   StdDev     Corr                 
Pro|Mixed:(Intercept)  2.0119465  1.4184310 Pro|Mixed:(Intercept)
Mixed|Con:(Intercept)  2.1191093  1.4557161 -0.3965395           
Number of obs: 372, subjects: 93

Category-specific fixed effects:
                        Estimate Std. Error z value
Pro|Mixed:(Intercept)   0.748421   0.414159  1.8071
Pro|Mixed:reviewSiskel  0.095040   0.472164  0.2013
Pro|Mixed:reviewEbert   0.081048   0.447603  0.1811
Pro|Mixed:reviewLyons   1.001761   0.459292  2.1811
Mixed|Con:(Intercept)  -0.996159   0.414159 -2.4053
Mixed|Con:reviewSiskel  0.965667   0.472164  2.0452
Mixed|Con:reviewEbert   1.806508   0.447603  4.0360
Mixed|Con:reviewLyons   0.194467   0.459292  0.4234