randTest {randomizationInference} | R Documentation |
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 |
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: |
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.
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). |
Author(s)
Joseph J. Lee and Tirthankar Dasgupta
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
# 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)
)