grim_explain: Explain a GRIM test step by step

In scrutiny: Error Detection in Science

Explain a GRIM test step by step

Description

grim_explain() tests a single mean like grim() does, but also lays out the calculation in plain words: which true means the reported one could stand for, which sums of the underlying integers follow from them, and whether any of these sums is possible.

The text is built from the numbers that decide the test itself, so it always agrees with grim().

Usage

grim_explain(
  x,
  n,
  digits_x,
  items_averaged,
  data_type,
  x_meaning = c("mean", "percentage"),
  rounding = "up_or_down",
  threshold = 5,
  symmetric = FALSE
)

Arguments

x	Numeric. The reported mean or percentage.
n	Integer. The reported sample size.
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).
items_averaged	Integer. The number of items averaged into each respondent's score: 1 for a single item or the percentage of participants with some answer, 4 for the mean of a four-item scale, 10 for the average percent correct on a ten-question test. Not the number of scale points. No default.
data_type	String. The kind of data that x summarizes. No default. "integer": whole numbers, such as answers on a rating scale, counts, or yes/no answers for a percentage. "continuous": anything else, such as body mass index or a visual analogue scale. The test does not apply, so the result is TRUE, or NA for a value set that describes no data, such as one with n = 0. If data_type is NA, the result is NA unless both types give the same one.
x_meaning	String. What x is: "mean" (the default) or "percentage". A percentage is divided by 100 and tested with two more decimal places, as the proportion it is. See Defaults in grim().
rounding	String. The rounding method assumed to have produced x. Default is "up_or_down", which accepts either direction; see Defaults in grim(). The others are "up_from_or_down_from", "ceiling_or_floor", "up", "down", "even", "up_from", "down_from", "ceiling", "floor", "trunc", "anti_trunc", "ties_up", "ties_down", "ties_away", "ties_zero", and "ties_even". See vignette("rounding-options", package = "roundwork").
threshold	Numeric. For rounding = "up_from", "down_from", or "up_from_or_down_from", the point within a step at which rounding switches direction, in tenths of a step. Default is 5. Ignored otherwise.
symmetric	Logical. If TRUE, negative numbers are rounded like their absolute values (-2.5 like 2.5) under "up", "down", and the "*_from" methods. Default is FALSE. Must not be TRUE with a "ties_*" rounding method, which already fixes the direction; see roundwork::reround().

Value

An object of class scrutiny_explain: a list with the result as consistency (TRUE, FALSE, or NA), the explanation's paragraphs, and the test and its inputs. It prints as the explanation.

See Also

grimmer_explain() and debit_explain() for the other tests, and explain_map() for mapper output.

Examples

grim_explain(
  x = 5.19,
  n = 28,
  digits_x = 2,
  items_averaged = 1,
  data_type = "integer"
)

grim_explain(
  x = 5.19,
  n = 32,
  digits_x = 2,
  items_averaged = 1,
  data_type = "integer"
)

grim_explain(
  x = 71,
  n = 43,
  digits_x = 0,
  items_averaged = 1,
  data_type = "integer",
  x_meaning = "percentage"
)

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