R/function-map.R

Defines functions function_map

Documented in function_map

#' Create new `*_map()` functions
#'
#' @description `function_map()` creates a basic mapper: a function that
#'   applies a single-case test such as `grim_scalar()` to every row of a data
#'   frame. [`grim_map()`], [`grimmer_map()`], and [`debit_map()`] are made by
#'   it.
#'
#'   See `vignette("consistency-tests-in-depth")`, section *Creating basic
#'   mappers with `function_map()`*.
#'
#'   `function_map()` is a developer tool: it may change in a minor release,
#'   with a NEWS entry.
#'
#' @param .fn Single-case function to apply to each row. It must return a
#'   single logical value or, if `.col_names` is specified, a list of values
#'   with the key result first.
#' @param .reported String. Names of the arguments of `.fn` that take the
#'   reported values, such as `c("x", "n")`. These become the key columns. May
#'   be `NULL` if `.reported_variadic` is specified. Key and helper columns
#'   named `n`, `items_averaged`, or `absolute` are taken to be whole numbers,
#'   as are the decimal counts of `.args_by_row`: a value within floating-point
#'   noise of one, such as `100 * 0.29`, is rounded to it before `.fn` sees it.
#' @param .reported_variadic Optionally, a single string naming an argument of
#'   `.fn` that takes the values of one row as a vector. The factory-made
#'   function gets an argument by that name, without a default, that selects
#'   any number of columns with tidyselect syntax. See *Details*.
#' @param .name_test String (length 1). Plain-text name of the test, such as
#'   `"GRIM"`.
#' @param .name_key_result (Experimental) String (length 1). Name of the key
#'   result column. Default is `"consistency"`.
#' @param .name_class String. Optionally, one or more classes to add to the
#'   output. Default is `NULL`; see *Details* for the class that is always
#'   added.
#' @param .args_disabled Optionally, names of arguments of `.fn` that the
#'   factory-made function should not have. Specifying one of them is an error.
#' @param .args_by_row Optionally, names of arguments of `.fn` that may vary
#'   by row, such as `"digits_x"`. The factory-made function takes a single
#'   value or one per row of `data` for each. If one is left out, it is read
#'   from a column of `data` by that name, if there is one. They are returned
#'   as columns. One whose name starts with `digits_` is a decimal count,
#'   returned as integer like `digits_x`.
#' @param .args_fixed Optionally, a named list of values that are always passed
#'   to `.fn`, such as `list(show_reason = TRUE)`. The factory-made function
#'   has no arguments for them; specifying one is an error.
#' @param .cols_helper Optionally, names of arguments of `.fn` that may also be
#'   given as columns of `data`, such as `"items_averaged"`. A helper column is
#'   returned after the key columns if it was given, as a column or as an
#'   argument. Giving both is an error if they disagree.
#' @param .col_names Optionally, names of the columns that a list returned by
#'   `.fn` unpacks into, as with `show_rec = TRUE`. The first name must be
#'   `.name_key_result`. If `data` has no rows, the columns are those that
#'   `.fn` returns for a row of missing values, or, if it fails on one, only
#'   the key result column.
#' @param .cols_derived Optionally, a named list of vectorized functions that
#'   compute further columns from the same input, such as
#'   `list(exp_incon = grim_exp_incon)`. Each is called once, with the whole
#'   columns and only the arguments it has formals for, and must return one
#'   value per row; a `.reported_variadic` argument comes as a list of each
#'   row's values. The columns follow the key result column.
#' @param ... These dots must be empty.
#'
#' @details `.reported_variadic` is for a test whose number of key columns
#'   depends on the data, such as whether the values in any number of columns
#'   add up to the value in another one. `.fn` takes those values as a single
#'   vector, and the factory-made function selects the columns with tidyselect;
#'   see *Examples*. The selection must not be empty and must not include a
#'   column that already has a role in the test. The selected columns are
#'   returned as themselves. Such a mapper cannot be wrapped by
#'   [`function_map_seq()`] or [`function_map_total_n()`], which derive their
#'   arguments from `.reported`.
#'
#'   The output has the class `"scrutiny_{tolower(.name_test)}_map"`, with
#'   spaces as underscores, e.g., `"scrutiny_grim_map"`, in addition to any
#'   `.name_class`. The arguments that applied to the whole call, such as
#'   `rounding`, are recorded on the output; see [`scrutiny_meta()`].
#'
#' @return A function with these arguments:
#' - `data`: a data frame with the key columns. Other columns are permitted.
#' - The `.args_by_row` arguments, such as `digits_x`.
#' - If `.reported_variadic` was given, an argument by that name.
#' - One argument per `.reported` value, for naming a column of `data` that
#'   holds that value under another name.
#' - `...`: must be empty. Every argument after it must be named in full.
#' - The other arguments of `.fn`, i.e., those not named in `.reported`,
#'   `.reported_variadic`, `.args_disabled`, or `.args_fixed`, with the same
#'   defaults.
#'
#' @section Value returned by the factory-made function: A tibble with the
#'   `.reported_variadic` columns, the `.reported` columns, the helper columns
#'   that were given, the `.args_by_row` columns, and the key result column
#'   (`consistency` by default), which is `TRUE` for consistent value sets,
#'   `FALSE` for inconsistent ones, and `NA` if the test can't decide. Any
#'   `.cols_derived` columns, any `.col_names` columns, and the other columns
#'   of `data` follow, in that order.
#'
#' @include grim.R debit.R function-factory-helpers.R bind-rows.R
#'
#' @export
#'
#' @examples
#' # A single-case function for SCHLIM, a mock test:
#' schlim_scalar <- function(y, n) {
#'   (y / 3) > n
#' }
#'
#' # The mapper:
#' schlim_map <- function_map(
#'   .fn = schlim_scalar,
#'   .reported = c("y", "n"),
#'   .name_test = "SCHLIM"
#' )
#'
#' df1 <- tibble::tibble(y = 16:25, n = 3:12)
#' schlim_map(df1)
#'
#' # A test over any number of columns: do the parts add up to the total?
#' # The single-case function takes the parts as one vector...
#' sum_check_scalar <- function(parts, total, tolerance = 0) {
#'   abs(sum(parts) - total) <= tolerance
#' }
#'
#' # ...which `.reported_variadic` names:
#' sum_check_map <- function_map(
#'   .fn = sum_check_scalar,
#'   .reported = "total",
#'   .reported_variadic = "parts",
#'   .name_test = "SUMCHECK"
#' )
#'
#' df2 <- tibble::tibble(
#'   item_1 = c(10, 20, 30),
#'   item_2 = c(5, 5, 5),
#'   item_3 = c(1, 2, 3),
#'   total  = c(16, 27, 40)
#' )
#'
#' # The `parts` argument selects columns with tidyselect syntax:
#' sum_check_map(df2, parts = starts_with("item"))

