rework GRIMMER docs; fix #66

R/grim-map.R

@@ -21,8 +21,8 @@
 #'   case.
 #' @param merge_items Logical. If `TRUE` (the default), there will be no `items`
 #'   column in the output. Instead, values from an `items` column or argument
-#'   will be multiplied with values in the `n` column. This does not affect
-#'   GRIM-testing.
+#'   will be multiplied with values in the `n` column. This is only for
+#'   presentation and does not affect test results.
 #' @param percent Logical. Set `percent` to `TRUE` if the `x` values are
 #'   percentages. This will convert them to decimal numbers and adjust the
 #'   decimal count (i.e., increase it by 2). It also affects the `ratio` column.

R/grimmer-map-seq.R

@@ -27,11 +27,10 @@
 #'   consistent cases (from among those reported), not just inconsistent ones?
 #'   Default is `FALSE` because the focus should be on clarifying
 #'   inconsistencies.
-#' @param ... Arguments passed down to [`grimmer_map()`]. *(NOTE: Don't use the
-#'   `items` argument. It currently contains a bug that will be fixed in the
-#'   future.)*
+#' @param ... Arguments passed down to [`grimmer_map()`].
 
-#' @return A tibble (data frame) with detailed test results.
+#' @return A tibble (data frame) with detailed test results. See
+#' [`grimmer_map()`] for an explanation of the `reason` column.
 
 #' @section Summaries with [`audit_seq()`]: You can call [`audit_seq()`]
 #'   following `grimmer_map_seq()`. It will return a data frame with these

R/grimmer-map-total-n.R

@@ -35,9 +35,7 @@
 #' @param n_max Numeric. Maximal group size. Default is `NULL`, i.e., no
 #'   maximum.
 #' @inheritParams disperse_total
-#' @param ... Arguments passed down to [`grimmer_map()`]. *(NOTE: Don't use the
-#'   `items` argument. It currently contains a bug that will be fixed in the
-#'   future.)*
+#' @param ... Arguments passed down to [`grimmer_map()`].
 
 #' @include function-map-total-n.R
 #'
@@ -60,7 +58,8 @@
 #' half. `"forth"` means that `x2` from the input is paired with the larger
 #' dispersed `n`, whereas `"back"` means that `x1` is paired with the larger
 #' dispersed `n`.
-#' - Other columns from [`grimmer_map()`] are preserved.
+#' - Other columns from [`grimmer_map()`] are preserved. See there for an
+#' explanation of the `reason` column.
 
 #' @section Summaries with [`audit_total_n()`]: You can call
 #'   [`audit_total_n()`] following up on `grimmer_map_total_n()`

R/grimmer-map.R

@@ -3,34 +3,41 @@
 #'
 #' @description Call `grimmer_map()` to GRIMMER-test any number of combinations
 #'   of mean, standard deviation, sample size, and number of items. Mapping
-#'   function for GRIMMER-testing.
+#'   function for GRIMMER testing.
 #'
 #'   For summary statistics, call [`audit()`] on the results. Visualize results
 #'   using [`grim_plot()`], as with GRIM results.
 #'
 #' @param data Data frame with columns `x`, `sd`, `n`, and optionally `items`
 #'   (see documentation for `grim()`). Any other columns in `data` will be
 #'   returned alongside GRIMMER test results.
-#' @param items *(NOTE: Don't use the `items` argument. It currently contains a
-#'   bug that will be fixed in the future.)* Integer. If there is no `items`
-#'   column in `data`, this specifies the number of items composing the `x` and
-#'   `sd` values. Default is 1, the most common case.
-#' @param merge_items Logical. If `TRUE` (the default), there will be no `items`
-#'   column in the output. Instead, values from an `items` column or argument
-#'   will be multiplied with values in the `n` column. This does not affect
-#'   GRIM- or GRIMMER-testing.
+#' @param items Integer. If there is no `items` column in `data`, this specifies
+#'   the number of items composing the `x` and `sd` values. Default is `1`, the
+#'   most common case.
 #' @param x,sd,n Optionally, specify these arguments as column names in `data`.
 #' @param show_reason Logical (length 1). Should there be a `reason` column that
-#'   shows the reasons for inconsistencies (and `NA` for consistent values)?
-#'   Default is `FALSE`.
+#'   shows the reasons for inconsistencies and `"Passed all"` for consistent
+#'   values? Default is `FALSE`. See below for reference.
 #' @param rounding,threshold,symmetric,tolerance Further parameters of
-#'   GRIMMER-testing; see documentation for [`grimmer()`].
+#'   GRIMMER testing; see documentation for [`grimmer()`].
+#' @inheritParams grim_map
 
 #' @return A tibble with these columns --
 #' - `x`, `sd`, `n`: the inputs.
 #' - `consistency`: GRIMMER consistency of `x`, `n`, and `items`.
+#' - `reason`: If consistent, `"Passed all"`. If inconsistent, it says which
+#'   test was failed (see below).
 #' - `<extra>`: any columns from `data` other than `x`, `n`, and `items`.
 #'
