Review multiple imputations of scores on assigned ratings

Check several completed versions of a rating table before analyzing them. Supply these completed data from an imputation model; this function checks that observed scores, rating assignments and identifiers are preserved. No person-by-facet grid is constructed. This function validates supplied imputations; it does not choose or fit an imputation model. Start with review_mfrm_imputations(), then use fit_mfrm_imputed() and pool_mfrm_imputed() for eligible fixed-facet analyses. The older name The former mfrm_response_imputations() name has been removed; use review_mfrm_imputations() with impute_ids for the selected event IDs.

Use review_mfrm_imputations() to review supplied completions, with impute_ids naming the selected event IDs. The former mfrm_response_imputations() name is no longer exported. Neither route fits an imputation model or generates completed ratings.

Usage

review_mfrm_imputations(
  data,
  completed,
  person,
  facets,
  score,
  event_id,
  impute_ids,
  categories,
  assigned = NULL,
  imputation_model = NULL,
  missing = c("error", "omit")
)

# S3 method for class 'mfrm_response_imputations'
print(x, ...)

# S3 method for class 'mfrm_response_imputations'
summary(object, ...)

Arguments

data

Original long-format rating roster, including missing scores.

completed

A list of at least two completed data frames, or a mids object from mice::mice() fitted to the long-format roster. Each completion must contain all original columns and rows. Row order may differ; rows are matched by event_id.

person, score, event_id

Column names. event_id uniquely identifies a rating event, including repeated ratings of the same person and facets.

facets

Nonempty character vector of facet column names.

impute_ids

Character vector of event IDs explicitly selecting missing scores on assigned ratings. Observed scores cannot be selected. These are values from the event_id column, not a column name or a logical switch. For example, c("E2", "E7") selects those two rating events.

categories

The full intended contiguous integer category vector, for example 0:4. It is preserved across all completed analyses.

assigned

Optional name of a complete logical column: TRUE denotes an assigned rating and FALSE an unassigned combination. Without this column every supplied row is declared assigned. Unassigned rows must have missing scores in the original and every completion.

imputation_model

For a list of completions, the saved model or a nonempty list containing its specification, settings and diagnostics. Required so that the provenance is retained. For a mids input, that object is retained automatically; omit this argument.

missing

How to handle assigned missing scores not selected by impute_ids: "error" (default) or explicit "omit". Omitted events remain in the roster and every completion, with missing scores, and are excluded from each analysis. This choice is not a correction for nonresponse.

x, object

An object returned by review_mfrm_imputations() or its entry point review_mfrm_imputations().

...

Unused for print and summary methods.

Value

An mfrm_response_imputations object containing the original data, aligned completed data sets, imputation_model, an events table with assignment/observation/imputation/omission status, a support table counting original observed and imputed scores by person/facet level, and settings. No imputations or failed analyses are silently discarded.

Details

The score must contain numeric integer category labels (numeric vectors, or character/factor labels such as "0", "1"). Recoded sentinel missing values must already be NA. Identifiers, assignment indicators and observed values must not change. Only selected scores may be filled; missing auxiliary predictors may also be completed. For a mids input, its original data and score where selection must agree with this review. Numeric identifiers must remain distinct when converted to text. Numeric observed predictors are compared exactly, without rounding to text, and must remain numeric in completions; integer/double storage may differ.

A sparse assignment and a missing assigned score are different events. Neither absent roster rows nor explicit unassigned rows are imputed. An entirely imputed person or facet level is visible in support; its analysis depends on the imputation model, not on observed ratings for that level. Imputed links do not establish empirical connectedness.

Proper multiple imputation must include uncertainty about missing values and imputation parameters, reflect the ordinal score support and the person/facet dependence, and be compatible with the intended analysis. Include relevant observed predictors of nonresponse. An MAR analysis requires an adequate conditional model; informative missingness beyond observed predictors requires sensitivity analysis. Passing these software checks does not establish MAR, model adequacy or interval coverage.

For a wide-format or multilevel imputation model, reshape each completion back to the original long roster using event identities and supply the resulting list with the saved model. Do not average completed scores. See online response-imputation guide for a joint RSM example with supplied posterior predictive completions, shared Person draws, sampling diagnostics, direct observed-score inference and a separate lower-score sensitivity analysis. The accompanying R/Stan script regenerates that example; it is not a general imputation engine. Under the same score model and ignorable missingness, observed-score MML can directly estimate the fixed-facet target without completing scores. MI does not create additional observed information.

See also

fit_mfrm_imputed(), pool_mfrm_imputed(), mfrm_cluster_imputed()

Examples

# Small supplied completions to illustrate input checks, not a fitted imputer.
ratings <- data.frame(Event = paste0("E", 1:4), Person = c("P1", "P1", "P2", "P2"),
  Rater = c("A", "B", "A", "B"), Score = c(0, NA, 1, 2))
first <- second <- ratings
first$Score[2] <- 1
second$Score[2] <- 2
reviewed <- review_mfrm_imputations(ratings, list(first, second),
  person = "Person", facets = "Rater", score = "Score", event_id = "Event",
  impute_ids = "E2", categories = 0:2,
  imputation_model = list(method = "Illustrative supplied completions"))
reviewed$events  # Only E2 is imputed; the three observed scores are retained.
#>   ID Assigned Observed Imputed Omitted
#> 1 E1     TRUE     TRUE   FALSE   FALSE
#> 2 E2     TRUE    FALSE    TRUE   FALSE
#> 3 E3     TRUE     TRUE   FALSE   FALSE
#> 4 E4     TRUE     TRUE   FALSE   FALSE
summary(reviewed)  # Original observed support and imputation counts per level.
#>    Facet Level Assigned Observed Imputed Omitted
#> 1 Person    P1        2        1       1       0
#> 2 Person    P2        2        2       0       0
#> 3  Rater     A        2        2       0       0
#> 4  Rater     B        2        1       1       0