#' @title Process Data by Generating Missing Values
#'
#' @description For the `process_data`
#' argument. It introduces missing
#' values in the generated data.
#'
#' @details
#' This function is to be used in
#' the `process_data` argument of
#' [power4test()].
#'
#' The missing values are generated by
#' [mice::ampute()]. Please refer to
#' its help page, the vignette for
#' this function:
#' [Generate missing values with ampute](https://rianneschouten.github.io/mice_ampute/vignette/ampute.html),
#' and Schouten, Lugtig, and Vink (2018).
#'
#' In addition to `data`, only two
#' arguments are explicitly defined for
#' [missing_values()]: `prop` and `mech`.
#' The argument `prop` is defined to remind
#' users of the default value for this
#' argument. The argument `mech`, specifying
#' the missing data mechanism, is
#' defined because its default value
#' is different from that of [mice::ampute()].
#' For [missing_values()], the default value
#' is `"MCAR"`, missing completely at
#' random.
#'
#' Please refer to the help page of
#' [mice::ampute()] for other available
#' arguments.
#'
#' ## Note for `patterns` and other arguments with variable names
#'
#' If arguments such as `patterns` are
#' specified, the variable names need to be
#' those in the generated data. If
#' indicator scores are generated, the
#' names need to be the names of the indicators,
#' not the names of the latent variables.
#'
#' @return
#' It returns a data frame with the
#' missing values inserted.
#'
#' @param data A data frame.
#'
#' @param ... Optional arguments to be
#' passed to [mice::ampute()].
#'
#' @param prop The proportion of missingness.
#' Default is 0.5, about 50% of the cases
#' have missing data.
#'
#' @param mech The missing data mechanism.
#' Default is `"MCAR"` (missing completely at random).
#' Other possible values are `"MAR"`
#' (missing at random) and `"MNAR"`
#' (missing not at random). Please refer
#' to the help of [mice::ampute()] for
#' details.
#'
#' @seealso [power4test()]. See also
#' [mice::ampute()] for the amputation
#' method.
#'
#' @references
#' Schouten, R. M., Lugtig, P., & Vink, G.
#' (2018). Generating missing values for
#' simulation purposes: A multivariate
#' amputation procedure.
#' *Journal of Statistical Computation and Simulation, 88*(15),
#' 2909--2930. \doi{10.1080/00949655.2018.1491577}
#'
#' @examples
#'
#' # Specify the model
#'
#' mod <-
#' "
#' m ~ x
#' y ~ m + x
#' "
#'
#' # Specify the population values
#'
#' mod_es <-
#' "
#' y ~ m: l
#' m ~ x: m
#' y ~ x: n
#' "
#' # Simulate the data
#'
#' out <- power4test(
#'          nrep = 2,
#'          model = mod,
#'          pop_es = mod_es,
#'          n = 200,
#'          process_data = list(fun = "missing_values",
#'                              args = list(prop = .75)),
#'          test_fun = test_parameters,
#'          test_args = list(op = "~"),
#'          parallel = FALSE,
#'          iseed = 1234)
#'
#' dat <- pool_sim_data(out)
#' head(dat, 50)
#'
#' @export
missing_values <- function(
  data,
  ...,
  prop = 0.5,
  mech = "MCAR"
) {
  args0 <- list(...)
  cnames <- colnames(data)
  if (!is.null(args0$patterns)) {
    args0$patterns <- args0$patterns[, cnames]
  }
  if (!is.null(args0$weights)) {
    args0$weights <- args0$weights[, cnames]
  }
  args <- utils::modifyList(
            args0,
            list(data = data,
                 prop = prop,
                 mech = mech,
                 run = TRUE))
  out <- do.call(mice::ampute,
                 args)
  out$amp
}