+#' The `reason` columns refers to GRIM and the three GRIMMER tests (Allard
+#' 2018). Briefly, these are:
+#'
+#' 1. The reconstructed sum of squared observations must be a whole number.
+#' 2. The reconstructed SD must match the reported one.
+#' 3. The parity of the reconstructed sum of squared observations must match the
+#'    parity of the reconstructed sum of integers of which the reported means
+#'    are fractions; i.e., either both are even or both are odd.
+#'
 #' The tibble has the `scr_grimmer_map` class, which is recognized by the
 #' [`audit()`] generic. It also has the `scr_grim_map` class, so it can be
 #' visualized by [`grim_plot()`].
@@ -44,12 +51,19 @@
 #' 2. `all_cases`: total number of value sets.
 #' 3. `incons_rate`: proportion of GRIMMER-inconsistent value sets.
 #' 4. `fail_grim`: number of value sets that fail the GRIM test.
-#' 5. `fail_test1`: number of value sets that fail the first GRIMMER test (sum
-#'     of squares is a whole number).
-#' 6. `fail_test2`: number of value sets that fail the second GRIMMER test
-#'     (matching SDs).
-#' 7. `fail_test3`: number of value sets that fail the third GRIMMER test (equal
-#'     parity).
+#' 5. `fail_test1`: number of value sets that fail the first GRIMMER test (see
+#'     below).
+#' 6. `fail_test2`: number of value sets that fail the second GRIMMER test.
+#' 7. `fail_test3`: number of value sets that fail the third GRIMMER test.
+#'
+#' The `reason` columns refers to the three GRIMMER tests (see Allard 2018).
+#' These are:
+#'
+#' 1. The reconstructed sum of squared observations must be a whole number.
+#' 2. The reconstructed SD must match the reported one.
+#' 3. The parity of the reconstructed sum of squared observations must match the
+#'    parity of the reconstructed sum of integers of which the reported means
+#'    are fractions; i.e., either both are even or both are odd.
 
 #' @include audit.R grimmer.R function-map.R
 #'
@@ -78,7 +92,7 @@
 #'   grimmer_map() %>%
 #'   audit()
 
-
+# # Test interactively:
 # data <- pigs5
 # items <- 1
 # merge_items <- TRUE

R/grimmer.R

@@ -3,13 +3,16 @@
 
 # Analytic-GRIMMER (A-GRIMMER) was developed by Aurélien Allard
 # (https://aurelienallard.netlify.app/post/anaytic-grimmer-possibility-standard-deviations/).
-# His original algorithm received some modifications here, for three reasons:
-# First, tapping scrutiny's infrastructure for implementing error detection
+# His original algorithm received some modifications here, for these reasons:
+# -- Tapping scrutiny's infrastructure for implementing error detection
 # techniques; for example, functions like `reround()` and
-# `decimal_places_scalar()`. Second, changing the return value to logical, which
-# is the expected output from the basic implementation of any consistency test
-# within scrutiny. Third, adjusting variable names to the tidyverse style guide
-# and scrutiny's domain-specific conventions.
+# `decimal_places_scalar()`.
+# -- Changing the return value to logical, which is the expected output from the
+# basic implementation of any consistency test within scrutiny.
+# -- Adjusting variable names to the tidyverse style guide and scrutiny's
+# domain-specific conventions.
+# -- Adding support for multi-item scales (see `items` argument) via
+# `rsprite2::GRIMMER_test()`.
 
 
 # Translation of variable names -------------------------------------------
@@ -253,33 +256,31 @@ grimmer_scalar <- function(x, sd, n, items = 1, show_reason = FALSE,
 #' @param x String. The reported mean value.
 #' @param sd String. The reported standard deviation.
 #' @param n Integer. The reported sample size.
-#' @param 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.
+#' @param items Integer. The number of items composing the `x` and `sd` values.
+#'   Default is `1`, the most common case.
 #' @param 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`.
+#'   [`grimmer_map()`]. See there for explanation. Default is `FALSE`.
 #'
 #' @inheritParams grim
 #'
 #' @return 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.
+#'   implementation follows Allard's (2018) refined Analytic-GRIMMER algorithm.
+#'   It uses a variant of Analytic-GRIMMER first implemented in
+#'   \href{https://lukaswallrich.github.io/rsprite2/reference/GRIMMER_test.html}{`rsprite2::GRIMMER_test()`}
+#'   that can be applied to multi-item scales.
 #'
-#'   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.
+#'   The scrutiny version embeds GRIMMER in the broader system of consistency
+#'   testing, as laid out in
+#'   \href{https://lhdjung.github.io/scrutiny/articles/consistency-tests-in-depth.html}{*Consistency
+#'   tests in depth*}. The `grimmer()` function
+#'   is a vectorized (multiple-case) version of this basic implementation. For
+#'   more context and variable name translations, see the top of the R/grimmer.R
+#'   source file.
 
 #' @references Allard, A. (2018). Analytic-GRIMMER: a new way of testing the
 #'   possibility of standard deviations.