brainGraph (version 2.7.3)

mtpc: 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, con.mat, con.type = c("t",
  "f"), con.name = NULL, level = c("vertex", "graph"),
  clust.size = 3L, N = 500L, perms = NULL, alpha = 0.05,
  res.glm = NULL, long = TRUE, ...)
# S3 method for mtpc
summary(object, contrast = NULL, digits = max(3L,
  getOption("digits") - 2L), print.head = TRUE, ...)
# S3 method for mtpc
plot(x, contrast = 1L, region = NULL,
  only.sig.regions = TRUE, show.null = TRUE, caption.stats = FALSE,
  ...)

Arguments

g.list

A list of lists of igraph graph objects for all thresholds and subjects

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

con.mat

Numeric matrix specifying the contrast(s) of interest; if only one contrast is desired, you can supply a vector

con.type

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

con.name

Character vector of the contrast name(s); if con.mat has row names, those will be used for reporting results (default: NULL)

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)

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

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)

x

A mtpc object

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)

Value

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

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 matrix with N rows and number of columns equal to the number of thresholds. Each element is the maximum statistic for that permutation and threshold.

perm.order

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

The plot method returns a list of ggplot objects

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}\).

References

Drakesmith M, Caeyenberghs K, Dutt A, Lewis G, David AS, Jones DK (2015). Overcoming the effects of false positives and threshold bias in graph theoretical analyses of neuroimaging data. NeuroImage, 118:313-333.

See Also

Other Group analysis functions: Bootstrapping, GLM, IndividualContributions, MediationAnalysis, NBS, brainGraph_permute

Other GLM functions: GLMdesign, GLMfit, GLM

Examples

# NOT RUN {
diffs.mtpc <- mtpc(g.list=g.norm, thresholds=thresholds, N=N,
     covars=covars.dti, measure='E.nodal.wt', coding='effects',
     con.mat=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]
# }
# NOT RUN {
mtpcPlots <- plot(mtpc.diffs)

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