changes_mice3.Rmd

---
output: github_document
---

<!-- changes_mice3.md is generated from changes_mice3.Rmd. Please edit that file -->

```{r, echo = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "README-"
)
```

# Overview

This documents describes the changes between `mice 2.46.0` and 
`mice 3.0.0`. Most code written for versions `mice 2.12 - mice 2.46.0`
should run unchanged. I have tried to minimize the changes to the 
function arguments, but it was not possible to remain 100% backward 
compatible. This document outlines the visible changes, and suggests
ways how to adapt old code to `mice 3.0`.

# `mice` function arguments

| Argument  | 2.46.0                   | 3.0.0
|:----------|:-------------------------|:-------------------------|
method      | length `ncol(data)`      | length `length(blocks)`  |
predictorMatrix | `ncol(data)` rows and columns | `length(blocks)` rows, `ncol(data)` columns |
blocks      | not defined | new argument |
visitSequence | `integer`, arbitrary length | `character`, arbitrary length |
form        | character, length `ncol(data)`| deprecated |
formulas    | not defined | named list of formulas |
blots       | not defined | named `list` of `alist` |  
diagnostics | | deprecated |
imputationMethod | | deprecated, use `method` |
defaultImputationMethod | | deprecated, use `defaultMethod` |
... | | |

No changes were made for the following arguments: `data`, `m`,
`where`, `post`, `defaultMethod`, `maxit`, `printFlag`, `seed` and
`data.init`. 

If `blocks` is not specified, then each variable is allocated to a
separate block. In that case, `length(blocks)` is identical to
`ncol(data)`, and the method in `mice 3.0.0` reduces to
variable-by-variable imputation, as in `mice 2.46.0` and before.

Argument `visitSequence` may still be specified as `integer` 
or `numeric`, but it will internally be converted into `character` 
using the column names in `data`.

An existing function call to `mice` using the old `form` argument
may result in an error `Argument "formulas" not a list`. The advice
is to specify the formula as a list, e.g.,

```{r}
library(mice, warn.conflicts = FALSE)
imp <- mice(nhanes, 
            formulas = list(hyp ~ bmi, 
                            chl ~ age + hyp + bmi,
                            bmi ~ age + hyp + chl),
            print = FALSE, m = 1, maxit = 1, seed = 1)
imp$formulas
```