jomoImpute | R Documentation |

`jomo`

Performs single- and multilevel imputation for (mixed) continuous and categorical data using the `jomo`

package
Supports imputation of missing data at level 1 and 2 as well as imputation using random (residual) covariance matrices.
See 'Details' for further information.

```
jomoImpute(data, type, formula, random.L1 = c("none", "mean", "full"),
n.burn = 5000, n.iter = 100, m = 10, group = NULL, prior = NULL,
seed = NULL, save.pred = FALSE, keep.chains = c("full", "diagonal"),
silent = FALSE)
```

`data` |
A data frame containing the incomplete data, the auxiliary variables, the cluster indicator variable, and any other variables that should be included in the imputed datasets. |

`type` |
An integer vector specifying the role of each variable in the imputation model or a list of two vectors specifying a two-level model (see 'Details'). |

`formula` |
A formula specifying the role of each variable in the imputation model or a list of two formulas specifying a two-level model. The basic model is constructed by |

`random.L1` |
A character string denoting if the covariance matrix of residuals should vary across groups and how the values of these matrices are stored (see 'Details'). Can be |

`n.burn` |
The number of burn-in iterations before any imputations are drawn. Default is 5,000. |

`n.iter` |
The number of iterations between imputations. Default is 100. |

`m` |
The number of imputed data sets to generate. Default is 10. |

`group` |
(optional) A character string denoting the name of an additional grouping variable to be used with the |

`prior` |
(optional) A list with components |

`seed` |
(optional) An integer value initializing R's random number generator for reproducible results. Default is to use the global seed. |

`save.pred` |
(optional) Logical flag indicating if variables derived using |

`keep.chains` |
(optional) A character string denoting which chains of the MCMC algorithm to store. Can be |

`silent` |
(optional) Logical flag indicating if console output should be suppressed. Default is |

This function serves as an interface to the `jomo`

package and supports imputation of single-level and multilevel continuous and categorical data at both level 1 and 2 (see Carpenter & Kenward, 2013; Goldstein et al., 2009).
In order for categorical variables to be detected correctly, these must be formatted as a `factor`

variables (see 'Examples').
The imputation model can be specified using either the `type`

or the `formula`

argument.

The `type`

interface is designed to provide quick-and-easy imputations using `jomo`

. The `type`

argument must be an integer vector denoting the role of each variable in the imputation model:

`1`

: target variables containing missing data`2`

: predictors with fixed effect on all targets (completely observed)`3`

: predictors with random effect on all targets (completely observed)`-1`

: grouping variable within which the imputation is run separately`-2`

: cluster indicator variable`0`

: variables not featured in the model

At least one target variable and, for multilevel imputation, the cluster indicator must be specified.
If the cluster indicator is omitted, single-level imputation will be performed.
The intercept is automatically included as both a fixed and (for multilevel models) a random effect.
If a variable of type `-1`

is found, then separate imputations are performed within each level of that variable.

The `formula`

argument is intended as a more flexible and feature-rich interface to `jomo`

.
Specifying the `formula`

argument is similar to specifying other formulae in R.
Given below is a list of operators that `jomoImpute`

currently understands:

`~`

: separates the target (left-hand) and predictor (right-hand) side of the model`+`

: adds target or predictor variables to the model`*`

: adds an interaction term of two or more predictors`|`

: denotes cluster-specific random effects and specifies the cluster indicator (e.g.,`1|ID`

)`I()`

: defines functions to be interpreted by`model.matrix`

If the cluster indicator is omitted, single-level imputation will be performed.
For multilevel imputation, predictors are allowed to have fixed effects, random effects, or both on all target variables.
The intercept is automatically included as both a fixed and (for multilevel models) a random effect.
Both can be suppressed if needed (see `panImpute`

).
Note that, when specifying random effects other than the intercept, these will *not* be automatically added as fixed effects and must be included explicitly.
Any predictors defined by `I()`

will be used for imputation but not included in the data set unless `save.pred = TRUE`

.

If missing data occur at both level 1 and 2, the imputation model is specified as a list of two `formula`

s or `type`

s, respectively.
The first element of this list denotes the model specification for variables at level 1.
The second element denotes the model specification for variables at level 2.
Missing data are imputed jointly at both levels (see 'Examples', see also Carpenter and Kenward, 2013; Goldstein et al., 2009).

It is possible to model the covariance matrix of residuals at level 1 as random across clusters (Yucel, 2011; Carpenter & Kenward, 2013).
The `random.L1`

argument determines this behavior and how the values of these matrices are stored.
If set to `"none"`

, a common covariance matrix is assumed across groups (similar to `panImpute`

).
If set to `"mean"`

, the covariance matrices are random, but only the average covariance matrix is stored at each iteration.
If set to `"full"`

, the covariance matrices are random, and all variances and covariances from all clusters are stored.

In order to run separate imputations for each level of an additional grouping variable, the `group`

argument can be used.
The name of the grouping variable must be given as a character string (i.e., in quotation marks).

The default prior distribution for the covariance matrices in `jomoImpute`

are "least informative" inverse-Wishart priors with minimum positive degrees of freedom (largest dispersion) and the identity matrix for scale.
The `prior`

argument can be used to specify alternative prior distributions.
These must be supplied as a list containing the following components:

`Binv`

: scale matrix for the covariance matrix of residuals at level 1`Dinv`

: scale matrix for the covariance matrix of random effects and residuals at level 2`a`

: starting value for the degrees of freedom of random covariance matrices of residuals (only used with`random.L1 = "mean"`

or`random.L1 = "full"`

)

Note that `jomo`

does not allow for the degrees of freedom for the inverse-Wishart prior to be specified by the user.
These are always set to the lowest value possible (largest dispersion) or determined iteratively if the residuals at level 1 are modeled as random (see above).
For single-level imputation, only `Binv`

