| function_map_total_n {scrutiny} | R Documentation |
Create new *_map_total_n() functions
Description
function_map_total_n() is the engine that powers functions
such as grim_map_total_n(). It creates new, "factory-made" functions
for consistency tests such as GRIM or GRIMMER. The new functions take
reported summary statistics (e.g., means) and apply those tests in cases
where only a total sample size is known, not group sizes.
This works by making disperse_total() create multiple pairs of
hypothetical group sizes, all of which add up to the reported total. There
need to be exactly two groups.
For background and more examples, see the total-n mapper section of Consistency tests in depth.
Usage
function_map_total_n(
.fun,
.reported,
.name_test,
.name_key_result = "consistency",
.name_class = NULL,
.dispersion = 0:5,
.n_min = 1L,
.n_max = NULL,
.constant = NULL,
.constant_index = NULL,
...
)
Arguments
.fun |
Function such as |
.reported |
String. Names of the columns containing group-specific
statistics that were reported alongside the total sample size(s). They will
be tested for consistency with the hypothetical group sizes. Examples are
|
.name_test |
String (length 1). The name of the consistency test, such
as |
.name_key_result |
(Experimental) Optionally, a single string that will
be the name of the key result column in the output. Default is
|
.name_class |
String. If specified, the tibbles returned by the
manufactured function will inherit this string as an S3 class. Default is
|
.dispersion, .n_min, .n_max, .constant, .constant_index |
Arguments passed
down to |
... |
These dots must be empty. |
Details
If functions created by function_map_total_n() are exported from
other packages, they should be written as if they were created with
purrr
adverbs; see explanations there, and examples in the
export
section of Consistency tests in depth.
This function is a so-called function factory: It produces other functions,
such as grim_map_total_n(). More specifically, it is a function
operator because it also takes functions as inputs, such as grim_map().
See Wickham (2019), ch. 10-11.
Value
A function such as these:
| Manufactured function | Reported statistics | Test vignette |
grim_map_total_n() | "x" | vignette("grim") |
grimmer_map_total_n() | "x", "sd" | vignette("grimmer") |
debit_map_total_n() | "x", "sd" | vignette("debit") |
The factory-made function will also have dots, ..., to pass arguments
down to .fun, i.e., the basic mapper function.
Conventions
The name of a function returned by
function_map_total_n() should mechanically follow from that of
the input function. For example, grim_map_total_n() derives
from grim_map(). This pattern fits best if the input function itself
is named after the test it performs on a data frame, followed by _map:
grim_map() applies GRIM, grimmer_map() applies GRIMMER, etc.
Much the same is true for the classes of data frames returned by the
manufactured function via the .name_class argument of
function_map_total_n(). It should be the function's own name preceded
by the name of the package that contains it, or by an acronym of that
package's name. Therefore, some existing classes are
scr_grim_map_total_n and scr_grimmer_map_total_n.
References
Bauer, P. J., & Francis, G. (2021). Expression of Concern: Is It Light or Dark? Recalling Moral Behavior Changes Perception of Brightness. Psychological Science, 32(12), 2042–2043. https://journals.sagepub.com/doi/10.1177/09567976211058727
Wickham, H. (2019). Advanced R (Second Edition). CRC Press/Taylor and Francis Group. https://adv-r.hadley.nz/index.html
See Also
Examples
# Function definition of `grim_map_total_n()`:
grim_map_total_n <- function_map_total_n(
.fun = grim_map,
.reported = "x",
.name_test = "GRIM"
)