randomizationInference (version 1.0.4)

randTest: Randomization-Based Hypothesis Testing

Description

Conducts randomization-based hypothesis tests according to the specified test statistic(s), assignment mechanism, and null and alternative hypotheses.

Usage

randTest(
  y,
  w,
  nrand,
  calcTestStat,
  calcOptions = NULL,
  calcPO = zeroEffect,
  poOptions = NULL,
  randOptions = list(
    type = c("complete", "block", "Latin", "user.defined"),
    block = NULL,
    row = NULL,
    col = NULL
  ),
  userRand = NULL,
  userOptions = NULL,
  null = NULL,
  alternative = c("two.sided", "greater", "less")
)

Arguments

y

a vector or matrix of outcomes.

w

a vector (or matrix, when multiple treatment factors are present) of assignments.

nrand

a number specifying the desired number of random hypothetical assignments.

calcTestStat

a function to calculate the specified test statistic(s).

calcOptions

a list of options for calculating the test statistic(s) (if necessary).

calcPO

a function to calculate potential outcomes (defaults to zeroEffect).

poOptions

a list of options for calculating potential outcomes (if necessary).

randOptions

a list of options governing the random assignment mechanism.

userRand

a function to generate random assignments (if necessary).

userOptions

a list of options governing the user-defined random assignment mechanism (if necessary).

null

a number or numeric vector specifying the comparison value(s) under the null hypothesis.

alternative

a character string specifying the alternative hypothesis, must be one of the following: "two.sided" (default), "greater", or "less".

Value

A list containing the following elements:

perm_stats

a vector or matrix of hypothetical test statistic values.

obs_stat

the observed test statistic value(s).

null

a number or numeric vector specifying the comparison value(s) under the null hypothesis.

alternative

a character string specifying the alternative hypothesis.

pvalue

the randomization-based p-value(s).

Details

The inputs to calcTestStat are y, w, and calcOptions (if necessary). The output of calcTestStat is a number or numeric vector representing the test statistic value(s). Several common test statistics (diffMeans, anovaF, diffMeansVector) are built-in for convenience. calcTestStat can also be a custom function, as long as the inputs and output are as described above. If multiple test statistics are tested simultaneously, users should be wary of multiple comparisons and make appropriate adjustments (e.g., Bonferroni corrections).

The inputs to calcPO are y, w, w_new (a vector or matrix of modified assignments), and poOptions (if necessary). The output of calcPO is a vector of potential outcomes under the modified assignments. Two common potential outcome calculations (zeroEffect (default) and constEffect) are built-in for convenience. calcPO can also be a custom function, as long as the inputs and output are as described above.

If unspecified, randOptions$type defaults to "complete". If randOptions$type equals "block", then randOptions$block must be specified. If randOptions$type equals "Latin", then randOptions$row and randOptions$col must be specified. If randOptions$type equals "user.defined", then userRand must be specified.

The inputs to userRand are nrand and userOptions (if necessary).

If null is specified, its length must equal the length of the output of calcTestStat. If unspecified, null defaults to 0 or an appropriately sized vector of 0's.

alternative = "greater" is the alternative that the test statistic is greater than the comparison value.

References

Wu, C. F. J. and Hamada, M. (2009) Experiments, Planning, Analysis and Optimization (2nd ed), Wiley.

Moore, David S., and George P. McCabe (1989). Introduction to the Practice of Statistics. Original source: study conducted by Jim Baumann and Leah Jones of the Purdue University Education Department.

See Also

diffMeans, anovaF, diffMeansVector, zeroEffect, constEffect, completeRand, blockRand, latinRand, randInterval, randPlot

Examples

