Graph Theory Analysis of Brain MRI Data

A set of tools for performing graph theory analysis of brain MRI data. It works with data from a Freesurfer analysis (cortical thickness, volumes, local gyrification index, surface area), diffusion tensor tractography data (e.g., from FSL) and resting-state fMRI data (e.g., from DPABI). It contains a graphical user interface for graph visualization and data exploration, along with several functions for generating useful figures.


brainGraph 2.2.0


Minor changes

  • Moved RGtk2 and cairoDevice to Suggests (from Depends) to allow installation on headless servers
    • Thanks to @michaelhallquist for the pull request!
  • Functions boot_global,, and plot_group_means are no longer accessible (deprecated since v2.0.0)

brainGraph 2.1.0

2018-05-03 (mostly changes to structural covariance network functionality)

Bug fix

  • Fixed a bug in mtpc that was introduced in v2.0.1

New functions/features

  • brainGraph_GLM_design has a new argument factorize which specifies whether or not to convert all character columns (excluding Study.ID) to factor variables. The default is TRUE. Previously, character columns were ignored.
  • get.resid
    • In the function call, you can choose whether or not to test a linear model for all groups together or separately, via the method argument
    • The plot method now returns a list of ggplot objects, and is similar to the plot methods for bg_GLM and mtpc
  • corr.matrix
    • The resids argument must be the output of get.resid (not a data.table as before)
    • Correlations will be calculated separately for all subject groups (as this information is stored in the output of get.resid); you no longer need to loop (or lapply) across groups
    • In the function call, you can choose whether to correlate the residuals or raw structural values, via the what argument
    • The exclusions argument was renamed to exclude.reg to highlight that you should specify region names to be excluded (if any)
    • You can explicitly choose whether to calculate Pearson or Spearman correlations, via the type argument (previously, this behavior was "hidden")

Minor changes

  • brainGraph_init: the modality argument now will accept any character string; the default is still thickness. The files with the string you supply still must be present on your system.
  • Due to corr.matrix expecting different input, the following functions also require, for their resids argument, the output of get.resid (instead of a data.table):
    • aop
    • brainGraph_boot
    • brainGraph_permute
    • loo

brainGraph 2.0.4


Bug fix

  • gateway_coeff: no longer throws an error for very sparse graphs; instead, it returns a vector with NaN values for unconnected vertices
  • make_mediate_brainGraph: did not return correct values (for the treatment condition) when INT=TRUE (it recycled the values for the control condition)
  • make_intersection_brainGraph
    • Previously exited with error if any of the input graphs did not contain vertices meeting the desired subgraph condition
    • Now returns an empty graph if none of the input graphs meet the subgraph condition
  • NBS:
    • When getting the indices for which matrix elements to transpose (so that result is symmetric), the result was slightly wrong for alt='greater'
    • Calculation of edge counts in summary method contained an error

Minor changes

  • All summary methods now provide a DT.sum element in the returned list; previously it was inconsistent

brainGraph 2.0.3


Bug fix

  • In mtpc, the stats table that is returned previously was not always unique
  • mtpc did not return a list with a named element clust.size (it was unnamed)
  • In, if the user selected a contrast other than the first, it would not plot the correct null statistics (green dots)

brainGraph 2.0.2


Release on CRAN; bugfix release.

Bug fix

  • Fixed a bug in create_mats in which the ordering (along the 3rd dimension) of the arrays in A.norm.sub did not match the ordering of the input matrix files (and therefore the ordering along the 3rd dimension of the arrays A and A.norm).
    • In the case that the input matrix files were already ordered by Group and Study.ID, then this is not a "bug", in that the ordering was already correct. So, if your subject groups are groups <- c('Control', 'Patient'), and the matrix files are separated on the filesystem by group, there is no change in behavior.
    • This bug only appeared when'consistency' or'consensus' (the default option).

brainGraph 2.0.1


Bug fix

  • Fixed error in mtpc when creating the MTPC statistics data.table

brainGraph 2.0.0


2nd major release; 6th CRAN release. (The previous CRAN release was at v1.0.0)

For other updates and bug fixes, see the minor release notes below.

