choplump {choplump} | R Documentation |
Choplump Test
Description
The choplump test is a two-sample permutation test, that is used when there are many responses that are zero with some positive.
Usage
choplump(x, ...)
## Default S3 method:
choplump(x, y, alternative = c("two.sided", "less", "greater"),
use.ranks=TRUE, exact = NULL, method=NULL,
methodRule=methodRule1, methodRuleParms=c(10^4),
nMC=10^4-1,seed=1234321, printNumCalcs=TRUE, ...)
## S3 method for class 'formula'
choplump(formula, data, subset, na.action, ...)
Arguments
x |
a numeric vector of responses in first group, or a formula. Should have some zeros and the rest positive. |
y |
numeric vector of responses in second group |
alternative |
a character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater" or "less". |
use.ranks |
a logical indicating whether to use ranks for the responses |
exact |
a logical indicating whether an exact p-value should be computed (see details) |
method |
a character value, one of 'approx','exact','exactMC'. If NULL method chosen by methodRule |
methodRule |
a function used to choose the method (see details). Ignored if method is not NULL |
methodRuleParms |
a vector of parameters passed to methodRule. Ignored if method is not NULL |
nMC |
number of Monte Carlo replications, used if method='exactMC', ignored otherwise |
seed |
value used in |
printNumCalcs |
logical, print number of calculations of test statistic for exact tests |
formula |
a formula of the form lhs~rhs where lhs is a numeric variable giving the data values and rhs a factor with two levels giving the corresponding groups. |
data |
an optional matrix or data frame containing the variables in the formula |
subset |
an optional vector specifying a subset of observations to be used. |
na.action |
a function which indicates what should happen when the data contain NAs. Defaults to getOption("na.action"). |
... |
further arguments to be passed to or from methods. |
Details
Consider a randomized trial where one wants to compare the responses in two groups, but there are many zeros in both groups. For example, in an HIV vaccine trial the response could be level of virus in the blood and very many in both groups will have zero values for the response. In order to gain power, the choplump test removes the same proportion of zeros from both groups, and compares the standardized means between the values left. The test can use ranks to obtain a Wilcoxon-like test. The choplump is a formal permutation test (in other words for each permutation, the chopping is redone) so the type I error is less than the nominal significance level either exactly (for exact methods) or approximately (for the approximate method).
There are a choice of 3 different methods to calculate the p-values:
approx, an approximation method, see vignette("choplumpComputation");
exact, an exact method, see vignette("choplumpComputation");
exactMC, exact method using Monte Carlo resampling with nMC
resamples.
The associated functions for the above methods (choplumpApprox
, choplumpExact
,
choplumpExactMC
), are internal and not to be called directly.
A methodRule function has 4 input values: W (a vector of all responses), Z (a vector of 0 or 1 denoting group membership),
exact (a logical value, same as exact
in the choplump call), and parms (the vector of parameters, same as methodRuleParms
in the choplump call). The methodRule function returns a character vector with one of the allowed methods.
The default method rule is methodRule1
. It gives a result of 'approx' if either exact=FALSE
or exact=NULL and there are more than parms
calculations of the test statistic. It gives a result
of 'exact' if there are less than methodRuleParms calculations of the test statistic, and it gives a result of
'exactMC' if exact=TRUE and there are more than methodRuleParms calculations of the test statistic.
Value
A htest object, a list with elements
p.value |
p value associated with alternative |
alternative |
description of alternative hypothesis |
p.values |
a vector giving lower, upper, and two-sided p-values |
METHOD |
a character vector describing the test |
data.name |
a character vector describing the two groups |
Author(s)
M.P. Fay
References
Follmann, DA, Fay, MP, and Proschan, MA. (2009) ”Chop-lump tests for Vaccine trials” Biometrics 65: 885-893. (see /doc/choplump.pdf)
Examples
set.seed(1)
Ntotal<-200
Mtotal<-12
Z<-rep(0,Ntotal)
Z[sample(1:Ntotal,Ntotal/2,replace=FALSE)]<-1
test<-data.frame(W=c(rep(0,Ntotal-Mtotal),abs(rnorm(Mtotal))),Z=Z)
## defaults to asymptotic approximation if
## the number of calculations of the test
## statistic is greater than parms
## see help for methodRule1
choplump(W~Z,data=test,use.ranks=TRUE)
## alternate form
cout<-choplump(test$W[test$Z==0],test$W[test$Z==1],use.ranks=TRUE,exact=TRUE)
cout
cout$p.values