is relevant.

In imputation models with many parameters, the number of chains in the MCMC algorithm being stored can be reduced with the `keep.chains`

argument (see also `panImpute`

).
This setting influences the storage mode of parameters (e.g., dimensions and indices of arrays) and should be used with caution.

An object of class `mitml`

, containing the following components:

`data` |
The original (incomplete) data set, sorted according to the cluster variable and (if given) the grouping variable, with several attributes describing the original order ( |

`replacement.mat` |
A matrix containing the multiple replacements (i.e., imputations) for each missing value. The replacement matrix contains one row for each missing value and one one column for each imputed data set. |

`index.mat` |
A matrix containing the row and column index for each missing value. The index matrix is used to |

`call` |
The matched function call. |

`model` |
A list containing the names of the cluster variable, the target variables, and the predictor variables with fixed and random effects, at level 1 and level 2, respectively. |

`random.L1` |
A character string denoting the handling of the (random) covariance matrix of residuals at level 1 (see 'Details'). |

`prior` |
The prior parameters used in the imputation model. |

`iter` |
A list containing the number of burn-in iterations, the number of iterations between imputations, and the number of imputed data sets. |

`par.burnin` |
A multi-dimensional array containing the parameters of the imputation model from the burn-in phase. |

`par.imputation` |
A multi-dimensional array containing the parameters of the imputation model from the imputation phase. |

For objects of class `mitml`

, methods for the generic functions `print`

, `summary`

, and `plot`

are available to inspect the fitted imputation model.
`mitmlComplete`

is used for extracting the imputed data sets.

Simon Grund, Alexander Robitzsch, Oliver Luedtke

Carpenter, J. R., & Kenward, M. G. (2013). *Multiple imputation and its application*. Hoboken, NJ: Wiley.

Goldstein, H., Carpenter, J., Kenward, M. G., & Levin, K. A. (2009). Multilevel models with multivariate mixed response types. *Statistical Modelling*, 9, 173-197.

Yucel, R. M. (2011). Random covariances and mixed-effects models for imputing multivariate multilevel continuous data. *Statistical Modelling*, 11, 351-370.

`panImpute`

, `mitmlComplete`

, `summary.mitml`

, `plot.mitml`

```
# NOTE: The number of iterations in these examples is much lower than it
# should be. This is done in order to comply with CRAN policies, and more
# iterations are recommended for applications in practice!
data(studentratings)
data(leadership)
# ***
# for further examples, see "panImpute"
#
?panImpute
# *** ................................
# the 'type' interface
#
# * Example 1.1 (studentratings): 'ReadDis' and 'SES', predicted by 'ReadAchiev'
# (random slope)
type <- c(-2, 0, 0, 0, 0, 1, 3, 1, 0, 0)
names(type) <- colnames(studentratings)
type
imp <- jomoImpute(studentratings, type = type, n.burn = 100, n.iter = 10, m = 5)
# * Example 1.2 (leadership): all variables (mixed continuous and categorical
# data with missing values at level 1 and level 2)
type.L1 <- c(-2, 1, 0, 1, 1) # imputation model at level 1
type.L2 <- c(-2, 0, 1, 0, 0) # imputation model at level 2
names(type.L1) <- names(type.L2) <- colnames(leadership)
type <- list(type.L1, type.L2)
type
imp <- jomoImpute(leadership, type = type, n.burn = 100, n.iter = 10, m = 5)
# * Example 1.3 (studentratings): 'ReadDis', 'ReadAchiev', and 'SES' predicted
# with empty model, groupwise for 'FedState' (single-level imputation)
type <- c(0, -1, 0, 0, 0, 1, 1, 1, 0, 0)
names(type) <- colnames(studentratings)
type
imp <- jomoImpute(studentratings, type = type, group = "FedState", n.burn = 100,
n.iter = 10, m = 5)
# *** ................................
# the 'formula' interface
#
# * Example 2.1 (studentratings): 'ReadDis' and 'SES' predicted by 'ReadAchiev'
# (random slope)
fml <- ReadDis + SES ~ ReadAchiev + (1|ID)
imp <- jomoImpute(studentratings, formula = fml, n.burn = 100, n.iter = 10, m = 5)
# * Example 2.2 (studentratings): 'ReadDis' predicted by 'ReadAchiev' and the
# the cluster mean of 'ReadAchiev'
fml <- ReadDis ~ ReadAchiev + I(clusterMeans(ReadAchiev, ID)) + (1|ID)
imp <- jomoImpute(studentratings, formula = fml, n.burn = 100, n.iter = 10, m = 5)
# * Example 2.3 (studentratings): 'ReadDis' predicted by 'ReadAchiev', groupwise
# for 'FedState'
fml <- ReadDis ~ ReadAchiev + (1|ID)
imp <- jomoImpute(studentratings, formula = fml, group = "FedState", n.burn = 100,
n.iter = 10, m = 5)
# * Example 2.4 (leadership): all variables (mixed continuous and categorical
# data with missing values at level 1 and level 2)
fml <- list( JOBSAT + NEGLEAD + WLOAD ~ 1 + (1|GRPID) , COHES ~ 1 )
imp <- jomoImpute(leadership, formula = fml, n.burn = 100, n.iter = 10, m = 5)
# * Example 2.5 (studentratings): 'ReadDis', 'ReadAchiev', and 'SES' predicted
# with empty model, groupwise for 'FedState' (single-level imputation)
fml <- ReadDis + ReadAchiev + SES ~ 1
imp <- jomoImpute(studentratings, formula = fml, group = "FedState", n.burn = 100,
n.iter = 10, m = 5)
```

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.