getME {lme4} | R Documentation

## Extract or Get Generalized Components from a Fitted Mixed Effects Model

### Description

Extract (or “get”) “components” – in a generalized sense – from a fitted mixed-effects model, i.e., (in this version of the package) from an object of class `"merMod"`.

### Usage

    getME(object, name, ...)

    ## S3 method for class 'merMod'
    getME(object,
          name = c("X", "Z", "Zt", "Ztlist", "mmList", "y", "mu", "u", "b",
                   "Gp", "Tp", "L", "Lambda", "Lambdat", "Lind", "Tlist",
                   "A", "RX", "RZX", "sigma", "flist",
                   "fixef", "beta", "theta", "ST", "REML", "is_REML",
                   "n_rtrms", "n_rfacs", "N", "n", "p", "q",
                   "p_i", "l_i", "q_i", "k", "m_i", "m",
                   "cnms", "devcomp", "offset", "lower", "devfun", "glmer.nb.theta"),
          ...)

### Arguments

`object` | a fitted mixed-effects model of class `"merMod"`, i.e., typically the result of `lmer()`, `glmer()` or `nlmer()`.

`name`

a character vector specifying the name(s) of the “component”. If `length(name) > 1` or if `name = "ALL"`, a named `list` of components will be returned. Possible values are:

`"X"`:

  fixed-effects model matrix

`"Z"`:

  random-effects model matrix

`"Zt"`:

  transpose of random-effects model matrix. Note that the structure of `Zt` has changed since `lme4.0`; to get a backward-compatible structure, use `do.call(Matrix::rBind,getME(.,"Ztlist"))`

`"Ztlist"`:

  list of components of the transpose of the random-effects model matrix, separated by individual variance component

`"mmList"`:

  list of raw model matrices associated with random effects terms

`"y"`:

  response vector

`"mu"`:

  conditional mean of the response

`"u"`:

  conditional mode of the “spherical” random effects variable

`"b"`:

  conditional mode of the random effects variable

`"Gp"`:

  groups pointer vector. A pointer to the beginning of each group of random effects corresponding to the random-effects terms, beginning with 0 and including a final element giving the total number of random effects

`"Tp"`:

  theta pointer vector. A pointer to the beginning of the theta sub-vectors corresponding to the random-effects terms, beginning with 0 and including a final element giving the number of thetas.

`"L"`:

  sparse Cholesky factor of the penalized random-effects model.

`"Lambda"`:

  relative covariance factor Lambda of the random effects.

`"Lambdat"`:

  transpose Lambda' of Lambda above.

`"Lind"`:

  index vector for inserting elements of theta into the nonzeros of Lambda.

`"Tlist"`:

  vector of template matrices from which the blocks of Lambda are generated.

`"A"`:

  Scaled sparse model matrix (class `"dgCMatrix"`) for the unit, orthogonal random effects, U, equal to `getME(.,"Zt") %*% getME(.,"Lambdat")`

`"RX"`:

  Cholesky factor for the fixed-effects parameters

`"RZX"`:

  cross-term in the full Cholesky factor

`"sigma"`:

  residual standard error; note that `sigma(object)` is preferred.

`"flist"`:

  a list of the grouping variables (factors) involved in the random effect terms

`"fixef"`:

  fixed-effects parameter estimates

`"beta"`:

  fixed-effects parameter estimates (identical to the result of `fixef`, but without names)

`"theta"`:

  random-effects parameter estimates: these are parameterized as the relative Cholesky factors of each random effect term

`"ST"`:

  A list of S and T factors in the TSST' Cholesky factorization of the relative variance matrices of the random effects associated with each random-effects term. The unit lower triangular matrix, T, and the diagonal matrix, S, for each term are stored as a single matrix with diagonal elements from S and off-diagonal elements from T.

`"n_rtrms"`:

  number of random-effects terms

`"n_rfacs"`:

  number of distinct random-effects grouping factors

