The GRIMMER test (granularity-related inconsistency of means mapped to error repeats)

grimmer() checks if reported mean and SD values of integer data are mathematically consistent with the reported sample size and the number of items that compose the mean value. It works much like grim().

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

Usage

grimmer(
  x,
  sd,
  n,
  items = 1,
  show_reason = FALSE,
  rounding = "up_or_down",
  threshold = 5,
  symmetric = FALSE,
  tolerance = .Machine$double.eps^0.5
)

Arguments

x: String. The reported mean value.
sd: String. The reported standard deviation.
n: Integer. The reported sample size.
items: (NOTE: Don't use the items argument. It currently contains a bug that will be fixed in the future.) Integer. The number of items composing the x and sd values. Default is 1, the most common case.
show_reason: Logical. For internal use only. If set to TRUE, the output is a list of length-2 lists which also contain the reasons for inconsistencies. Don't specify this manually; instead, use show_reason in grimmer_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().

Value

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

Details

GRIMMER was originally devised by Anaya (2016). The present implementation follows Allard's (2018) refined Analytic-GRIMMER (A-GRIMMER) algorithm. It adapts the R function aGrimmer() provided by Allard and modifies it to accord with scrutiny's standards, as laid out in vignette("consistency-tests-in-depth"), sections 1-2. The resulting grimmer() function, then, is a vectorized version of this basic implementation. For more context and variable name translations, see the top of the R/grimmer.R, the source file.

The present implementation can differ from Allard's in a small number of cases. In most cases, this means that the original flags a value set as inconsistent, but scrutiny's grimmer*() functions don't. For details, see the end of tests/testthat/test-grimmer.R, the grimmer() test file.

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/

Examples

# A mean of 5.23 is not consistent with an SD of 2.55
# and a sample size of 35:
grimmer(x = "5.23", sd = "2.55", n = 35)
#>  5.23 
#> FALSE 

# However, mean and SD are consistent with a
# sample size of 31:
grimmer(x = "5.23", sd = "2.55", n = 31)
#> 5.23 
#> TRUE 

# For a scale composed of two items:
grimmer(x = "2.74", sd = "0.96", n = 63, items = 2)
#> Warning: The `items` argument in GRIMMER functions doesn't currently work the way it
#> should.
#> 2.74 
#> TRUE