scrutiny (version 0.5.0)

disperse: Vary hypothetical group sizes

Description

Some published studies only report a total sample size but no group sizes. However, group sizes are crucial for consistency tests such as GRIM. Call disperse() to generate possible group sizes that all add up to the total sample size, if that total is even.

disperse2() is a variant for odd totals. It takes two consecutive numbers and generates decreasing values from the lower as well as increasing values from the upper. In this way, all combinations still add up to the total.

disperse_total() directly takes the total sample size, checks if it's even or odd, splits it up accordingly, and applies disperse() or disperse2(), respectively.

These functions are primarily intended as helpers. They form the backbone of grim_map_total_n() and all other functions created with function_map_total_n().

Usage

disperse(
  n,
  dispersion = 0:5,
  n_min = 1L,
  n_max = NULL,
  constant = NULL,
  constant_index = NULL
)
disperse2(
  n,
  dispersion = 0:5,
  n_min = 1L,
  n_max = NULL,
  constant = NULL,
  constant_index = NULL
)
disperse_total(
  n,
  dispersion = 0:5,
  n_min = 1L,
  n_max = NULL,
  constant = NULL,
  constant_index = NULL
)

Value

A tibble (data frame) with these columns:

• n includes the dispersed n values. Every pair of consecutive rows has n values that each add up to the total.

• n_change records how the input n was transformed to the output n. In disperse2(), the n_change strings label the lower of the input n values n1 and the higher one n2.

Arguments

n

Numeric:

• In disperse(), single number from which to go up and down. This should be half of an even total sample size.

• In disperse2(), the two consecutive numbers closest to half of an odd total sample size (e.g., c(25, 26) for a total of 51).

• In disperse_total(), the total sample size.

dispersion

Numeric. Vector that determines the steps up and down from n (or, in disperse_total(), from half n). Default is 0:5.

n_min

Numeric. Minimal group size. Default is 1L.

n_max

Numeric. Maximal group size. Default is NULL, i.e., no maximum.

constant

Optionally, add a length-2 vector or a list of length-2 vectors (such as a data frame with exactly two rows) to accompany the pairs of dispersed values. Default is NULL, i.e., no constant values.

constant_index

Integer (length 1). Index of constant or the first constant column in the output tibble. If NULL (the default), constant will go to the right of n_change.

Details

If any group size is less than n_min or greater than n_max, it is removed. The complementary size of the other group is also removed.

constant values are pairwise repeated. That is why constant must be a length-2 atomic vector or a list of such vectors. If constant is a data frame or some other named list, the resulting columns will have the same names as the list-element names. If the list is not named, the new column names will be "constant1", "constant2", etc; or just "constant", for a single pair.

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

See Also

function_map_total_n(), grim_map_total_n(), and seq_distance_df().

Examples

# For a total sample size of 40,
# set `n` to `20`:
disperse(n = 20)

# Specify `dispersion` to control
# the steps up and down from `n`:
disperse(n = 20, dispersion = c(3, 6, 10))

# In `disperse2()`, specify `n` as two
# consecutive numbers -- i.e., group sizes:
disperse2(n = c(25, 26))

# Use the total sample size directly
# with `disperse_total()`. An even total
# internally triggers `disperse()`...
disperse_total(n = 40)

# ...whereas an odd total triggers `disperse2()`:
disperse_total(n = 51)

# You may add values that repeat along with the
# dispersed ones but remain constant themselves.
# Such values can be stored in a length-2 vector
# for a single column...
disperse_total(37, constant = c("5.24", "3.80"))

# ... or a list of length-2 vectors for multiple
# columns. This includes data frames with 2 rows:
df_constant <- tibble::tibble(
  name = c("Paul", "Mathilda"), age = 27:28,
  registered = c(TRUE, FALSE)
)
disperse_total(37, constant = df_constant)