randomise: GLM non-parametric permutation testing

Description Usage Arguments Value Model partitioning Permutation methods References

View source: R/glm_randomise.R


randomise and randomise_3d perform non-parametric permutation testing for analyses in which there is a single or multiple design matrix per region, respectively. In the latter case, X should be a 3D array.

partition partitions a full design matrix into separate matrices of covariates of interest and nuisance covariates based on a given contrast and partition method.


partition(M, contrast, part.method = c("beckmann", "guttman", "ridgway"))

randomise(perm.method, part.method, N, perms, X, y, contrasts, ctype, nC,
  skip = NULL, n = dim(X)[1L], p = qr.default(X)$rank,
  ny = dim(y)[2L], dfR = n - p)

randomise_3d(perm.method, part.method, N, perms, X, y, contrasts, ctype,
  nC, runX = dimnames(X)[[3L]], n = dim(X)[1L], p = qr.default(X[, ,
  1L])$rank, ny = length(runX), dfR = n - p)



Numeric matrix or array of the full design matrix(es)


For partition, a numeric matrix with 1 or more rows (for T and F contrasts, respectively) representing a single contrast.


Character string; the method of partitioning the design matrix into covariates of interest and nuisance. Default: 'beckmann'


Character string indicating the permutation method. Default: 'freedmanLane'


Integer; number of permutations to create. Default: 5e3


Matrix of permutations, if you would like to provide your own. Default: NULL


Numeric matrix or 3D array of the design matrix(es)


Numeric matrix of outcome variables, with 1 column per region, or a single column if there is a different design matrix per region


Numeric matrix (for T statistics) or list of matrices (for F statistics) specifying the contrast(s) of interest; if only one contrast is desired, you can supply a vector (for T statistics)


The contrast type


Integer; the number of contrasts


Integer vector indicating which (if any) contrasts to skip. Only used by NBS.

n, p, ny, dfR

Integers for the number of observations, design matrix columns (its rank), number of regions/outcome variables, and residual degrees of freedom, respectively


Character vector of regions with non-singular designs


partition returns a list containing:


Numeric array; the combined partitioned arrays


Numeric array for the covariates of interest


Numeric array for the nuisance covariates


The effective contrast, equivalent to the original, for the partitioned model [X, Z] and considering all covariates


Same as eCm, but considering only X

A numeric array with dimensions n_y \times N \times n_c; the number of rows equals number of regions/outcome variables, number of columns equals N, and the 3rd dimension is the number of contrasts

Model partitioning

Consider the matrix formulation of the general linear model:

\mathbf{Y} = \mathbf{M} ψ + \in

where Y is the vector of outcomes, M is the full design matrix (including nuisance covariates), ψ is the vector of parameter estimates, and \in is the vector of error terms. In a permutation framework, algorithms are applied differently depending on the presence/absence of nuisance covariates; thus the model is separated depending on the contrast of interest:

\mathbf{Y} = \mathbf{X}β + \mathbf{Z}γ + \in

where \mathbf{X} contains covariates of interest, \mathbf{Z} contains nuisance covariates, and β and γ are the associated parameter estimates.

The manner of partitioning depends on the method. For example, for the guttman method, X is formed from the columns of contrast that have non-zero entries.

Permutation methods

The permutation methods can be split into 2 groups, depending on which part of the model they permute. For full details, see Winkler et al., 2014.

Permute Y

Freedman-Lane, Manly, and ter Braak

Permute X

Smith, Draper-Stoneman, and Still-White

Depending on the size of the data, it may be faster to use a method that permutes Y instead of X. For example, in NBS with dense matrices (more than 400-500 edges), it will be somewhat faster to use the “Smith” method compared to “Freedman-Lane”. If using brainGraph_GLM, the number of vertices follows the same relationship.

Furthermore, all methods except Still-White include the Z (nuisance covariate) matrix when calculating the permuted statistics.


Beckmann, C.F. and Jenkinson, M. and Smith, S.M. (2001) General multi-level linear modelling for group analysis in FMRI. Tech Rep. University of Oxford, Oxford.

Guttman, I. (1982) Linear Models: An Introduction. Wiley, New York.

Ridgway, G.R. (2009) Statistical analysis for longitudinal MR imaging of dementia. PhD thesis.

Draper, N.R. and Stoneman, D.M. (1966) Testing for the inclusion of variables in linear regression by a randomisation technique. Technometrics. 8(4), 695–699.

Freedman, D. and Lane, D. (1983) A nonstochastic interpretation of reported significance levels. J Bus Econ Stat, 1(4), 292–298. https://dx.doi.org/10.1080/07350015.1983.10509354

Manly B.F.J. (1986) Randomization and regression methods for testing for associations with geographical, environmental, and biological distances between populations. Res Popul Ecol. 28(2), 201–218.

Nichols, T.E. and Holmes, A.P. (2001) Nonparametric permutation tests for functional neuroimaging: A primer with examples. Human Brain Mapping. 15(1), 1–25. https://dx.doi.org/10.1002/hbm.1058

Smith, S.M. and Jenkinson, M. and Beckmann, C. and Miller, K. and Woolrich, M. (2007) Meaningful design and contrast estimability in fMRI. NeuroImage. 34(1), 127–36. https://dx.doi.org/10.1016/j.neuroimage.2006.09.019

Still, A.W. and White, A.P. (1981) The approximate randomization test as an alternative to the F test in analysis of variance. Br J Math Stat Psychol. 34(2), 243–252.

ter Braak, C.J.F. 1992. Permutation versus bootstrap significance tests in multiple regression and ANOVA. Bootstrapping and related techniques. Springer, Berlin, Heidelberg. 79–85.

Winkler, A.M. and Ridgway, G.R. and Webster, M.A. and Smith, S.M. and Nichols, T.E. (2014) Permutation inference for the general linear model. NeuroImage. 92, 381–397. https://dx.doi.org/10.1016/j.neuroimage.2014.01.060

brainGraph documentation built on Oct. 23, 2020, 6:37 p.m.