`"N"`:

  number of rows of `X`

`"n"`:

  length of the response vector, `y`

`"p"`:

  number of columns of the fixed effects model matrix, `X`

`"q"`:

  number of columns of the random effects model matrix, `Z`

`"p_i"`:

  numbers of columns of the raw model matrices, `mmList`

`"l_i"`:

  numbers of levels of the grouping factors

`"q_i"`:

  numbers of columns of the term-wise model matrices, `ZtList`

`"k"`:

  number of random effects terms

`"m_i"`:

  numbers of covariance parameters in each term

`"m"`:

  total number of covariance parameters

`"cnms"`:

  the “component names”, a `list`.

`"REML"`:

  `0` indicates the model was fitted by maximum likelihood, any other positive integer indicates fitting by restricted maximum likelihood

`"is_REML"`:

  same as the result of `isREML(.)`

`"devcomp"`:

  a list consisting of a named numeric vector, `cmp`, and a named integer vector, `dims`, describing the fitted model. The elements of `cmp` are:

  ldL2

    twice the log determinant of `L`

  ldRX2

    twice the log determinant of `RX`

  wrss

    weighted residual sum of squares

  ussq

    squared length of `u`

  pwrss

    penalized weighted residual sum of squares, “wrss + ussq”

  drsum

    sum of residual deviance (GLMMs only)

  REML

    REML criterion at optimum (LMMs fit by REML only)

  dev

    deviance criterion at optimum (models fit by ML only)

  sigmaML

    ML estimate of residual standard deviation

  sigmaREML

    REML estimate of residual standard deviation

  tolPwrss

    tolerance for declaring convergence in the penalized iteratively weighted residual sum-of-squares (GLMMs only)

  The elements of `dims` are:

  N

    number of rows of `X`

  n

    length of `y`

  p

    number of columns of `X`

  nmp

    `n-p`

  nth

    length of `theta`

  q

    number of columns of `Z`

  nAGQ

    see `glmer`

  compDev

    see `glmerControl`

  useSc

    `TRUE` if model has a scale parameter

  reTrms

    number of random effects terms

  REML

    `0` indicates the model was fitted by maximum likelihood, any other positive integer indicates fitting by restricted maximum likelihood

  GLMM

    `TRUE` if a GLMM

  NLMM

    `TRUE` if an NLMM

`"offset"`:

  model offset

`"lower"`:

  lower bounds on model parameters (random effects parameters only).

`"devfun"`:

  deviance function (so far only available for LMMs)

`"glmer.nb.theta"`:

  negative binomial θ parameter, only for `glmer.nb`.

`"ALL"`:

  get all of the above as a `list`.

`...` | currently unused in lme4, potentially further arguments in methods.

### Details

The goal is to provide “everything a user may want” from a fitted `"merMod"` object as far as it is not available by methods, such as `fixef`, `ranef`, `vcov`, etc.

### Value

Unspecified, as very much depending on the `name`.

### See Also

`getCall()`. More standard methods for `"merMod"` objects, such as `ranef`, `fixef`, `vcov`, etc.: see `methods(class="merMod")`

### Examples

    ## shows many methods you should consider *before* using getME():
    methods(class = "merMod")

    (fm1 <- lmer(Reaction ~ Days + (Days|Subject), sleepstudy))
    Z <- getME(fm1, "Z")
    stopifnot(is(Z, "CsparseMatrix"),
              c(180,36) == dim(Z),
    	  all.equal(fixef(fm1), b1 <- getME(fm1, "beta"),
    		    check.attributes=FALSE, tolerance = 0))

    ## A way to get *all* getME()s :
    ## internal consistency check ensuring that all work:
    parts <- getME(fm1, "ALL")
    str(parts, max=2)
    stopifnot(identical(Z,  parts $ Z),
              identical(b1, parts $ beta))

[Package lme4 version 1.1-21 Index]