flipMix: The main function for testing mixed models under a permutation (and rotation) framework

Description

It allows to test fixed effect in mixed models. You can test within-unit effects, between-unit and interactions of the two. The response can be uni- or multi-variate. See also examples below.

Usage

flipMix(modelWithin, X = NULL, Z = NULL, units, perms = 1000,
  data = NULL, tail = 0, statTest = NULL, flipReturn,
  testType = "permutation", Su = NULL, equal.se = FALSE, se = NA,
  replaceNA.coeffWithin = "coeffMeans",
  replaceNA.coeffWithin.se = replaceNA.coeffWithin, ...)

Arguments

modelWithin

When it is a formula object, a (possibly multivariate) multiple linear model is fitted. Responses are on the left, while the right part contains ONLY within-unit variables. In this case data must be supplied. Alternatively, it can be a glm, a lm or vgam (library(VGAM)) (i.e. vglm) object. The modelWithin have to be performed using only variables within-unit, without using units indicator (in this case the argument data is not used). It can be also a list of models. It can be null if data is provided in the right format (see below).

The part of the design matrix corresponding to the between-unit effect that are not null under the alternative hypothesis. If it is a matrix or a data.frame it must have a number of rows equal to the number of units or equal to the total number of observations (in the latest case all elements of the same units must have the same values since they are between-unit effects). The non-null between-unit covariates of null model are defined in Z (see argument below) and do not have to be supplied again here. See also the function flip

NOTE: When called from flipMixWithin, W is used only if statTest="TBTWest".

The part of the design matrix corresponding to the non-null between-unit covariates of the model under the null hypothesis. May be given as a design matrix or as a half formula object (e.g. ~a+b). See also the function flip. If it is a matrix or a data.frame it must have a number of rows equal to the number of units or equal to the total number of observations (in the latest case all elements of the same units must have the same values since they are between-unit effects).

units

Vector of units IDs. May be given as a vector or as a half formula object (e.g. ~subj).

perms

The number of permutations to use. The default is perms = 1000. Alternatively it can be a matrix (i.e. the permutation space) or a list with elements number and seed. See also the function flip.

data

Same as in the function flip. If can also be the results of obs2coeffWithin.

tail

Same as in the function flip.

statTest

For function flipMix choose among "t" and "F" (very similar to statTest in function flip.\ For function flipMixWithin choose among "Tnaive" (i.e. no estimate of the variance), "TH0est" (Default, i.e. estimate of the variance under H0), "TH1est" (i.e. estimate of the variance under H1 for each permutation. Slower but some time more powerful) and "TBTWest" (i.e. estimate of the variance using ILS algorithm at each permutation; it allows for Z different from a constant term. This is the same algorithm used for flipMix. MUCH slower but some time even more powerful).

Both functions allow for vector arguments.

flipReturn

Same as in the function flip.

testType

See also the function flip. Note that this option used only with function flipMix.

Usually NULL. It is the covariance matrix of the random effects. If not supplied, it is estimated by iterative least square algorithm.

equal.se

Logical. If TRUE it force the unit to have the same variance of errors (like it is usually assumed in the lmer methods).

Usually NULL. It is a matrix of unit-specific standard errors. If not supplied it is estimated by the algorithm.

replaceNA.coeffWithin

deafult is NA i.e. no replacement. You can provide a specific value (or a vector of values). You can also choose among "coeffMeans" and "unitMeans" (i.e. mean along columns or along rows of Y).

replaceNA.coeffWithin.se

deafult is Inf. Use the same options of replaceNA.coeffWithin (but means are over the variances and then rooted).

…

Further parameters. test.coeffWithin Vector of names or IDs of within-unit variables that have to be tested (and reported). Note that variables not in the list are used in the model (i.e. the they play the role of nuisance parameters). fastSumCombination,onlyMANOVA and linComb are used in flipMix to deal with combination of variables/coefficents.

See also the function flip for other parameters.

Value

flipMix and flipMixWithin return an object of class flip.object. Several operations and plots can be made from this object. See also flip.object-class.

Note that function flipMix with statTest="t" or "F" provides tests for each effect between (and interaction) and also provides the overall test PC1 and sum (i.e. all effects ar null, same as npc does).

Use npc with any comb.funct=c("data.sum","data.linComb","data.pc","data.trace") to combine results.

obs2coeffWithin return a list of objects that can be used as argument of data in the function flipMix and flipMixWithin.

References

L. Finos and D. Basso (2013) Permutation Tests for Between-Unit Fixed Effects in Multivariate Generalized Linear Mixed Models. Statistics and Computing.

D. Basso, L. Finos (2011) Exact Multivariate Permutation Tests for Fixed Effects in Mixed-Models. Communications in Statistics - Theory and Methods.

Examples

Run this code

# NOT RUN {
N=10
toyData= data.frame(subj=rep(1:N,rep(4,N)), Within=rep(1:2,N*2),
          XBetween= rep(1:2,rep(N/2*4,2)),ZBetween= rep(rnorm(N/2),rep(8,N/2)))
toyData= cbind(Y1=rnorm(n=N*4,mean=toyData$subj+toyData$ZBetween+toyData$XBetween),
               Y2=rnorm(n=N*4,mean=toyData$subj+toyData$ZBetween+toyData$Within*2),toyData)
(toyData)

#####################
###Testing Between-unit effects
(res=flipMix(modelWithin=as.matrix(toyData[,c("Y1","Y2")])~Within,data=toyData, 
      X=~XBetween,Z=~ZBetween,units=~subj,perms=1000,testType="permutation",statTest="t"))
#same as:
modelWithin <- lm(as.matrix(toyData[,c("Y1","Y2")])~Within,data=toyData)
(flipMix(modelWithin=modelWithin,data=toyData, X=~XBetween,Z=~ZBetween,units= ~subj, 
        perms=1000,testType="permutation",statTest="t"))

### Note that this is different from:
modelWithin <- list(Y1=lm(Y1~Within,data=toyData),Y2=lm(Y2~Within,data=toyData))
(flipMix(modelWithin=modelWithin,data=toyData, X=~XBetween,Z=~ZBetween,units= ~subj,
        perms=1000,testType="permutation",statTest="t"))

### combining results
(npc(res,"data.pc"))
(npc(res,"data.trace"))
################################
###Testing Within-unit effects
## The resulting test is approximated. The estimate of the variance within units 
## takes in account the presence of effects between units.
(flipMix(modelWithin=as.matrix(toyData[,c("Y1","Y2")])~Within,data=toyData, 
        units= ~subj, perms=1000,testType="permutation",statTest="t"))

###The resulting tests are exact. If effects between are presents, 
## statTest="Tnaive" or "TBTWest" are more suitable:
(res=flipMixWithin(modelWithin=as.matrix(toyData[,c("Y1","Y2")])~Within,data=toyData, 
        units= ~subj, perms=1000,statTest=c("TH1est")))
npc(res)

# }