Extract Variance and Correlation Components

This function calculates the estimated variances, standard deviations, and correlations between the random-effects terms in a mixed-effects model, of class merMod (linear, generalized or nonlinear). The within-group error variance and standard deviation are also calculated.

Usage

# S3 method for class 'merMod'
VarCorr(x, sigma=1, ...)

<!-- %% documented because of "surprising arguments": -->
# S3 method for class 'VarCorr.merMod'
as.data.frame(x, row.names = NULL,
    optional = FALSE, order = c("cov.last", "lower.tri"), ...)
# S3 method for class 'VarCorr.merMod'
print(x, digits = max(3, getOption("digits") - 2),
    comp = "Std.Dev.", corr = any(comp == "Std.Dev."),
    formatter = format, ...)

Arguments

x

for VarCorr: a fitted model object, usually an object inheriting from class merMod. For as.data.frame, a VarCorr.merMod object returned from VarCorr.

sigma

an optional numeric value used as a multiplier for the standard deviations.

digits

an optional integer value specifying the number of digits

order

arrange data frame with variances/standard deviations first and covariances/correlations last for each random effects term ("cov.last"), or in the order of the lower triangle of the variance-covariance matrix ("lower.tri")?

row.names, optional

Ignored: necessary for the as.data.frame method.

...

Ignored for the as.data.frame method; passed to other print() methods for the print() method.

comp

a character vector, specifying the components to be printed; simply passed to formatVC().

formatter

a function for formatting the numbers; simply passed to formatVC().

corr

(logical) print correlations (rather than covariances) of random effects?

Value

An object of class VarCorr.merMod. The internal structure of the object is a list of matrices, one for each random effects grouping term. For each grouping term, the standard deviations and correlation matrices for each grouping term are stored as attributes "stddev" and "correlation", respectively, of the variance-covariance matrix, and the residual standard deviation is stored as attribute "sc" (for glmer fits, this attribute stores the scale parameter of the model).

The as.data.frame method produces a combined data frame with one row for each variance or covariance parameter (and a row for the residual error term where applicable) and the following columns:

grp

grouping factor

var1

first variable

var2

second variable (NA for variance parameters)

vcov

variances or covariances

sdcor

standard deviations or correlations

Details

The print method for VarCorr.merMod objects has optional arguments digits (specify digits of precision for printing) and comp: the latter is a character vector with any combination of "Variance" and "Std.Dev.", to specify whether variances, standard deviations, or both should be printed.

Author

This is modeled after VarCorr from package nlme, by Jose Pinheiro and Douglas Bates.

See also

lmer, nlmer

Examples

data(Orthodont, package="nlme")
fm1 <- lmer(distance ~ age + (age|Subject), data = Orthodont)
print(vc <- VarCorr(fm1))  ## default print method: standard dev and corr
#>  Groups   Name        Std.Dev. Corr  
#>  Subject  (Intercept) 2.32736        
#>           age         0.22645  -0.609
#>  Residual             1.31002        
## both variance and std.dev.
print(vc,comp=c("Variance","Std.Dev."), digits=2)
#>  Groups   Name        Variance Std.Dev. Corr 
#>  Subject  (Intercept) 5.417    2.33          
#>           age         0.051    0.23     -0.61
#>  Residual             1.716    1.31          
## variance only
print(vc, comp=c("Variance"))
#>  Groups   Name        Variance Cov   
#>  Subject  (Intercept) 5.416600       
#>           age         0.051279 -0.321
#>  Residual             1.716157       
## standard deviations only, but covariances rather than correlations
print(vc, corr = FALSE)
#>  Groups   Name        Std.Dev. Cov   
#>  Subject  (Intercept) 2.32736        
#>           age         0.22645  -0.321
#>  Residual             1.31002        
as.data.frame(vc)
#>        grp        var1 var2       vcov      sdcor
#> 1  Subject (Intercept) <NA>  5.4166005  2.3273591
#> 2  Subject         age <NA>  0.0512792  0.2264491
#> 3  Subject (Intercept)  age -0.3211854 -0.6094270
#> 4 Residual        <NA> <NA>  1.7161573  1.3100219
as.data.frame(vc, order="lower.tri")
#>        grp        var1 var2       vcov      sdcor
#> 1  Subject (Intercept) <NA>  5.4166005  2.3273591
#> 2  Subject (Intercept)  age -0.3211854 -0.6094270
#> 3  Subject         age <NA>  0.0512792  0.2264491
#> 4 Residual        <NA> <NA>  1.7161573  1.3100219