grim_map_seq: GRIM-test values around the reported ones

grim_map_seqR Documentation

GRIM-test values around the reported ones

Description

grim_map_seq() varies the reported means and sample sizes a few steps up and down and GRIM-tests each resulting value set. This shows whether a small error in reporting or computing could explain an inconsistency.

Call audit() on the output for summary statistics.

Usage

grim_map_seq(
  data,
  digits_x,
  x = NULL,
  n = NULL,
  ...,
  items_averaged,
  data_type,
  x_meaning = c("mean", "percentage"),
  rounding = "up_or_down",
  threshold = 5,
  symmetric = FALSE,
  show_rec = FALSE,
  var = c("x", "n"),
  dispersion = 1:5,
  out_min = "auto",
  out_max = "auto",
  include_reported = FALSE,
  include_consistent = FALSE
)

Arguments

data

A data frame that grim_map() could take.

digits_x

Integer. The number of decimal places in x, including trailing zeros. There is no default, since a numeric value does not keep them (1.40 is 1.4). Either a single number for the whole column or one number per row of data. If left out, it is taken from a digits_x column of data. It also sets the step size for dispersing x.

x, n

Optionally, the names of the columns in data that contain these values, if they differ from the defaults.

...

These dots must be empty. Every argument after them must be named in full.

items_averaged

Integer. As in grim(): the number of items averaged into each score, not the number of scale points. Give it as an argument or as a column of data; there is no default. It is returned as a column.

data_type

String. As in grim(): "integer" or "continuous". Like items_averaged, give it as an argument or as a column of data; there is no default. It is returned as a column.

x_meaning

String. What the x values are: "mean" (the default) or "percentage". Percentages are divided by 100 and tested with two more decimal places. It applies to the whole call, so test a table that mixes means and percentages in parts, as in the examples of grim_map(). The parts record different settings, so they can't be combined with dplyr::bind_rows(). See Defaults in grim().

rounding, threshold, symmetric

Passed on to grim(), whose section Defaults explains the defaults.

show_rec

Logical. If TRUE, the reconstructed numbers are returned as columns; see Reconstructed numbers in grim_map(). Default is FALSE.

var

String. The variables to disperse. Default is c("x", "n").

dispersion

Numeric. Steps up and down from the reported values, in units of the last decimal place. Default is 1:5.

out_min, out_max

Limits on the dispersed values. Both default to "auto", which keeps n at 1 or above and leaves x unbounded. A number applies to every dispersed variable, and NULL removes the limit.

include_reported

Logical. Should the reported values themselves be part of the sequences? Default is FALSE.

include_consistent

Logical. Should consistent value sets be dispersed as well, not just inconsistent ones? Default is FALSE.

Value

A tibble with the columns of grim_map() output plus diff_var, the number of steps between the tested value and the reported one; case, the row number of the reported value set in data; and var, the dispersed variable. Other columns of data, such as study labels, play no role in the test and are dropped; use case to join them back.

Summaries with audit()

audit() on grim_map_seq() output returns a tibble with one row per case and these columns:

  • x and n: the reported values, with items_averaged, data_type, and their consistency.

  • hits_total: the number of GRIM-consistent value sets found within the dispersion range.

  • hits_x, hits_n: the number found by varying x and n, respectively. If both include_reported and include_consistent are TRUE, a consistent reported value set is counted as well: once per variable here, and once in hits_total.

  • diff_x: the distance from x to the nearest consistent dispersed value, in dispersion steps. diff_x_up and diff_x_down are the signed steps to the nearest consistent value above and below (⁠_down⁠ is negative).

  • diff_n, diff_n_up, diff_n_down: the same for n.

A count or distance is NA if it depends on a dispersed value set whose consistency is NA, on a variable whose reported value is missing, which is not dispersed, or on rows removed from the output, as by filter().

Call audit() again on that summary to summarize these columns further. na_count and na_rate there count the cases without a consistent value within the dispersion range, and those that a missing value leaves unknown.

Examples

# `grim_map_seq()` takes the same input as `grim_map()`:
pigs1

out <- grim_map_seq(
  pigs1,
  digits_x = 2,
  items_averaged = 1,
  data_type = "integer",
  include_consistent = TRUE
)
out

# Case-wise summaries:
out |>
  audit()

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