R: Exact or Asymptotic 2-sample, k-sample, and trend permutation...

perm {perm} | R Documentation

## Exact or Asymptotic 2-sample, k-sample, and trend permutation tests

### Description

These functions perform either: two-sample permutation tests (`permTS`), k-sample permutation tests (`permKS`), or trend permutation tests (`permTREND`). The test function can be transformed to a linear function of the scores times the covariate, where the covariate may be either a factor or character vector with two (`permTS`) or more (`permKS`) levels or a numeric vector (`permTREND`). By using suitable scores one can create for example, the permutation t-test (general scores), the Wilcoxon rank sum test (rank scores), the logrank test (need to use other functions to create these scores). It performs either exact (network algorithm, complete enumeration, or Monte Carlo) asymptotic calculations (using permutational central limit theorem).

### Usage

    permTS(x, ...)

    ## Default S3 method:
    permTS(x, y, alternative = c("two.sided", "less", "greater"),
        exact = NULL, method = NULL, methodRule = methodRuleTS1,
        control=permControl(), ...)

    ## S3 method for class 'formula'
    permTS(formula, data, subset, na.action, ...)

    permKS(x,...)

    ## Default S3 method:
    permKS(x, g, exact = NULL, method = NULL, methodRule = methodRuleKS1, control=permControl(), ...)

    ## S3 method for class 'formula'
    permKS(formula,data,subset, na.action,...)

    permTREND(x,...)

    ## Default S3 method:
    permTREND(x, y, alternative = c("two.sided", "less", "greater"), exact = NULL, method = NULL, methodRule = methodRuleTREND1, control=permControl(),...)

    ## S3 method for class 'formula'
    permTREND(formula,data,subset,na.action,...)

### Arguments

`x` | numeric vector of respose scores for the first group
`y` | numeric vector of either response scores for the second group (for permTS) or trend scores for each observation (for permTREND)
`g` | a factor or character vector denoting group membership
`alternative` | a character string specifying the alternative hypothesis, must be one of "two.sided" (default), "greater","less" (see details)
`exact` | a logical value, TRUE denotes exact test, ignored if method is not NULL
`method` | a character value, one of 'pclt','exact.network','exact.ce','exact.mc'. If NULL method chosen by methodRule
`methodRule` | a function used to choose the method (see details)
`control` | a list with arguments that control the algortihms, see `permControl`
`formula` | a formula of the form lhs~rhs where lhs is a numeric variable giving the response scores 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

There are 4 different methods for deciding how to determine the p-value by defining which test statistics are extreme. For `alternative` there are 3 choices, "two.sided", "less" or "greater", but within alternative="two.sided" there are 2 methods defined by the `tsmethod` given within `control`, see `permControl`. If Ti is a vector of test statistics, and T0 is the observed test statistic, then alternative="less" gives p.lte=Pr[Ti<=T0], alternative="greater" gives p.gte=Pr[Ti>=T0], alternative="two.sided" with tsmethod="central" (default) gives p.twosided=max(1, 2*min(p.lte,p.gte)), and alternative="two.sided" with tsmethod="abs" gives p.twosidedAbs=Pr[abs(Ti - mean(Ti) ) >=abs(T0-mean(Ti))]. For `permTS` the test statistic is equivalent to the mean of one group minus the mean of the other group. For `permTREND` the test statistic is equivalent to the correlation between the response (x) and the trend scores (y). For `permKS` only a twosided pvalue based on Pr[Ti>=T0] is allowed, where the test statistic, Ti, is the weighted sum of the square of the mean within group, where the weights are the sample size for each group. This will give for example, the usual Kruskal-Wallis test when the ranks are used on the responses.

Many standard statistical tests may be put into the form of the permutation test (see Graubard and Korn, 1987). There is a choice of four different methods to calculate the p-values (the last two are only available for `permTS`): (1) pclt: using permutational central limit theorem (see e.g., Sen, 1985). (2) exact.mc:exact using Monte Carlo. (3) exact.network: exact method using a network algorithm (see e.g., Agresti, Mehta, and Patel, 1990). Currently the network method does not implement many of the time saving suggestions such as clubbing. (4) exact.ce: exact using complete enumeration. This is good for very small sample sizes and when doing simulations, since the cm need only be calculated once for the simulation.

These associated functions for the above methods (e.g., `twosample.pclt`, `twosample.exact.network`, etc), are internal and are not to be called directly.

The `methodRule` is a function which takes the first two objects of the default implementation, and returns the method. This function can be used to appropriately choose the method based on the size of the data. For explanation of the default method rules see `methodRuleTS1`, `methodRuleKS1`, or `methodRuleTREND1`.

For more details see Fay and Shaw (2010, Section 5).

### Value

An object of class `htest` or for 'exact.mc' of class `mchtest`, a list with the following 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 as well as p.equal which is the proportion equal to the observed test statistic
`method` | a character vector describing the test
`estimate` | an estimate of the test statistic
`statistic` | statistic used for asymptotics, either Z statistics or chi square statistic, output if method="pclt"
`parameter` | degrees of freedom for chi square statistic, output if 'statistic' is the chi square statistic
`data.name` | character vector describing the response and group variables
`p.conf.int` | a confidence interval on the p-value if method='exact.mc' (see `calcPvalsMC`)
`nmc` | number of Monte Carlo replications if method='exact.mc', NULL otherwise

### Author(s)

Michael Fay

### References

Agresti, A, Mehta, CR, Patel, NR (1990). JASA 85: 453-458.

Fay, MP and Shaw, PA (2010). Exact and Asymptotic Weighted Logrank Tests for Interval Censored Data: The interval R package. Journal of Statistical Software. http://www.jstatsoft.org/v36/i02/. 36 (2):1-34.

Graubard, BI, and Korn, EL (1987). Biometrics 43: 471-476.

Sen, PK (1985) ‘Permutational central limit theorems’ in Encyclopedia of Statistics, Vol 6.

### Examples

    ## Example from StatExact manual
    dBP<-c(94,108,110,90,80,94,85,90,90,90,108,94,78,105,88)
    treatment<-c(rep("treated",4),rep("control",11))
    permTS(dBP~treatment,alternative="less",method="pclt")
    result<-permTS(dBP[treatment=="treated"],dBP[treatment=="control"],alternative="greater")
    result
    result$p.values

[Package perm version 1.0-0.0 Index]