Description Usage Arguments Details Value Note Author(s) References See Also Examples

Performs multiple imputation of multilevel data using the `pan`

package (Schafer & Yucel, 2002).
Supports imputation of continuous multilevel data with missing values at level 1.
See 'Details' for further information.

1 2 3 |

`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 (see 'Details'). |

`formula` |
A formula specifying the role of each variable in the imputation model. The basic model is constructed by |

`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. |

`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 |

`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 to |

This function serves as an interface to the `pan`

package and supports imputation of continuous multilevel data at level 1 (Schafer & Yucel, 2002).
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 `pan`

.
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 the cluster indicator must be specified.
The intercept is automatically included as both a fixed and 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 `pan`

.
Specifying the `formula`

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

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`

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 a random effect, but it can be suppressed if needed (see 'Examples').
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`

.

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 distributions for the covariance matrices in `panImpute`

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:

`a`

: degrees of freedom for the covariance matrix of residuals`Binv`

: scale matrix for the covariance matrix of residuals`c`

: degrees of freedom for the covariance matrix of random effects`Dinv`

: scale matrix for the covariance matrix of random effects

A sensible choice for a diffuse non-default prior is to set the degrees of freedom to the lowest value possible, and the scale matrices according to a prior guess of the corresponding covariance matrices (see Schafer & Yucel, 2002).

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

argument.
If set to `"full"`

(the default), all chains are saved.
If set to `"diagonal"`

, only chains pertaining to fixed effects and the diagonal entries of the covariance matrices are saved.
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 row 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, respectively. |

`random.L1` |
A character string denoting the handling of random residual covariance matrices (not used here; see |

`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

Schafer, J. L., and Yucel, R. M. (2002). Computational strategies for multivariate linear mixed-effects models with missing values. *Journal of Computational and Graphical Statistics, 11*, 437-457.

`jomoImpute`

, `mitmlComplete`

, `summary.mitml`

, `plot.mitml`

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 | ```
# 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)
# *** ................................
# the 'type' interface
#
# * Example 1.1: 'ReadDis' and 'SES', predicted by 'ReadAchiev' and
# 'CognAbility', with random slope for 'ReadAchiev'
type <- c(-2, 0, 0, 0, 0, 0, 3, 1, 2, 0)
names(type) <- colnames(studentratings)
type
imp <- panImpute(studentratings, type = type, n.burn = 1000, n.iter = 100, m = 5)
# * Example 1.2: 'ReadDis' and 'SES' groupwise for 'FedState',
# and predicted by 'ReadAchiev'
type <- c(-2, -1, 0, 0, 0, 0, 2, 1, 0, 0)
names(type) <- colnames(studentratings)
type
imp <- panImpute(studentratings, type = type, n.burn = 1000, n.iter = 100, m = 5)
# *** ................................
# the 'formula' interface
#
# * Example 2.1: imputation of 'ReadDis', predicted by 'ReadAchiev'
# (random intercept)
fml <- ReadDis ~ ReadAchiev + (1|ID)
imp <- panImpute(studentratings, formula = fml, n.burn = 1000, n.iter = 100, m = 5)
# ... the intercept can be suppressed using '0' or '-1' (here for fixed intercept)
fml <- ReadDis ~ 0 + ReadAchiev + (1|ID)
imp <- panImpute(studentratings, formula = fml, n.burn = 1000, n.iter = 100, m = 5)
# * Example 2.2: imputation of 'ReadDis', predicted by 'ReadAchiev'
# (random slope)
fml <- ReadDis ~ ReadAchiev + (1+ReadAchiev|ID)
imp <- panImpute(studentratings, formula = fml, n.burn = 1000, n.iter = 100, m = 5)
# * Example 2.3: imputation of 'ReadDis', predicted by 'ReadAchiev',
# groupwise for 'FedState'
fml <- ReadDis ~ ReadAchiev + (1|ID)
imp <- panImpute(studentratings, formula = fml, group = "FedState", n.burn = 1000,
n.iter = 100, m = 5)
# * Example 2.4: imputation of 'ReadDis', predicted by 'ReadAchiev'
# including the cluster mean of 'ReadAchiev' as an additional predictor
fml <- ReadDis ~ ReadAchiev + I(clusterMeans(ReadAchiev, ID)) + (1|ID)
imp <- panImpute(studentratings, formula = fml, n.burn = 1000, n.iter = 100, m = 5)
# ... using 'save.pred' to save the calculated cluster means in the data set
fml <- ReadDis ~ ReadAchiev + I(clusterMeans(ReadAchiev, ID)) + (1|ID)
imp <- panImpute(studentratings, formula = fml, n.burn = 1000, n.iter = 100, m = 5,
save.pred = TRUE)
head(mitmlComplete(imp, print = 1))
``` |

```
*** This is beta software. Please report any bugs!
*** See the NEWS file for recent changes.
ID FedState Sex MathAchiev MathDis SES
-2 0 0 0 0 0
ReadAchiev ReadDis CognAbility SchClimate
3 1 2 0
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
ID FedState Sex MathAchiev MathDis SES
-2 -1 0 0 0 0
ReadAchiev ReadDis CognAbility SchClimate
2 1 0 0
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
Running burn-in phase ...
Creating imputed data set ( 1 / 5 ) ...
Creating imputed data set ( 2 / 5 ) ...
Creating imputed data set ( 3 / 5 ) ...
Creating imputed data set ( 4 / 5 ) ...
Creating imputed data set ( 5 / 5 ) ...
Done!
ID ReadDis FedState Sex MathAchiev MathDis SES ReadAchiev CognAbility
1 2001 1.908635 B Boy 657.6592 NA 93 584.1848 61.75292
2 2001 3.580834 B Girl 503.4589 2.762476 NA 401.2042 49.21429
3 2001 2.220239 B Boy 516.6611 2.682086 42 461.0339 52.28463
4 2001 2.780738 B Girl 454.6908 2.689208 44 397.0767 43.22988
5 2001 4.409024 B Girl 565.5090 NA NA 488.4138 60.93126
6 2001 2.769426 B Boy 595.8878 NA 71 454.7897 52.26145
SchClimate I(clusterMeans(ReadAchiev, ID))
1 0.6898527 472.4092
2 NA 472.4092
3 2.2944023 472.4092
4 NA 472.4092
5 2.0094100 472.4092
6 1.4567406 472.4092
```

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.