misty (version 0.5.0)

multilevel.descript: Multilevel Descriptive Statistics

Description

This function computes descriptive statistics for multilevel data, e.g. average cluster size, variance components, intraclass correlation coefficient, design effect, and effective sample size.

Usage

multilevel.descript(x, cluster, print = c("all", "var", "sd"),
                    method = c("aov", "lme4", "nlme"), REML = TRUE,
                    digits = 2, icc.digits = 3, as.na = NULL, write = NULL,
                    check = TRUE, output = TRUE)

Value

Returns an object of class misty.object, which is a list with following entries:

call

function call

type

type of analysis

data

data frame specified in x including the group variable specified in cluster

args

specification of function arguments

model.fit

fitted lavaan object (mod.fit)

result

list with result tables, i.e., no.obs for the number of observations no.no.miss for the number of missing value, no.cluster for the number of clusters, m.cluster.size for the average cluster size, sd.cluster.size for the standard deviation of the cluster size, min.cluster.size for the minimum cluster size, max.cluster.size for the maximum cluster size, mean.x for the mean values, var.w for the variance within clusters, var.b for the variance between clusters, icc1 for ICC(1), icc2 for ICC(2), deff for the design effect, deff.sqrt for the square root of the design effect, n.effect for the effective sample size

Arguments

x

a vector, matrix or data frame.

cluster

a vector representing the nested grouping structure (i.e., group or cluster variable).

print

a character string or character vector indicating which results to show on the console, i.e. "all" for variances and standard deviations, "var" (default) for variances, or "sd" for standard deviations within and between clusters.

method

a character string indicating the method used to estimate intraclass correlation coefficients, i.e., "aov" ICC estimated using the aov function, "lme4" (default) ICC estimated using the lmer function in the lme4 package, "nlme" ICC estimated using the lme function in the nlme package.

REML

logical: if TRUE (default), restricted maximum likelihood is used to estimate the null model when using the lmer() function in the lme4 package or the lme() function in the nlme package.

digits

an integer value indicating the number of decimal places to be used.

icc.digits

an integer indicating the number of decimal places to be used for displaying intraclass correlation coefficients.

as.na

a numeric vector indicating user-defined missing values, i.e. these values are converted to NA before conducting the analysis. Note that as.na() function is only applied to x but not to cluster.

write

a character string for writing the results into a Excel file naming a file with or without file extension '.xlsx', e.g., "Results.xlsx" or "Results".

check

logical: if TRUE, argument specification is checked.

output

logical: if TRUE, output is shown on the console.

Author

Takuya Yanagida

Details

Note that this function is restricted to two-level models.

References

Hox, J., Moerbeek, M., & van de Schoot, R. (2018). Multilevel analysis: Techniques and applications (3rd. ed.). Routledge.

Snijders, T. A. B., & Bosker, R. J. (2012). Multilevel analysis: An introduction to basic and advanced multilevel modeling (2nd ed.). Sage Publishers.

See Also

write.result, multilevel.icc, descript

Examples

if (FALSE) {
# Load data set "Demo.twolevel" in the lavaan package
data("Demo.twolevel", package = "lavaan")

#---------------------------
# Cluster variable specification

# Cluster variable 'cluster' in 'x'
multilevel.descript(Demo.twolevel[, c("y1", "cluster")], cluster = "cluster")

# Cluster variable 'cluster' not in 'x'
multilevel.descript(Demo.twolevel$y1, cluster = Demo.twolevel$cluster)

#---------------------------

# Multilevel descriptive statistics for y1
multilevel.descript(Demo.twolevel$y1, cluster = Demo.twolevel$cluster)

# Multilevel descriptive statistics for y1, print variance and standard deviation
multilevel.descript(Demo.twolevel$y1, cluster = Demo.twolevel$cluster, print = "all")

# Multilevel descriptive statistics for y1, print ICC with 5 digits
multilevel.descript(Demo.twolevel$y1, cluster = Demo.twolevel$cluster, icc.digits = 5)

# Multilevel descriptive statistics for y1
# use lme() function in the nlme package to estimate ICC
multilevel.descript(Demo.twolevel$y1, cluster = Demo.twolevel$cluster, method = "nlme")

# Multilevel descriptive statistics for y1, y2, y3, w1, and w2
multilevel.descript(Demo.twolevel[, c("y1", "y2", "y3", "w1", "w2")],
                    cluster = Demo.twolevel$cluster)

# Write Results into a Excel file
multilevel.descript(Demo.twolevel[, c("y1", "y2", "y3", "w1", "w2")],
                    cluster = Demo.twolevel$cluster, write = "Multilevel_Descript.xlsx")

result <- multilevel.descript(Demo.twolevel[, c("y1", "y2", "y3", "w1", "w2")],
                              cluster = Demo.twolevel$cluster, output = FALSE)
write.result(result, "Multilevel_Descript.xlsx")
}