scrutiny (version 0.5.0)

grim: The GRIM test (granularity-related inconsistency of means)

Description

grim() checks if a reported mean value of integer data is mathematically consistent with the reported sample size and the number of items that compose the mean value.

Set percent to TRUE if x is a percentage. This will convert x to a decimal number and adjust the decimal count accordingly.

The function is vectorized, but it is recommended to use grim_map() for testing multiple cases.

Usage

grim(
  x,
  n,
  items = 1,
  percent = FALSE,
  show_rec = FALSE,
  rounding = "up_or_down",
  threshold = 5,
  symmetric = FALSE,
  tolerance = .Machine$double.eps^0.5
)

Value

Logical. TRUE if x, n, and items are mutually consistent, FALSE if not.

Arguments

x

String. The reported mean or percentage value.

n

Integer. The reported sample size.

items

Numeric. The number of items composing x. Default is 1, the most common case.

percent

Logical. Set percent to TRUE if x is a percentage. This will convert it to a decimal number and adjust the decimal count (i.e., increase it by 2). Default is FALSE.

show_rec

Logical. For internal use only. If set to TRUE, the output is a matrix that also contains intermediary values from GRIM-testing. Don't specify this manually; instead, use show_rec in grim_map(). Default is FALSE.

rounding

String. Rounding method or methods to be used for reconstructing the values to which x will be compared. Default is "up_or_down" (from 5).

threshold

Numeric. If rounding is set to "up_from", "down_from", or "up_from_or_down_from", set threshold to the number from which the reconstructed values should then be rounded up or down. Otherwise, this argument plays no role. Default is 5.

symmetric

Logical. Set symmetric to TRUE if the rounding of negative numbers with "up", "down", "up_from", or "down_from" should mirror that of positive numbers so that their absolute values are always equal. Default is FALSE.

tolerance

Numeric. Tolerance of comparison between x and the possible mean or percentage values. Default is circa 0.000000015 (1.490116e-08), as in dplyr::near().

Details

The x values need to be strings because only strings retain trailing zeros, which are as important for the GRIM test as any other decimal digits.

Use restore_zeros() on numeric values (or values that were numeric values at some point) to easily supply the trailing zeros they might once have had. See documentation there.

Browse the source code in the grim.R file. grim() is a vectorized version of the internal grim_scalar() function found there.

References

Brown, N. J. L., & Heathers, J. A. J. (2017). The GRIM Test: A Simple Technique Detects Numerous Anomalies in the Reporting of Results in Psychology. Social Psychological and Personality Science, 8(4), 363–369. https://journals.sagepub.com/doi/10.1177/1948550616673876

See Also

grim_map() applies grim() to any number of cases at once.

Examples

# A mean of 5.19 is not consistent with a sample size of 28:
grim(x = "5.19", n = 28)    # `x` in quotes!

# However, it is consistent with a sample size of 32:
grim(x = "5.19", n = 32)

# For a scale composed of two items:
grim(x = "2.84", n = 16, items = 2)

# With percentages instead of means -- here, 71%:
grim(x = "71", n = 43, percent = TRUE)