# NOT RUN {
# Completely randomized design example
# with one treatment factor at two levels
w <- c(rep(0, 5), rep(1, 5))
y <- rnorm(10, mean = 0, sd = 1)
# Two-sided test
twoSidedTest <- randTest(y, w, nrand = 50, calcTestStat = diffMeans)
# One-sided test
oneSidedTest <- randTest(
  y,
  w,
  nrand = 50,
  calcTestStat = diffMeans,
  alternative = "greater"
)
# Two=sided test with non-zero null hypothesis
nonZeroTest <- randTest(
  y,
  w,
  nrand = 50,
  calcTestStat = diffMeans,
  calcPO = constEffect,
  poOptions = list(tau = 2),
  null = 2
)

# Randomized block design example
# with one treatment factor at three levels
x <- rep(1:3, 4)
w_block <- rep(1:4, 3)
y_block <- rnorm(12, mean = x, sd = 1)
blockTest <- randTest(
  y_block,
  w_block,
  nrand = 50,
  calcTestStat = anovaF,
  calcOptions = list(block = x),
  randOptions = list(type = "block", block = x)
)

# 4x4 Latin square example (from the Wu/Hamada reference)
row <- rep(1:4, 4)
col <- c(rep(1, 4), rep(2, 4), rep(3, 4), rep(4, 4))
w_latin <- c(
  "C", "D", "B", "A", "A", "B", "D", "C",
  "D", "C", "A", "B", "B", "A", "C", "D"
)
y_latin <- c(
  235, 236, 218, 268, 251, 241, 227, 229,
  234, 273, 274, 226, 195, 270, 230, 225
)
latinTest <- randTest(
  y_latin,
  w_latin,
  nrand = 50,
  calcTestStat = anovaF,
  calcOptions = list(row = row, col = col),
  randOptions = list(type = "Latin", row = row, col = col)
)

# 2^3 factorial design example
# three treatment factors (OT, CP, and ST) at two levels each
OT <- c(-1, -1, -1, -1, 1, 1, 1, 1)
CP <- c(-1, -1, 1, 1, -1, -1, 1, 1)
ST <- rep(c(-1, 1), 4)
w_fac <- cbind(OT, CP, ST)
y_fac <- c(67, 79, 61, 75, 59, 90, 52, 87)
# Testing the main effect of factor "OT"
facTest1 <- randTest(
  y_fac,
  w_fac,
  nrand = 50,
  calcTestStat = diffMeans,
  calcOptions = list(factor = 1, pair = c(-1, 1))
)
# Testing all three main effects simultaneously
facTest2 <- randTest(
  y_fac,
  w_fac,
  nrand = 50,
  calcTestStat = diffMeansVector,
  calcOptions = list(
    factors = 1:3,
    pairs = matrix(rep(c(-1, 1), 3), ncol = 2, byrow = TRUE)
  )
)
# Testing all contrasts simultaneously
w_facNew <- cbind(OT, CP, ST, OT * CP, OT * ST, CP * ST, OT * CP * ST)
facTest3 <- randTest(
  y_fac,
  w_facNew,
  nrand = 50,
  calcTestStat = diffMeansVector,
  calcOptions = list(
    factors = 1:7,
    pairs = matrix(rep(c(-1, 1), 7), ncol = 2, byrow = TRUE)
  )
)

# Reading comprehension pre- and post-test example
data(reading)
# Ignoring blocks
readingTest1 <- randTest(
  y = reading$Diff1,
  w = reading$Group,
  nrand = 50,
  calcTestStat = anovaF
)
# Testing within-block pairwise effects
readingTest2 <- randTest(
  y = reading$Diff1,
  w = reading$Group,
  nrand = 50,
  calcTestStat = withinBlockEffects,
  calcOptions = list(
    block = reading$Block,
    pairs = rbind(
      c("Basal", "DRTA"),
      c("Basal", "Strat"),
      c("DRTA", "Strat"),
      c("Basal", "DRTA"),
      c("Basal", "Strat"),
      c("DRTA", "Strat")
    ),
    blockindex = c(rep(1, 3), rep(2, 3))
  ),
  randOptions = list(type = "block", block = reading$Block)
)
# }