Missing Values Analyses

Jana Welling, Christian Diegel

2026-09-23

General Information

For scaling a test, it is important to analyse the different types of missing values, i.e. to examine the reasons for missing responses and how often they occur. For NEPS tests, this is done both per person (how many items were not answered on average per person and for what reason) and per item (how many persons answered or did not answer an item and for what reason). To conduct these analyses, missing values of the competency items must be coded as user-defined missing values. Which values are typically used in NEPS and how to create the function arguments mvs and labels_mvs is described in Section User-Defined Missing Values in vignette prepare_data.

The analyses should only be conducted for all valid cases (function argument valid). Only those items that are also used for the final IRT scaling should be considered (provided in function argument select; in most cases dich or mixed, depending on the composition of the item set). The results of the analyses are automatically saved in RDS format. The summary of the results is saved as an Excel file and printed to the console. To generate and save plots, the function argument plots must be set to TRUE. If the file names need to be modified (e.g., because a test is scaled simultaneously for several cohorts), use the function argument name_group that adds a suffix to each file name (e.g., "cohort_6").

Analysis of Missing Values per Person

Main Function

The function mv_person() is used to analyse missing values per person. This analysis includes information on all user-defined missing values specified in the argument mvs. In addition, statistics are also computed for all missing values jointly defined in mvs. Missing values not included in mvs are not included in this sum. It is therefore important to include all existing user-defined missing values in mvs if the aggregate value (“ALL”) is to be meaningfully interpreted. An exception are design-related missing responses, which are automatically excluded from the dataset prior to the analysis. For this purpose, the corresponding user-defined missing value must be specified in the argument missing_by_design (default is -54). It is very important to specify the correct value here, otherwise incorrect responses will be filtered out and the number of persons to whom each item was administered will also be incorrect.

The analyses can also be conducted separately for different groups (e.g., test booklets). These must be defined in the argument grouping. Missing values are then calculated per group only for the items that were also administered to that group. The name of the grouping (e.g., “test version”) can be specified using the argument name_grouping for labelling the plots. If results are required not only by group but also for the total sample (both in tables and plots), the argument show_all must be set to TRUE.

If the analyses are conducted for a multistage test, the function argument stages needs to be defined. This argument is a named numeric vector which contains for each stage as vector element the number of items per stage and as name of the vector element the name of the stage variable as name. For example, if the test consisted of two stages with 10 items in the first and 8 items in the second stage, the argument should be stages = c(stage1 = 10, stage2 = 8).

Example code:

NEPSroutines::mv_person(
  resp = resp,
  vars = vars,
  select = "mixed",
  valid = "valid",
  grouping = c("easy", "difficult"),
  mvs = mvs,
  labels_mvs = labels_mvs,
  missing_by_design = -54,
  plots = TRUE,
  print = TRUE,
  save = TRUE,
  return = FALSE,
  path_results = "results",
  path_table = "tables",
  path_plots = "plots/missings_by_person",
  show_all = FALSE,
  overwrite = TRUE,
  name_grouping = "test version",
  digits = 3
)

Information on the individual function arguments can be obtained via the help function (?mvp_analysis).

Minor Functions

In addition to the main function, the following minor functions can be used:

Function Input Output
mvp_analysis Data.frames resp and vars containing information on responses, items, person characteristics, and optionally grouping Results of the MVP analyses (R object, optionally RDS)
mvp_plots Output of the function mvp_analysis or the element mv_p from the output of mv_person Plots for each user-defined missing value type (PNG)
mvp_table Output of the function mvp_analysis or the element mv_p from the output of mv_person Table with results of the MVP analyses for the Technical Report (R object, optionally Excel)
print _mvp_results Output of the function mvp_analysis or the element mv_p from the output of mv_person Summary of the MVP analysis results (printed in the console)

Information on the individual function arguments can be obtained via the help function (?mvp_analysis).

Analysis of Missing Values per Item

Main function

Similar to the function mv_person(), missing values can also be analysed using the function mv_item(). The difference compared to the function described above is that the proportions of specific missing values are now displayed for each item rather than per person. Information is again provided for all user-defined missing values specified in the argument mvs. As before, statistics are also computed for all missing values jointly defined in mvs. Missing values not included in mvs are not considered in this sum. It is therefore important to include all existing user-defined missing values in mvs if the aggregated value (“ALL”) is to be meaningfully interpreted. An exception are design-related missing responses, which are automatically excluded from the dataset prior to the analysis. For this purpose, the corresponding user-defined missing value must be specified in the argument missing_by_design (default is -54). It is very important to specify the correct value here; otherwise, incorrect responses will be filtered out and the number of persons to whom each item was administered will also be incorrect.

The analyses can also be conducted separately for different groups (e.g., test booklets). These must be defined in the argument grouping. Missing values are then calculated per group only for the items that were administered to that group. The name of the grouping (e.g., “test version”) can be specified using the argument name_grouping for labelling the plots. Missing values per item are displayed depending on item position and, if applicable, grouping.

If the analyses are conducted for a multistage test, the function argument stages needs to be defined. The argument is a character vector which contains the names of stage variables in resp and vars. For example, if the test consisted of three stages, three logical variables that indicate if a person reached stage X or an item was part of stage X need to be defined in resp and vars, respectively (e.g., named "stage1", etc.). The function argument would then be defined as stages = c("stage1", "stage2", "stage3"). Note that the variables need to be identically named in resp and vars.

By setting the argument save to TRUE, results can be saved in .rds and .xlsx files. The results from the Excel file can, for example, be used in the Technical Report. If the argument suf_item_names is set to TRUE, the names of polytomous items with collapsed categories are displayed without the suffix "_collapsed". By default (suf_item_names = FALSE), item names remain unchanged. Note that in .rds files, item names always remain unchanged.

Example code:

NEPSroutines::mv_item(
  resp = resp,
  vars = vars,
  select = "mixed",
  valid = "valid",
  grouping = c("easy", "difficult"),
  mvs = mvs,
  labels_mvs = labels_mvs,
  missing_by_design = -54,
  position = c(
    easy = "position_easy_mixed",
    difficult = "position_difficult_mixed"
  ),
  plots = TRUE,
  print = TRUE,
  save = TRUE,
  return = FALSE,
  path_results = "results",
  path_table = "tables",
  path_plots = "plots/missings_by_item",
  suf_item_names = TRUE,
  show_all = FALSE,
  overwrite = TRUE,
  name_grouping = "test version",
  digits = 3
)

Information on the individual function arguments can be obtained via the help function (?mvi_analysis).

Minor Functions

In addition to the main function, the following minor functions can be used:

Function Input Output
mvi_analysis Data.frames resp and vars containing information on responses, items, person characteristics, and optionally grouping Results of the MVI analyses (R object, optionally RDS)
mvi_plots Output of the function mvi_analysis (or element mv_i from the output of mv_item) Plots for each user-defined missing value type (PNG)
mvi_table Output of the function mvi_analysis (or element mv_i from the output of mv_item) Table with results of the MVI analyses for the Technical Report (R object, optionally Excel)
print_mvi_results Output of the function mvi_analysis (or element mv_i from the output of mv_item) Summary of the MVI analysis results (printed in the console)

Information on the individual function arguments can be obtained via the help function (e.g., ?mvi_analysis).