mixed.sdf {EdSurvey}

EdSurvey Mixed-Effects Model

Description

Fits a linear weighted mixed-effects model.

Usage

mixed.sdf(
  formula,
  data,
  weightVars = NULL,
  weightTransformation = TRUE,
  recode = NULL,
  defaultConditions = TRUE,
  tolerance = 0.01,
  nQuad = NULL,
  verbose = 0,
  family = NULL,
  centerGroup = NULL,
  centerGrand = NULL,
  fast = FALSE,
  ...
)

Arguments

formula

a formula for the multilevel regression or mixed model. See Examples and the vignette titled Methods Used for Estimating Mixed-Effects Models in EdSurvey for more details on how to specify a mixed model. If y is left blank, the default subject scale or subscale variable will be used. (You can find the default using showPlausibleValues.) If y is a variable for a subject scale or subscale (one of the names shown by showPlausibleValues), then that subject scale or subscale is used.

data

an edsurvey.data.frame or a light.edsurvey.data.frame

weightVars

character vector indicating weight variables for corresponding levels to use. The weightVar must be the weights for the edsurvey.data.frame. The weight variables must be in the order of level (from lowest to highest level).

weightTransformation

a logical value to indicate whether the function should standardize weights before using it in the multilevel model. If set to TRUE, the function will look up standard weight transformation methods often used for a specific survey. Weight transformation can be found in the vignette titled Methods Used for Estimating Mixed-Effects Models in EdSurvey. If set to FALSE or if the survey of the specified data does not have a standard weight transformation method, raw weights will be used.

recode

a list of lists to recode variables. Defaults to NULL. Can be set as recode=list(var1 = list(from= c("a", "b", "c"), to= "d")). See Examples in lm.sdf.

defaultConditions

a logical value. When set to the default value of TRUE, uses the default conditions stored in an edsurvey.data.frame to subset the data. Use print on an edsurvey.data.frame to see the default conditions.

tolerance

depreciated, no effect

nQuad

depreciated, no effect

verbose

an integer; when set to 1, it will print out the brief progress of the function mix.sdf. Users can use these traced messages for further diagnosis. When set to 2, it will print out the detailed progress, including temporary estimates during the optimization. Defaults to 0, which will run the function without output.

family

this argument is depreciated; please use the WeMix package's mix function directly for binomial models.

centerGroup

a list in which the name of each element is the name of the aggregation level, and the element is a formula of variable names to be group mean centered. For example, to group mean center gender and age within the group student: list("student"= ~gender+age). Defaults to NULL, which means predictors are not adjusted by group centering. See Examples in the WeMix function mix.

centerGrand

a formula of variable names to be grand mean centered. For example, to center the variable education by overall mean of education: ~education. Defaults to NULL, which means predictors are not adjusted by grand centering.

fast

depreciated, no effect

...

other potential arguments to be used in mix

Details

This function uses the mix call in the WeMix package to fit mixed models. When the outcome does not have plausible values, the variance estimator directly from the mix function is used; these account for covariance at the top level of the model specified by the user.

When the outcome has plausible values, the coefficients are estimated in the same way as in lm.sdf, that is, averaged across the plausible values. In addition, the variance of the coefficients is estimated as the sum of the variance estimate from the mix function and the imputation variance. The formula for the imputation variance is, again, the same as for lm.sdf, with the same estimators as in the vignette titled Statistical Methods Used in EdSurvey. In the section “Estimation of Standard Errors of Weighted Means When Plausible Values Are Present, Using the Jackknife Method” in the formula for V_{imp}, the variance and estimates of the variance components are estimated with the same formulas as the regression coefficients.

Value

A mixedSdfResults object with the following elements:

call

the original call used in mixed.sdf

formula

the formula used to fit the model

coef

a vector of coefficient estimates

se

a vector with the standard error estimates of the coefficients and the standard error of the variance components

vars

estimated variance components of the model

levels

the number of levels in the model

ICC

the intraclass correlation coefficient of the model

npv

the number of plausible values

ngroups

a data.frame that includes the number of observations for each group

n0

the number of observations in the original data

nused

the number of observations used in the analysis

model.frame

the data used in the model

If the formula does not involve plausible values, the function will return the following additional elements:

lnlf

the likelihood function

lnl

the log-likelihood of the model

If the formula involves plausible values, the function will return the following additional elements:

Vimp

the estimated variance from uncertainty in the scores

Vjrr

the estimated variance from sampling

Author(s)

Paul Bailey, Trang Nguyen, and Claire Kelley

References

Rabe-Hesketh, S., & Skrondal, A. (2006). Multilevel modelling of complex survey data. Journal of the Royal Statistical Society: Series A (Statistics in Society), 169(4), 805–827.

See Also

mix and lm.sdf

Examples

## Not run: 
# save TIMSS 2015 data to ~/TIMSS/2015
downloadTIMSS(root="~/", years=2015)
fin <- readTIMSS(path="~/TIMSS/2015", countries="fin", gradeLvl=4)
# uses all plausible values
mix1 <- mixed.sdf(formula=mmat ~ itsex + (1|idschool), data = fin,
                  weightVar=c("totwgt","schwgt"), weightTransformation=FALSE)
summary(mix1)
# uses only one plausible value
mix2 <- mixed.sdf(formula=asmmat01 ~ itsex + (1|idschool), data = fin,
                  weightVar=c("totwgt","schwgt"), weightTransformation=FALSE)
summary(mix2)

## End(Not run)