mer-class                package:lme4                R Documentation

_M_i_x_e_d _M_o_d_e_l _R_e_p_r_e_s_e_n_t_a_t_i_o_n_s _a_n_d *_m_e_r _M_e_t_h_o_d_s

_D_e_s_c_r_i_p_t_i_o_n:

     The 'mer' class represents linear or generalized linear or
     nonlinear mixed-effects models.  It incorporates sparse model
     matrices for the random effects and corresponding sparse Cholesky
     factors.  The 'summary.mer' class represents the summary of these
     objects.

_U_s_a_g_e:

     ## Methods with "surprising" arguments
     ## S4 method for signature 'mer':
     deviance(object, REML = NULL, ...)
     ## S4 method for signature 'mer':
     expand(x, sparse = TRUE, ...)
     ## S4 method for signature 'mer':
     logLik(object, REML = NULL, ...)
     ## S4 method for signature 'mer':
     print(x, digits, correlation, symbolic.cor, signif.stars, ...)

_A_r_g_u_m_e_n_t_s:

  object: object of class 'mer'.

    REML: logical indicating if REML should be used. A value of 'NULL',
          the default, or 'NA' indicates that the REML values should be
          returned if the model was fit by REML, otherwise the ML
          values.

       x: object of class 'mer' to expand.

  sparse: logical scalar indicating if the sparse form of the expanded
          'T' and 'S' matrices should be returned.

  digits: number of digits to use when printing tables of parameter
          estimates.  Defaults to 'max(3, getOption("digits") - 3)'.

correlation: logical - should the correlation matrix of the
          fixed-effects parameter estimates be printed?  Defaults to
          'TRUE'.

symbolic.cor: logical - should a symbolic form of the correlation
          matrix be printed instead of the numeric form?  Defaults to
          'FALSE'.

signif.stars: logical - should the 'significance stars' be printed as
          part of the table of fixed-effects parameter estimates? 
          Defaults to 'getOption("show.signif.stars")'.

     ...: potential further arguments passed to methods.

_O_b_j_e_c_t_s _f_r_o_m _t_h_e _C_l_a_s_s:

     Objects can be created by calls of the form 'new("mer", ...)'  or,
     more commonly, via the 'lmer', 'glmer' or 'nlmer' functions.