New functions/features

  1. Mediation analysis is now possible through brainGraph_mediate.
  2. I have introduced some simple S3 classes and methods. All of the classes have plot (except NBS) and summary methods. The classes and corresponding "creation functions" are:
Class Creation func. Description
brainGraph make_brainGraph Any graph with certain attributes
bg_GLM brainGraph_GLM Results of GLM analysis
NBS NBS Results of NBS analysis
mtpc mtpc Results of MTPC analysis
brainGraph_GLM make_glm_brainGraph Graphs from GLM analysis
brainGraph_NBS make_nbs_brainGraph Graphs from NBS analysis
brainGraph_mtpc make_glm_brainGraph Graphs from MTPC analysis
brainGraph_mediate make_mediate_brainGraph Graphs from mediation analysis
brainGraph_boot brainGraph_boot Results of bootstrap analysis
brainGraph_permute brainGraph_permute Results of permutation tests
brainGraph_resids get.resid Residuals for covariance networks
  1. Multiple contrasts (in the same function call), as well as F-contrasts, are now allowed in the GLM-based functions: brainGraph_GLM, mtpc, NBS, and get.resid.
    • There is a new function argument, con.type, for this purpose.
    • Since both contrast types are now specified in the form of a contrast matrix, the argument con.vec has been replaced by con.mat.
  2. Designs with 3-way interactions (e.g., 2 x 2 x 2) are now allowed for GLM-based analyses.
  3. Permutations for GLM-based analyses are now done using the Freedman-Lane method (the same as in FSL's randomise and in PALM).
  4. Plot the "diagnostics" from GLM analyses through the plot.bg_GLM method to the output of brainGraph_GLM.
  5. Plot the statistics from MTPC analyses through the method for mtpc results.
  6. aop has a new argument control.value allowing you to specify the control group; all comparisons will be to that group.
    • Removes the need to loop through patient groups in the console (if you have more than 1).
  7. Most of the GLM-based functions have a new argument, long, which will not return all of the permutation results if long=FALSE.

Removed/renamed functions

  • boot_global was renamed to brainGraph_boot.
  • check.resid was removed; you now just call the plot method to outputs of get.resid.
    1. Function was renamed to brainGraph_permute.
    2. The arguments are slightly re-ordered
    3. Argument permSet was renamed to perms.
    4. New argument auc lets you explicitly define whether or not you want statistics for the area under the curve (AUC).
  • plot_boot was removed; you now just call the plot method to outputs of brainGraph_boot.
  • plot_brainGraph_mni has been removed; this functionality can be changed by the mni argument to plot.brainGraph (i.e., the plot method for objects of class brainGraph)
  • plot_group_means was renamed to plot_volumetric, as it works specifically for structural covariance networks.
  • plot_perm_diffs was removed; you now just call the plot method to outputs of brainGraph_permute.

Major changes

  • NBS now automatically symmetrizes the input matrices. This is partly for speed and partly because igraph symmetrizes the matrices anyway.
    • There is a new function argument, (which is the same as that for create_mats) for this purpose.
  • corr.matrix:
    • Now expects as its first input the residuals from get.resid.
    • You may specify multiple densities (or thresholds),
    • Returns a list including the binarized, thresholded matrices as an array (still named r.thresh).
  • get.resid now allows for any design matrix for getting LM residuals (similar to brainGraph_GLM).
    • Must supply a data.table of covariates.
    • You may pass on arguments to brainGraph_GLM_design for creating the correct design matrix.
  • mtpc accepts 2 new arguments (in addition to explicitly naming required arguments that pass on to brainGraph_GLM):
    1. clust.size lets you change the "cluster size", the number of consecutive thresholds needed to deem a result significant (default: 3)
    2. res.glm lets you input the res.glm list element from a previous mtpc run. This is only useful if you would like to compare results with different values for clust.size.
  • (see above section for changes)
  • rich_club_norm now returns a data.table, which simplifies working with the data (and plotting).
  • set_brainGraph_attr: multiple (explicit) arguments were removed; these are now passed on to make_brainGraph and can still be specified in the function call.
  • I now use the ggrepel package for any ggplot objects with text labels.

brainGraph 1.6.0


Bug fix

  • brainGraph_init: fixed bug regarding the use of a custom atlas

Minor changes

  • Some function arguments have been modified to reflect the object type (e.g., changing g to g.list if the function requires a list object).
  • brainGraph_init:
    • New argument custom.atlas allows you to use an atlas that is not in the package (you must also specify atlas="custom").
    • This requires that the atlas you specify already be loaded into the R environment and meet the specifications of the package's atlases
      • It should be a data.table, and have columns name, x.mni, y.mni, z.mni, lobe, hemi (at a minimum).
  • can now calculate ev.cent

brainGraph 1.5.0


Bug fix

  • boot_global: fixed bug in modularity calculation

Major changes

  • boot_global:
    • can omit display of the progress bar (by setting .progress=FALSE)
    • can now create weighted networks; to do so, you must choose a weighted metric in the function argument measure
    • added some weighted metrics as options for measure (strength, mod.wt,
    • can specify the confidence level (for calculating confidence intervals) via the conf argument (default: 0.95)
  • set_brainGraph_attr:
    • New argument xfm.type, which allows you to choose how edge weights should be transformed for calculating distance-based metrics.
    • The default is the reciprocal (which is what was hard-coded in previous versions).
    • Other options are: 1-w (subtract weights from 1); and -log(w) (take the negative natural logarithm of weights).

New functions

  • symmetrize_array: a convenience function that applies symmetrize_mats along the third dimension of an array
  • xfm.weights: utility function to transform edge weights (necessary when calculating distance-based metrics).

Minor changes

  • graph_attr_dt and vertex_attr_dt will now include weighting, if present
  • set_brainGraph_attr has 2 new arguments:
    1. weighting will create a graph-level attribute indicating how the edges are weighted (e.g., 'fa' for FA-weighted tractography networks)
    2. threshold will create a graph-level attribute indicating the (numeric) threshold used to create the network (if applicable)

brainGraph 1.4.0


Bug fix

  • mtpc: fixed a bug that would incorrectly calculate A.crit

New functions

  • apply_thresholds: threshold an additional set of matrices (e.g., FA-weighted matrices in DTI tractography) based on a set of matrices that have already been thresholded (e.g., streamline-weighted matrices in DTI tractography)

Minor changes

  • analysis_random_graphs: no longer requires a covars argument

brainGraph 1.3.0


Bug fix

  • create_mats
    • fixed bug for deterministic tractography when the user would like to normalize the matrices by ROI size.
    • Fixed bug for when'density'. Previously, it would keep the top X% for each subject

Major changes

  • create_mats
    •'consensus' is the name of the new default, as this is what is called "consensus-based" thresholding in the literature.
    •'consistency' is a new option, for performing consistency-based thresholding. See Roberts et al., 2017.

Minor changes

  • set_brainGraph_attr no longer calculates the graph's clique number, which takes exceedingly long in denser and/or larger graphs (e.g., craddock200)

brainGraph 1.2.0


Bug fix

  • plot_brainGraph: now returns NA (instead of throwing an error) if the specified subgraph expression results in a network with 0 vertices.
  • edge_asymmetry fixed bug when the input graph had only one contralateral connection (usually only encountered in the GUI with neighborhood plots)

Major changes

  • create_mats: you can specify'mean', which will threshold the matrices such that a connection will be kept if mean(A_ij) + 2*sd(A_ij) > mat.thresh, for each of mat.thresh.

New functions

  • make_empty_brainGraph: this is not a new function, but rather was not exported in previous versions
  • s_core: calculate the s-core membership of a graph's vertices (Eidsaa & Almaas, 2013)
    • Adds a vertex attributes called s.core to the graph through set_brainGraph_attr.
    • Analogous to the k-core but for weighted networks.
    • The vertex attribute for k-core has been changed from coreness to k.core to distinguish these metrics.

brainGraph 1.1.0


Bug fix

  • plot_brainGraph_gui had multiple issues and a few features have been changed:
    • Overall execution should be faster than in previous versions
    • Lobe, neighborhood, and community selection are now in "scrolled windows" instead of drop-down lists. Multiple selections can be made either by pressing Ctrl and clicking, or by holding Shift and moving the arrow keys
    • Fixed problem with vertex colors
    • When choosing to plot neighborhoods, you can color the vertices based on which neighborhood they belong to (useful if multiple vertices are selected)
  • gateway_coeff returned an error if the number of communities equals 1; this has been fixed

New functions

  • centr_betw_comm: calculate vertex communicability betweenness centrality (Estrada et al., 2009)
  • communicability: calculate network communicability (Estrada & Hatano, 2008)
  • mtpc: the multi-threshold permutation correction (MTPC) method for statistical inference of either vertex- or graph-level measures (Drakesmith et al., 2015)
  • symmetrize_mats: symmetrize a connectivity matrix by either the maximum, minimum, or average of the off-diagonal elements. You may select one of these as an argument to create_mats.

Major changes

  • brainGraph_GLM has 2 new function arguments:
    • level allows you to perform inference for graph- or vertex-level measures
    • perms lets you specify the permutation set explicitly
  • create_mats: All A.norm.sub matrices will be symmetrized, regardless of the value of (previously they were only symmetrized if using'density').
    • This should not pose a problem, as the default (to take the maximum of the off-diagonal elements) is also the default when creating graphs in igraph.

Minor changes

  • get.resid: no longer requires a covars argument, as it was redundant
  • sim.rand.graph.par: the argument clustering is no longer TRUE by default

brainGraph 1.0.0


First major release; Fifth CRAN release

Bug fix

  • plot_perm_diffs previously didn't work with a low number of permutations, but now will work with any number
  • sim.rand.graph.par previously didn't work with graphs lacking a degree vertex attribute
  • Fixed problem with plot_brainGraph_GUI when plotting in the sagittal view for neighborhood graphs

Major changes

  • Multiple functions now run significantly faster after I updated the code to be more efficient
  • has been removed, and now accepts multiple densities and returns the same results. It can still take a single density for the old behavior
  • The lobe and network vertex attributes are now character vectors
  • NBS now handles more complex designs and contrasts through brainGraph_GLM_design and brainGraph_GLM_fit. The function arguments are different from previous versions
  • SPM has been removed and is replaced by brainGraph_GLM
  • Added atlas craddock200 (with coordinates from DPABI/DPARSF)

New functions

  • brainGraph_GLM: replaces SPM and allows for more complex designs and contrasts
  • brainGraph_GLM_design: function that creates a design matrix from a data.table
  • brainGraph_GLM_fit: function that calculates the statistics from a design matrix and response vector
  • create_mats: replaces dti_create_mats and adds functionality for resting-state fMRI data; also can create matrices that will have a specific graph density
  • gateway_coeff: calculate the gateway coefficient (Vargas & Wahl, 2014); graphs will have vertex attributes GC or GC.wt (if weighted graph)
  • plot_brainGraph_multi: function to write a PNG file of 3-panel brain graphs (see User Guide for example)

Minor changes

  • efficiency replaces graph.efficiency; the old function name is still accessible (but may be removed eventually)
  • set_brainGraph_attr replaces set.brainGraph.attributes; the old function name is still accessible (but may be removed eventually)
  • part_coeff replaces part.coeff
  • All of the rich. functions have been renamed. The period/point/dot in each of those functions is replaced by the underscore. So, is now rich_club_norm, etc.
  • set_vertex_color and set_edge_color replace color.vertices and color.edges (these functions are not exported, in any case)
  • contract_brainGraph replaces graph.contract.brain
  • make_ego_brainGraph replaces graph_neighborhood_multiple (so it is a similar name to igraph's function make_ego_graph)
  • write_brainnet replaces write.brainnet
  • In the GUI, vertex order in circle plots now more closely reflect their anatomical position, being ordered by y- and x-coordinates (and within lobe)

brainGraph 0.72.0


Fourth CRAN release

Bug fix

  • sim.rand.graph.clust previously returned a list; now it correctly returns an igraph graph object
  • aop and loo: regional contributions were calculated incorrectly (without an absolute value)
  • changed the p-value calculation again; this shouldn't affect many results, particularly if N=1,000 (random graphs)
  • NBS:
    • the t.stat edge attribute was, under certain situations, incorrectly assigning the values; this has been fixed in the latest version
    • fixed bug when permutations didn't result in any connected components
    • fixed bug w/ data randomization; the bug didn't seem to affect the results
  • SPM:
    • the permutation p-values were previously incorrect; has been fixed
    • added an argument to remove NA values
  • vec.transform: fixed bug which occurred when the input vector is the same number repeated (i.e., when range(x) = 0)

Major changes

  • dti_create_mats: new function argument algo can be used to specify either 'probabilistic' or 'deterministic'. In the case of the latter, when dividing streamline count by ROI size, you can supply absolute streamline counts with the mat.thresh argument.
  • Changed instances of .parallel to use.parallel; also, added it as an argument to set.brainGraph.attributes to control all of the functions that it calls; also added the argument to part.coeff and within_module_deg_z_score
  • Added atlases aal2.94, aal2.120, and dosenbach160
  • plot_brainGraph: can now specify the orientation plane, hemisphere to plot, showing a legend, and a character string of logical expressions for plotting subgraphs (previously was in plot_brainGraph_list)

New functions

  • auc_diff: calculates the area-under-the-curve across densities for two groups
  • cor.diff.test: calculates the significance of the difference between correlation coefficients
  • does permutation testing across all densities, and returns the permutation distributions for the difference in AUC between two groups
  • give a graph attributes based on rich-club analysis

Minor changes

  • Removed the x, y, and z columns from the atlas data files; now only the MNI coordinates are used. This should simplify adding a personal atlas to use with the package
  • Added a column, name.full to some of the atlas data files
  • NBS:
    • New edge attribute p, the p-value for that specific connection
    • Returns the p.init value for record-keeping
  • brainGraph_init: can now provide a covars data table if you want to subset certain variables yourself, or if the file is named differently from covars.csv
  • plot_brainGraph: can now manually specify a subtitle;
  • plot_brainGraph_gui:
    • Option for specifying maximum values for edge widths
  • plot_corr_mat: color cells based on weighted community or network
  • plot_global:
    • legend position is now "bottom" by default
    • can specify xvar to be either "density" or "threshold"; if the latter, the x-axis is reversed
    • If data has a Study.ID column, the ggplot2 function stat_smooth is used and the statistic is based on a generalized additive model
  • plot_perm_diffs: added argument auc for using the area-under-the-curve across densities
  • plot_rich_norm:
    • Added argument fdr to choose whether or not to use FDR-adjusted p-values
    • Should work for more than 2 groups
    • Now works with multi-subject data; collapses by Group and plots the group mean
  • plot_vertex_measures: can facet by different variables (e.g., lobe, community, network, etc.)
  • set.brainGraph.attributes:
    • calculate graph strength, which is the mean of vertex strength (weighted networks)
    • Invert edge weights for distance-based measures
  • write.brainnet:
    • Now allows for writing weighted adjacency matrices, using the edge.wt function argument
    • Can color vertices by multiple variables

brainGraph 0.62.0


Third CRAN release

Bug fix

  • had a bug in calculating the p-values. If you have already gone through the process of creating random graphs and the object phi.norm, you can fix with the following code: (add another loop if you have single-subject graphs, e.g. DTI data)
for (i in seq_along(groups)) {
  for (j in seq_along(densities)) {
    max.deg <- max(V(g[[i]][[j]])$degree)
    phi.norm[[i]][[j]]$p <- sapply(seq_len(max.deg), function(x)
        sum(phi.norm[[i]][[j]]$phi.rand[, x] >= phi.norm[[i]][[j]]$phi.orig[x]) / N)

where N is the number of random graphs generated.

  • dti_create_mats: there was a bug when sub.thresh equals 0; it would take matrix entries, even if they were below the mat.thresh values. This has been fixed. Argument checking has also been added.

Major changes

  • Now requires the package RcppEigen for fast linear model calculations; resulted in major speed improvements
  • Now requires the package permute for the NBS function
  • group.graph.diffs:
    • Uses the function fastLmPure from RcppEigen for speed/efficiency
    • Can specify multiple alternative hypotheses
    • Linear model specification is more limited now, though
  • Added data table for the destrieux.scgm atlas

New functions

  • SPM: new function that replaces and improves upon both group.graph.diffs and permute.vertex
  • NBS: implements the network-based statistic
  • analysis_random_graphs: perform all the steps for getting small-world parameters and normalized rich-club coefficients and p-values
  • plot_global: create a line plot across all densities of global graph measures in the same figure
  • vertex_spatial_dist: calculates the mean edge distance for all edges of a given vertex

Minor changes

  • dti_create_mats: changed a few arguments
  • edge_spatial_dist: re-named from spatial.dist
  • group.graph.diffs: returns a graph w/ spatial coord's for plotting
  • plot_brainGraph_list:
    • You can now specify a condition for removing vertices (e.g. hemi == "R" will keep only right hemisphere vertices; includes complex logical expressions (i.e., with multiple '&' and '|' conditions)
    • Vertex sizing and coloring is a bit more flexible
  • New vertex attribute Lp (average path length for each vertex)
  • plot_brainGraph_gui:
    • Added a checkbox for displaying a color legend or not
    • Can color vertices by weighted community membership
    • Added an Other option for adjusting edge widths by a custom attribute
    • More options for adjusting vertex sizes when the graph is weighted
    • Made the GUI window more compact to fit lower screen resolutions
  • plot_rich_norm:
    • New argument to group the plots by either "density" (default) or "threshold" (for multi-subject, e.g. DTI data)
  • set.brainGraph.attributes: New calculations for weighted graphs:
    • Modularity and community membership
    • Participation coefficient and within-module degree z-score
    • Vertex-level transitivity
    • Vertex-level shortest path lengths

brainGraph 0.55.0


Second CRAN release

New functions

  • aop and loo calculate measures of individual contribution (see Reference within the function help)
    • Now requires the package ade4
  • plot_boot: new function based on the removed plotting code from boot_global
  • plot_rich_norm: function to plot normalized rich club coefficient curves

Minor changes

  • boot_global:

    • added an OS check to get multicore functionality on Windows
    • removed the code that created some plots
    • updated to work with the newer version of corr.matrix
  • brainGraph_init:

    • does a better job of dealing with subcortical gray matter data
    • now also returns the "tidied" dataset
  • corr.matrix:

    • was basically reverted back for speed purposes
    • minor syntax change
  • count_interlobar no longer takes atlas.dt as an argument

  • dti_create_mats now accepts argument P for "number of samples"

  • edge_asymmetry now works on Windows (changed from mclapply to foreach)

  • get.resid:

    • got a complete overhaul; now works with data.table syntax
    • now returns data.table of residuals with a Study.ID column
    • fixed minor bug when use.mean=FALSE but covars has columns mean.lh and/or mean.rh; fixed minor bug w/ RH residual calculation
    • fixed bug when use.mean=TRUE (syntax error for RH vertices)
  • graph.efficiency: now works on Windows (changed from mclapply to foreach)

  • part.coeff: has a workaround to work on Windows


    • updated to work with new version of corr.matrix
    • no longer takes atlas.dt as an argument
  • vertex_attr_dt is now essentially a wrapper for igraph's function as_data_frame

  • Exported plot_perm_diffs

  • Added argument checking for most functions

brainGraph 0.48.0


Initial CRAN release

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


3.0.0 by Christopher G. Watson, 5 months ago

Report a bug at!forum/brainGraph-help

Browse source code at

Authors: Christopher G. Watson [aut, cre]

Documentation:   PDF Manual  

GPL-3 license

Imports abind, data.table, doParallel, foreach, grid, lattice, MASS, Matrix, methods, permute, parallel

Depends on igraph

Suggests Hmisc, RGtk2, ade4, boot, cairoDevice, car, expm, ggplot2, ggrepel, gridExtra, mediation, oro.nifti, scales

Imported by netjack.

See at CRAN