mtpc {brainGraph}

Multi-threshold permutation correction

Description

Applies the multi-threshold permutation correction (MTPC) method to perform inference in graph theory analyses of brain MRI data.

Plot the statistics from an MTPC analysis, along with the maximum permuted statistics. The output is similar to Figure 11 in Drakesmith et al. (2015).

Usage

mtpc(g.list, thresholds, covars, measure, contrasts, con.type = c("t",
  "f"), outcome = NULL, con.name = NULL, level = c("vertex",
  "graph"), clust.size = 3L, perm.method = c("freedmanLane",
  "terBraak", "smith", "draperStoneman", "manly", "stillWhite"),
  part.method = c("beckmann", "guttman", "ridgway"), N = 500L,
  perms = NULL, alpha = 0.05, res.glm = NULL, long = TRUE, ...)

## S3 method for class 'mtpc'
summary(object, contrast = NULL, digits = max(3L,
  getOption("digits") - 2L), print.head = TRUE, ...)

## S3 method for class 'mtpc'
plot(x, contrast = 1L, region = NULL,
  only.sig.regions = TRUE, show.null = TRUE, caption.stats = FALSE,
  ...)

## S3 method for class 'mtpc'
nobs(object, ...)

## S3 method for class 'mtpc'
terms(x, ...)

## S3 method for class 'mtpc'
formula(x, ...)

## S3 method for class 'mtpc'
labels(object, ...)

## S3 method for class 'mtpc'
case.names(object, ...)

## S3 method for class 'mtpc'
variable.names(object, ...)

## S3 method for class 'mtpc'
df.residual(object, ...)

## S3 method for class 'mtpc'
region.names(object)

## S3 method for class 'mtpc'
nregions(object)

Arguments

g.list

A list of brainGraphList objects for all thresholds

thresholds

Numeric vector of the thresholds applied to the raw connectivity matrices.

covars

A data.table of covariates

measure

Character string of the graph measure of interest

contrasts

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)

con.type

Character string; either 't' or 'f' (for t or F-statistics). Default: 't'

outcome

Character string specifying the name of the outcome variable, if it differs from the graph metric (measure)

con.name

Character vector of the contrast name(s); if contrasts has row/list names, those will be used for reporting results

level

Character string; either vertex (default) or graph

clust.size

Integer indicating the size of “clusters” (i.e., consecutive thresholds for which the observed statistic exceeds the null) (default: 3L)

perm.method

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

part.method

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

N

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

perms

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

alpha

Numeric; the significance level. Default: 0.05

res.glm

A list of bg_GLM objects, as output by a previous run of mtpc. Useful if you want to change the cluster size without re-running all of the GLM's and permutations (default: NULL)

long

Logical indicating whether or not to return all permutation results. Default: FALSE

...

Other arguments passed to brainGraph_GLM and/or brainGraph_GLM_design

object, x

A mtpc object

contrast

Integer specifying the contrast to plot/summarize; defaults to showing results for all contrasts

digits

Integer specifying the number of digits to display for P-values

print.head

Logical indicating whether or not to print only the first and last 5 rows of the statistics tables (default: TRUE)

region

Character string specifying which region's results to plot; only relevant if level='vertex'. Default: NULL

only.sig.regions

Logical indicating whether to plot only significant regions (default: TRUE)

show.null

Logical indicating whether to plot points of the maximum null statistics (per permutation)

caption.stats

Logical indicating whether to print the MTPC statistics in the caption of the plot. Default: FALSE

Details

This is a multi-step procedure: (steps 3-4 are the time-consuming steps)

1. Apply thresholds \tau to the networks, and compute network metrics for all networks and thresholds. (already done beforehand)

2. Compute test statistics S_{obs} for each threshold. (done by brainGraph_GLM)

3. Permute group assignments and compute test statistics for each permutation and threshold. (done by brainGraph_GLM)

4. Build a null distribution of the maximum statistic across thresholds (and across brain regions) for each permutation. (done by brainGraph_GLM)

5. Determine the critical value, S_{crit} from the null distribution of maximum statistics.

6. Identify clusters where S_{obs} > S_{crit} and compute the AUC for these clusters (denoted A_{MTPC}).

7. Compute a critical AUC (A_{crit}) from the mean of the supra-critical AUC's for the permuted tests.

8. Reject H_0 if A_{MTPC} > A_{crit}.

Value

An object of class mtpc with some input arguments plus the following elements:

X, qr, cov.unscaled

Design matrix, QR decomposition, and unscaled covariance matrix, if the design is the same across thresholds

contrasts

The contrast matrix or list of matrices

con.name

Contrast names

removed.subs

Named integer vector of subjects with incomplete data

atlas

The atlas of the input graphs

rank, df.residual

The model rank and residual degrees of freedom

res.glm

List with length equal to the number of thresholds; each list element is the output from brainGraph_GLM

DT

A data.table for all thresholds, combined from the outputs of brainGraph_GLM

stats

A data.table containing S.mtpc (the max. observed statistic), tau.mtpc (the threshold of the max. observed statistic), S.crit (the critical statistic value), and A.crit (the critical AUC)

null.dist

Numeric array with N columns and number of rows equal to the number of thresholds. The 3rd dimension is for each contrast. Each element of the array is the maximum statistic for that permutation, threshold, and contrast combination.

perm.order

Numeric matrix; the permutation set applied for all thresholds (each row is a separate permutation)

The plot method returns a trellis object or a list of ggplot objects

Author(s)

Christopher G. Watson, [e-mail]

References

Drakesmith, M. and Caeyenberghs, K. and Dutt, A. and Lewis, G. and David, A.S. and Jones, D.K. (2015) Overcoming the effects of false positives and threshold bias in graph theoretical analyses of neuroimaging data. NeuroImage, 118, 313–333. doi: 10.1016/j.neuroimage.2015.05.011

See Also

Other Group analysis functions: Bootstrapping, GLM, Mediation, NBS, brainGraph_permute

Other GLM functions: GLM design, GLM fits, GLM

Examples

## Not run: 
diffs.mtpc <- mtpc(g.list=g.norm, thresholds=thresholds, N=N,
     covars=covars.dti, measure='E.nodal.wt', coding='effects',
     contrasts=c(0, 0, 0, 0, -2), alt='greater',
     binarize=c('Sex', 'Scanner'), con.name='Group 1 > Group 2')
sig.regions <- diffs.mtpc$DT[A.mtpc > A.crit]

## End(Not run)
## Not run: 
mtpcPlots <- plot(mtpc.diffs)

## Arrange plots into 3x3 grids
ml <- marrangeGrob(mtpcPlots, nrow=3, ncol=3)
ggsave('mtpc.pdf', ml)

## End(Not run)