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

Source:`R/grimmer.R`

`grimmer.Rd`

`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*Integer. The number of items composing the`items`

argument. It currently contains a bug that will be fixed in the future.)`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()`

.

## 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
```