grimmer_map: GRIMMER-test many cases at once

grimmer_mapR Documentation

GRIMMER-test many cases at once

Description

grimmer_map() applies grimmer() to every row of a data frame with means, standard deviations, and sample sizes.

Call audit() on the output for summary statistics. grim_plot_grid() accepts it as well.

Usage

grimmer_map(
  data,
  digits_x,
  digits_sd,
  x = NULL,
  sd = NULL,
  n = NULL,
  ...,
  items_averaged,
  data_type,
  sd_meaning = c("sd_sample", "sd_pop", "sd_sample_or_pop", "se"),
  rounding = "up_or_down",
  threshold = 5,
  symmetric = FALSE
)

Arguments

data

Data frame with columns x, sd, and n, and optionally items_averaged, data_type, digits_x, and digits_sd. Any other columns are returned alongside the results.

digits_x, digits_sd

Integer. The number of decimal places in x and sd, including trailing zeros. There are no defaults, 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, they are taken from digits_x and digits_sd columns of data.

x, sd, 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, data_type

As in grim_map(), for x and sd.

rounding, threshold, symmetric, sd_meaning

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

Value

A tibble with these columns:

  • x, sd, n: the inputs.

  • items_averaged: the number of items averaged into each score.

  • data_type: the kind of data, as given.

  • digits_x, digits_sd: the numbers of decimal places, as given.

  • consistency: GRIMMER consistency of x, sd, n, and items_averaged. NA for a case that cannot be decided, such as one with a missing value.

  • reason: "Passed all" if consistent, or "Continuous data" if the test does not apply; otherwise the test that failed, or why the case cannot be decided.

  • Any other columns from data.

The reason column refers to GRIM and the GRIMMER tests of Allard (2018):

  1. The reconstructed sum of squared observations must be a whole number, and one that n whole numbers with the reconstructed sum can reach: at least the sum of squares of these numbers as close together as possible. For n < 5, some larger sums of squares are impossible, too.

  2. The reconstructed SD must match the reported one. Test 1 implies this, so it is never a reason.

  3. The parity of the reconstructed sum of squared observations must match that of the reconstructed sum of the values.

A negative sd gives "Negative SD".

Under sd_meaning = "sd_sample_or_pop", a consistent value set gives "Passed all (sample SD)" or, if it passes as a population SD only, "Passed all (population SD)". If the two conventions fail for different reasons, the reason names both, and audit() counts the sample SD's, as under the default sd_meaning.

The tibble has the class scrutiny_grimmer_map, which is recognized by audit() and grim_plot_grid().

Summaries with audit()

audit() on grimmer_map() output returns a tibble with one row and these columns:

  1. all_cases: total number of value sets.

  2. incon_cases: number of GRIMMER-inconsistent value sets.

  3. emp_incon: proportion of GRIMMER-inconsistent value sets.

  4. fail_grim: number of value sets that fail GRIM.

  5. fail_test1, fail_test3: number of value sets that fail GRIMMER's first or third test. Test 2 is implied by test 1, so it never fails.

References

Allard, A. (2018). Analytic-GRIMMER: a new way of testing the possibility of standard deviations. https://aurelienallard.netlify.app/post/anaytic-grimmer-possibility-standard-deviations/

Anaya, J. (2016). The GRIMMER test: A method for testing the validity of reported measures of variability. PeerJ Preprints. https://peerj.com/preprints/2400v1/

See Also

explain_map() and explain_print() to explain each row's result in plain words.

Examples

# Use `grimmer_map()` on data like these:
pigs5

# The `consistency` column shows whether the values to its left are
# GRIMMER-consistent. If they aren't, the `reason` column gives the reason:
pigs5 |>
  grimmer_map(
    digits_x = 2,
    digits_sd = 2,
    items_averaged = 1,
    data_type = "integer"
  )

# Get summaries with `audit()`:
pigs5 |>
  grimmer_map(
    digits_x = 2,
    digits_sd = 2,
    items_averaged = 1,
    data_type = "integer"
  ) |>
  audit()

# Explain the results in plain words:
pigs5 |>
  grimmer_map(
    digits_x = 2,
    digits_sd = 2,
    items_averaged = 1,
    data_type = "integer"
  ) |>
  explain_print(1:2)

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