_S_l_o_t_s:

     The class '"mer"' represents a linear or generalized linear or
     nonlinear or generalized nonlinear mixed model and contains the
     slots:



     '_e_n_v': An environment (class '"environment"') created for the
          evaluation of the nonlinear model function. Not used except
          by 'nlmer' models.

     '_n_l_m_o_d_e_l': The nonlinear model function as an object of class
          '"call"'.  Not used except by 'nlmer' models.

     '_f_r_a_m_e': The model frame (class '"data.frame"').

     '_c_a_l_l': The matched call to the function that created the object.
          (class '"call"').

     '_f_l_i_s_t': The list of grouping factors for the random effects.

     '_X': Model matrix for the fixed effects. In an 'nlmer' fitted
          model this matrix has 'n * s' rows where 'n' is the number of
          observations and 's' is the number of parameters in the
          nonlinear model.

     '_Z_t': The transpose of model matrix for the random effects, stored
          as a compressed column-oriented sparse matrix (class
          '"dgCMatrix"').

     '_p_W_t': Numeric prior weights vector. This may be of length zero
          (0), indicating unit prior weights.

     '_o_f_f_s_e_t': Numeric offset vector. This may be of length zero (0),
          indicating no offset.

     '_y': The response vector (class '"numeric"').

     '_G_p': Integer vector of group pointers within the random effects
          vector.  The elements of 'Gp' are 0-based indices of the
          first element from each random-effects term.  Thus the first
          element is always 0.  The last element is the total length of
          the random effects vector.

     '_d_i_m_s': A named integer vector of dimensions.  Some of the
          dimensions are n, the number of observations, p, the number
          of fixed effects, q, the total number of random effects, s,
          the number of parameters in the nonlinear model function and
          nf, the number of random-effects terms in the model.

     '_S_T': 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.

     '_V': Numeric gradient matrix (class '"matrix"') of the nonlinear
          model function. Not used except by 'nlmer' models.

     '_A': Scaled sparse model matrix (class '"dgCMatrix"') for the the
          unit, orthogonal random effects, U.

     '_C_m': Reduced, weighted sparse model matrix (class '"dgCMatrix"')
          for the unit, orthogonal random effects, U.  Not used except
          by 'nlmer' models.

     '_C_x': The '"x"' slot in the weighted sparse model matrix (class
          '"dgCMatrix"') for the unit, orthogonal random effects, U, in
          generalized linear mixed models.  For these models the
          matrices A and C have the same sparsity pattern and only the
          '"x"' slot of C needs to be stored.

     '_L': The sparse lower Cholesky factor of P(AA'+I)P' (class
          '"dCHMfactor"') where P is the fill-reducing permutation
          calculated from the pattern of nonzeros in A.

     '_d_e_v_i_a_n_c_e': Named numeric vector containing the deviance
          corresponding to the maximum likelihood (the '"ML"' element)
          and '"REML"' criteria and various components. The '"ldL2"'
          element is twice the logarithm of the determinant of the
          Cholesky factor in the 'L' slot. The '"usqr"' component is
          the value of the random-effects quadratic form.

     '_f_i_x_e_f': Numeric vector of fixed effects.

     '_r_a_n_e_f': Numeric vector of random effects on the original scale.

     '_u': Numeric vector of orthogonal, constant variance, random
          effects.

     '_e_t_a': The linear predictor at the current values of the
          parameters and the random effects.

     '_m_u': The means of the responses at the current parameter values.

     '_m_u_E_t_a': The diagonal of the Jacobian of mu by eta.  Has length
          zero (0) except for generalized mixed models.

     '_v_a_r': The diagonal of the conditional variance of Y given the
          random effects, up to prior weights.  In generalized mixed
          models this is the value of the variance function for the
          'glm' family.

     '_r_e_s_i_d': The residuals, y-mu, weighted by the 'sqrtrWt' slot (when
          its length is >0).

     '_s_q_r_t_X_W_t': The square root of the weights applied to the model
          matrices X and Z. This may be of length zero (0), indicating
          unit weights.

     '_s_q_r_t_r_W_t': The square root of the weights applied to the residuals
          to obtain the weighted residual sum of squares. This may be
          of length zero (0), indicating unit weights.

     '_R_Z_X': The dense solution (class '"matrix"') to L RZX = ST'Z'X =
          AX.

     '_R_X': The upper Cholesky factor (class '"matrix"') of the
          downdated X'X.


     The '"summary.mer"' class _contains_ the '"mer"', class and has
     additional slots,


     '_m_e_t_h_T_i_t_l_e': character string specifying a method title

     '_l_o_g_L_i_k': the same as 'logLik(object)'.

     '_n_g_r_p_s': the number of levels per grouping factor in the 'flist'
          slot.

     '_s_i_g_m_a': the scale factor for the variance-covariance estimates

     '_c_o_e_f_s': the matrix of estimates, standard errors, etc. for the
          fixed-effects coefficients

     '_v_c_o_v': the same as 'vcov(object)'.

     '_R_E_m_a_t': the formatted Random-Effects matrix

     '_A_I_C_t_a_b': A named vector of values of AIC, BIC, log-likelihood and
          deviance

_M_e_t_h_o_d_s:


     _V_a_r_C_o_r_r 'signature(x = "mer")': Extract variance and correlation
          components.  See 'VarCorr'

     _a_n_o_v_a 'signature(object = "mer")': returns the sequential
          decomposition of the contributions of fixed-effects terms or,
          for multiple arguments, model comparison statistics. See
          'anova'.

     _c_o_e_f 'signature(object = "mer")': returns an object similar to the
          'ranef' method but incorporating the fixed-effects
          parameters, thereby forming a table of linear model
          coefficients (the columns) by level of the grouping factor
          (the rows).

     _c_o_e_r_c_e 'signature(from = "mer", to = "dtCMatrix")': returns the
          'L' slot as a '"dtCMatrix"' (column-oriented, sparse,
          triangular matrix) object.

     _d_e_v_i_a_n_c_e 'signature(object = "mer")': returns the 'deviance' of
          the fitted model, or the "REML deviance" (i.e. negative twice
          the REML criterion), according to the REML argument.  See the
          arguments section above for a description of the REML
          argument.

     _e_x_p_a_n_d 'signature(object = "mer")':

          returns a list of terms in the expansion of the 'ST' slot. If
          'sparse' is 'TRUE', the default, the elements of the list are
          the numeric scalar '"sigma"', the REML or ML estimate of the
          standard deviation in the model, and three sparse matrices:
          '"P"', the permutation matrix, '"S"', the diagonal scale
          matrix and '"T"', the lower triangular matrix determining
          correlations.  When 'sparse' is 'FALSE' each element of the
          list is the expansions of the corresponding element of the
          'ST' slot into a list of 'S', the diagonal matrix, and 'T',
          the (dense) unit lower triangular matrix.


     _f_i_t_t_e_d 'signature(object = "mer")':

          returns the fitted conditional means of the responses. See
          'fitted'.  The 'napredict' function is called to align the
          result with the original data if the model was fit with
          'na.action = na.exclude'.


     _f_i_x_e_f 'signature(object = "mer")':

          returns the estimates of the fixed-effects parameters.  See
          'fixef'.


     _f_o_r_m_u_l_a 'signature(x = "mer")':

          returns the model formula.  See 'formula'.


     _l_o_g_L_i_k 'signature(object = "mer")':

          returns the log-likelihood or the REML criterion, according
          to the optional 'REML' argument (see the arguments section
          above), of the fitted model.  See also 'logLik'.


     _m_c_m_c_s_a_m_p 'signature(object = "mer")':

          Create a Markov chain Monte Carlo sample from a posterior
          distribution of the model's parameters.  See 'mcmcsamp' for
          details.


     _m_o_d_e_l._f_r_a_m_e 'signature(formula = "mer")': returns the model frame
          (the 'frame' slot).

     _m_o_d_e_l._m_a_t_r_i_x 'signature(object = "mer")': returns the model matrix
          for the fixed-effects parameters (the 'X' slot). 

     _p_r_i_n_t 'signature(x = "mer")': print information about the fitted
          model.  See the arguments section above for a description of
          optional arguments.

     _r_a_n_e_f 'signature(object = "mer")': returns the conditional modes
          of the random effects.  See 'ranef'.

     _r_e_f_i_t 'signature(object = "mer", newresp = "numeric")': Update the
          response vector only and refit the model. See 'refit'.

     _r_e_s_i_d 'signature(object = "mer")': returns the (raw) residuals. 
          This method calls 'napredict'.  See the above description of
          the 'fitted' method for details.  See also 'resid'.

     _r_e_s_i_d_u_a_l_s 'signature(object = "mer")': Another name for the
          'resid' method.

     _s_h_o_w 'signature(object = "mer")': Same as the 'print' method
          without the optional arguments.

     _s_i_m_u_l_a_t_e 'signature(object = "mer")': simulate 'nsim' (defaults to
          1) responses from the theoretical distribution corresponding
          to the fitted model.  The 'refit' method is particularly
          useful in combination with this method. See also 'simulate'.

     _t_e_r_m_s 'signature(x = "mer")': Extract the  'terms' object for the
          fixed-effects terms in the model formula.

     _u_p_d_a_t_e 'signature(object = "mer")': see 'update' on how to update
          fitted models.

     _v_c_o_v 'signature(object = "mer")': Calculate variance-covariance
          matrix of the _fixed_ effect terms, see also 'vcov'.

     _w_i_t_h 'signature(data = "mer")': Evaluate an R expression in an
          environment constructed from the 'frame' slot.

_S_e_e _A_l_s_o:

     'lmer()', 'glmer()' and 'nlmer()', which produce these objects. 
      'VarCorr' for extracting the variance and correlation components
     of the _random_-effects terms.

_E_x_a_m_p_l_e_s:

     (fm2 <- lmer(Reaction ~ Days + (1|Subject) + (0+Days|Subject),
                  data = sleepstudy))
     print(fm2, digits = 10, corr = FALSE) # more precision; no corr.matrix

     logLik(fm2)
     (V2 <- vcov(fm2))
     terms(fm2)
     str(model.matrix(fm2))
     str(model.frame(fm2))
     str(resid(fm2))

     VarCorr(fm2)
     ee <- expand(fm2)
     op <- options(digits = 3)
     tcrossprod(ee$sigma * ee$P %*% ee$T %*% ee$S)
     options(op)

     ## Not run: 
     ## Simulate 'Reaction' according to the fitted model:
     dim(ss <- simulate(fm2, nsim = 200, seed = 101)) ## -> 180 x 200
     ## End(Not run)