function_map <- function(
  .fn,
  .reported = NULL,
  .name_test,
  .name_key_result = "consistency",
  .name_class = NULL,
  .args_disabled = NULL,
  .args_by_row = NULL,
  .args_fixed = NULL,
  .cols_helper = NULL,
  .col_names = NULL,
  .cols_derived = NULL,
  # Last, not next to `.reported`, so that positional calls keep their meaning:
  .reported_variadic = NULL,
  ...
) {
  force(.fn)
  force(.reported)
  force(.name_test)
  force(.reported_variadic)
  force(.name_class)
  force(.name_key_result)
  force(.args_disabled)
  force(.args_by_row)
  force(.args_fixed)
  force(.cols_helper)
  force(.col_names)
  force(.cols_derived)

  # Checks ---

  # The dots only prevent a false-positive CRAN warning:
  rlang::check_dots_empty()

  check_args_disabled_unnamed(.args_disabled)
  check_string(.name_key_result)

  fn_name <- deparse(substitute(.fn))
  formals_fn <- formals(.fn)

  check_factory_arg_names(.reported, formals_fn, fn_name, ".reported")
  check_factory_arg_names(
    .reported_variadic,
    formals_fn,
    fn_name,
    ".reported_variadic"
  )
  check_factory_arg_names(.args_by_row, formals_fn, fn_name, ".args_by_row")
  check_factory_arg_names(.cols_helper, formals_fn, fn_name, ".cols_helper")
  check_factory_arg_names(
    names(.args_fixed),
    formals_fn,
    fn_name,
    ".args_fixed"
  )

  if (!is.null(.reported_variadic)) {
    check_length(.reported_variadic, 1L)
    if (any(.reported_variadic == .reported)) {
      abort_in_export(
        "`.reported_variadic` must not also be a `.reported` value.",
        "x" = "{wrap_in_backticks(.reported_variadic)} is both.",
        "i" = "A key argument of `{fn_name}()` either takes the values of \\
        one column or the values of any number of them, not both."
      )
    }
  } else if (length(.reported) == 0L) {
    abort_in_export(
      "`.reported` must name at least one column.",
      "i" = "Unless `.reported_variadic` is specified, in which case the \\
      columns it selects are the only key columns."
    )
  }

  if (length(.cols_derived) > 0L && !rlang::is_named(.cols_derived)) {
    abort_in_export(
      "`.cols_derived` must be a named list: each name becomes a column name."
    )
  }

  if (!all(vapply(.cols_derived, is.function, logical(1L)))) {
    abort_in_export(
      "Every element of `.cols_derived` must be a function.",
      "x" = "{wrap_in_backticks(names(.cols_derived)[
      !vapply(.cols_derived, is.function, logical(1L))
      ])} {?is/are} not."
    )
  }

  if (!is.null(.col_names) && !identical(.col_names[1L], .name_key_result)) {
    col_names_first <- .col_names[1L]
    name_key_result <- .name_key_result
    abort_in_export(
      "`.col_names` must start with `.name_key_result`.",
      "x" = "It starts with \"{col_names_first}\", but `.name_key_result` \\
      is \"{name_key_result}\"."
    )
  }

  # Fixed values are passed to `.fn` by name, so each needs one:
  if (
    !is.null(.args_fixed) &&
      !(is.list(.args_fixed) && rlang::is_named2(.args_fixed))
  ) {
    abort_in_export("`.args_fixed` must be a named list.")
  }

  # A fixed value can't also come from `data` or from the caller:
  args_fixed_offenders <- intersect(
    names(.args_fixed),
    c(.reported, .reported_variadic, .args_by_row, .cols_helper, .args_disabled)
  )
  if (length(args_fixed_offenders) > 0L) {
    abort_in_export(
      "`.args_fixed` can't name arguments that are key, by-row, helper, or \\
      disabled arguments.",
      "x" = "{wrap_in_backticks(args_fixed_offenders)} \\
      {cli::qty(length(args_fixed_offenders))}{?is/are} already one of these."
    )
  }

  # The arguments of `.fn` that become arguments of the factory-made function,
  # in `.fn`'s order. Key arguments are inserted at the very end:
  args_promoted <- setdiff(
    names(formals_fn),
    c(.reported, .reported_variadic, .args_disabled, names(.args_fixed), "...")
  )

  # The body of the factory-made function assigns these names before it is
  # done reading the arguments, so an argument of `.fn` by one of these names
  # would be shadowed:
  names_locals <- c(
    "data",
    "fn",
    "reported",
    "reported_variadic",
    "args_by_row",
    "args_helper",
    "args_helper_given",
    "args_const",
    "args_fixed",
    "args_required",
    "args_enum",
    "col_names",
    "cols_derived_funs",
    "add_class",
    "cols_variadic",
    "names_variadic",
    "enum_defaults",
    "enum_vals",
    "args_vals",
    "cols_tested",
    "col_variadic",
    "arg_given",
    "vals",
    "arg",
    # Only the variadic part of the body assigns these:
    if (!is.null(.reported_variadic)) {
      c(
        "quo_variadic",
        "cols_added",
        "data_given",
        "index_variadic",
        "index_given",
        "index",
        "cols_renamed"
      )
    }
  )
  check_reported_reserved(
    c(.reported, .reported_variadic),
    names_locals,
    "function_map"
  )
  args_shadowed <- intersect(args_promoted, names_locals)
  if (length(args_shadowed) > 0L) {
    abort_in_export(
      "`{fn_name}()` has arguments that `function_map()` uses internally.",
      "x" = "Rename {wrap_in_backticks(args_shadowed)}.",
      "i" = "Reserved: {wrap_in_backticks(names_locals)}."
    )
  }

  formals_promoted <- formals_fn[args_promoted]
  args_required <- args_promoted[
    vapply(formals_promoted, rlang::is_missing, logical(1L), USE.NAMES = FALSE)
  ]

  args_by_row <- intersect(args_promoted, .args_by_row)
  args_helper <- intersect(args_promoted, .cols_helper)
  args_const <- setdiff(args_promoted, c(args_by_row, args_helper))

  # Arguments whose default is a set of strings, such as `sd_meaning`. A call
  # that leaves one out gets the first string, as `rlang::arg_match()` would
  # resolve it. Resolving it here records that string, not the whole set, in the
  # "scrutiny" attribute:
  args_enum <- args_const[vapply(
    formals_promoted[args_const],
    is_enum_default,
    logical(1L),
    USE.NAMES = FALSE
  )]

  # The whole sets, for the manufactured function to recognize one given as
  # such (`eval_defaults()` below resolves them to their first string):
  enum_defaults <- eval_enum_defaults(
    formals_promoted[args_enum],
    environment(.fn)
  )

  # For the `default` column of the "scrutiny" attribute:
  defaults_const <- eval_defaults(
    formals_promoted[args_const],
    environment(.fn)
  )

  # Settings whose default is a single value must stay one. Another `.fn` may
  # have a setting such as `bounds = NULL` or `scale = c(1, 7)`:
  args_single <- names(defaults_const)[lengths(defaults_const) == 1L]

  # The by-row arguments, in practice `digits_*`, have no defaults, so they go
  # right after `data`, in the same position in every mapper. This must come
  # after `args_required`, which pairs `formals_promoted` with `args_promoted`
  # by position:
  formals_promoted <- formals_promoted[
    c(args_by_row, setdiff(names(formals_promoted), args_by_row))
  ]

  # With variadic key columns, `.reported` may be empty, leaving nothing to
  # rename:
  code_key_arg_checks <- if (length(.reported) > 0L) {
    code_missing <- paste0("!missing(", .reported, ")", collapse = " || ")
    list(rlang::expr({
      if (`!!`(rlang::parse_expr(code_missing))) {
        data <- scrutiny::absorb_key_args(data, `!!`(.reported))
      }
    }))
  } else {
    list()
  }

  # `tidyselect::eval_select()` both finds and renames the variadic columns.
  # The argument is spliced in as a symbol so that `rlang::enquo()` captures
  # the expression instead of evaluating it:
  # The row names of a data frame become a `rowname` column, which is no column
  # of the user's and so not selected. Whether they will is only known before
  # `data` is converted:
  code_variadic_input <- if (is.null(.reported_variadic)) {
    list()
  } else {
    list(rlang::expr({
      cols_added <- if (
        is.data.frame(data) &&
          !tibble::is_tibble(data) &&
          is.character(attr(data, "row.names"))
      ) {
        "rowname"
      }
    }))
  }

  # `data` before its key columns are renamed and moved to the front: the
  # selection may name a key column as the user knows it, as in
  # `summands = !sum, total = sum`, and positions count as in `data` as given,
  # without the `rowname` column that `as_tibble_input()` puts first.
  code_variadic_given <- if (is.null(.reported_variadic)) {
    list()
  } else {
    list(rlang::expr(data_given <- data[setdiff(colnames(data), cols_added)]))
  }

  code_variadic <- if (is.null(.reported_variadic)) {
    list()
  } else {
    list(rlang::expr({
      quo_variadic <- rlang::enquo(`!!`(as.name(.reported_variadic)))
      check_variadic_arg(quo_variadic, `!!`(.reported_variadic))
      # By the columns as the user knows them, so that a position counts
      # in `data` as given, not after the key columns moved to the front. A
      # name only `data` has, i.e., that of a key column after renaming, is
      # tried next; if that fails too, the first error stands:
      index_variadic <- tryCatch(
        {
          index_given <- tidyselect::eval_select(
            quo_variadic,
            data_given,
            exclude = cols_added
          )
          # The same columns in `data`. A renamed key column has no match by
          # name; it stands for all of them, which the check below rejects:
          index <- match(colnames(data_given)[index_given], colnames(data))
          names(index) <- names(index_given)
          cols_renamed <- which(!colnames(data) %in% colnames(data_given))
          names(cols_renamed) <- colnames(data)[cols_renamed]
          # Such a column has a role in the test, so it is an error; the
          # message names it as the user knows it:
          if (anyNA(index)) {
            check_variadic_cols(
              index = index_given,
              data = data_given,
              spoken_for = setdiff(colnames(data_given), colnames(data)),
              name = `!!`(.reported_variadic)
            )
          }
          c(index[!is.na(index)], if (anyNA(index)) cols_renamed)
        },
        vctrs_error_subscript_oob = function(cnd) {
          tryCatch(
            tidyselect::eval_select(quo_variadic, data, exclude = cols_added),
            error = function(cnd_renamed) rlang::cnd_signal(cnd)
          )
        }
      )
      check_variadic_cols(
        index = index_variadic,
        data = data,
        spoken_for = c(`!!`(.reported), args_helper),
        name = `!!`(.reported_variadic)
      )
      cols_variadic <- as.list(data)[index_variadic]
      # `eval_select()` may rename the columns it selects. The new names go
      # into the output; the old ones keep the columns from being returned a
      # second time:
      names_variadic <- colnames(data)[index_variadic]
      names(cols_variadic) <- names(index_variadic)
    }))
  }

  # `manage_helper_col()` reads the column name off the expression it was
  # given, so the argument is spliced in as a symbol. A helper without a
  # default, like `items_averaged`, gets none here either, so that a missing
  # one reaches `fn()` as missing:
  code_cols_helper <- lapply(
    args_helper,
    function(name) {
      if (name %in% args_required) {
        return(rlang::expr(
          data <- scrutiny::manage_helper_col(
            data = data,
            arg = `!!`(as.name(name))
          )
        ))
      }
      rlang::expr(
        data <- scrutiny::manage_helper_col(
          data = data,
          arg = `!!`(as.name(name)),
          default = `!!`(formals_promoted[[name]])
        )
      )
    }
  )

  all_classes <- c(
    class_name_test(.name_test, "_map"),
    .name_class
  )

  # So that `dplyr::bind_rows()` rejects output of different calls; see
  # `R/bind-rows.R`:
  register_bind_methods(all_classes[[1L]])

  # --- Start of the factory-made function, `fn_out()` ---

  # The dots come right after the key arguments, which `insert_key_args()` puts
  # in front of them below. Every argument after the dots must then be named in
  # full, so that `items = 2` can't partially match `items_averaged`:
  fn_out <- rlang::new_function(
    args = rlang::pairlist2(
      data = ,
      !!!formals_promoted[args_by_row],
      ... = ,
      !!!formals_promoted[setdiff(names(formals_promoted), args_by_row)]
    ),
    body = rlang::expr({
      fn <- `!!`(.fn)
      reported <- `!!`(.reported)
      reported_variadic <- `!!`(.reported_variadic)
      args_by_row <- `!!`(args_by_row)
      args_helper <- `!!`(args_helper)
      args_const <- `!!`(args_const)
      args_fixed <- `!!`(.args_fixed)
      args_required <- `!!`(args_required)
      args_enum <- `!!`(args_enum)
      col_names <- `!!`(.col_names)
      cols_derived_funs <- `!!`(.cols_derived)

      add_class <- function(x, new_class) {
        `class<-`(x, value = c(new_class, class(x)))
      }

      # Checks ---

      `!!!`(code_variadic_input)

      # First, before anything reads columns off `data`:
      data <- as_tibble_input(data)
      `!!!`(code_variadic_given)

      # Rename columns named by key arguments:
      `!!!`(code_key_arg_checks)

      check_args_disabled(`!!`(c(.args_disabled, names(.args_fixed))))
      check_factory_dots(fn, `!!`(fn_name), ...)
      scrutiny::check_mapper_input_colnames(
        data,
        `!!`(.reported),
        `!!`(.name_test),
        `!!`(.name_key_result)
      )

      # After the renaming, so that a selection may also name a key column
      # by its argument:
      cols_variadic <- list()
      names_variadic <- character(0L)
      `!!!`(code_variadic)

      # See `args_enum` above. Before the length check, which would see the
      # whole set. One given as the whole set, e.g. by a wrapper that forwards
      # its own default, is resolved the same way, so that the "scrutiny"
      # attribute records one string:
      enum_defaults <- `!!`(enum_defaults)
      for (arg in args_enum) {
        if (eval(call("missing", as.name(arg)))) {
          assign(arg, enum_defaults[[arg]][[1L]])
        }
      }
      enum_vals <- resolve_enums(mget(args_enum), enum_defaults)
      for (arg in args_enum) {
        assign(arg, enum_vals[[arg]])
      }

      # A helper column is returned if it was given, as a column of `data` or
      # as an argument. One that `fn()` only has a default for is not:
      args_helper_given <- character(0L)
      for (arg in args_helper) {
        if (arg %in% colnames(data) || !eval(call("missing", as.name(arg)))) {
          args_helper_given <- c(args_helper_given, arg)
        }
      }

      # Add missing helper columns; error if `data` and an argument disagree:
      `!!!`(code_cols_helper)

      # Main part ---

      # An argument with no default, such as `digits_x`, must reach `fn()` as
      # missing, so that the test function's own error message is shown rather
      # than a generic one:
      args_vals <- list()
      for (arg in c(args_by_row, args_const)) {
        if (arg %in% args_required && eval(call("missing", as.name(arg)))) {
          next
        }
        args_vals[arg] <- list(get(arg))
      }

      # The columns that `fn()` is applied to, row by row: the key columns,
      # then any helper columns, then one column per argument that may vary by
      # row (recycled to the number of rows if it is a single value):
      cols_tested <- as.list(data[reported])

      # A variadic key argument gets all of a row's values at once, so its
      # "column" is a list with one vector per row. `fn()` has a single
      # argument for it, whatever the number of columns behind it:
      if (!is.null(reported_variadic)) {
        col_variadic <- cols_variadic |>
          purrr::pmap(function(...) c(...)) |>
          list() |>
          rlang::set_names(reported_variadic)
        cols_tested <- c(col_variadic, cols_tested)
      }

      for (arg in args_helper) {
        cols_tested[[arg]] <- data[[arg]]
        # An all-`NA` column of any type as `NA_character_`; see
        # `na_as_integer()`, which does the same for the whole numbers below:
        if (arg %in% ARGS_STRING) {
          cols_tested[[arg]] <- na_as_character(cols_tested[[arg]])
        }
      }

      # A number with a class, as from `tibble::num()`, is tested as a plain
      # one: `as.character()` and `as.integer()` fail on some such classes.
      for (arg in names(cols_tested)) {
        check_not_integer64(cols_tested[[arg]], arg)
        if (is.numeric(cols_tested[[arg]]) && is.object(cols_tested[[arg]])) {
          cols_tested[[arg]] <- vctrs::vec_data(cols_tested[[arg]])
        }
      }

      # Tested as the whole numbers they are accepted as; see `round_whole()`.
      # A factor, as `read.csv()` may leave, gets a hint at converting it:
      for (arg in intersect(ARGS_WHOLE, names(cols_tested))) {
        check_not_factor(cols_tested[[arg]], arg)
        cols_tested[[arg]] <- round_whole(cols_tested[[arg]])
      }

      for (arg in args_by_row) {
        # An argument that was not given takes its values from a column by its
        # name, if `data` has one. A required one, such as `digits_x`, is then
        # stated by the column:
        arg_given <- !eval(call("missing", as.name(arg)))
        if (!arg_given && arg %in% colnames(data)) {
          args_vals[[arg]] <- data[[arg]]
        }
        if (!is.null(args_vals[[arg]])) {
          # A whole-number argument, such as `digits_x`, as integer, so that
          # the output column is the value tested. Any other argument as is:
          # `tol = 1e-8` is no 0.
          vals <- args_vals[[arg]]
          if (arg %in% ARGS_WHOLE || startsWith(arg, "digits_")) {
            vals <- as_integer_if_lossless(vals)
          }
          if (startsWith(arg, "digits_")) {
            check_digits_numeric(vals, arg, from_column = !arg_given)
          }
          cols_tested[[arg]] <- recycle_digits(vals, nrow(data), arg)
          # A column of `data` by the same name is replaced by the argument's
          # values (see `other_cols` below), which is only right if the two
          # agree, as they do when a mapper's output is tested again:
          if (
            arg %in%
              colnames(data) &&
              !values_agree(data[[arg]], cols_tested[[arg]])
          ) {
            abort_in_export(
              "`{arg}` is both an argument and a column of `data`, and the \
              two disagree.",
              "i" = "Drop or rename the column, or make the two agree."
            )
          }
        }
      }

      args_const_vals <- args_vals[intersect(args_const, names(args_vals))]

      # roundwork checks the rounding arguments once per row, but its errors
      # would name the roundwork function instead of the mapper:
      if ("rounding" %in% names(args_const_vals)) {
        check_rounding_args(
          args_const_vals$rounding,
          args_const_vals$threshold,
          args_const_vals$symmetric
        )
      }

      # The other settings describe the call as a whole, too, so each is a
      # single value if its default is one. The enums have been resolved above,
      # so one given as its whole set passes:
      for (arg in intersect(names(args_const_vals), `!!`(args_single))) {
        check_setting_length(
          arg,
          args_const_vals[[arg]],
          c(reported_variadic, reported, args_by_row, args_helper),
          name_last_export()
        )
      }

      # Test the first row on its own, so that an error about the arguments,
      # such as a missing `digits_x`, is the test function's own, not wrapped
      # in `purrr::pmap()`'s indexed-error context. The result is discarded.
      #
      # Do *not* muffle warnings or messages here: `lifecycle::deprecate_warn()`
      # records that it has warned before the muffle discards the warning, so a
      # once-per-session warning would be lost for good.
      #
      # The error names row 1 only if another row passes; an error about the
      # arguments fails on every row. Row 2 alone is not enough: in the data
      # that a total-n mapper builds, it is the other group of the same case:
      if (nrow(data) > 0L) {
        test_row <- function(row) {
          row_values <- lapply(cols_tested, function(x) x[[row]])
          do.call(fn, c(row_values, args_const_vals, args_fixed, list(...)))
        }
        withCallingHandlers(
          test_row(1L),
          error = function(cnd) {
            if (passes_any_row(test_row, nrow(data))) {
              signal_in_row(cnd, 1L)
            }
          }
        ) |>
          check_fn_result(`!!`(fn_name))
      } else {
        # No row to test, but a required argument that is missing must still
        # be reported by `fn()`, so test a row of missing values. Otherwise,
        # its result gives the output the columns it has with rows, if `fn()`
        # takes missing values:
        row_na <- lapply(cols_tested, function(x) x[NA_integer_])
        test_row_na <- function() {
          do.call(fn, c(row_na, args_const_vals, args_fixed, list(...)))
        }
        args_missing <- setdiff(
          args_required,
          c(names(args_vals), args_helper_given)
        )
        result_na <- if (length(args_missing) > 0L) {
          test_row_na()
          NULL
        } else {
          # Only the shape is used, so what `fn()` says about missing values
          # is not passed on, except a once-per-session deprecation warning,
          # which would be lost for good (see the first-row test above):
          tryCatch(
            withCallingHandlers(
              write_result_cols(list(test_row_na()), col_names, `!!`(fn_name)),
              warning = function(cnd) {
                if (!inherits(cnd, "lifecycle_warning_deprecated")) {
                  tryInvokeRestart("muffleWarning")
                }
              },
              message = function(cnd) tryInvokeRestart("muffleMessage")
            ),
            error = function(cnd) NULL
          )
        }
      }

      results <- withCallingHandlers(
        do.call(
          purrr::pmap,
          c(
            list(cols_tested, fn),
            args_const_vals,
            args_fixed,
            list(...)
          )
        ),
        purrr_error_indexed = rethrow_row_error
      )

      # The key columns of the output, then the helper columns that were given,
      # as tested. Whole-number columns such as `n` as integer, which prints
      # better:
      cols_key <- c(cols_variadic, cols_tested[reported])

      for (arg in args_helper_given) {
        cols_key[[arg]] <- cols_tested[[arg]]
      }

      for (arg in intersect(ARGS_WHOLE, names(cols_key))) {
        cols_key[[arg]] <- as_integer_if_lossless(cols_key[[arg]])
      }

      # Only the arguments with values: one that is `NULL` has no column.
      cols_by_row <- cols_tested[intersect(args_by_row, names(cols_tested))]

      cols_result <- write_result_cols(results, col_names, `!!`(fn_name))
      if (nrow(data) == 0L && is.list(result_na)) {
        cols_result <- lapply(result_na, function(col) col[0L])
      }

      # Derived columns, such as `exp_incon` in `grim_map()`. Each function only gets the
      # arguments it has formals for, so it needs to know nothing about the
      # test around it. It is called once on the whole columns: once per row,
      # the call itself took most of `grim_map()`'s time:
      cols_derived <- list()

      for (col_name in names(cols_derived_funs)) {
        fn_derived <- cols_derived_funs[[col_name]]
        args_names_derived <- names(formals(fn_derived))
        vals_derived <- do.call(
          fn_derived,
          c(
            cols_tested[intersect(names(cols_tested), args_names_derived)],
            args_const_vals[
              intersect(names(args_const_vals), args_names_derived)
            ]
          )
        )
        vals_derived <- unlist(vals_derived, use.names = FALSE)
        # A wrong length would make a tibble that only fails when printed:
        if (length(vals_derived) != nrow(data)) {
          abort_in_export(
            "The `.cols_derived` function for `{col_name}` must return one \\
            value per row.",
            "x" = "It returned {length(vals_derived)} value{?s} for \\
            {nrow(data)} row{?s}."
          )
        }
        cols_derived[[col_name]] <- if (is.null(vals_derived)) {
          numeric(0L)
        } else {
          vals_derived
        }
      }

      cols_result <- c(cols_result[1L], cols_derived, cols_result[-1L])

      # A column of `data` by the name of a result column would be silently
      # dropped:
      names_taken <- intersect(names(cols_result), colnames(data))
      if (length(names_taken) > 0L) {
        abort_in_export(
          "`data` has columns that the output needs for its results.",
          "x" = "{wrap_in_backticks(names_taken)} would be overwritten.",
          "i" = "Rename or remove {cli::qty(length(names_taken))}{?it/them}."
        )
      }

      # Columns that the output has already, such as `digits_x` in a mapper's
      # output tested again, are skipped. Variadic columns go by their names in
      # `data`: skipping the new name would drop a column of `data` that has
      # it, rather than catching the clash below:
      other_cols <- data[
        !colnames(data) %in%
          c(
            names(cols_by_row),
            names(cols_result),
            reported,
            names_variadic,
            args_helper
          )
      ]

      cols_out <- c(cols_key, cols_by_row, cols_result, as.list(other_cols))

      # A variadic column renamed to a name the output uses, as in
      # `summands = c(total = a, b)` or to the name of another column of
      # `data`, would appear twice:
      names_dup <- unique(names(cols_out)[duplicated(names(cols_out))])
      if (length(names_dup) > 0L) {
        abort_in_export(
          "The output would have {wrap_in_backticks(names_dup)} twice.",
          "i" = "A selected column can't be renamed to a name the output uses."
        )
      }

      out <- tibble::new_tibble(cols_out, nrow = nrow(data), class = NULL)

      out <- add_class(out, `!!`(all_classes))

      # Settings of this call for functions downstream, such as `rounding`,
      # which `grim_plot_grid()` reads. A missing value, as from a
      # `lifecycle::deprecated()` default of a `.fn` written elsewhere, is no
      # setting:
      attr(out, "scrutiny") <- list(
        settings = new_settings(
          Filter(Negate(rlang::is_missing), args_const_vals),
          `!!`(defaults_const),
          `!!`(name_mapper(.name_test, "_map"))
        )
      )

      # Which columns a variadic argument selected, such as the summands of
      # `add_up_to_map()`: output of calls that selected others must not be
      # combined (see `R/bind-rows.R`):
      if (!is.null(reported_variadic)) {
        attr(out, "scrutiny")$cols_variadic <- names(cols_variadic)
      }

      # Unnest the key result column if it is a list, and rename it if
      # `.name_key_result` was specified:
      `!!!`(write_code_col_key_result(
        name_key_result = .name_key_result,
        name_data = rlang::expr(out),
        rename = is.null(.col_names)
      ))
    }),
    # The body relies on scrutiny's internal helpers, so the enclosure must
    # inherit from scrutiny's namespace. Never use the caller's environment: a
    # factory-made function exported from another package would then fail to
    # find them.
    env = rlang::env()
  )

  # --- End of the factory-made function, `fn_out()` ---

  # The body is spliced from code blocks that keep their source references if
  # the package is installed with `R_KEEP_PKG_SOURCE=yes`. These no longer
  # match the statements, which crashed `codetools` in `R CMD check`:
  fn_out <- utils::removeSource(fn_out)

  # Keep the enclosure of `fn_out()` small:
  rm(
    fn_name,
    formals_fn,
    formals_promoted,
    code_key_arg_checks,
    code_variadic,
    code_cols_helper,
    all_classes
  )

  # Key arguments go after `data` and the by-row arguments, led by the
  # variadic one if there is one. That one has no default, because guessing
  # which columns to test would silently test the wrong ones:
  fn_out <- insert_key_args(
    fn = fn_out,
    reported = .reported,
    insert_after = 1L + length(args_by_row),
    variadic = .reported_variadic
  )

  # A helper argument that was given is a column of the output, so
  # `function_map_seq()` and `function_map_total_n()` must not pass it again
  # when they re-test. They read this attribute to know which ones those are:
  attr(fn_out, "scrutiny_args_helper") <- args_helper
  # The other tiers take these as single values only, `digits_*` aside:
  attr(fn_out, "scrutiny_args_by_row") <- args_by_row
  # The result columns that the mapper may add, which `function_map_total_n()`
  # keeps a `constant` from being named like:
  attr(fn_out, "scrutiny_cols_result") <- c(names(.cols_derived), .col_names)
  # The other tiers derive their arguments from `.reported`, so they refuse a
  # mapper with a variadic argument:
  attr(fn_out, "scrutiny_arg_variadic") <- .reported_variadic

  fn_out
}

Try the scrutiny package in your browser

Any scripts or data that you put into this service are public.

scrutiny documentation built on Nov. 11, 2026, 1:09 a.m.