SOUP: SOUP Main Function

In SOUP: Stochastic Ordering Using Permutations (and Pairwise Comparisons)

Description

Main function of the package, interface for every analysis. The dataset can be balanced or not for almost all possible choices of the input parameters. The function allows also for the presence of one or more continuous covariates or for stratified analysis.

Usage

  SOUP(Y, covars, data = NULL, analysisType, p.adj.method,
    p.valuesType, testStatistic, combFunct,
    univ.p.values = TRUE, tails = NULL,
    linearInter = FALSE, returnPermSpace = TRUE,
    nPerms = 999L, alpha = 0.05, seed, iteratedNPC, ...)

Arguments

Y	input matrix where each column is a response variables.
covars	it can be a matrix, a data.frame or a formula, in the first two cases it must contains at least the labels of groups, in the latter case it has to be a right-sided formula (e.g. ~ v1 + v2) specifying the model to extract from the data input.
data	optional data.frame containing covariates requested by covars, if covars is not a formula this input is useless.
analysisType	character, type of the analysis to be performed: it can be "simple" if the only covariate is the labels of groups, "strata" if there is also a stratifying (categorical) covariate, "regres" if there is one or more (numerical or not) covariate(s) besides labels of groups. In the latter case the linear effect of the covariates is removed from the response variables are residualised by the matrix V^{-1/2} obtained from V = I - H (where I is the identity matrix and H is the “hat” matrix of the OLS, by means of a spectral decomposition.
p.adj.method	character string containing the type of required p-value adjustment
p.valuesType	character string indicating the type of p-value to be used, it can be "permutation" or "asymptotic"
testStatistic	character string indicating the test statistic to be used, it depends on both analysisType and on p.valuesType and the alternatives are: AD, meanDiff for all analysisType but only using permutation p-values Ttest for all analysisType but only using asymptotic p-values Hotelling with both permutation and asymptotic emphp-values, with "simple" and "regres" but not with "strata" analysisType lmCoef only with "strata" analysisType and with "asymptotic" p-values
combFunct	character string containing the desired combining function to be used, choices are: Fisher the famous Fisher's p-values combining function Liptak it uses the quantile function of the Normal distribution to combine p-values minP, tippett combine p-values by taking the minimum across the set maxT combines directly the test statistics by taking the maximum across the set direct, sumT combine the test statistics by summing them sumT2 combines the test statistics by squaring and summing them See the references for more details about their properties.
univ.p.values	logical, if TRUE (default) p-values are returned for each variable separately in a 3-ways array, the chosen multiplicity correction is performed independently for each variable
tails	integer vector of {+1,-1} containing the alternatives for response variables: +1 means “the higher the better”, -1 means “the lower the better” (direction of preference), if NULL (default) all variables are considered to be of the type “the higher the better”
linearInter	logical, if TRUE the presence of linear interaction is assumed between levels of the stratifying covariate and response variables, this affects only the "lmCoef" test statistic in the (in the "strata" analysisType), basically the contrasts matrix of groups is multiplied by the levels of the stratifying factor.
returnPermSpace	logical if TRUE (default) the whole permutation space is returned, class PermSpace, otherwise it is an empty instance of the class.
nPerms	integer number of permutation to be performed
alpha	numeric desired significance level, i.e. type-I error
seed	integer seed for the Random Number Generator
iteratedNPC	logical, single or iterated Non-Parametric Combination, see \ codeiterNPC for details.
...	put here the optional weights and subsets for the NPC function and the permutation space of rows indexes permSpaceID. The latter allows to exactly reproduce a previous analysis, if all other inputs are kept equal, or to see what happens changing for example only the testStatistic.

Details

Depending on the chosen p-values type and on the analysis type, only some options can be selected:

• with "simple" or "regres" analysis and "asymptotic" p-values, "Hotelling" and "Ttest"; with permutation p-values "AD", "Hotelling" and "meanDiff" can be selected.

• With "strata" analysis and "asymptotic" p-values, "lmCoef" and "Ttest"; with "permutation" p-values "AD" and "meanDiff" can be selected.

Value

an object of class SoupObject.

Author(s)

Federico Mattiello <[e-mail]>

References

Pesarin, F. and Salmaso, L. (2010) Permutation Tests for Complex Data. Wiley: United Kingdom.

Pesarin F. (2001) Multivariate Permutation Tests with Applications in Biostatistics Wiley: New York.

Federico Mattiello (2010) Some resampling-based procedures for ranking of multivariate populations, Master's Thesis, Faculty of Statistical Sciences: Padova.

Examples

###
### testing SOUP
###
rm(list = ls()); gc(reset = TRUE)

require(SOUP)
n <- 5L         # replication of the experiment
G <- 4L         # number of groups
nVar <- 10L     # number of variables
shift <- 1.5    # shift to be added to group 3
alpha <- c(0.01, 0.05, 0.1)        # significance levels

## groups factor
groups <- gl(G, n, labels = paste("gr", seq_len(n), sep = "_"))

set.seed(12345)
Y <- matrix(rnorm(n * G * nVar), nrow = n * G, ncol = nVar)
colnames(Y) <- paste("var", seq_len(nVar), sep = "_")
ind1 <- groups == unique(groups)[3L]
Y[ind1, ] <- Y[ind1, ] + shift

res <- SOUP(Y = Y, covars = as.matrix(groups), analysisType = "simple",
        testStatistic = "meanDiff", combFunct = "Fisher",
        alpha = alpha,
        subsets = list("first" = 1:5, "second" = 6:10),
        weights = list(
                "firstW" = c(.1, .2, .1, .5, .1),
                "secondW" = rep.int(1, 5)),
        p.valuesType = "permutation", p.adj.method = "FWEminP")
res

SOUP documentation built on May 2, 2019, 8:18 a.m.