brainGraph_UserGuide
brainGraph_UserGuide
Version 3.0.0
Christopher G. Watson, Ph.D.
Dept. of Pediatrics, Children’s Learning Institute
University of Texas Health Science Center at Houston
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
I Introductory Material 1
Chapter 1: Installation and Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1: System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.2: GUI-related note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3: OS-specific instructions and notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.1 Preferred method, any OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.2 Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3.3 Mac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3.4 Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4: Compatible neuroimaging software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.5: Compatible atlases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5.1 Using your own atlas: required format . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.5.2 Atlases to be added (potential) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
II brainGraph Basics 14
Chapter 4: Overview of the brainGraph Package . . . . . . . . . . . . . . . . . . . . . . . 15
4.1: Concepts/workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
ii
4.1.1 “Step 0”: Setting up data and scripts . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1.2 Step 1: Import data and create connectivity matrices . . . . . . . . . . . . . . . . 15
4.1.3 Step 2: Create graphs and calculate metrics . . . . . . . . . . . . . . . . . . . . . . 16
4.1.4 Step 3: Perform group analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.1.5 Step 4: Visualize results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2: Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.1 Graph creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.2 Graph metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.3 Group comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.2.4 Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.2.5 Random graphs, small world, and rich club . . . . . . . . . . . . . . . . . . . . . . 18
4.2.6 Generic methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
iii
7.1: Setting up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.1.1 Tractography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.1.2 fMRI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
7.2: Import, normalize, and filter matrices for all subjects . . . . . . . . . . . . . . . . . . . . . 42
7.2.1 Function arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.2.2 Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
7.2.3 Code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.2.4 Applying the same thresholds to other matrices . . . . . . . . . . . . . . . . . . . . 45
7.3: Graph creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.4: Graph- and vertex-level measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.5: Example commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
iv
10.1: Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
10.2: Function arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
10.3: Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
10.4: Code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
10.5: Creating a graph of the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.6: Plotting the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
10.7: Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
v
14.2: Euclidean distance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
14.3: Individual contributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
14.3.1 Add one patient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
14.3.2 Leave one out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
14.3.3 Plot types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
VI Visualization 125
Chapter 15: GUI and other plotting functionality . . . . . . . . . . . . . . . . . . . . . . 126
15.1: The GUI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
15.1.1 Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
15.1.2 Hemi/Edges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
15.1.3 Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
15.1.4 Vertex “decorations” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
15.1.5 Edge “decorations” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
15.1.6 Vertex groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
15.1.7 Keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
15.2: Other plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
15.2.1 Adjacency matrix plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
15.2.2 Plot global graph measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
15.2.3 Save a three-panel plot of the brain graphs . . . . . . . . . . . . . . . . . . . . . . 129
15.2.4 Save a single view for multiple brain graphs . . . . . . . . . . . . . . . . . . . . . . 129
15.2.5 Plot vertex-level measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
15.2.6 Plot group-wise volumetric data for ROI’s . . . . . . . . . . . . . . . . . . . . . . . 130
15.2.7 Save a list of graph plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
15.2.8 Other visualization tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Appendices 130
Chapter A: Attributes created by set brainGraph attr . . . . . . . . . . . . . . . . . . . 143
A.1: Graph-level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
A.1.1 Housekeeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
A.1.2 Unweighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
A.1.3 Weighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
A.2: Vertex-level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
A.2.1 Housekeeping/Other . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
A.2.2 Unweighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
A.2.3 Weighted . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
A.3: Edge-level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
vi
D.1.1 Randomise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
D.1.2 NBS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
D.1.3 Mediation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
D.2: Random graph generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
vii
List of Tables
viii
Preface
brainGraph is an R package for performing graph theory analysis of brain MRI data. It started out essentially
as one long script I wrote while taking a course in Fall 2013 on the statistical analysis of network data.
Initially, the functionality was specific to cortical thickness data only (from Freesurfer), but I have since
extended it to include functionality for DTI tractography (e.g., fdt network matrix from FSL’s probtrackx2,
and matrices from PANDA (21)) and resting-state fMRI (e.g., DPABI (132) and AFNI (17)). It should work for
any data that can be represented as a connectivity matrix.
There is some plotting functionality, but it doesn’t look as “polished” as other software. (However, it looks
comparable to figures I have seen in publications; see Plotting for some example plots and a function to
export the network data, and The GUI for a few screenshots of the GUI).
At the highest level of organization, there are several Parts. The general contents of each part are:
Introductory material contains installation information, validity of graph metrics calculated by igraph
and brainGraph, neuroimaging software and brain atlas compatibility, how to get help, other R packages
that may be of interest to neuroimaging researchers, and some code examples for getting data from
Freesurfer and FSL.
brainGraph basics contains information for starting to use the package. This includes a general overview
of the package, a brief introduction to R notation/conventions, a recommended workflow/script organization,
and an introduction to the package’s features and most basic operations.
Graph creation covers the necessary steps for creating graphs from your neuroimaging data. There
are separate chapters for structural covariance networks and data for which single-subject networks can
be created (e.g., DTI tractography or resting-state fMRI). The code blocks in these chapters start with
importing your data and end with some example operations you can perform on the graphs.
Group analyses detail the available methods for comparing groups (or performing within-group analyses).
These include the standard GLM, the Network-Based Statistic (NBS), and statistical mediation analysis for
single-subject graphs. For covariance networks, this includes bootstrapping, permutation/randomization
tests, and individual contributions. And for both types of network, random graph generation, small world
calculations, and rich club analysis.
Visualization describes the components of the brainGraph GUI, in addition to other functions for
visualizing different aspects of your data, such as adjacency matrix plots, plotting global (graph-level)
metrics by density, boxplots of vertex-level metrics, creating three-panel plots of the networks overlaid on a
brain MRI slice, and saving a list of graph plots. The chapter closes with description of a function for
exporting your data to work with the BrainNet Viewer tool.
Appendices list the attributes set by the function set brainGraph attr, several benchmarks (i.e.,
runtimes) for various functions/analyses, and the computing environment used in creating this document.
ix
Intended Audience
This User Guide is appropriate for researchers who use brain MRI to study connectivity. brainGraph
is not strictly limited to human MRI data, but it does not contain atlases for animal brains (but these
can be provided by the user). It is expected that the user has some experience with R (and/or other
programming languages), but this document should be appropriate for beginners. The user should have some
understanding of network/graph theoretical concepts. This User Guide is quite long, but I have attempted to
be comprehensive in documenting the functions in the package and the types of analysis that are common in
neuroimaging, with extensive code examples and figures. To learn more about the relevant topics (i.e., the
mathematics of networks, R programming), see some of my suggestions at Getting Help and Other Resources.
If you are a non-MRI researcher, there are many functions you can still use. See Functions for generic data
for a list.
Rationale
“The nice thing about standards is that you have so many to choose from.”
— Andrew S. Tanenbaum
Other tools for performing graph theory analysis of brain MRI data already exist. So why create a new one,
and why do it in R?
R is Free Software Using R does not require an expensive license (like Matlab), and does not involve
any “red tape” (such as the need to upgrade annually, having to deal with a licensing office, etc.). You can
simply download and install it. R is also open source, so you can add features, fix bugs, etc. Finally, you
can write your own packages, either for personal or public use. This package is, and will remain to
be, free and open source, in line with the recent push for sharing your code along with publications
(see Eglen et al. (32) for discussion).
R was made to do statistics The designers of R were statisticians (as are most/all of the R core
members). Many statisticians use R in their work. Additionally, there are currently more than 10,000
packages in the CRAN repository (as of Dec. 2020), many of which are created and maintained by experts
in statistics. If there is a statistical analysis you would like to perform, there’s a good chance it is available
in R. The R community is very extensive, with multiple e-mail lists, blogs, and forums (such as Stack
Overflow) available for help.
Package management Package management is very well done in R; downloading and updating packages
is nearly trivial. I have had a much easier time with R compared to dealing with dependencies for e.g., some
Python-based software (I know there is pip, but I had some issues; see this Stack Overflow question, which
I’m sure is now out-of-date). I consider myself tech-savvy, so I imagine it would be even more frustrating
for beginners. Downloading and installing brainGraph and its dependencies should be very simple, so the
user can focus on learning graph theory and how to interact with their data.
Documentation I have found the documentation for other tools/software specializing in graph theory
analysis of MRI data to be lacking (and in some cases non-existent), particularly in terms of the first step:
getting your data (cortical thickness/volumes, tractography, etc.) into a format that will just work. It has
been said that software is “only as good as its documentation”; I appreciate that many users just want a
tutorial to walk them through the steps, and I hope I have succeeded in that aspect.
Good support for reproducible research It is very easy to generate reproducible reports (or docu-
ments such as this one) on-the-fly. For this User Guide, I used knitr (131) with LATEX, and all the code is
in a git repository for version control. This system allows for easy documentation of analysis workflow and
any changes in output resulting from parameter changes; (re-)running all the code is essentially automatic
(I simply press \kp using Nvim-R with tmux to knit the pdf). I use the same process for generating results
x
from other analyses I do in R, such as reporting summary statistics from DTI analyses of FA/MD/RD.1
Furthermore, Tables are generated automatically, so I don’t have to type all entries by hand, or copy-paste
things and worry about formatting (reducing user error). In fact, my dissertation was written with knitr
and LATEX because of these features.
Typographical conventions
! New in v3.x.x
This box indicates a major change to brainGraph that was introduced in v3.0.0 and later.
! Warning
This box indicates a warning; e.g., operations that will take an extremely long time.
Note
This box replaces a footnote if the note is long.
1 There are other solutions in R that are similar to the Jupyter notebook, see for example rNotebook and editR
xi
Release Notes
Including all release notes would extend this document unnecessarily. You can always find the NEWS.md file
at the brainGraph repository: https://github.com/cwatson/brainGraph/blob/master/NEWS.md
Citing brainGraph
First, please cite Ref. Csardi and Nepusz (20) and any other relevant references for calculating certain graph
theory measures (see function documentation for some references). brainGraph is very reliant on igraph,
and they should be cited for their work.
I do not currently have a manuscript that specifically describes/introduces the package, but you may cite
Watson et al. (124). You also can get some citation information with the following code:
citation('brainGraph')
##
## To cite package 'brainGraph' in publications use:
##
## Christopher G. Watson (2020). brainGraph: Graph Theory Analysis
## of Brain MRI Data. R package version 3.0.0.
## https://github.com/cwatson/brainGraph
##
## A BibTeX entry for LaTeX users is
##
## @Manual{,
## title = {brainGraph: Graph Theory Analysis of Brain MRI Data},
## author = {Christopher G. Watson},
## year = {2020},
## note = {R package version 3.0.0},
## url = {https://github.com/cwatson/brainGraph},
## }
xii
11. Ohashi et al. (82)
12. Homan et al. (52)
13. Ramos-Prats et al. (88)
xiii
xiv
Part I
Introductory Material
1
1
Installation and Requirements
! New in v3.0.0
There are several fewer package dependencies in the latest version. This should allow for faster/leaner
installs.
There aren’t any, specifically (aside from required R packages). But I have some recommendations:
Hardware You should have a multi-core CPU and lots of RAM (the more, the better; probably
at least 4 GB). Having a large number of cores is very important, particularly if you
want to do permutation testing or bootstrapping (or if you are working with very
large graphs). Note that you will need a lot of RAM with more CPU cores.
Operating System I 100% recommend using Linux (my personal preference is CentOS; RHEL and
Scientific Linux are the same, and Fedora is similar). If you have been us-
ing Freesurfer and/or FSL, then you likely have access to a Linux machine. It may
be worthwhile to spin up a virtual machine running some flavor of Linux. Almost all
testing and developing of this package was done on 64-bit CentOS 6 and CentOS 7.
Some (early development) was done on 64-bit Windows 7.
Suggested Packages required for 1 or a few functions, and other general packages, include:
• RGtk2 and cairoDevice are mandatory only if you want to use the GUI. Thanks
to @michaelhallquist for his contribution in making this work!
2
1.2 GUI-related note 3
The GUI requires both RGtk2 and cairoDevice to be installed. These can sometimes be difficult to properly
install without issue.
If your operating system is Mac OS or Windows, please see this GitHub Gist. The comments contain more
recent information. You may need to install a couple additional packages; the code is at the end of the gist
(repeated here). The third package listed (RGtk2Extras) might not be required.
install.packages('gWidgets', dependencies=TRUE)
install.packages('gWidgetsRGtk2', dependencies=TRUE)
install.packages('RGtk2Extras', dependencies=TRUE)
install.packages('brainGraph')
For the latest development version, use devtools to install it from Github. It should install all dependencies
for you.
require(devtools)
devtools::install_github('cwatson/brainGraph')
1.3.2 Linux
You may download the tarball from the official CRAN page or elsewhere, and in R you would install it by
typing one of the following two commands:
The latter command above is equivalent to installing from the command line, and requires that all dependencies
have already been installed:
1.3.3 Mac
I haven’t tested on Mac yet, but here are the versions that it should work on:
macOS 10.13 High Sierra see the note and link in GUI-related note
OS X 10.11 El Capitan has not passed recent CRAN checks (specifically, version 10.11.6 ), but I
have had previous confirmation from a user that it works.
OS X 10.10.5 Yosemite it may be necessary to download the binary GTK package (.pkg file) from
https://r.research.att.com/.
1.3.4 Windows
You should first try to download directly from CRAN (using install.packages() ). If that causes any
problems, I recommend using devtools and installing directly from Github. See also the URL listed in
GUI-related note for some instructions when it comes to installing RGtk2. You may end up needing to
add/edit a couple environment variables.
Some additional information:
• To install from source on Windows, you first have to download and install Rtools
• You may have to install either the 32- or 64-bit version only, in case there is a problem with GTK+
(required for the plotting GUI). To install the package for just one architecture, run the following
command:
install.packages('brainGraph', INSTALL_opts='--no-multiarch')
The functions in brainGraph should work for any software that returns a text file containing connectivity
matrices (unless you are creating covariance/correlation networks). Here is a list of software that I know to
work (either first-hand or from a brainGraph user):
Table 1.1: Brain atlases, their corresponding R object names, and a reference for the atlas.
There are a handful of atlases that will work “out-of-the-box”. See Table 1.1 for the atlases, the R object
names, and references for each.
! New in v3.0.0
The following atlases are new in v3.0.0:
hcp mmp1.0
power264
gordon333
brainnetome
In the next code block, I show several lines of the dk atlas (this object is a data.table), along with the
structure of the object. The name.full column is provided (for a handful of atlases) for use in tables for
publication (if desired).
dk[4:9]
str(dk, strict.width='cut')
6 Chapter 1: Installation and Requirements
dosenbach160[, table(network)]
## network
## default fronto-parietal cingulo-opercular sensorimotor
## 34 21 32 33
## cerebellum occipital
## 18 22
I recommend writing the data object as a rda file (using save ); then it can be re-loaded with load .
1. Join the Google Group, brainGraph-help, by going to the Google Group page and clicking Apply to
join group. The email address for the group is [email protected].
2. Open an issue on the Github issues page. This requires that you have a Github username already. I am
emailed any time an issue is opened.
For both of these, there are a few things you can do to aid me in figuring out the problem, including:
• Include your session info using either of the commands sessionInfo() or session info() (from
the devtools package).
• Save the relevant data needed for me to reproduce the problem. Use save if there are multiple
variables, and saveRDS for individual objects/variables.
• Include the exact code/command line that you used when you encountered the problem. Ideally, send
me the code in a .R script.
7
8 Chapter 2: Getting Help and Other Resources
2.2.2 R programming
For help with learning R itself, there are a multitude of tutorials (freely) available, and I can help with code
issues specific to brainGraph. Some websites that might be of use:
• R-tutor
• Quick-R
2.3.3 Neuroconductor
Neuroconductor is a repository of medical image analysis packages as well. The name calls to mind the
Bioconductor project for molecular biology. More information can be found here.
2.3.5 Other
Finally, there are still more packages for working with MRI data:
Since I don’t expect potential users to blindly trust that my code will do what they want it to do, I have
compared results using brainGraph with results from Brain Connectivity Toolbox (BCT). There are a
few minor differences that appear to be off by just a scalar:
Measure
Degree Strength (weighted networks)
Edge betweenness K-coreness centrality
No differences Subgraph centrality Within-module degree z-score
Participation coefficient Clustering coefficient
Transitivity (graph-wise) Assortativity (graph-wise)
Global efficiency Local efficiency
Connected components Motif frequency (# of triangles)
Betweenness centrality Results obtained from BCT are exactly 2x that of igraph.
Eigenvector centrality Results obtained from BCT are ≈ 3.6x that of igraph (for unknown reasons)
mean(shortest.paths(g)[!is.infinite(shortest.paths(g))])
Modularity (Louvain) There are differences, but minor. I don’t know if they are systematic or
not.
If you still would like to convince yourself, or do your own testing (please do so!), download the R.matlab
package and use the following code. To understand what these variables are, see Chapter 5 (and later). To
use these variables in Matlab, simply type (in Matlab) load g1.mat.
10 Chapter 2: Getting Help and Other Resources
This chapter describes how to get data that can easily be imported into R for use with brainGraph. Specifically,
I will use cortical thickness data from Freesurfer in the first section, and will explain how to use Freesurfer
ROI’s as seed regions for tractography in the second section.
Note
The code in this chapter is specific to Bash; there should be a similar solution for other shells.
Use aparcstats2table to get mean cortical thickness for each region and each subject into a single file.
You may also get subcortical gray matter volumes with asegstats2table. Replace the subjects variable
definition with something that makes sense for your data.
Collect regional statistics
3.2 Tractography
In this section, I describe the steps for using one of the Freesurfer atlases (along with subcortical gray
matter) as seed regions for probtrackx2 in FSL. I have a script for automation, but the code in this section
is a good start. It is assumed that recon-all has been completed for the current subject (because I use the
transformation matrices that are calculated by TRACULA). I use the Desikan-Killiany atlas for cortical regions,
and the subcortical regions are included.
11
12 Chapter 3: Getting data from Freesurfer and FSL
I have more tools in a Bash library which can be found at my GitHub repository. The code in this library
includes initial preprocessing steps through to tractography.
The existence of the file anatorig2diff.bbr.mat is from TRACULA; if you want to use this file, you must run
the first step of trac-all. The code example assumes that a dmrirc config file for the subject exists.
Get individual ROI’s
1 if [ ! -e "${SUBJECTS_DIR}/${subj}/dmri/xfms/anatorig2diff.bbr.mat" ]; then
2 trac-all -c ${subj}.dmrirc -intra -masks
3 fi
4
5 labelfile='dk.scgm.txt'
6 mkdir -p seeds/dk.scgm && cd seeds/dk.scgm
7 while read line; do
8 roiID=$(echo ${line} | awk '{print $1}' -)
9 roiNAME=$(echo ${line} | awk '{print $2}' -)
10 fslmaths
11 ${SUBJECTS_DIR}/${subj}/dlabel/diff/aparc+aseg.bbr
12 -thr ${roiID} -uthr ${roiID}
13 -bin ${roiNAME}
14 fslstats ${roiNAME} -V | awk '{print $1}' >> sizes.txt
15 done < ${labelfile}
16
1 The mgz volumes for the DK and Destrieux atlases are created automatically by recon-all.
3.2 Tractography 13
22 --ventricles -o ventricles.nii.gz
The final step of the while loop calculates the ROI sizes, which you may wish to use when normalizing the
connectivity matrices; see Tractography and fMRI. The final lines of the code create a text list of the seed
region files and sorts them by size; this is used as input to probtrackx2 (specifically, the -x option).
Part II
brainGraph Basics
14
4
Overview of the brainGraph Package
This chapter provides an overview of brainGraph both in terms of concepts/workflow and the functions
themselves. This package relies almost entirely on the igraph package (20) (hence the creative name for my
package), so all operations/functions require this package. A complete list of the functions and their help
sections is in the package manual.
4.1 Concepts/workflow
There are a handful of conceptual/workflow-related categories (or “levels”) under which functionality in
brainGraph falls. By “workflow”, I mean this is more or less the order of operations for your user scripts.
The steps I list below are very generic, and some of them will likely have multiple “sub-steps” (e.g., different
types of group analyses).
Structural covariance The input data need to be csv or tsv files containing the region-wise brain
metrics (e.g., cortical thickness; see Import the data) for all subjects.
DTI tractography The input data should be the connectivity matrices as calculated from the
tractography program of your choosing. I personally use FSL’s probtrackx2.
See Setting up for more info.
Resting-state fMRI The input data should be the connectivity matrices as calculated by your software-
of-choice, representing the inter-regional (partial) correlations, for example.
Once the data are imported, matrices of structural covariance will be created from partial correlations, linear
model residuals, etc. (see Correlation Matrix and Graph Creation). The same function that performs those
correlations will threshold the matrices by density or threshold. These networks will typically be group-level ;
i.e., there will be 1 network per group.
For subject-level networks (DTI tractography or resting state fMRI), you threshold the connectivity matrices
based on criteria of your choosing (see Import, normalize, and filter matrices for all subjects).
15
16 Chapter 4: Overview of the brainGraph Package
4.2 Functions
! New in v3.0.0
All of the following (except the last 2) are new functions, while make brainGraph is now an S3 method.
make brainGraphList Creates an object containing, in addition to some metadata, a list of brainGraph
objects. This list should contain all study subjects, irrespective of group membership, for a single threshold
or density.1 This same function is used to create graphs of the results from brainGraph GLM (see Vertex-wise
group analysis (GLM)), mtpc (see Multi-threshold permutation correction), and NBS (see Network-based
statistic (NBS)). Furthermore, you can supply the output of corr.matrix directly to this function for
structural covariance networks (see Graph creation).
make brainGraph Creates a brainGraph graph object, given an igraph graph object or matrix. This
assigns several attributes that are specific to brain MRI data (mostly related to the brain atlas in use).
You most likely should not have to call this function yourself (except when creating graphs of the results
from brainGraph mediate; see Graph- and vertex-level mediation analysis). Otherwise, you should use
make brainGraphList.
make auc brainGraph Creates a single brainGraphList object in which each graph contains the area
under the curve (AUC) of the specified graph- or vertex-level metric(s).
make intersection brainGraph Create a graph based on the intersection of vertices meeting some
criteria. For example, if you have multiple t- or F-contrast graphs, you can determine vertices showing a
significant difference. See ?make intersection brainGraph for examples.
make empty brainGraph Creates an empty graph (i.e., one with no edges); typically the end user will
not need to call this. This is analogous to igraph’s make empty graph.
make ego brainGraph Creates a graph of the union of multiple vertex neighborhoods. This extends
igraph’s make ego graph.
1 You can think of these objects as analogous to the 4-D NIfTI files that are created by FSL’s tbss (i.e., the files used as input
to randomise).
4.2 Functions 17
• Vertex roles; gateway coeff (118), part coeff and within module degree z score (45)
• Rich club calculations; rich club coeff, rich club norm, and rich core (71)
• Edge counts; count homologous (counts the number of edges between homologous brain regions) and
count inter (counts the number of edges between and within all lobes, hemispheres, etc.)
One function in the package, set brainGraph attr, calculates most of these metrics and more for a given
graph (e.g., global efficiency, clustering coefficient, characteristic path length, and many more), and for its
vertices (e.g., degree, nodal efficiency, etc.) and edges (e.g., edge betweenness). This is very useful because it
removes the nuisance of having to type a separate command for every measure of interest. To see exactly what
it calculates, see Attributes created by set brainGraph attr or check the function help (accessible by typing
?set brainGraph attr ) under the heading Value. However, you will likely not call this function yourself;
it will be done automatically, for all subjects, if you pass set.attrs=TRUE to make brainGraphList.
• Between-group vertex-wise analysis of graph metrics with the General Linear Model (GLM): brain
Graph GLM. See Vertex-wise group analysis (GLM) for details.
• The network-based statistic (NBS) (134): NBS. See Network-based statistic (NBS) for details.
• Multi-threshold permutation correction (MTPC) (30) method for inference: mtpc. See Multi-threshold
permutation correction for details.
• Mediation analysis: brainGraph mediate. See Graph- and vertex-level mediation analysis for details.
• Bootstrapping and permutation testing (for structural covariance networks): brainGraph boot and
brainGraph permute. Details can be found in Further analysis.
• “Individual contributions” for data in which single-subject graphs are not available (e.g., structural
covariance networks); loo and aop. See Individual contributions for details. (100)
• Targeted attack and failure analyses: robustness. See the “Robustness” section in Further analysis for
implementation and plotting.
18 Chapter 4: Overview of the brainGraph Package
4.2.4 Visualization
There is a GUI for plotting the graphs overlaid on a slice of the MNI152 brain (plot brainGraph gui). You
can visualize up to two brains (single orientation; e.g., axial) at once. The GUI controls vertex/edge color
and size, labels, inclusion/exclusion, and more. See The GUI for more details. In addition, there are some
functions for plotting various graph metrics; see Other plotting. Finally, there is a plotting method for the
classes mentioned in Box 4.1. See the respective chapters introducing the classes for details.
groups Returns a character vector of group names for each subject. Works for brainGraphList,
brainGraph resids, and corr mats objects.
nobs Returns an integer of the number of subjects in an object. Works for bg GLM, NBS, mtpc,
brainGraphList, and brainGraph resids objects.
case.names Returns a character vector of the subject ID’s in an object. Works for bg GLM and
brainGraph resids objects.
region.names Returns a character vector of region names in an object. Works for data.table, bg GLM,
mtpc, brainGraph resids, and corr mats objects.
nregions Returns an integer of the number of regions in an object. Works for bg GLM, NBS, mtpc,
corr mats, and brainGraph resids objects.
4.2 Functions 19
brainGraph This class is essentially the same as an igraph graph object, but adds several
graph-level (atlas, modality, Group, etc.) and vertex-level (lobe, hemi, spatial coordinates, etc.)
specific to brain MRI analysis. These are created directly by make brainGraph and indirectly by
make brainGraphList.
brainGraphList A class containing various metadata (e.g., the package version used to create
it and the date), as well as a list of graphs. Most of the group analysis functions work on these
objects.
bg GLM Contains results from brainGraph GLM (see Vertex-wise group analysis (GLM)).
NBS Contains results from NBS (see Network-based statistic (NBS)).
mtpc Contains results from mtpc (see Multi-threshold permutation correction).
bg mediate Results from brainGraph mediate (see Graph- and vertex-level mediation analysis).
brainGraph GLM The graph associated with bg GLM objects. It has GLM-specific attributes
(for plotting), created by the function make brainGraphList.
brainGraph NBS The graph associated with NBS objects. It has NBS-specific attributes (for
plotting), also created by make brainGraphList.
brainGraph mtpc The graph associated with mtpc objects. It is also created by
make brainGraphList.
brainGraph mediate The graph associated with bg mediate objects. It has mediation-specific
attributes (for plotting), created by make brainGraph.
brainGraph boot Returned by brainGraph boot. See Bootstrapping for details.
brainGraph permute Returned by brainGraph permute. See Permutation testing for details.
brainGraph resids Returned by get.resid for structural covariance networks (see Structural
covariance networks).
corr mats Returned by corr.matrix for structural covariance networks
In this Chapter, I describe the most basic aspects of using brainGraph. I begin by suggesting some script/code
organization. Then I show the other R packages that I load. Next, I show the structure of my covariates data.
Finally, I introduce graph, vertex, and edge attributes and show how to plot from the terminal. For some
information about R notation, see Box 5.1.
01 load myProject.R loads/imports the [thickness/tractography/rs-fMRI] data and creates some initial
variables. I have a different script for each modality and for each project/study.
02 create graphs.R creates the graphs, etc. I have a different script for volumetric (covariance
networks) data and for tractography/rs-fMRI.
03 random graphs.R runs analysis random graphs, and does extra processing if, for example, I create
random graphs controlled for clustering.
main.R sources all of the other scripts. I can comment out specific lines if I don’t want to
re-do a step.1
This is similar in philosophy to the top response to this Stack Overflow question. I also recommend that you
read Noble (81) which is specific to computational biology but has very good recommendations for project
organization. In the future, I would like to move to using Makefiles for this kind of data processing workflow.
I keep my code, data, and results in separate directories. Within the results, I have sub-directories for
different modalities and the date the analysis was performed.
1 I actually haven’t done analyses this way lately because it seems to be slower overall (possibly due to how R handles memory,
20
5.1 Setting up files for your project 21
Assignment Unlike Matlab, assignment is usually done with the symbol <- . Reasons for
this are beyond the scope of this document. However, argument specification
within a function call will always use the equals sign.
Lists A list is very similar to a cell array in Matlab. To access list elements in R, you
must use double square brackets (whereas in Matlab you would use curly braces).
For example, to access the graphs for group 1 (shown later), you would type
g[[1]] .
Dollar sign The dollar sign $ is used to access list or data frame elements if they are named.
In the section on covariates, if I want to access the column for subject Age, I
would just type covars$Age .
data.table In some code using data tables, I use the assignment operator := . This allows
assignment you to insert/change a column in-place, and is very fast and memory efficient.
The *apply These functions (sapply, lapply, mapply, Map, llply, etc.) all operate on
functions lists/vectors. They are equivalent to a for loop in other languages, but require
less typing.
Object names Following the Google style guide, I name my constants beginning with a k, e.g.,
kNumDensities refers to the number of densities. Object names should be as
informative as possible; however, some of the ones I use are stupid/bad and were
done out of laziness. Most of the data.table’s I create begin with dt and the
graphs I create begin with g. I usually include a dot/period in object names, which
differs from Hadley Wickham’s style guide, and also differs from dot notation in
Object-Oriented Programming.
! New in v3.0.0
Global options are new in v3.0.0.
There are a few package-specific global options that affect package usage. I will first list the option names,
and then describe how you can change them.
bg.subject id The character string specifying the variable name (in your project) corresponding to subject
ID’s. The default value is Study.ID (this was hard-coded in all previous versions). If your
project uses a different name (e.g., if you follow the BIDS suggestion of participant id)
then you can specify it with this option.
bg.group The character string specifying the variable name (in your project) corresponding to the
group variable. The default is Group (this was hard-coded in previous versions). One
possible alternative (suggested by BIDS ) is group.
bg.session (not used ) The character string specifying the session/time variable name. The default is
Time; one alternative (BIDS ) is session id.
22 Chapter 5: Getting started
bg.progress A logical indicating whether to always/never show a progress bar (for functions with the
option). The default is TRUE.
bg.ncpus Integer indicating how many CPU cores to use for parallel operations. The default is
2. This is only a fallback; it is expected that the user registers the appropriate number
themselves (see next section).
Changing any of these options is simple, and can be specified in your .Rprofile or at the start of your
analysis scripts. For example, to use the BIDS defaults, you would include
options(bg.subject_id='participant_id', bg.group='group')
If you would like to use the defaults, you do not need any code.
suppressMessages(library(brainGraph))
# Check OS version for parallel processing
OS <- .Platform$OS.type
if (OS == 'windows') {
pacman::p_load(snow, doSNOW)
num.cores <- as.numeric(Sys.getenv('NUMBER_OF_PROCESSORS'))
cl <- makeCluster(num.cores, type='SOCK')
clusterExport(cl, 'sim.rand.graph.par')
registerDoSNOW(cl)
} else {
suppressMessages(library(doMC))
registerDoMC(detectCores())
}
Once brainGraph is loaded, you can quickly see all its functions and the package help section:
ls('package:brainGraph')
help(package='brainGraph')
covars
str(covars)
One of the nice things about R is that you don’t need to change a variable such as sex to 0’s and 1’s; it
considers the M and F as factors and can handle them easily. The same goes for subject group names (and
pretty much any other non-numeric variable).
What I consider to be a smart thing to do (regarding covariates files) is to include some kind of “indicator
variable” in your spreadsheet/database of all study subjects, where a 1 means the subject has acceptable
data for that [MRI sequence, neuropsychological test, experiment, etc.], and a 0 otherwise. You can see this
in the first code block of Tractography and fMRI, in which I subset the covars.all data table using
tract == 1 . I then only select the first 5 columns, as those contain the only relevant covariates I wanted
for that application. Later, if I choose to, for example, test for correlation between vertex betweenness and
full-scale IQ (FSIQ), I can access that variable easily:
There are three types of attributes that an igraph graph object can have: graph-, vertex-, and edge-level.
version A named list with the versions of R, igraph, and brainGraph at the time of graph creation
24 Chapter 5: Getting started
date A character string with the datetime for when the graph was created. The format is the ISO
8601 date standard, uppercase T, and the ISO 8601 time standard.
type Whether the graph is observed or a random graph
atlas The atlas
modality The imaging modality represented by the data
weighting If the graph is weighted, it will print either the value of g$weighting or what the edge
weights represent (e.g., if weighting=’sld’ , it will print Streamline density)
clust.method The clustering (i.e., community detection) method used to calculate communities
density The graph density (percent)
threshold The numeric value used to threshold graphs (if applicable)
Subject ID The Study.ID (taken from the name attribute), if one was supplied to make brainGraph or
make brainGraphList
Group The subject group, if one was supplied
level Either subject, group, or contrast
summary(g.ex)
##
## ============================================
## Summary for *observed* subject-level graph:
## ============================================
##
## Software versions
## R release: R version 3.6.0 (2019-04-26)
## brainGraph: 3.0.0
## igraph: 1.2.4.1
## Date created: 2020-12-31 06:49:24
## Observed or random? Observed
## Brain atlas used: Desikan-Killiany
## Imaging modality: Cortical thickness
## Edge weighting: Unweighted
## Clustering method: Louvain (multi-level modularity optimization)
## Graph density: 15.76%
## Threshold: N/A
## Subject ID: N/A
## Group: Eg
## Graph attributes-----------------------------
##
## version Lp diameter vulnerability
## sys rich transitivity
## date E.global assort
## atlas clust.method assort.lobe
## level mod assort.lobe.hemi
## type density asymm
## modality conn.comp spatial.dist
## Group max.comp num.hubs
## Cp num.tri E.local
5.2 Graph object attributes 25
## Vertex attributes----------------------------
##
## name degree k.core
## lobe comp transitivity
## lobe.hemi color.comp E.local
## hemi asymm E.nodal
## x.mni dist vulnerability
## x dist.strength eccentricity
## y.mni knn comm
## y Lp color.comm
## z.mni btwn.cent circle.layout.comm
## z hubs GC
## color.lobe ev.cent PC
## circle.layout lev.cent z.score
## Edge attributes-----------------------------
##
## color.lobe color.comp dist btwn color.comm
g.ex$conn.comp
## size number
## 1 68 1
Also of interest may be the rich club coefficient of a graph (see Colizza et al. (16), Zhou and Mondragón (135)).
Briefly, the rich club coefficient is the ratio of edges present to total possible edges in a subgraph with minimum
degree k.3 The following example returns a data.frame for (in this specific example) k = 1, 2, · · · , 16; R is
the rich club coefficient, Nk is the number of vertices present, and Ek is the number of edges present:
g.ex$rich
## k phi Nk Ek
## 1: 1 0.1576 68 359
## 2: 2 0.1576 68 359
## 3: 3 0.1610 67 356
## 4: 4 0.1641 66 352
## 5: 5 0.1641 66 352
## 6: 6 0.1687 64 340
## 7: 7 0.1768 60 313
## 8: 8 0.1938 52 257
## 9: 9 0.2068 46 214
## 10: 10 0.2365 36 149
2 Calculated by the igraph function components, and set by set brainGraph attr
3 See Rich-club Analysis for more details.
26 Chapter 5: Getting started
If you’re working with single-subject graphs, you can use the subject argument to set brainGraph attr.
This will give the graph a name attribute, which is displayed when you print the graph; the name is on the
first line of the output:4
print(g.tmp, full=FALSE)
g.tmp$name
V(g.ex)$degree
## [1] 10 9 11 10 8 12 11 7 14 10 9 4 8 13 12 12 12 10 12 7 12 12 8
## [24] 11 13 10 8 8 14 9 14 11 16 10 10 9 8 10 12 7 12 11 12 3 15 8
## [47] 11 8 11 13 7 13 10 6 13 12 12 16 13 10 15 6 9 12 14 12 12 9
E(g.ex)[2:6]
head(E(g.ex)$btwn)
There are multiple community detection algorithms available in igraph. You can run community detection on
your own or through make brainGraph (or make brainGraphList). Alternatively, you can specify which via
4 You will most likely want to use subject ID’s, not real names.
5.4 Plotting 27
the clust.method argument. All clustering functions begin with the string ’cluster ’ ; the function
argument recognizes the remainder of the function name. For example, if you would like to specify the
Walktrap algorithm, you would pass clust.method=’walktrap’ .
The benefit of letting the package choose one automatically is that the appropriate method will be chosen
depending on the type of input graph. There are a few different behaviors:
• By default, the Louvain algorithm (see Ref. Blondel et al. (12)) is applied (mainly because it seems to
be the most popular one for neuroscience studies)
• If you select ’spinglass’ , but the graph is unconnected, then the Louvain algorithm is used.
• The Walktrap algorithm is used if there are any negative edge weights, unless you pass ’spinglass’ .
• If ’edge betweenness’ is selected, the edges are first transformed because this algorithm considers
the edges as distances (not connection strengths).
For general help with communities, type ?communities . For a great demo on community detection (from
which you can get useful code) is accessed by typing demo(community) . A description of some of the
algorithms can be found in this Stack Overflow answer.
To plot the communities with a specific layout, use the following code.5 Here, the function layout_with_fr
uses the Fruchterman-Reingold method, which is a force-directed layout algorithm (41). This is shown in
Figure 5.1.6
5.4 Plotting
Plotting graphs is much simpler when using the GUI plot brainGraph gui; however, you can achieve almost
all of its functionality on the command line. For example, the subgraph argument allows you to specify a
condition for which vertices to keep; if you wanted to plot only vertices with degree greater than 10, this
would be subgraph=’degree > 10’ . You can combine multiple conditions, using either & (AND) or |
(OR), e.g., subgraph=’degree > 10 & btwn.cent > 50’ . Plotting a single hemisphere is a “special”
subgraph and can be chosen using the hemi argument. Additonally, you may choose to show a legend for
vertex colors, using the show.legend argument.
suppressMessages(library(oro.nifti))
mni152 <- nifti(brainGraph:::mni152_mat, datatype=4, regular='r', reoriented=TRUE,
scl_slope=1, quatern_c=1, descrip='FSL3.3', sform_code=4, xyzt_units=10,
srow_x=c(-2, 0, 0, 90), srow_y=c(0, 2, 0, -126), srow_z=c(0, 0, 2, -72),
5 To avoid seeing the polygons that highlight each group, include the argument mark.groups=NULL .
6 For more layouts, type the command ?layout (include the trailing underscore).
28 Chapter 5: Getting started
●
●
● ● ●
● ● ●
●
● ● ● ●
● ● ●
● ● ●
● ● ●
● ● ●
● ● ●
●
● ● ● ● ●
●
● ●
● ● ● ● ●
● ● ●
● ●
● ● ● ● ● ●
● ●
● ● ●
● ●
● ●
●
●
●
●
●
●
5.4.2 Axial
Figure 5.2 shows an example plot of an axial view7 ; here, vertex size is proportional to vertex degree. The
vertex color is based on community (module) membership.
5.4.3 Sagittal
Figure 5.3 shows an example of left and right sagittal views. These only show the intra-hemispheric connections.
Here, lobe colors are based on lobe membership.
! New in v3.0.0
You can include the label argument to include text labels in the figures. Here, I include A) and B).
5.4.4 Circular
Figure 5.4 shows a circular plot. As the legend indicates, vertex color indicates lobe membership. Vertices of
the left hemisphere are located on the left half of the plot, frontal lobe vertices at the front, etc.
31
6
Structural covariance networks
6.1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
6.2: Import the data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3: Model residuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
6.4: Data checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
6.5: Correlation Matrix and Graph Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
6.6: Getting measures of interest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
6.7: Long and wide data tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
This chapter shows how to create graphs of structural covariance networks. The code is specific to Freesurfer
and cortical thickness, but will also work with volume, surface area, and local gyrification index (LGI). It is
possible that structural MRI data from other software packages are compatible, but (currently) the data files
will have to conform to the outputs from Freesurfer.
6.1 Overview
The following is the sequence of steps for structural covariance network analysis. Each of these is discussed in
subsequent sections of this chapter.
2. Generate model residuals (and check the QQ plots) (this is optional; you may also correlate the raw
volumetric data)
3. Create correlation matrices (of residuals or raw volumetric data) for a number of densities/thresholds
5. Put the data into tables for easy exploration of graph- and vertex-level metrics (e.g., global efficiency,
vertex degree, etc.)
32
6.2 Import the data 33
# 3. Correlation matrices
densities <- seq(0.05, 0.20, 0.01)
corrs <- corr.matrix(myResids, densities=densities)
The following code block is what I put in my 01_load_project.R script; however, this script will have to be
project-specific. The main purpose is to import the data through import scn, which will do a few things:
• Changes the first column name to match the subject ID string; i.e., the value of
getOption(’bg.subject id’) .
• Removes the mean thickness (or volume, area, etc.) column(s) (if present)
• For subcortical gray matter (SCGM): keeps only the first 15 columns (i.e., the subject ID column and
the 14 SCGM data columns). Requires asegstats.csv to be in the same directory as the other files.
• For atlases including SCGM: finds “missing” subjects; i.e., those that are not present in both the cortical
and subcortical data files
34 Chapter 6: Structural covariance networks
The next step is to get the model residuals. You can perform linear models on a per-group basis or across all
groups at once. get.resid calculates the studentized residuals (sometimes called leave-one-out residuals).1
use.mean Logical indicating whether or not to include the mean per-hemispheric structural measure in
the models. Default: FALSE
exclude.cov A character vector of columns in covars that you would like to exclude from the models (if
any).
6.3.3 Example
Here I accept the default arguments except that I choose to exclude Group from the models.
If you would like to get the residuals for each group separately, you simply include method=’sep.groups’ .
It is always useful to check the quality of your data (which should have been done at a previous step). The
plot method for structural covariance residuals plots a qqplot for the desired region(s) (see the Wikipedia
page if you are unfamiliar with qqplots); these are useful for checking normality.
6.4.1 Summary
On visual inspection of my data, for rSMAR (right supramarginal gyrus), I saw that there is one sample
quantile (i.e., one subject) with a value less than ≈ −3; this is very likely to be an outlier. To check which
subject this is, you can look at the summary method output. When I looked at the subject’s brain MRI, it
turns out he/she had a stroke in the right supramarginal/inferior parietal lobe.
If you do not include a value for the regions argument, then the function prints outlier information for
all regions (not shown).
summary(resids, region='rSMAR')
##
## =====================================
## Structural covariance residuals
## =====================================
## # of outliers for region rSMAR:
36 Chapter 6: Structural covariance networks
## 6
## Subjects that are outliers:
## ------------------
## [1] "029" "075" "098" "103" "125" "131"
## Outliers
## ------------------
6.4.2 Plot
As an example of the plotting output, Figure 6.1 shows the qqplot for one region; one panel is the “standard”
output, and the second shows points colored by group. In both, “outliers” (those further than 2 SD’s from
the mean) are triangles. The outliers are also marked with their number in the data.table of residuals.
plot(resids, region='rSMAR')[[1]]
plot(resids, region='rSMAR', cols=TRUE)[[1]]
●●●●● ●●●●●
●●●●● ●●●●●
●●●●● ●●●●●
●● ●●
● ●
●● ●●
●● ●●
●●●● ●●●●
●● ●●
●●●●●● ●●●●●●
● ●
● ●
●●● ●●●
Sample Quantiles
Sample Quantiles
●● ●●
●● ●●
●● ●●
●●● ●●●
●●● ●●●
0
●●● ●●●
●●●●●● ●●●●●●
●● ●●
●●●● ●●●●
●●●● ●●●●
●●●●● ●●●●●
● ●
●●● ●●●
●● ●●
●●● ●●●
●● ●●
●● ●●
●● ●●
●● ●●
●● ●●
● ●
●●● ●●●
●● ●●
●● ●●
● ●
●●● ●●●
●● ●●
● ●
●● ●●
● ●
● ●
● ●
● ●
● ●
−2
−2
● ●
029 029
075
075
103 103
125 125
−2 −1 0 1 2 −2 −1 0 1 2
Theoretical Quantiles Theoretical Quantiles
For all regions, you should save the plots to a multi-page PDF using the function marrangeGrob from the
gridExtra package:
6.5 Correlation Matrix and Graph Creation 37
Next, correlate between pairs of regions for each group using corr.matrix. Simply use the output of
get.resid for the first argument here.
The function corr.matrix has an argument, density, which indicates the density of the desired graph. So,
if you want a graph with 10% of all possible connections, this value should be 0.1. To access the (correlation)
threshold used, see code below.
## Control Patient
## [1,] 0.5362 0.4846
## [2,] 0.5192 0.4685
## [3,] 0.5049 0.4560
## [4,] 0.4936 0.4380
## [5,] 0.4800 0.4234
## [6,] 0.4714 0.4118
## [7,] 0.4604 0.4030
## [8,] 0.4520 0.3958
## [9,] 0.4460 0.3869
## [10,] 0.4353 0.3747
## [11,] 0.4291 0.3667
## [12,] 0.4218 0.3581
## [13,] 0.4126 0.3498
## [14,] 0.4063 0.3409
## [15,] 0.3971 0.3360
## [16,] 0.3901 0.3284
Alternatively, you can skip the step in the previous section and just correlate the raw cortical thickness values.
I don’t recommend this, though, as variables like age and sex have known effects on cortical thickness. Simply
include what=’raw’ in the call to corr.matrix.
Note
Compare the new code in the next block with the old code here:
If you prefer that your graphs are weighted by the correlation coefficient, then you simply need to add
weighted=TRUE to the above function call.
! New in v3.0.0
An alternate method of getting a subgraph of e.g., the left hemisphere only, is to use the subnet
argument:
There are a number of graph measures that may be of interest to you, so there are a couple of helper
functions to make plotting and exploring easier. graph attr dt will get graph-level (global) attributes into a
data.table, ordered by graph density. Similarly, vertex attr dt will get vertex-level attributes; for multiple
densities, they are combined (by row) into a single data.table.
# List the regions with the highest participation coefficient at one density
dt.V[abs(density - densities[N]) < .001,
.SD[order(-PC, -degree)[1:5],.(density, region, lobe, hemi, degree, PC)],
by=Group]
## Group N
## 1: Control 34
## 2: Patient 34
To make some plotting functions and data exploration easier, it’s important to “melt” the data into “long”
format (see Wickham (127)). The “melt” operation is an example of data reshaping. This step is usually
optional, but can make data exploration simpler.
7.1: Setting up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
7.2: Import, normalize, and filter matrices for all subjects . . . . . . . . . . . . . . . . . . . . . 42
7.3: Graph creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
7.4: Graph- and vertex-level measures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
7.5: Example commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
This section will list the code needed to get fdt network matrix and waytotal into R so you can create and work
with graphs. This example code uses the dkt.scgm atlas and 2 subject groups. I used FSL for DTI-related
processing; see relevant references (8, 9, 60, 61).
Note
The information in this chapter is not specific to FSL, nor to DTI tractography. The code is applicable
to any set of single-subject graphs. If you use different software with different outputs, just adjust the
code (e.g., filenames) accordingly. I call the covariates object covars.dti simply because I don’t want
it to be over-written if I am loading data from multiple modalities concurrently and the covariates set
is different for each. In my fMRI scripts, I call it covars.fmri.
7.1 Setting up
First, as mentioned in Setting up files for your project, you will need to load the required packages. Then,
you set some initial variables that will depend on your project, data, directory structure, etc.
7.1.1 Tractography
The files containing connectivity matrices must contain the Study.ID’s for your study in the file names. For
example, the directory structure might look like:
sub001-fdt_network_matrix
sub001-sizes.txt
sub001-waytotal
sub002-fdt_network_matrix
sub002-sizes.txt
sub002-waytotal
etc.
41
42 Chapter 7: Tractography and fMRI
The *-sizes.txt files contain the ROI volume (in # of voxels) for each of the 76 ROI’s (i.e., it contains a
single column vector with 76 elements). The waytotal files have the same format. The fdt network matrix
files are output by probtrackx2 and are 76 × 76 matrices (in this example).
You can place the following code in a script, e.g., 01_load_DTI.R. Note again that these files are not required;
if you use a different software for tractography (or for fMRI), just change the relevant lines in the following
code block.
#===============================================================================
# These variables need to be set correctly before any data analysis is done
#===============================================================================
grps <- c('Control', 'Patient')
matfiles <-
list(A=list.files(datadir, pattern='fdt_network_matrix', full.names=T),
way=list.files(datadir, pattern='waytotal', full.names=T),
size=list.files(datadir, pattern='sizes.txt', full.names=T))
inds <- lapply(grps, function(x) covars.dti[Group == x, which=TRUE])
7.1.2 fMRI
The code for resting-state fMRI is almost exactly the same, except the matrix files are different. The following
code example is using the outputs of DPABI:
Now we will load all the relevant data from the files provided, and normalize the connection matrices based
on what you want (e.g., divide every entry by the corresponding waytotal ). For resting-state fMRI, the
thresholds will likely be different (e.g., correlation coefficients), or you may choose to threshold in such a way
that the graphs have a specific density (but see (116)). Either way, the same function is used. In this section,
I describe the inputs and outputs of create mats.
7.2 Import, normalize, and filter matrices for all subjects 43
! New in v3.0.0
You can also specify directories and/or patterns for the A.files and div.files arguments. In
addition to supplying a character vector of filenames, you can:
• Specify a single character string naming the directory in which the files exist. This will load all
files in the directory.
• Specify a named list in which the names match arguments to list.files. For example,
this may be list(path=’/data/probtrack results’, pattern=’.*fdt network matrix’)
. You may also specify recursive=TRUE to search all child directories.
A.files A character vector of the filenames containing the connectivity matrices (and see above).
modality A character string; either dti (default) or fmri.
divisor A character string specifying how to normalize the matrices. Either none (default), waytotal,
size (normalize by average size of ROI pairs), or rowSums (normalize by the row sums of the connection
matrix). Ignored if modality=’fmri’ .
div.files Character vector of the filenames of the files containing the normalization factor (e.g., the waytotal
files from FSL’s probtrackX2). Ignored if divisor=’none’ .
threshold.by Character string with 5 possible options. The 3rd and 4th options will enforce the same
connections across all study subjects.
consensus Perform “consensus-based” thresholding; i.e., keep connections that are above a given
threshold for a certain percentage of subjects in each group. The default value for
sub.thresh of 0.5 means it will keep connections if they are present in at least 50% of
subjects. See de Reus and van den Heuvel (24).
density Threshold the matrices such that they result in a specific graph density. The values given
to mat.thresh must be between 0 and 1. See van den Heuvel et al. (116).
mean You may choose to specify a set of thresholds τ (which you would supply to mat.thresh)
and keep connections only if
where Aijk is a connectivity matrix, and k indexes Subject. See for example (14, 43).
consistency Perform “consistency-based” thresholding (94). Similar to specifying density, you supply
the desired graph densities to mat.thresh, and the matrices are thresholded to keep the
most consistent connections across all study subjects (as determined by the coefficient of
variation).
raw Threshold each subject individually, irrespective of group membership. Ignores the
sub.thresh argument.
mat.thresh Numeric vector of the thresholds to apply. See the description for threshold.by for how this
is applied. Default: 0 . These values may end up being arbitrary, but with deterministic tractography
you may choose streamline counts; for probabilistic tractography, this may be some measure of streamline
density or connectivity probability; and with resting-state fMRI you may choose to threshold based on
correlation coefficients.
sub.thresh Numeric (between 0 and 1); only valid if threshold.by=’consensus’ . Default: 0.5
44 Chapter 7: Tractography and fMRI
inds List (number of elements equal to the number of groups) containing integer vectors; the integers
should represent the indexes for each group, and the length of each individual vector should equal the
number of subjects per group. For example, if you have 3 groups of 12 subjects each, this would be:
inds=list(1:12, 13:24, 25:36) .
algo Character string specifying the tractography algorithm used; either probabilistic (the default) or
deterministic. Ignored if modality=’fmri’ .
P Integer; the number of samples per voxel for probabilistic tractography (default: 5000 ). Only valid if
algo=’probabilistic’ .
... Other arguments passed to symmetrize. Here you can pass the argument symm.by which tells the
function how to symmetrize the matrices. The default in igraph is to take the maximum of {Aij , Aji }, so
the default option is symm.by=’max’ . You may also specify min or avg .
First, I set the subject threshold to 0.5, meaning I will only accept connections which are present in at least
50% of the subjects of a given group. If you do not want to impose any subject constraint, set equal to 0.
The matrix threshold is determined by the variable thresholds, which may end up being arbitrary (i.e., it
will depend on the tractography algorithm and the actual values of the matrices, and would be different if you
used correlations for fMRI). For deterministic tractography, this could be equal to the number of streamlines
connecting two ROI’s (e.g., an integer between 1 and 10, or higher).
In the case where you have connectivity matrices in which the entries are from the same subjects but are
a different metric (e.g., in DTI tractography streamline count and mean FA), you can use the function
apply thresholds to threshold the second set by the first. See the following code block and Ref. (69).
We now create graphs from the matrices from the previous section, and calculate the relevant attributes for
these graphs.
In this case, I will use the list of arrays stored in A.norm.sub (which contains the arrays thresholded by
both the % of subjects with a connection, and by a series of thresholds). The list g will have multiple
brainGraphList objects (1 for each threshold). You may want to place the following code in its own script,
e.g., 02_create_graphs_DTI.R.
46 Chapter 7: Tractography and fMRI
Note
Compare the old code in this box to the new code in the block that follows. This is meant to highlight
the improvements in v3.0.0.
for (i in seq_along(grps)) {
for (j in seq_along(thresholds)) {
foreach (k=seq_along(inds[[j]])) %dopar% {
g.tmp <- graph_from_adjacency_matrix(A.norm.sub[[j]][, , inds[[i]][k]],
mode='undirected', diag=F, weighted=T)
g.tmp <- set_brainGraph_attr(g.tmp, atlas, modality='dti',
weighting='sld', threshold=thresholds[j],
subject=covars.dti[groups[i], Study.ID[k]], group=grps[i],
use.parallel=FALSE, A=A.norm.sub[[j]][, , inds[[i]][k]])
saveRDS(g.tmp, file=paste0(savedir,
sprintf('g%i_thr%02i_subj%03is', i, j, k, '.rds')))
}
}
Just as we did in Getting measures of interest, we will create data.table’s of graph- and vertex-level measures
for further analysis. (This is also much more compact in the latest version.)
Similar to Getting measures of interest, here are some example commands for looking at your data.
## threshold p
## 1: 0.005 2.482e-01
## 2: 0.015 2.373e-01
## 3: 0.025 1.735e-01
## 4: 0.035 9.670e-02
## 5: 0.045 1.577e-01
## 6: 0.055 3.196e-02
48 Chapter 7: Tractography and fMRI
## 7: 0.065 1.824e-05
## 8: 0.075 8.523e-03
## 9: 0.085 5.396e-02
## 10: 0.095 2.816e-03
## 11: 0.105 2.775e-01
## 12: 0.001 3.575e-01
## 13: 0.002 2.985e-01
## 14: 0.003 3.049e-01
## 15: 0.004 4.160e-01
We can also create a plot of the global graph measures across the thresholds we applied, shown in Figure 7.1.
Here I use my function plot global, specifying that I want to plot across threshold instead of density.
This uses the stat smooth function, which creates a line plot along with a smoother.
0. 0
0. 5
0. 0
0. 5
0
0. 0
0. 5
0. 0
0. 5
0
10
07
05
02
00
10
07
05
02
00
0.
0.
0.
45
0.9
40 0.8
35 0.7
30 0.6
25 0.5
0. 0
0. 5
0. 0
0. 5
0
0. 0
0. 5
0. 0
0. 5
0
10
07
05
02
00
10
07
05
02
00
0.
0.
threshold
49
8
Vertex-wise group analysis (GLM)
Analysis of between-group differences in a given vertex measure (e.g., degree, betweenness centrality, etc.) is
described in this chapter (equivalent to a voxel-wise analysis common in fMRI, DTI, VBM, etc. analyses).
This is only possible if you have a graph for each subject (at a given density/threshold). In this chapter, I
describe the inputs and outputs of the function brainGraph GLM. Next, I provide a “mini-tutorial” on design
matrix coding and provide several examples of common experimental designs. Finally, I show an example
using permutations (as in FSL’s randomise).(40, 80, 129)
args(brainGraph_GLM)
50
8.1 Function arguments 51
! New in v3.0.0
There are a few new arguments in v3.0.0. These are described in more detail below:
Furthermore, con.mat has been renamed to contrasts because lists of matrices (for multiple F-
contrasts) are allowed in addition to single matrices.
8.1.1 Mandatory
The following list details the mandatory function arguments:
g.list A brainGraphList object. If your study has multiple groups, this object should contain
graphs for all subjects.
covars A data.table of covariates which will be used to create the design matrix. It should have
as its first column Study.ID (or whatever the value of getOption(’bg.subject id’)
is); the data in this column must match the name graph-level attribute of the graphs in
g.list (or at least a subset of them). You may include any additional columns of your
choosing (e.g., age, sex, etc.).
contrasts A list or numeric matrix specifying the contrast(s) of interest. The contrasts can have
multiple rows, and you can specify row names. If you provide a list of matrices, then the
list element names will be used.
8.1.2 Optional
The following are optional function arguments:
outcome If you would like the outcome (dependent variable) to be something other than a graph
metric, you can specify it here. In this case, the graph metric specified by measure will be
included in the design matrix as a covariate. At the vertex-level, there will be one design
matrix per region (since the graph metric differs for each vertex).
X If you wish to provide your own design matrix, you can specify it with this argument.
Note that, if you do this, you still need to provide the covars data table; this is used for
making sure the covariates and the graph metrics are in the same order, and to remove
the appropriate data if some are missing for certain subjects. However, the function
will assume that you have correctly created your own design matrix, and doesn’t do any
checking.
52 Chapter 8: Vertex-wise group analysis (GLM)
Note
If you specify a variable for outcome, then passing in a design matrix is ignored.
This argument will be deprecated in a future version.
con.name A character vector of the name(s) of the contrast(s); e.g., ’Control > Patient’ . If
this argument is not provided, the function first checks if contrasts has row names (if
it is a matrix) or list names otherwise. You can create these yourself. If names are not
supplied, they will be generic; e.g., ’Contrast 1’
HA : γ̂ 6= 0
HA : γ̂ ≤ 0
HA : γ̂ ≥ 0
level Either vertex or graph, depending on if the measure of interest is vertex- or graph-level.
Permutation-related arguments
The following optional arguments pertain to permutation/randomization tests (see Permutation testing):
perm.method The permutation method to use. The default is to use the freedmanLane method (40).
You may also choose terBraak (2), smith (108), draperStoneman (31), manly (77), or
stillWhite (109).
part.method The method used to partition the design matrix. The default is the beckmann method (7).
You may also choose guttman (46) or ridgway (93).
perms A numeric matrix of the permutation order, if you would like to provide your own.
long A logical specifying whether or not to return the null distribution of the maximum statistics
across permutations. Default: FALSE
coding A character string, either dummy (default), effects, or cell.means. This determines how
your factor variables will be coded in the design matrix. See Tutorial: design matrix coding
for more.
factorize A logical specifying whether or not to convert character columns to factor. Default: TRUE
binarize A character vector of the column name(s) of covars to convert from factor to numeric
(binary) vector. If the factor has k > 2 levels, it will not be binarized but instead changed
to 0, 1, . . . , k − 1.
8.2 Return object 53
int A character vector of the column names of covars to test for an interaction. The resulting
columns will be appended to the end of the design matrix. If you provide only one column,
nothing will happen. If you provide 3, then the 3-way and all 2-way interactions will be
added to the design.
mean.center A logical specifying whether or not to mean-center numeric variables. Default: FALSE .
Mean-centering will be done for all subjects, by default, but see the next bullet point. Note
that any factor variables that were binarized will also be mean-centered.
center.how A character string specifying whether variables should be centered based on all subjects
(the default), or within-groups. The groups are specified by the center.by argument (see
next bullet point). Although this may not be the most common choice in neuroimaging, see
this article on the AFNI site for an excellent discussion.
center.by A character string specifying which variable is the grouping variable (only valid if
center.how=’within-groups’ ). By default, it will center according to the Group variable,
if present. If your design has factor interactions (e.g., Group X Sex ), then you may want to
specify both variables here; i.e., center.by=c(’Group’, ’Sex’) .
Note
It is recommended that, if you include interaction terms, you should also mean-center the other
variables to partially reduce multicollinearity (e.g., see Chapter 8.2 of Kutner et al. (70)).
To summarize, columns in the design matrix X will be in a different order than the input covars. The
first column will be the Intercept (a column of all 1’s), if coding is not set to cell.means. The next
column(s) will by any numeric variables, followed by factor column(s), and finally interaction columns (if
applicable). You may wish to inspect the design matrix before specifying your contrast matrix by typing,
e.g., head(brainGraph GLM design(covars, ...)) .
This function returns an object of class bg_GLM with several of the input arguments in addition to a data.table
of the statistics of interest. For details on the statistics calculated, see GLM Statistics.
54 Chapter 8: Vertex-wise group analysis (GLM)
! New in v3.0.0
There are several new elements of the return object in v3.0.0.
outcome Can now be different from (or the same as) measure
measure Formerly called outcome
DT.Xy A data.table with all design matrix and outcome variable data
contrasts Renamed from con.mat
part.method
perm The element null.dist is now a 3-D array, and null.max is a column matrix with the
maximum statistic for each permutation
outcome The name of the outcome variable; this will either be the graph metric chosen by the measure
function argument or the variable specified by the outcome argument.
covars The data table used to create the design matrix. If any subjects have incomplete data, they
will not be included in the table.
DT A data.table containing statistics of interest; see the next section for details.
8.2 Return object 55
removed.subs A character vector of the subjects removed from the analyses (due to incomplete data). If
none were removed, this will be NULL .
β̂0 = µ1
β̂1 = µ2 − µ1
..
.
β̂k−1 = µk − µ1
To compare group means, assume there are k = 3 factor levels. Group 1 (the reference group) is coded +1 for
the intercept and 0 for the other parameters; group 2 is coded +1 for the intercept and second parameter,
and 0 for the third:
HA : µ1 − µ2 > 0
⇒ (β̂0 ) − (β̂0 + β̂1 ) > 0
⇒ − β̂1 > 0
⇒ C = (0, −1, 0)
HA : µ1 − µ3 > 0
⇒ (β̂0 ) − (β̂0 + β̂2 ) > 0
⇒ −β̂2 > 0
⇒ C = (0, 0, −1)
For a general between-group comparison (that does not involve the reference group), the contrast has a +1 in
the ith entry and a -1 in the j th entry:
HA : µi − µj > 0
⇒ (β̂i−1 + β̂0 ) − (β̂j−1 + β̂0 ) > 0
⇒ β̂i−1 − β̂j−1 > 0
⇒ C = (0, 0, · · · , 1, 0, · · · , −1, 0, 0, · · · , 0)
8.3 Tutorial: design matrix coding 57
## Study.ID Group
## 1: 02-115-0 Control
## 2: 02-126-1 Control
## 3: 02-127-2 Control
## 4: 02-128-9 Control
## ---
## 153: 02-629-8 Patient
## 154: 02-630-6 Patient
## 155: 02-631-5 Patient
## 156: 02-632-2 Patient
# There are only 2 columns, with the second indicating membership in Group 2
model.matrix(~ Group, data=X)[c(1:4, 153:156), ]
## (Intercept) GroupPatient
## 1 1 0
## 2 1 0
## 3 1 0
## 4 1 0
## 153 1 1
## 154 1 1
## 155 1 1
## 156 1 1
β̂1 = µ1
β̂2 = µ2
..
.
β̂k = µk
If you prefer this kind of parameterization, you can exclude the intercept with the following code. This is the
same matrix that results from setting coding=’cell.means’ in a call to brainGraph GLM.
## GroupControl GroupPatient
## 1 1 0
## 2 1 0
## 3 1 0
## 4 1 0
## 153 0 1
## 154 0 1
## 155 0 1
## 156 0 1
Note
This value will not equal the mean of all observations if there are an unequal number of observations
in each level.
8.3 Tutorial: design matrix coding 59
β̂0 = µ.
β̂1 = µ2 − µ.
..
.
β̂k−1 = µk − µ.
If you are interested in comparing group means under this coding scheme, first assume that there are k = 3
factor levels. Then, since group 1 (the reference group) is coded +1 for the intercept and -1 for the other
parameters, and group 2 is coded +1 for the intercept and the second parameter, and 0 for the third:
HA : µ1 − µ2 > 0
⇒(β̂0 − β̂1 − β̂2 ) − (β̂0 + β̂1 ) > 0
⇒ − 2β̂1 − β̂2 > 0
⇒C = (0, −2, −1)
6 j=
The contrast for a difference in groups i and j (where i = 6 1), i.e., H0 : µi − µj 6= 0, is the same as in the
dummy coding example.
## Intercept GroupPatient
## 02-115-0 1 -1
## 02-126-1 1 -1
## 02-127-2 1 -1
## 02-294-3 1 1
## 02-295-3 1 1
## 02-311-4 1 1
## 02-312-4 1 1
# Contrasts
Cmat <- matrix(c(1, -1, 1, 1, 0, -2, 0, 2), nrow=4, ncol=2, byrow=TRUE)
rownames(Cmat) <- c(paste('Mean', grps),
'Control > Patient', 'Patient > Control')
Cmat
## [,1] [,2]
## Mean Control 1 -1
## Mean Patient 1 1
## Control > Patient 0 -2
## Patient > Control 0 2
8.4 Examples
This section contains examples of common analysis scenarios. This is the first demonstration of the summary
method for brainGraph GLM results. See Box 8.1.
In all examples, the brainGraphList object g.glm contains all the graphs for both groups at a single
threshold. The covariates table used in each example (varying the inclusion of certain columns) is:
env.glm$covars.dti
##
## =====================================
## brainGraph GLM results (vertex-level)
## =====================================
## GLM formula:
## E.nodal.wt ~ Group * Sex
## based on 156 observations, with 152 degrees of freedom.
##
## Contrast type: T contrast
## Alternative hypothesis: C > 0
## Contrasts:
## Intercept GroupPatient SexM GroupPatient:SexM
## Group x Sex interaction . . . 1
##
## Statistics
## ------------------
## Group x Sex interaction:
## Region Estimate 95% CI low 95% CI high Std. error t value Pr(>|t|)
## 1: lENT 0.001186 1.12e-04 0.00226 0.000543 2.18 0.01533
## 2: lFUS 0.000767 -9.32e-05 0.00163 0.000435 1.76 0.04007
## 3: lpORB 0.000865 -8.88e-05 0.00182 0.000483 1.79 0.03758
## 4: lTT 0.000963 2.67e-04 0.00166 0.000353 2.73 0.00351
## 5: lTHAL 0.001186 1.85e-04 0.00219 0.000506 2.34 0.01024
## ---
## 9: rENT 0.000962 -6.32e-05 0.00199 0.000519 1.85 0.03284
1 The t-statistics and p-values would be unchanged if you did not divide by 4.
8.4 Examples 63
For cell-means coding, I show part of the design matrix, but omit the summary , as it is identical to that
for effects coding. Note that the contrast matrix is divided by 4 to give equivalent results.
# A few rows of the design matrix; get rid of 'NA' values first
incomp <- covars2x3[!complete.cases(covars2x3), Study.ID]
X <- brainGraph_GLM_design(covars2x3[!Study.ID %in% incomp],
coding='effects', int=c('A', 'B'))
head(X)
## 02-014-6 1 1 0 1 0 1
## 02-016-1 1 -1 -1 -1 1 1
##
## =====================================
## brainGraph GLM results (vertex-level)
## =====================================
## GLM formula:
## E.nodal.wt ~ A * B
## based on 105 observations, with 99 degrees of freedom.
##
## Contrast type: T contrast
## Alternative hypothesis: C > 0
## Contrasts:
## Intercept A2 B2 B3 A2:B2 A2:B3
## Main A . 1 . . . .
## Main B (1st) . . 1 . . .
## Main B (2nd) . . . 1 . .
## A X B (1st) . . . . 1 .
## A X B (2nd) . . . . . 1
## 7 subjects removed due to incomplete data:
## 02-006-8, 02-123-7, 02-161-8, 02-170-3, 02-203-8, 02-287-7, 02-521-5
##
## Statistics
## ------------------
## Main A:
## No signficant results!
## Main B (1st):
## No signficant results!
## Main B (2nd):
## Region Estimate 95% CI low 95% CI high Std. error t value Pr(>|t|)
## 1: lFUS 0.00123 -1.70e-04 0.00262 0.000703 1.74 0.0423
## 2: lPARH 0.00173 -3.60e-05 0.00350 0.000892 1.94 0.0274
## 3: lpORB 0.00139 -1.62e-04 0.00294 0.000781 1.78 0.0394
## 4: lrMFG 0.00140 -1.80e-04 0.00297 0.000794 1.76 0.0410
## 5: lPUT 0.00216 2.06e-05 0.00430 0.001079 2.00 0.0239
## 6: lPALL 0.00181 -5.69e-05 0.00367 0.000940 1.92 0.0286
## 7: lHIPP 0.00193 -1.34e-04 0.00399 0.001040 1.86 0.0332
## 8: rparaC 0.00178 8.46e-05 0.00347 0.000854 2.08 0.0199
## 9: rPALL 0.00171 -1.97e-04 0.00362 0.000963 1.78 0.0391
## Pr(>|t|) (FDR)
## 1: 0.357
## 2: 0.357
## 3: 0.357
8.4 Examples 65
## 4: 0.357
## 5: 0.357
## 6: 0.357
## 7: 0.357
## 8: 0.357
## 9: 0.357
## A X B (1st):
## No signficant results!
## A X B (2nd):
## Region Estimate 95% CI low 95% CI high Std. error t value Pr(>|t|)
## 1: lcMFG 0.00167 2.92e-04 0.00306 0.000697 2.40 0.00907
## 2: lCUN 0.00211 4.48e-04 0.00377 0.000837 2.52 0.00667
## 3: lENT 0.00188 8.90e-06 0.00376 0.000945 1.99 0.02447
## 4: liCC 0.00228 3.82e-04 0.00419 0.000959 2.38 0.00956
## 5: lLOF 0.00263 5.09e-04 0.00475 0.001068 2.46 0.00780
## ---
## 22: rpORB 0.00111 -1.84e-04 0.00240 0.000650 1.70 0.04601
## 23: rpTRI 0.00151 1.37e-04 0.00289 0.000695 2.18 0.01578
## 24: rPCC 0.00156 -1.24e-04 0.00324 0.000847 1.84 0.03456
## 25: rrACC 0.00165 -9.17e-05 0.00339 0.000878 1.88 0.03154
## 26: rSFG 0.00131 -1.53e-04 0.00278 0.000739 1.78 0.03930
## Pr(>|t|) (FDR)
## 1: 0.0733
## 2: 0.0733
## 3: 0.1123
## 4: 0.0733
## 5: 0.0733
## ---
## 22: 0.1399
## 23: 0.0857
## 24: 0.1194
## 25: 0.1194
## 26: 0.1245
For cell-means coding, I only show part of the design matrix. Note the order of the columns: all of the A1
factors come first, and then the A2’s. I also show how to construct the contrast matrix. Notice that I divide
the matrix by 6; this will give equivalent results to the effects coding run.
1, 0, -1, -1, 0, 1,
0, 1, -1, 0, -1, 1), nrow=5, byrow=TRUE)
con.mat <- con.mat / 6
rownames(con.mat) <- c('Main A', 'B2-B1', 'B3-B1',
'A1B1 - A2B1 - A1B3 + A2B3', 'A1B2 - A2B2 - A1B3 + A2B3')
• Sex (M and F )
If you also would like to get permutation-based p-values, then you can specify permute=TRUE to perform the
permutations, calculate the maximum test statistic across vertices (or a single statistic if level=’graph’
), and compare this null distribution of maximum statistics to the observed statistics. This is essentially
the same as the procedure from FSL’s randomise and the PALM utility (albeit without as much of the
functionality).(40, 80, 129) The default matrix partitioning scheme is (like that of PALM) called ’beckmann’
.(108)
8.6 Plotting LM diagnostics 67
! New in v3.0.0
You can choose from 3 permutation methods: Freedman-Lane (the default), Smith, and Ter Braak.
See Winkler et al. (129) for details/discussion of these methods. You may also now explicitly choose
the matrix partitioning scheme; either Beckmann (the default), Guttman, or Ridgway.
When long=TRUE , an additional element called perm is returned in the bg GLM object. See the section
Return object for details.
8.5.1 Example
str(diffs.perm$perm)
## List of 3
## $ thresh : Named num 3.01
## ..- attr(*, "names")= chr "Control > Patient"
## $ null.dist: num [1:76, 1:5000, 1] -0.341 -0.67 -1.23 -2.408 -2.142 ...
## $ null.max : num [1:5000, 1] 0.416 1.233 0.715 1.986 1.253 ...
The plot method for bg GLM objects has the same functionality as plot.lm in base R: it shows linear
model “diagnostics”. There are 6 possible plots (for a given region), chosen by the argument which :
2. QQ plot
4. Cook’s distance
The plots shown in Figure 8.1 were generated by the function call in the following code block. The plot title
lists the outcome variable (the graph metric of interest) and the region; there is a plot sub-title (at bottom)
which shows the linear model formula used in R (in what is sometimes called “Wilkinson notation”).
68 Chapter 8: Vertex-wise group analysis (GLM)
3
02−591−3
02−236−1 02−236−1 02−236−1
1.5
Standardized residuals
02−025−6 ●●●● 02−025−6 ● 02−142−4
2
02−025−6 ● ● ●●
0.01
● ● ● ● ● ● ●●
● ●
Sample Quantiles
● ● ● ● ●
●
● ● ●
● ● ●
● ●
● ● ●● ●
●● ● ● ● ● ●
● ● ●●
●
●● ●● ● ●
● ● ●
● ● ● ●
● ● ● ● ● ●
1
● ●
●
●● ● ●
● ● ● ● ●
●
● ●
● ● ● ● ● ● ●● ● ● ●
● ●
● ● ●●
1.0
● ● ● ●● ●
●
● ● ● ● ●● ● ●
resid
●●
●● ● ●● ● ● ●●
● ●●
● ● ● ● ● ● ● ●
●
●
●
●
● ● ● ● ● ●
● ● ● ● ● ●
● ● ●
●● ●
●
● ● ● ●
● ●● ●●
0.00
● ● ●●
●
● ● ● ● ●
0
●●● ●● ●●●●
●
●●
●●●● ●●
● ●●
● ●●
●
●
●
●
●
●●
● ●
●●●● ● ● ● ● ●
●
●●
●
●●
●
● ● ● ●
●●
●
● ● ● ● ● ●
● ● ● ● ● ●● ●
●
●
● ● ● ●● ● ●● ● ●
● ● ● ● ● ● ●
●● ●
● ● ●● ● ●
● ● ● ● ● ● ●● ● ●●
−1
● ●●
●
0.5
● ● ●
●●
● ●● ●
●●●● ●● ● ●● ● ● ● ● ● ●●
●● ● ●
●
● ● ●
●
●● ● ●
● ● ● ● ●
●●
● ●
● ● ● ● ●
−0.01
● ● ● ●● ● ●
● ●● 02−142−4
●● ●● ● ● ●●● ●● ● ● ●
●
−2
● ● ●● ●
● ● ● ● ●
● ● ●
02−142−4 02−591−3 ●
●
●
0.0
● ●
02−447−7 02−591−3 02−447−7
−3
02−447−7
02−262−8 02−447−7
02−591−3
02−236−1
Standardized residuals
02−591−3
0.04
0.04 ●
2
02−262−8 ● 02−262−8
Cook's distance
02−025−6 ● ●● ●
Cook's distance
● ●
● ●
●● ● ● ●
● ● ● ●● ● ●
● ● ●●
● ●
● ● ● ●
02−142−4 ● ●● ●●●● ● 02−142−4 ●
●
●●● ●● ●● ●● ● ● ● ● ●
●● ● ●●● ●● ● ●
02−236−1 ●
●● ●●● ●
● ●● ● ● ●●
0
●
●
●●●●● ●
●●●●● ●● ● ● 02−236−1
●
0.02
0.02
● ● ● ●● ● ●●
●●●● ●● 02−025−6 ●● ●
● ●
● ●● ●
● ● ●
02−025−6 ● ●● ● ● ● ●●
●
●● ● ●
● ● ●● ● ● ● ●
● ● ● ●●●
● ● ● ●
● ● ●● ●
● ● ●● ●● ●●
−2
02−142−4 ● ●●
●● ● ●●●● ● ●
02−591−3 ●● ●
● ●●● ●● ● ● ●
●●●● ●●● ●● ● ● ●
● ●● ●● ●● ● ● ●
0.00
02−447−7 ●
0.00
● ●
●●
●●
●● ●
●●● ●●●●
●●●●●● ●●
●●●
● ●●
● ●
●●
●●●●●●●●
●
●●●●● ● ● ●
0 50 100 150 0.00 0.02 0.04 0.06 0.00 0.02 0.04 0.06
Obs. number Leverage Leverage hii
If you would like plots for multiple regions, you can supply a character vector, or leave the default (
region=NULL ). The following code block shows how to get the plots for all regions and save each to a page
in a PDF. On my system, with 76 regions, it takes 44 seconds for the function call itself, and 38 seconds to
save the file to disk. The glmPlots object is 60 MB (in memory), and the PDF is 1.1 MB.
Table 8.1: GLM graph attributes. The graph- and vertex-level attributes that are added after calling
make brainGraphList.
To create a graph with attributes specific to GLM, use make brainGraphList. The number of graphs equals
the number of contrasts, and they will have several additional attributes; see Table 8.1.
##
## ======================================================================
## A "brainGraphList" object of *observed* graphs containing 5 contrasts.
## ======================================================================
##
## Software versions
## R release: R version 3.6.0 (2019-04-26)
## brainGraph: 3.0.0
## igraph: 1.2.4.1
## Date created: 2020-12-31 06:49:39
## Brain atlas used: Desikan-Killiany-Tourville + SCGM
## Imaging modality: N/A
## Edge weighting: Unweighted
## Threshold: N/A
## Contrast names:
If you would like to plot only significant regions, you can simply call the plot method on the graph. The
p.sig function argument lets you choose which P-value determines significance (the standard P-value,
FDR-adjusted, or permutation-based). Below I use the standard P-value, which is the default behavior.
70 Chapter 8: Vertex-wise group analysis (GLM)
9.1: Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.2: Function arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
9.3: Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
9.4: Code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
9.5: Plotting the statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
9.6: Create a graph of the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
9.7: Plotting a graph of the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
The multi-threshold permutation correction (MTPC) method for statistical inference was introduced by
Drakesmith et al.(30) Its goal is to reduce the effects of false positives and the use of multiple thresholds in
network analyses. This is because network metrics are not stable across thresholds (sometimes even adjacent
thresholds), and there is no real standard for choosing a threshold to examine a priori. The brainGraph
function for performing MTPC is mtpc.
9.1 Background
As I have described in previous chapters, it is common to generate sets of thresholded networks for a given
subject or group; this is necessary because most “raw” brain networks have an unrealistically-high density (i.e.,
the proportion of present to possible connections). In structural covariance and resting-state fMRI networks,
it is common to threshold the covariance matrix with a range of correlation values; in DTI tractography, the
threshold can be a range of streamline counts, connectivity probabilities, or average DTI metric for each tract
(e.g., FA). However, there is no principled way to choose the “correct” threshold to use for your final results.
71
72 Chapter 9: Multi-threshold permutation correction
5. Determine the critical value Scrit from the null distribution of maximum test statistics (by taking the
top αth percentile).
6. Identify cluster(s) where Sobs > Scrit and compute the area under the curve (AUC) for the cluster(s);
the AUC(s) are denoted AM T P C . Note that these clusters are across thresholds; in brainGraph, I
consider 3 consecutive significant test statistics as a cluster.
7. Compute a critical AUC Acrit from the mean of the supra-critical AUC’s for the permuted tests.
8. Reject the null hypothesis H0 if the AUC of the significant (observed) clusters is greater than the
critical AUC; i.e., if AM T P C > Acrit .
Note that the procedure is nearly identical for graph- and vertex-level metrics; with vertex-level metrics, step
4 (building the null distribution of maximum test statistics) is the only difference in that the maximum is
taken across thresholds and brain regions.
Many arguments are the same as those of brainGraph GLM; any listed below without accompanying information
are described in Vertex-wise group analysis (GLM).
args(mtpc)
9.2.1 Mandatory
g.list A list of brainGraphList objects.
thresholds A numeric vector of the thresholds that were used to create the networks. This can be either
the actual threshold values or just an integer vector from 1 to the number of thresholds.
covars
measure
contrasts
9.2.2 Optional
con.type
outcome
con.name
level
9.3 Return value 73
clust.size The “cluster size” (i.e., the number of consecutive thresholds for which the observed statistic
exceeds the null). Default: 3
perm.method
part.method
N Default: 500
perms
alpha
res.glm A list of bg GLM objects, as output by a previous run of mtpc. This is useful if you want
to assess differences when varying clust.size , as it will avoid calculating all of the null
statistics over again. Default: NULL
long
9.2.3 Unnamed
The unnamed arguments are the same as those in brainGraph GLM; please see the relevant section in
Vertex-wise group analysis (GLM) for information.
The function returns an object of class mtpc. Many of the returned elements are the same as those returned
by brainGraph GLM; if they have no accompanying information here, see Vertex-wise group analysis (GLM).
The elements are: (τ refers to thresholds, and Nτ is the number of thresholds)
level
outcome
measure
con.type
contrasts
con.name
alt
alpha
removed.subs
atlas
rank
df.residual
N
res.glm A list (with length equal to Nτ ) in which each element is the output from brainGraph GLM
for a single threshold.
clust.size
DT A data.table, which is combined, for all thresholds, from each run of brainGraph GLM.
stats A data.table with the statistics calculated by MTPC: τmtpc , Smtpc , Scrit , and Acrit .
null.dist A numeric array of the maximum statistic for each permutation and threshold. It will have
Nτ × Nrand × NC dimensions, where Nrand is the number of permutations and NC is the
number of contrasts.
perm.order
The following code blocks show how to run mtpc for a few different network measures, storing all results in a
single list. As with some other functions with long runtimes and/or high processing demands, it would be
quite a bit faster to run each individually from a fresh R session, but you can let this run without having
to repeatedly execute the code while only changing the measure argument. There are some benchmarks in
Benchmarks.
I have been storing all parameters in a single data.table, which makes it easier to loop through without
much effort. In the example below, I look at 4 network metrics: 2 graph-level and 2 vertex-level. I show how
to change the alternative hypothesis for given metrics. This approach is, of course, optional.
mtpcVars
# The 2nd-level is for each network metric (for the given level 'x')
mtpc.diffs.list[[x]] <- sapply(mtpcVars[x, unique(outcome)], function(x) NULL)
for (y in mtpcVars[x, outcome]) {
# Print some timing info in the terminal; optional
print(paste('Level:', x, '; Outcome:', y, ';', format(Sys.time(), '%H:%M:%S')))
mtpc.diffs.list[[x]][[y]] <-
mtpc(g, thresholds, covars=covars.dti, measure=y, contrasts=mtpcContrast,
con.type='t', level=x, N=mtpcVars[.(x, y), N], perms=mtpcPerms[[x]],
alt=mtpcVars[.(x, y), alt])
}
}
Here I show what the summary method produces. This analysis consisted of 3 groups and 3 t-contrasts.
You have the option to choose a single contrast (the default is to print results for all contrasts) and to
print longer summary tables (the default is to print only the first and last 5 rows).
summary(res.mtpc)
##
## =====================================
## MTPC results (vertex-level)
## =====================================
## GLM formula:
## E.nodal.wt ~
## based on 103 observations, with 97 degrees of freedom.
##
## Contrast type: T contrast
## Alternative hypothesis: C != 0
## Contrasts:
## Intercept age_mri_6w gender ScannerChange GroupPt1 GroupPt2
## Control > Pt1 . . . . -2 -1
## Control > Pt2 . . . . -1 -2
76 Chapter 9: Multi-threshold permutation correction
##
## Permutation analysis
## ------------------
##
## Statistics
## ------------------
## EI > TBI:
## Region tau.mtpc S.mtpc S.crit A.mtpc A.crit
## 1: lAMYG 5555 22.67 3.26 36411 13473
## 2: rBSTS 6190 20.34 3.26 35767 13473
## 3: lLOF 9365 16.81 3.26 27834 13473
## 4: lENT 1222 16.31 3.26 18254 13473
## 5: rFP 8730 13.24 3.26 20976 13473
## ---
## 12: lCUN 8095 8.54 3.26 15358 13473
## 13: rrACC 600 8.14 3.26 22893 13473
## 14: lcACC 8095 7.03 3.26 17747 13473
## 15: lrMFG 1533 6.63 3.26 14686 13473
## 16: rMTG 8730 -8.74 3.26 13481 13473
If you would like to see how the (t- or F-) statistic changes with the threshold, in addition to the critical null
statistic value, and the null distribution of maximum statistics, you can simply call the plot method for
your results. This figure is essentially the same as Figure 11 in Drakesmith et al. (30).
argsAnywhere(plot.mtpc)
In Figure 9.1 I show the statistics plots for 4 regions. I use the grid.arrange function (from the gridExtra
package) to plot all 4. As you can see, regions determined to be significant can have very different statistics
profiles, so you should always check these.
To save a plot for every region, use (a variant of) the following code. You can also save the PDF with multiple
plots per page by changing the nrow and ncol values.
78 Chapter 9: Multi-threshold permutation correction
8 20
T−statistic
T−statistic
●●
● ●
● ●
4 ●● ●
10
0
0
●
●●
10 8
T−statistic
T−statistic
● ●
●
5 ● ●
4 ● ● ●
0
0
−5
10000 7500 5000 2500 10000 7500 5000 2500
Threshold Threshold
Scrit = 3.255 ; Acrit = 13757 Scrit = 3.255 ; Acrit = 13757
(p < 0.05) (p < 0.05)
Smtpc = 15.44 ; Amtpc = 22914 Smtpc = 11.91 ; Amtpc = 21730
Figure 9.1: MTPC statistics. The red shaded areas are those that are above the critical null statistic
(dashed line) for at least 3 consecutive thresholds. The green points are the maximum null
statistics (per permutation).
To create a graph with attributes specific to MTPC, use make brainGraphList. This will return a list (with
length equal to the number of contrasts) of graphs with several additional attributes; see Table 9.1 for the
list and a brief description of them.
Table 9.1: MTPC graph attributes. The graph- and vertex-level attributes that are added after calling
make brainGraphList.
If you would like to plot only significant regions, you can simply call the plot method on the graph. Here I
plot the first contrast.
10.1: Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
10.2: Function arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
10.3: Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
10.4: Code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
10.5: Creating a graph of the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.6: Plotting the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
10.7: Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
The network-based statistic (NBS) was introduced by Zalesky et al. for performing FWE control of brain
network data in a way that is analogous to cluster-based thresholding in fMRI.(133) The brainGraph function
for performing NBS is NBS.
10.1 Background
Most brain networks are relatively large, in terms of the number of possible pairwise connections: even for a
brain atlas with 90 regions (the AAL atlas), there are 90 × (90 − 1)/2 = 4005 possible connections. This
is a multiple comparisons problem, but a Bonferroni correction is inappropriate because the data are not
independent; a FDR adjustment is a better alternative. However, this still treats each data point as isolated;
i.e., it does not consider the data as a network. The network-based statistic (NBS) was thus developed to
provide weak FWE control for “mass univariate” testing of all edges in a network.
This algorithm operates directly on the connectivity matrices. A GLM is specified at every matrix element;
the model can be as simple as a two-group difference, or as complex as a three-way ANOVA. All designs that
are allowed by brainGraph GLM will also work for this function (see Examples). An initial p-value threshold is
provided by the user, and the connected component size(s) of this graph is (are) calculated. The data are then
permuted, and for each permutation the largest connected component is recorded, creating a null distribution.
A p-value is assigned to the observed connected component size(s) based on the location relative to the null
distribution. As in brainGraph GLM, randomization is done through the Freedman-Lane procedure.(40)
As with mtpc, many of the arguments are the same as those in brainGraph GLM; see Vertex-wise group
analysis (GLM) for more information.
81
82 Chapter 10: Network-based statistic (NBS)
args(NBS)
covars
contrasts
con.type
con.name
p.init An initial p-value threshold for calculating the observed component sizes. Default: 0.001
perm.method
part.method
N Default: 1000
perms
symm.by Character string indicating how to symmetrize the matrices (see Import, normalize, and
filter matrices for all subjects). Default behavior is to use the maximum of the off-diagonal
elements.
alternative
long
... Arguments that are used for creating the design matrix; see Vertex-wise group analysis (GLM)
for more information
The function returns an object of class NBS . Any values not described here can be found in Vertex-wise
group analysis (GLM).
covars
con.type
contrasts
10.4 Code example 83
con.name
alt
p.init
removed.subs
T.mat A 3-D numeric array containing the t- or F-statistics. The extent of the array will equal the
number of contrasts.
p.mat A 3-D numeric array containing the p-values. The extent of the array will equal the number
of contrasts.
rank
df.residual
qr
cov.unscaled
perm.method
part.method
components A list with two elements: a data.table of the observed components and p-values, and a
Nrand × NC matrix of the null distributions of maximum component sizes.
Here is what the summary method for a NBS object returns. First are some details on user-specified
inputs. Then it prints a table of the significant components and their associated P-values.
summary(res.nbs)
##
## =====================================
## Network-based statistic results
## =====================================
## GLM formula:
## weight ~ Age.MRI + Sex + Scanner + Group
## based on 156 observations, with 151 degrees of freedom.
84 Chapter 10: Network-based statistic (NBS)
##
## Permutation analysis
## ------------------
## Permutation method: Freedman-Lane
## Partition method: Beckmann
## # of permutations: 1,000
## Initial p-value: 0.001
##
## Contrast type: T contrast
## Alternative hypothesis: C > 0
## Contrasts:
## Intercept Age.MRI Sex Scanner GroupPatient
## Control > Patient . . . . -2
## Patient > Control . . . . 2
##
## Statistics
## ------------------
## Control > Patient:
To create a graph with attributes specific to NBS, use make brainGraphList. This returns a list (length
equal to the number of contrasts) of graphs with several attributes (in addition to those created by
set brainGraph attr); see Table 10.1.
Table 10.1: NBS graph attributes. The graph- and vertex-level attributes that are added after calling
make brainGraphList.
The default behavior of the plotting method for NBS results will only show the component(s) with a
significant effect, given some value α. As you can see in Figure 10.1, it will also plot vertices and edges of
the same component with the same color and give the plot a title containing the contrast name (this can be
over-ridden by changing the main argument). You can adjust various other aspects of the plot, as with
any other graph; for example, you could change the edge width to scale with the statistic value (by typing
edge.width=’stat’ .
plot(g.nbs[1], alpha=0.05)
10.7 Testing
For some benchmarking info, see Benchmarks. I have done some testing of this function; the t-statistics
calculated in my function matched those of the Matlab toolbox NBS; the connected component sizes differed
by only 1, and I assume this is due to their toolbox thresholding by T-statistic, whereas I threshold by p-value.
I encourage you to do your own testing if you wish.
86 Chapter 10: Network-based statistic (NBS)
Figure 10.1: Significant connected components. Vertices of the same component are plotted in the same
color.
11
Graph- and vertex-level mediation analysis
11.1: Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
11.2: Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
11.3: Function arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
11.4: Return value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
11.5: Code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
11.6: Create a graph of the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
11.7: Plot a graph of the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
11.8: Benchmarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Performing mediation analysis in brainGraph follows the potential outcomes framework that is implemented
in the mediation package (113), as opposed to the more well-known “Baron & Kenny approach” (6). A few
advantages of the potential outcomes framework include:
• Allows for mediation-treatment interaction and nonlinearities
• Addresses confounds
• Allows for the decomposition of the total effect into direct and indirect effects
A full treatment of mediation is beyond the scope of this document, but I provide some background here as it
can be quite difficult to understand without prior exposure.
11.1 Background
As explained in Preacher (87), the potential outcomes framework for causal inference was re-introduced (or
popularized) by Donald Rubin in the 1970’s (97, 98).1 In fact, Holland (50) calls it the Rubin Causal Model.
To re-iterate, for binary treatment variable X, the effect of X on outcome Y for case/subject i can be defined
as the difference between two potential outcomes:
1. Yi (1) – the outcome that would be realized if Xi = 1
2. Yi (0) – the outcome that would be realized if Xi = 0
We can say that X causes Y if Yi (1) 6= Yi (0). However, we can never observe both Xi = 1 and Xi = 0;
Holland (50) calls this the fundamental problem of causal inference. Under random assignment, the expected
mean between-group difference is equal to the difference in group means; i.e.,
87
88 Chapter 11: Graph- and vertex-level mediation analysis
There are also potential outcomes for the mediator M , only one of which can be observed for a given unit i
(i.e., either Mi (1) or Mi (0)). The outcomes for unit i can then be defined using the notation Yi (Xi , Mi (Xi )),
and the indirect effect δ is defined as the “change that would occur in Y when moving from the value of M if
Xi = 0 to the value of M if Xi = 1” (Preacher 2015, p. 834). In equation form,
And under certain assumptions (see below), the average indirect effect δ̄(x) is simply the difference in expected
value: (also known as the average causal mediation effect (ACME))
The average direct effect (ADE) is he difference in potential outcomes between treatment groups:
And, under the potential outcomes framework, the total effect is the sum of the ACME and ADE:
11.2 Notation
As I mentioned, it is critical that you read Tingley et al. (113). For convenience, I will include some notation
here, including the variable names as seen in the summary method.2
??.acme The average causal mediation effect (see Equation 11.1). This is typically the effect
of interest in mediation analysis. Represented by the variables d0,d1
??.ade The average direct effect (see Equation 11.2). Represented by the variables z0,z1
?.tot The total effect (see Equation 11.3). Represented by the variable tau
??.prop The proportion mediated. This is the ACME divided by the total effect. Represented
by the variables n0,n1
There are a few arguments that are the same as in brainGraph GLM, so their descriptions are omitted here.
args(brainGraph_mediate)
11.3.1 Mandatory
g.list As with brainGraph GLM, a “flat” list of graph objects for ≥ 1 subject group at a single
threshold/density.
covars Must have columns ’Study.ID’ and several names you supply in the function call:
treat , outcome , covar.names
mediator The name of the mediator variable; this must be a valid graph- or vertex-level attribute
(e.g., ’E.global.wt’ , ’btwn.cent’ , etc.)
treat The name of the treatment variable. A common example would be ’Group’
outcome The name of the outcome variable. This is usually going to be a non-MRI variable you
measure in the subject; e.g., IQ some other neuropsychological test/questionnaire score
(e.g., WISC processing speed, CVLT immediate recall, etc.)
covar.names Character vector of the nuisance covariates you would like to include in your analyses (e.g.,
age, sex, etc.)
11.3.2 Optional
level
control.value The value of treat to be used as the control condition. If your treat variable is a
factor, then you may wish to use the first level. The default, 0 , essentially has this effect.
treat.value The value of treat to be used as the treatment condition. If your treat variable
is a factor, then you may wish to use the second (or a higher) level. The default, 1 ,
essentially has this effect.
int Logical indicating whether or not to include a mediator-treatment interaction term. Default:
FALSE
boot Logical indicating whether or not to do bootstrap resampling for estimating confidence
intervals (CI) and statistical significance. You should always do bootstrap resampling.
Default: TRUE
boot.ci.type Character string indicating the type of bootstrap confidence intervals. The default is
’perc’ (percentile bootstrap), but you may also choose ’bca’ (bias-corrected and
accelerated). However, see Biesanz et al. (11) and Falk and Biesanz (36) which find that
the BCa approach results in inflated Type I error while the percentile bootstrap performs
well.
long Logical indicating whether or not to also return the statistics for each bootstrap sample.
Default: FALSE
... Arguments that are used for creating the design matrix. See Vertex-wise group analysis
(GLM) for more information; you should not specify the coding argument, thus accepting
the default coding ’dummy’
The function returns an object of class bg mediate . You will usually not work with the specific elements
of this object yourself, but I list them for completeness. Any elements that are simply input arguments are
included without description. For more details, see the help file for the mediate function in the mediation
package.
level
removed.subs
X.m The design matrix of the model in which the mediator is the outcome variable
y.m A matrix of the mediator variable; the number of columns equals the number of brain
regions
X.y A named list (the names will be the vertex/region names) of the design matrices of the
models in which the mediator is another predictor variable
y.y A numeric vector; the outcome variable specified in the function call
res.obs A data.table of the observed statistics (point estimates)
res.ci A data.table of the confidence intervals
res.p A data.table of the (two-sided) P-values
boot
boot.ci.type
res.boot A data.table of the statistics from all bootstrap samples (if long=TRUE )
treat
mediator
outcome
covariates NULL
The following code blocks show how to run brainGraph mediate for a few different network measures. This
is basically the same approach I used in Multi-threshold permutation correction. First, I create a table with
some of the function argument values.
Then you can loop through these values to create a list (of lists) of bg mediate objects. I usually separate
graph- and vertex-level analyses into different objects.
Below is code to loop across all thresholds for the graph-level measures. Depending on the number of
thresholds, this can take a very long time. The list object med.list.g will have 3 “levels”:
Note that it is not recommended that you perform analyses for every outcome-mediator combination and
then choose to report only those with significant results.
##
## =====================================
## Vertex-level mediation results
## =====================================
## # of observations: 71
##
## Variables
## ------------------
##
## Mediator: E.nodal.wt
## Treatment: Group
## Control condition: Control
## Treatment condition: Patient
## Outcome: brief_gec_raw_6m
##
## Covariates: age
## gender
## scanner
##
## Treatment-mediator interaction? FALSE
##
## Bootstrapping
## ------------------
## Bootstrap CI type: Percentile bootstrap
## # of bootstrap replicates: 1,000
## Bootstrap CI level: [2.5% 97.5%]
## Mediation summary for: lHIPP
## ------------------
##
## Causal Mediation Analysis
##
## Nonparametric Bootstrap Confidence Intervals with the Percentile Method
##
## Estimate % CI Lower % CI Upper p-value
## ACME (control) 1.1049 -10.2795 11.74 0.780
## ACME (treated) 1.1049 -10.2795 11.74 0.780
## ADE (control) 17.4068 -0.5028 33.66 0.062 .
## ADE (treated) 17.4068 -0.5028 33.66 0.062 .
## Total Effect 18.5116 6.5066 29.60 0.006 **
## Prop. Mediated (control) 0.0597 -0.6195 1.03 0.786
## Prop. Mediated (treated) 0.0597 -0.6195 1.03 0.786
## ACME (average) 1.1049 -10.2795 11.74 0.780
11.5 Code example 93
The second option will print the entire statistics table (for all regions). Since everything above the “Boot-
strapping” section is the same, I only show the summary table.
summary(res.med)$DT[]
Table 11.1: Mediation graph attributes. The graph- and vertex-level attributes that are added after
calling make brainGraph.
## 3: 0.884
## 4: 0.784
## 5: 0.812
## ---
## 78: 0.834
## 79: 0.228
## 80: 0.312
## 81: 0.746
## 82: 0.970
To create a graph with attributes specific to mediation analysis, use make brainGraph. This will return a
graph with several additional attributes; see Table 11.1 for the list and a brief description of them.
If you would like to plot only significant regions, you can simply call the plot method on the graph. In this
example, however, there were no vertices for which PACM E < α, so I relax this for display purposes. Note
that I use the form p0.acme > X , as the P-values are actually subtracted from 1.3 I also use the default
main value for printing the plot title (which includes the names of the mediator, treatment, and outcome
variables).
11.8 Benchmarks
The mediate function in the mediation package is quite slow, but very feature-rich (i.e., there are many
different types of models you can use in your analyses such as generalized additive models). In brain
Graph mediate, only simple linear models are allowed. This is a sacrifice in features but comes with a high
speed advantage. Second, mediate works with model objects (e.g., R objects of type lm). These objects are
convenient for interactive data analysis, but overall slower to work with. Third, mediate does not have a
parallel or multi-core option, whereas I take advantage of the foreach package. For a multi-region analysis
in which the same model is used for every brain region (e.g., 82 regions in the dk.scgm atlas), and with 1,000
(or more) bootstrap samples calculated, the speed increase can be large (particularly with a higher number of
bootstrap samples). Finally, I use data.table for fast calculations.
I have seen speed increases of 10x–30x. You can see the actual numbers in Benchmarks.
Part V
Group Analyses: Other
96
12
Random graphs, small world, and rich-club
Random graph generation is a necessary step if you want to calculate a graph’s small-worldness.(55, 126)
However, generating an appropriate random graph is not trivial. This is particularly true when working with
data generated from correlations (e.g., structural covariance and resting-state fMRI networks), as graphs
generated from this kind of data will necessarily have a higher than expected level of clustering.(53, 134) It is
true for other data, as well, because random networks have low clustering in general. For more discussion,
see Chapter 12 of Newman (79), and also Telesford et al. (112).
1. Generate N random graphs for each group and density/threshold (and subject if you have subject-
specific graphs).
2. Write the random graphs to disk (in savedir ).
3. Read the random graphs back into R and combine into lists; there will be one list object per group and
density/threshold combination.
4. Write the combined list objects to disk (in a sub-directory named ALL ); you can delete the individual
.rds files afterwards (after ensuring that you have all the data).
5. Calculate small world parameters, along with a few global graph measures that may be of interest.
6. Calculate normalized rich-club coefficients and associated P-values.
The return object is a list, with three elements (each one is a data.table):
rich (normalized) rich-club coefficients and p-values
97
98 Chapter 12: Random graphs, small world, and rich-club
! Warning
This will take a long time. See Benchmarks for example processing times.
12.2 Small-worldness
The function small.world will calculate small world parameters, including normalized clustering coefficient
and characteristic path length, as well as the small world coefficient σ.(55) It returns a data.table with
those values. Each row corresponds to a group/density combination.
head(small.dt)
To calculate ω (see Telesford et al. (112)), which is a better metric for small-worldness, you will have to:
1. Generate simple random graphs to get the characteristic path length Lrand (see previous section).
2. Create random graphs controlling for the level of clustering, and use the clustering coefficient of these
random graphs as the value for equivalent lattice networks (Clatt )
3. The values L and C are characteristic path length and clustering coefficient, respectively, for the
observed graphs.
C/Crand
σ= (12.1)
L/Lrand
Lrand C
ω= − (12.2)
L Clatt
The only downside to this approach is the processing time needed. As I mentioned earlier, a reasonable
compromise would be to limit the number of Markov Chain steps (via the max.iters function argument),
as even with only 100 iterations, the resultant graphs will be much closer to a lattice than a simple random
graph controlling only for degree distribution.
The R code for calculating ω is:
To show that the random graph generation approach from the last section does result in networks with higher
clustering, we can plot these values, shown in Figure 12.1. As you can see, the random graphs generated by
the Markov Chain process (dotted lines) have a similar clustering level as the observed networks (solid lines).
As expected, the “simple” random graphs have much lower clustering. This is also reflected in the much
higher normalized clustering coefficients in calculating σ.
If you refer back to Equation 12.1 and Equation 12.2, the normalized path length will roughly equal 1; i.e.,
L/Lrand ≈ Lrand /L ≈ 1. It is also the case that C/Crand 1 and C/Clatt ≈ 1. So we should see σ 1 and
ω ≈ 0, which is confirmed in Figure 12.2.
0.6
0.5
Group, type
Clustering coefficient
Control, Cp
Patient, Cp
0.4
Control, rand
Patient, rand
Control, latt
Patient, latt
0.3
0.2
Figure 12.1: Clustering coefficients for random networks. The solid lines are clustering for the observed
networks. The dotted line are values from networks generated by the Markov Chain approach,
and the dashed lines are values from networks generated by the “simple” approach.
We can plot both σ and ω in the same plot, shown in Figure 12.2. As stated in Telesford et al. (112), networks
with ω closer to 0 indicate more balance between high clustering and low path length; networks with ω closer
12.2 Small-worldness 101
to −1 are more similar to a lattice network. The results of this analysis indicate that the Patient group’s
networks at higher density are closer to a lattice than the Control networks.
small.long[, yint := 1]
small.long[variable == 'omega', yint := 0]
ggplot(small.long[variable %in% c('sigma', 'omega')],
aes(x=density, y=value, col=Group, group=Group)) +
geom_line() +
geom_hline(aes(yintercept=yint), lty=2) +
facet_wrap(~ variable, scales='free_y', ncol=1) +
theme(legend.position=c(1, 1), legend.justification=c(1, 1)) +
ylab('Small-worldness')
sigma
Group
Control
2.5 Patient
2.0
1.5
Small−worldness
1.0
omega
0.0
−0.1
−0.2
−0.3
−0.4
Figure 12.2: Small-world indexes. (top) The classic small-world index, σ; the dashed horizontal line at
y = 1 is included to show the minimum value for a network to be considered “small-world” (126)
(bottom) The small-world index ω introduced by Telesford et al. (112); the dashed horizontal
line at y = 0 indicates the value at which the network displays a balance between clustering
coefficient and characteristic path length.
102 Chapter 12: Random graphs, small world, and rich-club
Table 12.1: Rich-club graph attributes. The and vertex- and edge-level attributes that are added after
calling rich club attrs.
The rich club is a set of vertices that have a high degree themselves and which also have a high probability of
being connected to one another (see Colizza et al. (16), Zhou and Mondragón (135)).
When creating random graphs with analysis random graphs, normalized rich-club coefficients and P-values
were also calculated (now in rich.dt ). This will be used later for plotting.
12.3.1 Rich-core
A recent paper provided an algorithm for determining the cut-off degree for inclusion in the rich club (71).
The function to calculate this is called rich core. The degree value is given in the output data frame, with
column name k.r ( k stands for degree and the r is for rank ). You can calculate the rich-core for
both binary and weighted graphs. In the next code section, I show how to plot a shaded region that starts at
the maximum cut-off value from 2 groups which is automatically calculated by the plotting function.
0.15 0.16
1.4
1.4
1.2
1.2
φnorm
1.0
1.0
0.8
# Alternatively, the degree range could use the following command, but in the
# current example, the number of random graphs was very low
#rich.dt[density == densities[N] & Group == grps[1] & p.fdr < 0.05, range(k)]
To generate random graphs in the case of single-subject data, the code is largely the same as in Random
graph generation. Just substitute g.norm for g (or whatever your graph list object happens to be named).
The function analysis random graphs will return a data.table with the normalized rich club coefficients
and P-values. The code in the following block may be necessary if you later want to plot these results.
For single-subject data (e.g., DTI tractography or rs-fMRI), you will have to change the function call of
plot rich norm to facet.by=’threshold’ (assuming this is how you generated the connectivity matrices
104 Chapter 12: Random graphs, small world, and rich-club
to begin with). Furthermore, the default behavior is to plot a loess smoother ; if you would like to see an
individual line for each subject, then you must specify smooth=FALSE .
13.1 Bootstrapping
In structural covariance analyses, since there is only one graph per group (at a given density)—as atlas-based
brain regions typically are different sizes—it is not possible to directly compute the within-group variability
of graph measures (e.g., modularity). In this case, bootstrapping is necessary. The function brainGraph boot
will perform bootstrap resampling in this case; the boot package does all of the resampling.(23)
args(brainGraph_boot)
densities The (numeric) vector of network densities (since the function creates networks of the same
density for bootstrap samples).
measure Character string indicating which global graph metric to test (default: ’mod’ ; i.e., modularity)
conf The confidence level; the default, 0.95 , returns 95% confidence intervals.
.progress Logical indicating whether or not to print a progress bar (default: getOption, bg.progress
.
There are several graph-level metrics you can choose from; currently, the options are: modularity (weighted
and unweighted), global efficiency (weighted and unweighted), clustering coefficient, characteristic path length,
(degree) assortativity, and mean graph strength. Your data may also have an arbitrary number of groups (i.e.,
not just 2).
105
106 Chapter 13: Bootstrapping and permutation testing
boot A list (with length equal to the number of groups). Each element of the list is an object of class
boot. See the help file for more information (by typing help(boot) ).
The summary method prints some analysis-specific information, and then a data.table with the observed
values, standard errors, and confidence intervals for each group and density tested.
summary(bootmod)
##
## =====================================
## Bootstrap analysis
## =====================================
Bootstrapping can give you an estimate of the variability of a group measure (e.g., modularity). In order to
determine the significance of a between-group difference, you need to do permutation testing.
args(brainGraph_permute)
densities
resids
N The number of permutations. Default: 5000
108 Chapter 13: Bootstrapping and permutation testing
get(gID)
0.6
Control
Patient
0.5
Modularity
0.4
0.3
0.7
get(gID)
Control
Patient
0.6
Modularity
0.5
0.4
0.3
0.2
0.05 0.10 0.15 0.20
density
atlas
auc
N
level
13.2 Permutation testing 109
measure
densities
resids
DT A data.table with the permutation differences for each density (if auc=FALSE ), and each
region (there are multiple if level=’vertex’ ).
obs.diff A data.table of the observed group difference. The number of rows equals the number of
densities. If level=’vertex’ , the number of columns equals the number of regions.
13.2.3 Graph-level
Several graph-level measures are calculated: modularity, clustering coefficient, average path length, assortativity
(degree and lobe), asymmetry, and global efficiency.
For the summary method, if level=’graph’ , then you must choose which network measure to
summarize. You additionally specify an alternative hypothesis, alpha level, and which P-value to
use for determining significance (either the standard P-value, or FDR-adjusted). Here, I show the summary
for Lp . In this case, the group difference was significant for only one density.
##
## =====================================
## Permutation analysis
## =====================================
## # of permutations: 1,000
## Level: graph
## Graph metric: Characteristic path length
## Alternative hypothesis: Control - Patient < 0
## Alpha: 0.05
##
## densities region Lp.Control Lp.Patient obs.diff perm.diff 95% CI low
## 1: 0.05 graph 3.042 4.754 -1.7123 -0.22302 -1.4956
## 2: 0.06 graph 2.896 4.024 -1.1281 -0.20345 -0.9930
## 3: 0.07 graph 2.985 3.831 -0.8461 -0.16363 -0.8095
## 4: 0.09 graph 2.579 3.053 -0.4743 -0.04932 -0.4431
## 95% CI high p p.fdr
## 1: 2.1486 0.02697 0.1718
## 2: 1.8582 0.03297 0.1718
## 3: 1.7304 0.04296 0.1718
## 4: 0.6577 0.03996 0.1718
110 Chapter 13: Bootstrapping and permutation testing
Plotting: graph-level
The plot method has the same arguments as the summary method, and returns a list with two ggplot
objects:
1. A line plot of the observed graph-level measure across densities, with an asterisk added if p < α; a blue
asterisk is added if α < p < 0.10 (i.e., a “trend” towards significance). This is shown in Figure 13.2.
2. A line plot of the observed group difference across densities. Also shown are dashed lines of the (1 − α)%
confidence interval based on the permutation distribution (see Figure 13.3 and the following paragraph).
4
Observed values
2
* * * * *
0.05 0.10 0.15 0.20
Density
Figure 13.2: Permutation testing, graph-level. Observed avg. path length across densities
Instead of plotting the observed value for both groups, you can also plot the group differences along with
a (1 − α)% confidence interval. In Figure 13.3, the red line indicates observed between-group differences,
the central dashed line is the mean permutation difference, and the outer dashed lines are upper and lower
bounds. In this example, I used a one-sided test, assuming group 1 would be lower than group 2.
print(permPlot[[2]])
13.2 Permutation testing 111
0 ● ●
● ●
● ● ● ● ● ● ●
● ●
●
−1
●
Figure 13.3: Permutation testing, graph-level. Observed and permuted differences in avg. path length
across densities
The summary method has the same type of output as with graph-level measures:
summary(perms.btwn)
##
## =====================================
## Permutation analysis
## =====================================
## # of permutations: 1,000
## Level: vertex
## Graph metric: Betweenness centrality
112 Chapter 13: Bootstrapping and permutation testing
Plotting: vertex-level
The plot method for vertex-level measures is slightly different. There is only one type of plot, a barplot
of the permutation differences at those vertices for which Psig < α (depending on the function arguments).
The output is shown in Figure 13.4; the horizontal red line segments represent the observed between-group
differences.
plot(perms.btwn)
Betweenness centrality
0.1 0.11 0.12
300 300
200
200
100
100
100
Observed and permutation difference (Control − Patient)
● ● ●
● ● ●
0 ●
● ●
0 ● 0
−100
−100
−200
−100
−200
−300
lMTG
lPARH
lpTRIrFUSrINSrMOFrTT rSTG lMTG rpreC
200
200
100
100 100
0 ● ● 0 ●
● ●
● ●
0
−100
−100
−100 −200
Figure 13.4: Permutation testing, vertex-level. Group differences in vertex betweenness centrality
(observed difference in red)
identical to that of the previous sections, except you add auc=TRUE to the function call.
Similarly, this can be done for vertex-level measures. The plot method will only work if level=’vertex’
.
Betweenness centrality
1
40
20
● ● ●
0 ●
●
−20
Figure 13.5: Permutation testing, vertex-level. Group differences in AUC of vertex betweenness central-
ity (observed difference in red)
level='other', .function=clocent.diffs.perm,
auc=TRUE)
Since auc=TRUE , the summary method only shows results from one “density”:
summary(perms.clocent, alt='less')
##
## =====================================
## Permutation analysis
## =====================================
## # of permutations: 100
## Level: vertex
## Graph metric:
## Area-under-the-curve (AUC) calculated across 16 densities:
## 0.05 0.06 0.07 0.08 0.09 0.1 0.11 0.12 0.13 0.14 0.15 0.16 0.17 0.18 0.19 0.2
## Alternative hypothesis: Control - Patient < 0
## Alpha: 0.05
##
## No significant results!
14
Further analysis
There is of course much more you can do with network data. In this Chapter I will briefly describe some of
what is available in my package, and how to perform these analyses.
14.1 Robustness
If you are interested in vulnerability, see the function vulnerability; also, each graph is given both global-
and vertex-level attributes called vulnerability through set brainGraph attr.
116
14.1 Robustness 117
0.75
comp.pct
0.50
0.25
0.00
1.00
0.75
0.50
% of max. component remaining
0.25
0.00
1.00
0.75
0.50
0.25
Group
Control
0.00 Patient
0.00 0.25 0.50 0.75 1.00 0.00 0.25 0.50 0.75 1.00
% edges/vertices removed
It’s very easy to get the spatial distance of edges. However, note that this distance is Euclidean (i.e., it
doesn’t follow a geodesic along the cortical surface), and it is based on coordinates that represent (roughly)
the median coordinates of the atlas in MNI space.
You will notice that in my code, I use a Kruskal-Wallis test. This is an extension of the Wilcoxon test
allowing for an arbitrary number of subject groups. If you only have 2 groups, then it is equivalent to a
Wilcoxon test.
The following code example and Figure 14.3 show group-wise histograms of edge distances for 2 densities. In
this case, the control group tends to have more long-range connections.
You can also plot the average edge distance across all densities, with a shaded region signifying the confidence
interval (here I plot the 99th %ile). This is shown in Figure 14.4.
Saggar et al. (2015) recently introduced two methods for estimating the individual contributions of subjects
to a group graph (100). I wrote two functions to calculate these measures: aop (“add-one-patient”) and loo
(“leave-one-out”). This is useful for structural covariance networks in which there is just a single graph for
each group. For both functions, you can calculate either a “global” or a “regional” metric. For the global
metrics, these can easily be merged with other data so you can correlate the individual contribution ( IC )
with some variable of interest (e.g., full-scale IQ (FSIQ)).
120 Chapter 14: Further analysis
0.1 0.11
Group
Control
Patient
0.015
0.010
density
0.005
0.000
##
## Individual contributions
## -------------------------------------
## Method: Add one patient
## Level: regional
##
## Number of outliers per region: (sorted in descending order)
## rLING rMOF rpTRI lFUS lparaC lSPL lTP rPARH
## 8 8 7 6 6 6 6 6
## rPCC rSFG lCUN lIPL liCC lLING lpreC lrACC
14.3 Individual contributions 121
70
Edge distance (mm)
60 Group
Control
Patient
* * * * * * * * * * * * * * * *
50
0.05 0.10 0.15 0.20
density
Figure 14.4: Average edge distances (in mm) with 99% confidence intervals
## 6 6 5 5 5 5 5 5
## lSFG rMTG rparaC rpORB rpostC rpreC rPCUN rFP
## 5 5 5 5 5 5 5 5
## lITG lLOF lMOF lpORB lpTRI lPCC lPCUN lrMFG
## 4 4 4 4 4 4 4 4
## lFP lTT rcACC rcMFG rFUS rIPL rITG rLOG
## 4 4 4 4 4 4 4 4
## rLOF rperiCAL rrMFG rSTG rTP lcACC lcMFG lENT
## 4 4 4 4 4 3 3 3
## lMTG lperiCAL lpostC lSMAR lINS rBSTS rENT rpOPER
## 3 3 3 3 3 3 3 3
## rrACC rTT rINS lBSTS lPARH lpOPER lSTG rCUN
## 3 3 3 2 2 2 2 2
## riCC rSPL rSMAR lLOG
## 2 2 2 1
##
## Group region avg stdev se
## 1: Patient lBSTS 0.9419 0.8990 0.09373
## 2: Patient lcACC 0.9684 0.6882 0.07175
## 3: Patient lcMFG 1.0546 0.9803 0.10221
## 4: Patient lCUN 0.8047 0.6834 0.07124
## 5: Patient lENT 0.9493 0.7151 0.07456
## ---
122 Chapter 14: Further analysis
We can also plot the regional contribution for the group using the plot method (not shown, as it is almost
the same as Figure 14.5).
plot(RC.aop)
##
## Individual contributions
## -------------------------------------
## Method: Leave one out
## Level: global
##
## "Outliers"
## Group Study.ID IC
## 1: Control 131 0.015283
## 2: Control 103 0.012979
## 3: Control 4 0.011464
## 4: Patient 108 0.014513
## 5: Patient 47 0.009209
We can also plot the regional contribution for the groups using the plot method (see Figure 14.5):
plot(RC.loo)
plot(IC.loo)
mean The default, which plots a shaded area of values within 2 standard errors of the mean
smooth Plot the result of applying a loess smoother to the data. This is much less useful, particularly
when plotting a large number of regions
boxplot Plot the data as boxplots. This will also be a very “busy” plot if there are a lot of regions.
Regional contribution
0.5
0.7
0.9
1.1
lB
S
lc TS
A
lc CC
M
lC FG
U
lE N
N
lF T
U
lIP S
lIT L
liCG
lL C
O
lL G
lL OF
IN
lM G
lMOF
lP TG
A
lp RH
lp ara
O C
lp PE
O R
l R
lp pTRB
er I
lp iCA
o
lP stCL
lp CC
lP reC
C
lrA UN
lrMCC
lS FG
F
lS G
Group
lS PL
lS TG
M
lF AR
P
lT
P
lT
lINT
rB S
rc STS
Control
rc ACC
M
Region
rC FG
rEUN
rF NT
U
rIP S
rIT L
riCG
rL C
O
rL G
Patient
rL OF
I
rMNG
rMOF
rP TG
rpAR
rp araH
O C
rP stCL
rp CC
rP reC
C
rrA UN
rrMCC
rS FG
rSFG
rS PL
rS TG
M
rF AR
rTP
rTP
rINT
14.3 Individual contributions
S
123
124
Individual contribution
0.000
0.005
0.010
0.015
●
●
●
111100
●
110010
●
●
111000243
●
●
103
108
111000576
●
●
11101189
●
●
●
111111021
●
●
111111354
●
11111687
1
●
●
122
11122290
●
●
111222132
●
●
111222465
●
12278
●
● ●
111339
●
111333102
●
●
131
Chapter 14: Further analysis
●
111333435
●
11333768
1
●
●
●
1144490
●
1151
●
1176
●
● ●
189
●
2220
●
2
Group
●
222213
●
●
●
222546
a●
●
●
22879
●
3
●
33301
●
●
●
333324
●●
333657
●
4
Control
389
Subject
●
4440
●
●
4412
a
●
●
444435
●
444768
●
●
47
55590
48
●
●
555213
Patient
●
●
555546
●
●
●
55879
●
6
●
66601
●
64
●
666324
●●●
●
689
7770
●
7712
● ●●
●
●
Individual contributions, leave one out method
777354
●
●
●
777687
●
●
●
88890
●●
888132
●●
●
888465 ●
●
●
88789
9
●●●
99910
●
●
999243
● ●
●
9956 ●
●
9978 ●
9
Part VI
Visualization
125
15
GUI and other plotting functionality
The purpose of the brainGraph GUI is to quickly and flexibly compare graphs (up to two at a time). The
function to open it is plot brainGraph gui. See Figure 15.1 for a screenshot.
The most obvious feature of the GUI is that there are 1–2 plotting sections for showing 1–2 graphs (of
subjects, groups, etc.) side-by-side. If you have a single graph you would like to inspect, you can enter the
same graph object twice to look at different densities, orientations, etc.
The # of vertices, # of edges, and the graph’s density are printed at the bottom of each figure window if
“Display subtitle” is checked. At the top of each figure window, the graph’s name attribute is printed (in
this case, group) if “Display main title” is checked.
15.1.1 Orientation
You can choose one of: axial, sagittal (L), sagittal (R), or circular. The sagittal plots necessarily show only
intra-hemispheric edges. If you choose circular, there is a slider widget beneath each plot that controls the
edge curvature.
15.1.2 Hemi/Edges
This option lets you show a subset of edges based on vertex classification/grouping. The default is to show
all edges. Other options are:
• Individual hemispheres
• Inter- and intra-network edges; these refer to the network attribute for the power264 , gordon333 ,
and dosenbach160
• Inter- and intra-area edges; here, area is an attribute of the hcp mmp1.0 atlas
• Inter- and intra-Yeo 7 or Yeo 17 edges; this is only applicable for the brainnetome atlas
126
15.1 The GUI 127
15.1.3 Annotations
There are 4 checkboxes that can be (de-)selected to annotate the plot areas:
• Main title
• Subtitle
• Vertex labels
• Legend
There is also a “combo box” for changing vertex colors. The options are the same as those listed in the
previous sections, in addition to class (for the Destrieux atlases) and connected components. There is no
legend if vertex colors are based on communities or components. The numbers in the legend box represent
the # of vertices present out of the total # of vertices for that lobe/network/etc.
Alt+f Opens the File dropdown menu Ctrl+y Plot Yeo-7 networks ( brainnetome
only)
Ctrl+o Select new graph objects (same as clicking
Pick new graphs) Ctrl+7 Plot Yeo-17 networks ( brainnetome
only)
Ctrl+1 Save figure 1 (left)
Ctrl+2 Save figure 2 (right) Ctrl+g Plot Gyri ( brainnetome only)
Alt+p Opens the Plot dropdown menu Alt+n Same as clicking Pick new graphs
Ctrl+e Plot Entire graphs (optionally selecting Alt+m Toggle the Display main title checkbox
combinations of lobes)
Alt+s Toggle the Display subtitle checkbox
Ctrl+n Plot Neighborhoods
Alt+l Toggle the Display vertex labels checkbox
Ctrl+c Plot Communities
Alt+g Toggle the Show legend checkbox
Ctrl+f Plot Functional networks (i.e., the
network attribute) Alt+d Toggle the Show diameter checkbox
Ctrl+a Plot Cortical Areas ( hcp mmp1.0 only) Alt+e Toggle the Show edge differences checkbox
print(matplot.comm[[2]])
print(matplot.lobe[[1]])
print(matplot.lobe[[2]])
15.2 Other plotting 129
plot_vertex_measures(g[[N]], facet.by='lobe',
'btwn.cent', show.points=TRUE,
ylabel='Betweenness centrality')
130 Chapter 15: GUI and other plotting functionality
There is also an option to view only a subgraph of vertices. The subgraph argument accepts logical
expressions joined by & and/or by | for multiple conditions. For example, if you only want to plot vertices
with degree greater than 10 and nodal efficiency greater than 0.5, you type:
After this, you can convert this series of PNG’s to either a GIF or to a video file. Converting to a GIF is
done using ImageMagick, a powerful command-line utility for general image processing. You may then view
the GIF in any image viewer, or, on Linux, gifview lets you step through each frame. Converting to a video
will require a tool called ffmpeg (available on Linux).
Convert to gif
# The delay argument means show each frame for 0.5 seconds (i.e. 50/100)
convert -delay 50 -loop 0 group1.pdf animation.gif
Control
lBSTS
lcMFG
lENT
lFUS
lITG
lMTG
lpOPER
lpreC
lSTG
lTT
lINS
rBSTS
rcMFG
rENT
rFUS
rITG
rMTG
rPARH
rpOPER Community (#)
rpTRI
rSTG 1
rTP
rINS
lLOF 2
lMOF
lpORB
lpTRI 3
lperiCAL
lrMFG 4
lSFG
lFP
lTP 5
rcACC
rLOF
rMOF 6
rparaC
rpORB 7
rPCC
rpreC
rrACC 8
rrMFG
rSFG 9
rFP
lCUN
lIPL 10
lLOG
lLING
lparaC Inter
lpostC
lPCUN
lSPL
lSMAR
rCUN
rIPL
rLOG
rLING
rpostC
rPCUN
rSPL
rSMAR
riCC
rTT
lcACC
liCC
lPARH
lPCC
lrACC
rperiCAL
L
lS FGL
rSTR R
lSreCR
riCAR
rSSP N
R
rP RC
rp CCB
lSSP N
rp PEH
C tC
lE FG
rE FGS
lplpTRB
lPos C
rMO C
rS FG
lP RH
A
M S
C tC
lPiCCC
MC
A
rPos G
er C
rp ARG
rparaF
lparaG
TI
rr reC
r UN
O G
OF
rL OG
rT G
lrMriC I
r G
lI N
rF NT
rI US
lL OG
rplrACC
lT G
lF G
rp OF
lF NT
lI US
ML
lp PE
lp OF
ML
r C
rMTG
lLNS
lpMTG
rBINS
e R
rLIPL
lLPL
r U
rC A
rc T
rI P
lCFP
l U
lc TT
iC
lc ST
P
rc P
rL C
l T
l C
rr C
rp IN
rP T
lp IN
lMO
C
F
T
F
S
lT
O
M
T
A
A
A
A
O
lB
Patient
lBSTS
lENT
lFUS
lITG
lMTG
lSTG
lTP
lINS
rENT
rFUS
rITG
rMTG
rpOPER
rSTG
rTP
rTT
rINS
lIPL
lparaC Community (#)
lpostC
lpreC 1
lPCUN
lSPL
lSMAR 2
rcMFG
rIPL
rLING 3
rparaC
rpostC
rpreC
4
rPCUN
rSFG 5
rSPL
rSMAR
lcMFG 6
lLOF
lMOF 7
lpOPER
lpORB
lpTRI 8
lrMFG
lSFG 9
lFP
rLOF
rMOF 10
rpORB
rpTRI
rrMFG Inter
rFP
lCUN
lLOG
lLING
lperiCAL
lTT
rCUN
rLOG
rperiCAL
lPCC
rcACC
rPCC
lcACC
lrACC
lPARH
rPARH
liCC
rBSTS
riCC
rrACC
rc CCAL
rC T L
rT GR
lp R R
lL F R
r FN
M R
rr TRB
r os C
lSSP N
rLIPLG
rBiCCH
rPpretC
l OG
lrMTRB
riCTS
lp s C
lc CCC
r FG
A H
lE TS
lP retC
lPAC C
C
lTCA
rparaG
rPARC
O G
rpORF
er G
CC
M I
rp O N
lS TG
lp PEF
e G
CC
rSSPG
lS FGI
lL UN
rF NT
rI US
lplLING
rSPE
lT G
lF G
rMOF
lF NT
lI US
lc MAL
lpMOF
rcMAL
rr C
rpMTG
l S
lMTG
rENS
lp IPL
rS U
rTP
l U
lCFP
rINT
lPriC
l R
lI P
rL P
lpara
r F
rP C
lr C
rp O
AC
rp IN
U
T
O
T
F
rT
S
S
A
A
i
o
L
lB
Control
lcMFG
lLOF
lMOF
lparaC
lpOPER
lpORB
lpTRI
lpreC
lrMFG
lSFG
lFP
rcMFG
rLOF
rMOF
rparaC
rpOPER
rpORB
rpTRI
rpreC
rrMFG
rSFG
rFP
lIPL
lpostC Lobe
lPCUN
lSPL
lSMAR Frontal
rIPL
rpostC
rPCUN
Parietal
rSPL
rSMAR Temporal
lBSTS
lENT
lFUS Occipital
lITG
lMTG Insula
lPARH
lSTG
lTP Cingulate
lTT
rBSTS Inter
rENT
rFUS
rITG
rMTG
rPARH
rSTG
rTP
rTT
lCUN
lLOG
lLING
lperiCAL
rCUN
rLOG
rLING
rperiCAL
lINS
rINS
lcACC
liCC
lPCC
lrACC
rcACC
riCC
rPCC
rrACC
r SL
rL UN L
rp R R
lp R R
lE TSR
rSSP N
rpIPLR
rpTRB
rp P C
rL FG
lSSP N
rS RH
C tC
lL FG
lpTRB
S
lp PEC
ri CC
rS FG
lS RH
lINiCA
CC
liCCC
lS FG
C
rCiCA
er G
AC
rppar F
AG
er G
rr re I
MC
lp ar F
lP TG
rL OG
rr CC
lrMreCI
rF G
rT G
lL UN
rF T
rI US
lp LING
lrACC
OE
FG
r OF
lT G
L
lF NT
lI S
lMOF
ML
rPCC
rMTG
lcINS
lMTG
lP C
lBMA
lpIPL
r U
r A
Oa
l P
l U
rEST
rP
lCTT
rclFP
P
Oa
rBlTT
lP st
AC
lp O
rc C
N
rp IN
rMO
rP T
rPos
U
F
l O
T
M
S
M
A
o
lc
Patient
lcMFG
lLOF
lMOF
lparaC
lpOPER
lpORB
lpTRI
lpreC
lrMFG
lSFG
lFP
rcMFG
rLOF
rMOF
rparaC
rpOPER
rpORB
rpTRI
rpreC
rrMFG
rSFG
rFP
lIPL
lpostC Lobe
lPCUN
lSPL
lSMAR Frontal
rIPL
rpostC
rPCUN
Parietal
rSPL
rSMAR Temporal
lBSTS
lENT
lFUS Occipital
lITG
lMTG Insula
lPARH
lSTG
lTP Cingulate
lTT
rBSTS Inter
rENT
rFUS
rITG
rMTG
rPARH
rSTG
rTP
rTT
lCUN
lLOG
lLING
lperiCAL
rCUN
rLOG
rLING
rperiCAL
lINS
rINS
lcACC
liCC
lPCC
lrACC
rcACC
riCC
rPCC
rrACC
r SL
rL UN L
rp R R
lp R R
lE TSR
rSSP N
rpIPLR
rpTRB
rp P C
rL FG
lSSP N
rS RH
C tC
lL FG
lpTRB
S
lp PEC
ri CC
rS FG
lS RH
lINiCA
CC
liCCC
lS FG
C
rCiCA
er G
AC
rppar F
AG
er G
rr re I
MC
lp ar F
lP TG
rL OG
rr CC
lrMreCI
rF G
rT G
lL UN
rF T
rI US
lp LING
lrACC
OE
FG
r OF
lT G
L
lF NT
lI S
lMOF
ML
rPCC
rMTG
lcINS
lMTG
lP C
lBMA
lpIPL
r U
r A
Oa
l P
l U
rEST
rP
lCTT
rclFP
P
Oa
rBlTT
lP st
AC
lp O
rc C
N
rp IN
rMO
rP T
rPos
U
F
l O
T
M
S
M
A
o
lc
Clustering coeff. Char. path length Global eff. Modularity Max. conn. comp.
0.60 0.5
3.5 0.5 60
0.4
0.56 3.0
0.3 0.4 50
0.52 2.5 0.2 40
0.48 * * * * 0.3
2.0
# of triangles Diameter Transitivity assortativity Strength
1500 10
9 0.25 12
1000 0.52 10
8 0.20
7 0.15 8
500 0.48 6
6 0.10
5 4
0 0.44 0.05
Modularity (wt) Local eff. (wt) Global eff. (wt) Diameter (wt) Char. path length (wt)
0.80 0.5 10
0.5 9 3.5
0.75 0.4
value
8 3.0
0.4 0.70 0.3 7
0.65 0.2 6 2.5
0.3 5
0.60 2.0
# of hubs (wt) assortativity.lobe assortativity.lobe.hemi Asymmetry index Edge distance
0.6 −0.2 75
20 0.25
0.5 −0.3 70
18 0.20 −0.4 65
0.4
0.15 −0.5 60
16 0.3
−0.6 55
05
10
15
20
05
10
15
20
# of hubs Local eff. Vulnerability
0.
0.
0.
0.
0.
0.
0.
0.
0.7 0.3
20
0.6 0.2
18
0.5 0.1
16
0.4
0.0
05
10
15
20
05
10
15
20
05
10
15
20
0.
0.
0.
0.
0.
0.
0.
0.
0.
0.
0.
0.
density
40 100
200
●
●
●
●
●
20 ●
100 ●
50
● ●
● ●
● ●● ●
● ●
Betweenness centrality
● ●
● ●
● ●●
● ●
● ●●
●●
● ●●
0 ●
●● ●
● ●
● ●● 0 ●●
●●
● ●●● ●
200
100 ●
200
150
●
● ● ●
●
100
50
100 ●
● ● ●
●
●
● ●
●
● 50
●
●●
●
● ●●
● ● ●
●
● ● ● ● ● ●●
●
● ●●
● ●
● ● ● ●● ●●
0 ●
●● ● ●
●● ● 0 ●●
●●● ●●●●
0
Control Patient Control Patient Control Patient
Group
A.1 Graph-level
A.1.1 Housekeeping
Some attributes are included only for “housekeeping” purposes. Most are optional, but I suggest supplying
them.
version The version of brainGraph that was used to create the graph
atlas The atlas (e.g., dk for Desikan-Killiany)
clust.method The clustering (community detection) algorithm used
clust.method.wt Same as above, but using edge weights (if the graph is weighted). This is not necessarily
different from the unweighted value.
Group The subject/patient group name
name The subject/study ID of the subject
modality The imaging modality
weighting The edge weighting. For example, fa (for FA-weighted matrices from tractography), or
partial (for partial correlation coefficients).
threshold The threshold applied to the raw connectivity matrices.
xfm.type The method used to transform edge weights for distance-based metrics (if the graph is
weighted)
A.1.2 Unweighted
Cp The graph’s clustering coefficient (using the localaverage option)
Lp Characteristic path length
rich A data.table of the rich-club coefficients and subgraph sizes
E.global The global efficiency
E.local The mean local efficiency across vertices
mod Modularity, calculated using the algorithm specified by clust.method
density
143
144 Chapter A: Attributes created by set brainGraph attr
diameter
transitivity
assort.class Assortativity calculated using class membership (if the atlas is destrieux)
A.1.3 Weighted
strength Average vertex strength
mod.wt Modularity, calculated using the algorithm specified by clust.method and taking into
account edge weights
Lp.wt The weighted characteristic path length, which is the mean of the vertices’ average path
lengths
num.hubs.wt The number of hubs, determined using edge weights to calculate path lengths, clustering
coefficients, and vertex strength
A.2 Vertex-level
A.2.1 Housekeeping/Other
name The name of the brain region
lobe.hemi Integer vector corresponding to a combination of the lobe and hemi attributes
A.2 Vertex-level 145
class The “class”, if the atlas is destrieux. Either G (gyral), S (sulcal), or G and S (both)
network The “network”, if the atlas is dosenbach160
x,y,z The spatial coordinates
x.mni,y.mni,z.mni (same as above)
color.lobe The colors corresponding to lobe membership
color.class The colors corresponding to class membership (if the atlas is destrieux)
color.network The colors corresponding to network membership (if the atlas is dosenbach160)
color.comm Colors corresponding to community membership
color.comm.wt The colors corresponding to weighted community membership
color.comp Colors corresponding to component membership
A.2.2 Unweighted
degree
asymm Edge asymmetry
dist The mean (Euclidean) edge distance of each vertex’s connections
dist.strength Vertices’ dist multiplied by the degree
knn Average nearest neighbor degree
Lp The vertices’ average shortest path lengths
btwn.cent Betweenness centrality
ev.cent Eigenvector centrality
lev.cent Leverage centrality
hubs “Hubness” scores (calculated by hubness)
k.core k-core membership
transitivity Transitivity
E.local Local efficiency
E.nodal Nodal efficiency
vulnerability
eccentricity The “longest shortest path length”; i.e., the maximum of shortest path lengths from a
vertex to all other vertices
comm Integer vector of the vertices’ community membership (from largest to smallest)
comp Integer vector of the vertices’ connected component membership (from largest to
smallest)
GC Gateway coefficient
PC Participation coefficient
z.score Within-module degree z-score
146 Chapter A: Attributes created by set brainGraph attr
A.2.3 Weighted
strength
knn.wt Average nearest neighbor strength
A.3 Edge-level
! New in v3.0.0
All of these functions/methods are new in v3.0.0.
There are several new model fitting functions that are much faster than other solutions (see Benchmarks).
There are multiple default function arguments that greatly improve speed in various scenarios; this is most
helpful when permuting and fitting the data.
Note
Only the first 2 of the following should be used directly.
fastLmBG Requires a design matrix X and numeric matrix of outcome variables Y. The outcome
matrix should have 1 column for each outcome variable.
fastLmBG 3d Fits models when there are multiple design matrices, so X will be a 3-D array, and
a single outcome variable, so Y will be a column matrix. The array X must have
dimension names, and the input argument runX specifies the regions for which a
model should be fit.
fastLmBG 3dY Fits models when there is both a different design and outcome variable for each
region. This only occurs under permutation for the Freedman-Lane, ter Braak, and
Still-White methods.
fastLmBG 3dY 1p Fits models when there is both a different design and outcome for each region, and
also when X is a rank-1 matrix (i.e., has a single column). This only occurs under
permutation with the Still-White method if there is a single regressor of interest.
There are 2 functions for calculating contrast-based statistics for F- and t-contrasts, respectively. Both require
a list object that is returned from one of the model fitting functions (see previous section) as well as a list of
contrast matrices (F-contrasts) or a single matrix (t-contrasts).
147
148 Chapter B: GLM Statistics
fastLmBG t Returns a multidimensional array with the contrast of parameter estimates, standard error
of the contrast, t-statistics, P-values, FDR-adjusted P-values, and confidence intervals
fastLmBG f Returns a multidimensional array with the extra sum of squares, standard error (the sum of
squared errors of the full model), F-statistic, P-values, and FDR-adjusted P-values
γ̂ = C T β̂
This is equivalent to the cope? images from FSL, the con_???? images from SPM, and
gamma.mgh from Freesurfer.
ESS (if con.type=’f’ ) The extra sum of squares due to the full model, compared to the
reduced model. This is specific to the contrast matrix, and is equivalent to the ess_????
images from SPM.
Standard error (if con.type=’t’ ) The standard error of the contrast, SE, is
√
SE = CΣC T
Σ = s2 XT X
Standard error (if con.type=’f’ ) The sum of squared errors (or residual sum of sqares) of the full
model. This is, for residuals ê,
RSS = êT ê
γ̂ ± tα/2,df × SE
There are now a few dozen methods for bg GLM objects, many of which are meant to mimic methods of lm
objects. All the methods for this class can be viewed with
methods(class='bg_GLM')
B.3 GLM methods 149
The next few sections will list and describe these based on a few categories.
formula(anova2x3)
terms(anova2x3)
## $Intercept
## [1] 1
##
## $A
## [1] 2
##
## $B
## [1] 3 4
##
## $`A:B`
## [1] 5 6
variable.names(anova2x3)
coeff_table(diffs.perm)[, , 'lcACC']
anova(diffs.perm)[[1]]
str(influence(diffs.perm))
## List of 5
## $ infmat: num [1:156, 1:9, 1:76] -0.0163 0.087 -0.1074 -0.0286 -0.0631 ...
## ..- attr(*, "dimnames")=List of 3
## .. ..$ : chr [1:156] "02-001-4" "02-003-2" "02-006-8" "02-008-7" ...
## .. ..$ : chr [1:9] "dfb.Intercept" "dfb.Age.MRI" "dfb.Sex" "dfb.Scanner" ...
## .. ..$ : chr [1:76] "lcACC" "lcMFG" "lCUN" "lENT" ...
## $ is.inf: logi [1:156, 1:9, 1:76] FALSE FALSE FALSE FALSE FALSE FALSE ...
## ..- attr(*, "dimnames")=List of 3
## .. ..$ : chr [1:156] "02-001-4" "02-003-2" "02-006-8" "02-008-7" ...
## .. ..$ : chr [1:9] "dfb.Intercept" "dfb.Age.MRI" "dfb.Sex" "dfb.Scanner" ...
## .. ..$ : chr [1:76] "lcACC" "lcMFG" "lCUN" "lENT" ...
## $ f : chr "E.nodal.wt ~ Age.MRI + Sex + Scanner + Group"
## $ sigma : num [1:156, 1:76] 0.00588 0.00585 0.00584 0.00587 0.00584 ...
## ..- attr(*, "dimnames")=List of 2
## .. ..$ : chr [1:156] "02-001-4" "02-003-2" "02-006-8" "02-008-7" ...
## .. ..$ : chr [1:76] "lcACC" "lcMFG" "lCUN" "lENT" ...
## $ wt.res: num [1:156, 1:76] 0.00142 -0.00654 0.008 0.00353 0.00795 ...
## ..- attr(*, "dimnames")=List of 2
## .. ..$ : chr [1:156] "02-001-4" "02-003-2" "02-006-8" "02-008-7" ...
## .. ..$ : chr [1:76] "lcACC" "lcMFG" "lCUN" "lENT" ...
## - attr(*, "class")= chr [1:2] "infl.bg_GLM" "list"
Although brainGraph has been developed specifically for brain MRI data, there are several functions that
will work on generic (non-brain) data. These are functions that do not make use of graph attributes such as
atlas, lobe, hemisphere, spatial coordinates, etc. Some functions require an attribute that, while not specific
to brain MRI data, do need to be added by the user; these will be marked clearly in the following list.
• fastLmBG and the other model fitting functions (see GLM Statistics)
• Matrix utilities: colMax, colMaxAbs, colMin; diag sq (simplified version of diag); is binary;
symmetrize; inv and pinv (methods for calculating matrix inverses; see ?inv )
• Functions requiring a brainGraphList object will need at least a “dummy” atlas argument, and the
gnames should match the Study.ID in the covars data table if applicable.
• brainGraph GLM and its related functions (needs name graph attribute that matches the Study.ID
column in the input covars data table)
• centr lev
• communicability
• efficiency
• hubness
• mean distance wt Calculates weighted graph or vertex average shortest path lengths
• sim.rand.graph.clust
• Rich-club functions (although rich club norm will require Group and possibly Study.ID graph attributes
if you do not supply a list of random graphs)
153
154 Chapter C: Functions for generic data
• robustness
• s core
• small.world (observed and random graphs all need Cp and Lp graph attributes)
Most functions will run quickly on just about any machine, since igraph is based on C routines. Nevertheless,
here is some benchmarking information. The more CPU cores you have, the better.
The timing of the graph algorithms is extremely fast for “small” graphs (e.g., with any atlas-based brain
parcellation), and are generally going to take either O(n) or O(m) time, where n is the # of vertices, and m is
the # of edges. The longest processing times will be Random graph generation, Bootstrapping, Permutation
Testing, and Random Failure Analysis.
All testing was done on the same system:
System Information
D.1.1 Randomise
Benchmarks for randomise are shown in Table D.1. The first section is when outcome=measure (the
default) and the second is for a different outcome (multiple design matrices). As expected, the latter case
takes longer to run.
Table D.1: Runtimes (in seconds) for randomise. These are analyses with 2 contrasts and using the
dk.scgm atlas (82 vertices). The number of permutations for each run is 1,000. Where it says
Same, it is for analyses in which outcome=measure .
When Y is very large—for example, in a graph with a very large number of vertices and/or edges—fitting
a single model is still very fast. For example, it takes on the order of 0.15 seconds to fit a model where
Y is a 101 × 64, 620 matrix (which is equal to the total number of edges possible with a 360 vertex graph,
like the HCP atlas). Furthermore, in these cases I recommend using one of the smith or draperStoneman
permutation methods as they are more efficient.
155
156 Chapter D: Benchmarks
D.1.2 NBS
Benchmarks for NBS are shown in Table D.2. This example used “raw” matrices with approximately 97%
density (3,225 edges). As you can see, for N = 5000 permutations, what previously would have taken more
than 10 minutes now takes 16 seconds.
Table D.2: Runtimes (in seconds) for NBS. These analyses were in graphs with approx. 97% density (3,225
edges).
D.1.3 Mediation
Table D.3 lists runtime for brainGraph mediate with the dk.scgm atlas (82 vertices).
Table D.3: Runtimes for vertex- and graph-level mediation for graphs with 76 vertices. These
analyses were for 101 subjects in 3 groups. Runtimes are the median of 100 repetitions in seconds.
For random graph generation, runtimes vary depending on whether or not the graph is connected, whether or
not you control for clustering, on the graph size (i.e., number of edges), and on the number of subjects/groups
(i.e., total number of graphs).
Note
These benchmarks were run on older R and igraph versions, so it’s possible these will be faster on a
similar system.
Random graph generation (control for clustering) For 1 group and 1 density (20%), generat-
ing 1,000 random graphs, total processing time was 5 min. 45 sec.. Compared to a runtime of 5
hr. 17 min. in the oldest version (which was on a machine with more and faster CPU cores), this is
approximately a 55x speed increase. (The processing time prior to v2.5.0 was about 10 minutes).
Random graph generation (control for clustering) For 2 groups and 44 densities (from 7-50%,
steps of 1%), and with 100 random graphs generated (per density per group) (i.e., 8,800 graphs), total
processing time was (estimated to be) 2 hr. 29 min.. The # of iterations per graph was limited to
100 (the default value for the max.iters argument to sim.rand.graph.clust; see Random graph
generation). Compared to a runtime of 18 hr. 33 min. in the older version (and on a machine with
more and faster CPU cores), this is a 7.5x speed increase.
• The dk.scgm atlas (82 vertices) for DTI tractography:
Random graph generation For 3 groups, 30 thresholds, and 104 subjects total, generating 100
random graphs for all combinations (i.e., 312,000 graphs) took 6 hr. 6 min.. Total disk space
used was 4.0 GB. The bulk of the increase in processing time was due to several of the thresholds
containing unconnected graphs; for the connected graphs, generating 100 random graphs for 36
subjects took between 0 min. 42 sec. – 1 min. 32 sec. per threshold.
Random graph generation For 3 groups and 30 thresholds, generating 1,000 random graphs for
all combinations (i.e., 90,000 graphs) took 2 hr. 29 min.. Total disk space used was 1.2 GB.
E
Computing environment
This document was typeset with LATEX (through the knitr package in R), using the book document class.
The main typeface is Computer Modern, designed by Donald Knuth for TEX. The bibliography was typeset
with BibTEX using the natbib package.
The following versions of R, the operating system, and R packages used include:
• RNG: Mersenne-Twister
• Normal: Inversion
• Sample: Rounding
• Matrix products: default
• BLAS/LAPACK: /usr/lib64/R/lib/libRblas.so
• Base packages: base, datasets, graphics, grDevices, methods, parallel, stats, utils
• Other packages: brainGraph 3.0.0, colorout 1.2-2, data.table 1.12.6, doMC 1.3.6, foreach 1.4.7,
ggplot2 3.2.1, gridExtra 2.3, igraph 1.2.4.1, iterators 1.0.12, knitr 1.25, microbenchmark 1.4-7,
nvimcom 0.9-83, pacman 0.5.1, permute 0.9-5, setwidth 1.0-4
• Loaded via a namespace (and not attached): abind 1.4-5, acepack 1.4.1, assertthat 0.2.1,
backports 1.1.5, base64enc 0.1-3, boot 1.3-23, checkmate 1.9.4, cluster 2.0.8, codetools 0.2-16,
colorspace 1.4-1, compiler 3.6.0, crayon 1.3.4, digest 0.6.22, doParallel 1.0.15, dplyr 0.8.3, evaluate 0.14,
foreign 0.8-71, Formula 1.2-3, ggrepel 0.8.1, glue 1.3.1, grid 3.6.0, gtable 0.3.0, highr 0.8, Hmisc 4.2-0,
htmlTable 1.13.2, htmltools 0.4.0, htmlwidgets 1.5.1, labeling 0.3, lattice 0.20-38, latticeExtra 0.6-28,
lazyeval 0.2.2, lme4 1.1-21, lpSolve 5.6.13.3, magrittr 1.5, MASS 7.3-51.4, Matrix 1.2-17,
mediation 4.5.0, minqa 1.2.4, munsell 0.5.0, mvtnorm 1.0-11, nlme 3.1-139, nloptr 1.2.1, nnet 7.3-12,
pillar 1.4.2, pkgconfig 2.0.3, purrr 0.3.3, R6 2.4.0, RColorBrewer 1.1-2, Rcpp 1.0.4, RcppEigen 0.3.3.5.0,
rlang 0.4.1, rpart 4.1-15, rstudioapi 0.10, sandwich 2.5-1, scales 1.0.0, splines 3.6.0, stringi 1.4.3,
stringr 1.4.0, survival 2.44-1.1, tibble 2.1.3, tidyselect 0.2.5, tools 3.6.0, withr 2.1.2, xfun 0.10, zoo 1.8-6
158
Bibliography
[1] Réka Albert, Hawoong Jeong, and Albert-László Barabási. Error and attack tolerance of complex
networks. Nature, 406(6794):378–382, 2000. doi:10.1515/9781400841356.503.
[2] Marti Anderson and Cajo ter Braak. Permutation tests for multi-factorial analysis of variance. Journal
of Statistical Computation and Simulation, 73(2):85–113, 2003. doi:10.1080/00949650215733. URL
https://doi.org/10.1080/00949650215733.
[3] Corson N Areshenkoff, Joseph Y Nashed, R Matthew Hutchison, Melina Hutchison, Ron Levy, Douglas J
Cook, Ravi S Menon, Stefan Everling, and Jason P Gallivan. Muting, not fragmentation, of functional
brain networks under general anesthesia. bioRxiv, pages 1–24, 2020.
[4] Shweta Bansal, Shashank Khandelwal, and Lauren A Meyers. Exploring biological network structure
with clustered random networks. BMC Bioinformatics, 10(1):405, 2009. doi:10.1186/1471-2105-10-405.
[5] Gaetano Barbagallo, Maria Eugenia Caligiuri, Gennarina Arabia, Andrea Cherubini, Angela Lupo, Rita
Nisticò, Maria Salsone, Fabiana Novellino, Maurizio Morelli, Giuseppe Lucio Cascini, et al. Structural
connectivity differences in motor network between tremor-dominant and nontremor Parkinson’s disease.
Human Brain Mapping, 38(9):4716–4729, 2017. doi:10.1002/hbm.23697.
[6] Reuben M Baron and David A Kenny. The moderator–mediator variable distinction in social psycho-
logical research: Conceptual, strategic, and statistical considerations. Journal of Personality and Social
Psychology, 51(6):1173, 1986. doi:10.1037/0022-3514.51.6.1173.
[7] Christian F Beckmann, Mark Jenkinson, and Stephen M Smith. General multilevel linear modeling for
group analysis in FMRI. NeuroImage, 20(2):1052–1063, 2003.
[9] TEJ Behrens, H Johansen Berg, Saad Jbabdi, MFS Rushworth, and MW Woolrich. Probabilistic
diffusion tractography with multiple fibre orientations: What can we gain? NeuroImage, 34(1):144–155,
2007. doi:10.1016/j.neuroimage.2006.09.018.
[10] Boris C Bernhardt, Zhang Chen, Yong He, Alan C Evans, and Neda Bernasconi. Graph-theoretical
analysis reveals disrupted small-world organization of cortical thickness correlation networks in temporal
lobe epilepsy. Cerebral Cortex, 21(9):2147–2157, 2011. doi:10.1093/cercor/bhq291.
[11] Jeremy C Biesanz, Carl F Falk, and Victoria Savalei. Assessing mediational models: testing
and interval estimation for indirect effects. Multivariate Behavioral Research, 45(4):661–701, 2010.
doi:10.1080/00273171.2010.498292.
[12] Vincent D Blondel, Jean-Loup Guillaume, Renaud Lambiotte, and Etienne Lefebvre. Fast unfolding of
communities in large networks. Journal of Statistical Mechanics: Theory and Experiment, 2008(10):
P10008, 2008. doi:10.1088/1742-5468/2008/10/P10008.
159
160 BIBLIOGRAPHY
[13] Maria Eugenia Caligiuri, Gennarina Arabia, Gaetano Barbagallo, Angela Lupo, Maurizio Morelli,
Rita Nisticò, Fabiana Novellino, Andrea Quattrone, Maria Salsone, Basilio Vescio, et al. Structural
connectivity differences in essential tremor with and without resting tremor. Journal of Neurology,
pages 1–10, 2017. doi:10.1007/s00415-017-8553-5.
[14] Qingjiu Cao, Ni Shu, Li An, Peng Wang, Li Sun, Ming-Rui Xia, Jin-Hui Wang, Gao-Lang Gong, Yu-Feng
Zang, Yu-Feng Wang, et al. Probabilistic diffusion tractography and graph theory analysis reveal abnor-
mal white matter structural connectivity networks in drug-naive boys with attention deficit/hyperactivity
disorder. Journal of Neuroscience, 33(26):10676–10687, 2013. doi:10.1523/JNEUROSCI.4793-12.2013.
[15] Matteo Cinelli, Giovanna Ferraro, and Antonio Iovanella. Rich-club ordering and the dyadic effect:
two interrelated phenomena. Physica A: Statistical Mechanics and its Applications, 490:808–818, 2018.
doi:10.1016/j.physa.2017.08.122.
[16] Vittoria Colizza, Alessandro Flammini, M Angeles Serrano, and Alessandro Vespignani. Detecting
rich-club ordering in complex networks. Nature Physics, 2(2):110–115, 2006. doi:10.1038/nphys209.
[17] Robert W Cox. AFNI: software for analysis and visualization of functional magnetic resonance
neuroimages. Computers and Biomedical Research, 29(3):162–173, 1996. doi:10.1006/cbmr.1996.0014.
[18] R Cameron Craddock, G Andrew James, Paul E Holtzheimer, Xiaoping P Hu, and Helen S Mayberg. A
whole brain fMRI atlas generated via spatially constrained spectral clustering. Human Brain Mapping,
33(8):1914–1928, 2012. doi:10.1002/hbm.21333.
[19] Jonathan J Crofts and Desmond J Higham. A weighted communicability measure applied to complex
brain networks. Journal of the Royal Society, Interface, 6(33):411–414, 2009. doi:10.1098/rsif.2008.0484.
[20] Gabor Csardi and Tamas Nepusz. The igraph software package for complex network research. Inter-
Journal, Complex Systems, 1695(5):1–9, 2006.
[21] Z Cui, S Zhong, P Xu, Y He, and G Gong. PANDA: a pipeline toolbox for analyzing brain diffusion
images. Frontiers in Human Neuroscience, 7(7):42, 2013. doi:10.3389/fnhum.2013.00042.
[22] Dina R. Dajani, Catherine A. Burrows, Mary Beth Nebel, Stewart H. Mostofsky, Kathleen M.
Gates, and Lucina Q. Uddin. Parsing heterogeneity in autism spectrum disorder and attention-
deficit/hyperactivity disorder with individual connectome mapping. Brain Connectivity, 9(9):673–
691, 2019. doi:10.1089/brain.2019.0669. URL https://doi.org/10.1089/brain.2019.0669. PMID:
31631690.
[23] Anthony Christopher Davison and David Victor Hinkley. Bootstrap methods and their application,
volume 1. Cambridge University Press, 1997. doi:10.1017/CBO9780511802843.
[24] Marcel A de Reus and Martijn P van den Heuvel. Estimating false positives and negatives in brain
networks. NeuroImage, 70:402–409, 2013. doi:10.1016/j.neuroimage.2012.12.066.
[25] Manuel Delgado-Baquerizo, Peter B Reich, Chanda Trivedi, David J Eldridge, Sebastián Abades,
Fernando D Alfaro, Felipe Bastida, Asmeret A Berhe, Nick A Cutler, Antonio Gallardo, et al. Multiple
elements of soil biodiversity drive ecosystem functions across biomes. Nature Ecology & Evolution, 4(2):
210–220, 2020.
[26] Daniel DellaPosta and Victor Nee. Emergence of diverse and specialized knowledge in a metropolitan
tech cluster. Social Science Research, 86:102377, 2020.
[28] Christophe Destrieux, Bruce Fischl, Anders Dale, and Eric Halgren. Automatic parcellation of
human cortical gyri and sulci using standard anatomical nomenclature. NeuroImage, 53(1):1–15, 2010.
doi:10.1016/j.neuroimage.2010.06.010.
[29] Nico UF Dosenbach, Binyam Nardos, Alexander L Cohen, Damien A Fair, Jonathan D Power, Jes-
sica A Church, Steven M Nelson, Gagan S Wig, Alecia C Vogel, Christina N Lessov-Schlaggar,
et al. Prediction of individual brain maturity using fMRI. Science, 329(5997):1358–1361, 2010.
doi:10.1126/science.1194144.
[30] Mark Drakesmith, Karen Caeyenberghs, A Dutt, G Lewis, AS David, and Derek K Jones. Overcoming
the effects of false positives and threshold bias in graph theoretical analyses of neuroimaging data.
NeuroImage, 118:313–333, 2015. doi:10.1016/j.neuroimage.2015.05.011.
[31] Norman R Draper and David M Stoneman. Testing for the inclusion of variables in einear regression by
a randomisation technique. Technometrics, 8(4):695–699, 1966.
[32] Stephen J Eglen, Ben Marwick, Yaroslav O Halchenko, Michael Hanke, Shoaib Sufi, Padraig Gleeson,
R Angus Silver, Andrew P Davison, Linda Lanyon, Mathew Abrams, et al. Toward standard practices
for sharing computer code and programs in neuroscience. Nature Neuroscience, 20(6):770–773, 2017.
doi:10.1038/nn.4550.
[33] Marius Eidsaa and Eivind Almaas. S-core network decomposition: a generalization of k-core analysis
to weighted networks. Physical Review E, 88(6):062819, 2013. doi:10.1103/PhysRevE.88.062819.
[34] Ernesto Estrada and Naomichi Hatano. Communicability in complex networks. Physical Review E, 77
(3):036111, 2008. doi:10.1103/PhysRevE.77.036111.
[35] Ernesto Estrada, Desmond J Higham, and Naomichi Hatano. Communicability betweenness in
complex networks. Physica A: Statistical Mechanics and its Applications, 388(5):764–774, 2009.
doi:10.1016/j.physa.2008.11.011.
[36] Carl F Falk and Jeremy C Biesanz. Two cross-platform programs for inferences and interval es-
timation about indirect effects in mediational models. SAGE Open, 6(1):2158244015625445, 2016.
doi:10.1177/2158244015625445.
[37] Lingzhong Fan, Hai Li, Junjie Zhuo, Yu Zhang, Jiaojian Wang, Liangfu Chen, Zhengyi Yang, Congying
Chu, Sangma Xie, Angela R Laird, et al. The human brainnetome atlas: a new brain atlas based on
connectional architecture. Cerebral Cortex, 26(8):3508–3526, 2016. doi:10.1093/cercor/bhw157.
[38] Maria Feldmann, Ting Guo, Steven P Miller, Walter Knirsch, Raimund Kottke, Cornelia Hagmann,
Beatrice Latal, and Andras Jakab. Delayed maturation of the structural brain connectome in neonates
with congenital heart disease. bioRxiv, pages 1–17, 2020.
[39] Alex Fornito, Andrew Zalesky, and Edward Bullmore. Fundamentals of Brain Network Analysis.
Academic Press, 2016. ISBN 9780124081185.
[40] David Freedman and David Lane. A nonstochastic interpretation of reported significance levels. Journal
of Business and Economic Statistics, 1(4):292–298, 1983. doi:10.1080/07350015.1983.10509354. URL
https://www.tandfonline.com/doi/abs/10.1080/07350015.1983.10509354.
[41] Thomas MJ Fruchterman and Edward M Reingold. Graph drawing by force-directed placement. Softw.,
Pract. Exper., 21(11):1129–1164, 1991. doi:10.1002/spe.4380211102.
[42] Matthew F Glasser, Timothy S Coalson, Emma C Robinson, Carl D Hacker, John Harwell, Essa Yacoub,
Kamil Ugurbil, Jesper Andersson, Christian F Beckmann, Mark Jenkinson, et al. A multi-modal
parcellation of human cerebral cortex. Nature, 536(7615):171–178, 2016.
[43] Gaolang Gong, Pedro Rosa-Neto, Felix Carbonell, Zhang J Chen, Yong He, and Alan C Evans. Age-
and gender-related differences in the cortical anatomical network. Journal of Neuroscience, 29(50):
15684–15693, 2009. doi:10.1523/JNEUROSCI.2308-09.2009.
162 BIBLIOGRAPHY
[44] Evan M Gordon, Timothy O Laumann, Babatunde Adeyemo, Jeremy F Huckins, William M Kelley,
and Steven E Petersen. Generation and evaluation of a cortical area parcellation from resting-state
correlations. Cerebral Cortex, 26(1):288–303, 2016. doi:10.1093/cercor/bhu239.
[45] Roger Guimera and Luis A Nunes Amaral. Functional cartography of complex metabolic networks.
Nature, 433(7028):895–900, 2005. doi:10.1038/nature03288.
[46] Irwin Guttman. Linear Models: an Introduction. Krieger Pub Co, 1982.
[47] MohammadHossein Manuel Haqiqatkhah and Cees van Leeuwen. Adaptive rewiring in non-uniform
coupled oscillators. PsyArXiv, pages 1–45, 2020.
[48] Yong He, Zhang Chen, and Alan Evans. Structural insights into aberrant topological patterns of
large-scale cortical networks in alzheimer’s disease. Journal of Neuroscience, 28(18):4756–4766, 2008.
[49] Markus Hirschberger, Yue Qi, and Ralph E Steuer. Randomly generating portfolio-selection covariance
matrices with specified distributional characteristics. European Journal of Operational Research, 177
(3):1610–1625, 2007.
[50] Paul W Holland. Statistics and causal inference. Journal of the American Statistical Association, 81
(396):945–960, 1986.
[51] Petter Holme, Beom Jun Kim, Chang No Yoon, and Seung Kee Han. Attack vulnerability of complex
networks. Physical Review E, 65(5):056109, 2002. doi:10.1103/PhysRevE.65.056109.
[52] Philipp Homan, Miklos Argyelan, Pamela DeRosse, Philip Szeszko, Juan A Gallego, Lauren Hanna,
Delbert Robinson, John M Kane, Todd Lencz, and Anil K Malhotra. Structural similarity net-
works predict clinical outcome in early-phase psychosis. Neuropsychopharmacology, 0:1–33, 2019.
doi:10.1038/s41386-019-0322-y. URL https://doi.org/10.1038/s41386-019-0322-y.
[53] SM Hadi Hosseini and Shelli R Kesler. Influence of choice of null network on small-world parameters of
structural correlation networks. PLoS One, 8(6):e67354, 2013. doi:10.1371/journal.pone.0067354.
[54] SM Hadi Hosseini, Fumiko Hoeft, and Shelli R Kesler. GAT: a graph-theoretical analysis toolbox for
analyzing between-group differences in large-scale structural and functional brain networks. PloS One,
7(7):e40709, 2012. doi:10.1371/journal.pone.0040709.
[55] Mark D Humphries and Kevin Gurney. Network ’small-world-ness’: a quantitative method for determin-
ing canonical network equivalence. PLoS One, 3(4):e0002051, 2008. doi:10.1371/journal.pone.0002051.
[56] Kosuke Imai, Luke Keele, and Dustin Tingley. A general approach to causal mediation analysis.
Psychological Methods, 15(4):309, 2010. doi:10.1037/a0020761.
[57] Kosuke Imai, Luke Keele, and Teppei Yamamoto. Identification, inference and sensitivity analysis for
causal mediation effects. Statistical Science, 25(1):51–71, 2010. doi:10.1214/10-STS321.
[58] Kosuke Imai, Luke Keele, Dustin Tingley, and Teppei Yamamoto. Unpacking the black box of causality:
learning about causal mechanisms from experimental and observational studies. American Political
Science Review, 105(4):765–789, 2011. doi:10.1017/S0003055411000414.
[59] Amy C Janes, Maya Zegel, Kyoko Ohashi, Jennifer Betts, Elena Molokotos, David Olson, Lauren Moran,
and Diego A Pizzagalli. Nicotine normalizes cortico-striatal connectivity in non-smoking individuals
with major depressive disorder. Neuropsychopharmacology, page 1, 2018. doi:10.1038/s41386-018-0069-x.
[60] Saad Jbabdi, MW Woolrich, JLR Andersson, and TEJ Behrens. A bayesian framework for global
tractography. NeuroImage, 37(1):116–129, 2007. doi:10.1016/j.neuroimage.2007.04.039.
[61] Mark Jenkinson, Christian F Beckmann, Timothy EJ Behrens, Mark W Woolrich, and Stephen M
Smith. FSL. NeuroImage, 62(2):782–790, 2012. doi:10.1016/j.neuroimage.2011.09.015.
BIBLIOGRAPHY 163
[62] Karen E Joyce, Paul J Laurienti, Jonathan H Burdette, and Satoru Hayasaka. A new measure of
centrality for brain networks. PLoS One, 5(8):e12200, 2010. doi:10.1371/journal.pone.0012200.
[63] David Kaufman and Robert Sweet. Contrast coding in least squares regression analysis. American
Educational Research Journal, 11(4):359–377, 1974. doi:10.2307/1162790.
[64] Luke Keele. Causal mediation analysis: warning! Assumptions ahead. American Journal of Evaluation,
36(4):500–513, 2015. doi:10.1177/1098214015594689.
[65] Daniel J King, Stefano Seri, Richard Beare, Cathy Catroppa, Vicki A Anderson, and Amanda G Wood.
Developmental divergence of structural brain networks as an indicator of future cognitive impairments
in childhood brain injury: executive functions. Developmental Cognitive Neuroscience, page 100762,
2020.
[66] Arno Klein and Jason Tourville. 101 labeled brain images and a consistent human cortical labeling
protocol. Frontiers in Neuroscience, 6, 2012. doi:10.3389/fnins.2012.00171.
[67] Eric D. Kolaczyk. Statistical Analysis of Network Data. Springer Series in Statistics. Springer-Verlag
New York, 2009. ISBN 978-0-387-88146-1. doi:10.1007/978-0-387-88146-1.
[68] Eric D Kolaczyk and Gábor Csárdi. Statistical analysis of network data with R, volume 65. Springer,
2014. doi:10.1007/978-0-387-88146-1.
[69] Marsh Königs, LW van Heurn, Roel Bakx, R Jeroen Vermeulen, J Carel Goslings, Bwee Tien Poll-The,
Marleen van der Wees, Coriene E Catsman-Berrevoets, Jaap Oosterlaan, and Petra JW Pouwels. The
structural connectome of children with traumatic brain injury. Human Brain Mapping, 38(7):3603–3614,
2017. doi:10.1002/hbm.23614.
[70] Michael H Kutner, Chris Nachtsheim, John Neter, and William Li. Applied linear statistical models.
McGraw-Hill Irwin, 2005. doi:10.2307/1271154.
[71] Athen Ma and Raúl J Mondragón. Rich-cores in networks. PloS One, 10(3):e0119678, 2015.
doi:10.1371/journal.pone.0119678.
[72] Jennifer K MacCormack, Andrea G Stein, Jian Kang, Kelly S Giovanello, Ajay B Satpute, and Kristen A
Lindquist. Affect in the aging brain: a neuroimaging meta-analysis of older vs. younger adult affective
experience and perception. Affective Science, pages 1–27, 2020.
[73] Patrick Mair. Analysis of fMRI Data. Springer International Publishing, Cham, 2018. ISBN 978-3-319-
93177-7. doi:10.1007/978-3-319-93177-7 14. URL https://doi.org/10.1007/978-3-319-93177-7_
14.
[74] Nikos Makris, Jill M Goldstein, David Kennedy, Steven M Hodge, Verne S Caviness, Stephen V Faraone,
Ming T Tsuang, and Larry J Seidman. Decreased volume of left and total anterior insular lobule in
schizophrenia. Schizophrenia Research, 83(2):155–171, 2006. doi:10.1016/j.schres.2005.11.020.
[75] Anvita Gupta Malhotra, Sudha Singh, Mohit Jha, and Khushhali Menaria Pandey. A parametric tar-
getability evaluation approach for vitiligo proteome extracted through integration of gene ontologies and
protein interaction topologies. IEEE/ACM Transactions on Computational Biology and Bioinformatics,
pages 1–14, 2018. ISSN 1545-5963. doi:10.1109/TCBB.2018.2835459.
[76] Irengbam Rocky Mangangcha, Md Zubbair Malik, Ömer Küçük, Shakir Ali, and RK Brojen Singh.
Identification of key regulators in prostate cancer from gene expression datasets of patients. bioRxiv,
page 643643, 2019.
[77] Bryan FJ Manly. Randomization and regression methods for testing for associations with geographical,
environmental and biological distances between populations. Population Ecology, 28(2):201–218, 1986.
[78] R Milo, N Kashtan, S Itzkovitz, MEJ Newman, and U Alon. On the uniform generation of random
graphs with prescribed degree sequences. eprint arXiv:cond-mat/0312028, 2003.
164 BIBLIOGRAPHY
[79] Mark Newman. Networks: An Introduction. Oxford University Press, 2010. ISBN 0199206651.
doi:10.1093/acprof:oso/9780199206650.001.0001.
[80] Thomas E Nichols and Andrew P Holmes. Nonparametric permutation tests for functional neuroimaging:
a primer with examples. Human Brain Mapping, 15(1):1–25, 2002. doi:10.1002/hbm.1058.
[81] William Stafford Noble. A quick guide to organizing computational biology projects. PLoS Computational
Biology, 5(7):e1000424, 2009. doi:10.1371/journal.pcbi.1000424.
[82] Kyoko Ohashi, Carl M. Anderson, Elizabeth A. Bolger, Alaptagin Khan, Cynthia E. McGreenery,
and Martin H. Teicher. Susceptibility or resilience to maltreatment can be explained by specific
differences in brain network architecture. Biological Psychiatry, 85(8):690–702, 2019. ISSN 0006-3223.
doi:https://doi.org/10.1016/j.biopsych.2018.10.016. URL http://www.sciencedirect.com/science/
article/pii/S0006322318319784.
[83] Agustı́n Ostachuk. What is it like to be a crab? a complex network analysis of eucaridan evolution.
Evolutionary Biology, 46(2):179–206, 2019.
[84] John E Overall and Douglas K Spiegel. Concerning least squares analysis of experimental data.
Psychological Bulletin, 72(5):311, 1969. doi:10.1037/h0028109.
[85] Dimitrios Pantazis, Anand Joshi, Jintao Jiang, David W Shattuck, Lynne E Bernstein, Hanna Damasio,
and Richard M Leahy. Comparison of landmark-based and automatic methods for cortical surface
registration. NeuroImage, 49(3):2479–2493, 2010. doi:10.1016/j.neuroimage.2009.09.027.
[86] Jonathan D Power, Alexander L Cohen, Steven M Nelson, Gagan S Wig, Kelly Anne Barnes, Jessica A
Church, Alecia C Vogel, Timothy O Laumann, Fran M Miezin, Bradley L Schlaggar, et al. Functional net-
work organization of the human brain. Neuron, 72(4):665–678, 2011. doi:10.1016/j.neuron.2011.09.006.
[87] Kristopher J Preacher. Advances in mediation analysis: a survey and synthesis of new developments.
Annual Review of Psychology, 66:825–852, 2015. doi:10.1146/annurev-psych-010814-015258.
[88] Arnau Ramos-Prats, Julia Kölldorfer, Elena Paolo, Maximilian Zeidler, Gabriele Schmid, and
Francesco Ferraguti. An appraisal of the influence of the metabotropic glutamate 5 (mGlu5) re-
ceptor on sociability and anxiety. Frontiers in Molecular Neuroscience, 12:30, 2019. ISSN 1662-5099.
doi:10.3389/fnmol.2019.00030. URL https://www.frontiersin.org/article/10.3389/fnmol.2019.
00030.
[89] Neda Rashidi-Ranjbar, Tarek K Rajji, Sanjeev Kumar, Nathan Herrmann, Linda Mah, Alastair J
Flint, Corrine E Fischer, Meryl A Butters, Bruce G Pollock, Erin W Dickie, et al. Frontal-executive
and corticolimbic structural brain circuitry in older people with remitted depression, mild cognitive
impairment, Alzheimer’s dementia, and normal cognition. Neuropsychopharmacology, pages 1–14, 2020.
[90] Jaideep Ray, Ali Pinar, and Comandur Seshadhri. Are we there yet? When to stop a Markov chain while
generating random graphs. In International Workshop on Algorithms and Models for the Web-Graph,
pages 153–164. Springer, 2012. doi:10.1007/978-3-642-30541-2 12.
[91] Jonas Richiardi, Andre Altmann, Anna-Clare Milazzo, Catie Chang, M Mallar Chakravarty, Tobias
Banaschewski, Gareth J Barker, Arun LW Bokde, Uli Bromberg, Christian Büchel, et al. Correlated
gene expression supports synchronous activity in brain networks. Science, 348(6240):1241–1244, 2015.
doi:10.1126/science.1255905.
[92] Sally Richmond, Richard Beare, Katherine A. Johnson, Nicholas B. Allen, Marc L. Seal, and Sarah
Whittle. Structural covariance networks in children and their associations with maternal behaviors.
NeuroImage, 202:115965, 2019. ISSN 1053-8119. doi:https://doi.org/10.1016/j.neuroimage.2019.06.043.
URL http://www.sciencedirect.com/science/article/pii/S1053811919305403.
[93] Gerard Robert Ridgway. Statistical analysis for longitudinal MR imaging of dementia. PhD thesis,
UCL (University College London), 2009.
BIBLIOGRAPHY 165
[94] James A Roberts, Alistair Perry, Gloria Roberts, Philip B Mitchell, and Michael Breakspear.
Consistency-based thresholding of the human connectome. NeuroImage, 145:118–129, 2017.
doi:10.1016/j.neuroimage.2016.09.053.
[95] James M Robins and Sander Greenland. Identifiability and exchangeability for direct and indirect
effects. Epidemiology, pages 143–155, 1992. doi:10.1097/00001648-199203000-00013.
[96] ET Rolls, Marc Joliot, and Nathalie Tzourio-Mazoyer. Implementation of a new parcellation of
the orbitofrontal cortex in the automated anatomical labelling atlas. NeuroImage, 122:1–5, 2015.
doi:10.1016/j.neuroimage.2015.07.075.
[97] Donald B Rubin. Estimating causal effects of treatments in randomized and nonrandomized studies.
Journal of Educational Psychology, 66(5):688, 1974. doi:10.1037/h0037350.
[98] Donald B Rubin. Bayesian inference for causal effects: the role of randomization. The Annals of
Statistics, pages 34–58, 1978. doi:10.1214/aos/1176344064.
[99] Valentina Saba, Enrico Premi, Viviana Cristillo, Stefano Gazzina, Fernando Palluzzi, Orazio Zanetti,
Roberto Gasparotti, Alessandro Padovani, Barbara Borroni, and Mario Grassi. Brain connectivity
and information-flow breakdown revealed by a minimum spanning tree-based analysis of MRI data in
behavioral variant frontotemporal dementia. Frontiers in Neuroscience, 13:211, 2019. ISSN 1662-453X.
doi:10.3389/fnins.2019.00211. URL https://www.frontiersin.org/article/10.3389/fnins.2019.
00211.
[100] Manish Saggar, SM Hadi Hosseini, Jennifer L Bruno, Eve-Marie Quintin, Mira M Raman, Shelli R
Kesler, and Allan L Reiss. Estimating individual contribution from group-based structural correlation
networks. NeuroImage, 120:274–284, 2015. doi:10.1016/j.neuroimage.2015.07.006.
[101] Mohammed Saqr, Jalal Nouri, Henriikka Vartiainen, and Matti Tedre. Robustness and rich clubs in
collaborative learning groups: a learning analytics study using network science. Scientific Reports, 10
(1):1–16, 2020.
[102] Alexander Schaefer, Ru Kong, Evan M Gordon, Timothy O Laumann, Xi-Nian Zuo, Avram J Holmes,
Simon B Eickhoff, and BT Yeo. Local-global parcellation of the human cerebral cortex from intrinsic
functional connectivity MRI. Cerebral Cortex, pages 1–20, 2017. doi:10.1093/cercor/bhx179.
[103] Lianne H Scholtens, Marcel A de Reus, Siemon C de Lange, Ruben Schmidt, and Mar-
tijn P van den Heuvel. An mri von economo–koskinas atlas. NeuroImage, 170:249–256, 2018.
doi:10.1016/j.neuroimage.2016.12.069.
[104] Ronald C Serlin and Joel R Levin. Teaching how to derive directly interpretable coding schemes for
multiple regression analysis. Journal of Educational Statistics, 10(3):223–238, 1985. doi:10.2307/1164794.
[105] David W Shattuck and Richard M Leahy. Brainsuite: an automated cortical surface identification tool.
Medical Image Analysis, 6(2):129–142, 2002. doi:10.1016/S1361-8415(02)00054-3.
[106] David W Shattuck, Mubeena Mirza, Vitria Adisetiyo, Cornelius Hojatkashani, Georges Salamon,
Katherine L Narr, Russell A Poldrack, Robert M Bilder, and Arthur W Toga. Construction
of a 3d probabilistic atlas of human cortical structures. NeuroImage, 39(3):1064–1080, 2008.
doi:10.1016/j.neuroimage.2007.09.031.
[107] Xilin Shen, F Tokoglu, Xenios Papademetris, and R Todd Constable. Groupwise whole-brain parcel-
lation from resting-state fMRI data for network node identification. NeuroImage, 82:403–415, 2013.
doi:10.1016/j.neuroimage.2013.05.081.
[108] Stephen Smith, Mark Jenkinson, Christian Beckmann, Karla Miller, and Mark Woolrich.
Meaningful design and contrast estimability in FMRI. NeuroImage, 34(1):127–136, 2007.
doi:10.1016/j.neuroimage.2006.09.019.
166 BIBLIOGRAPHY
[109] AW Still and AP White. The approximate randomization test as an alternative to the F test in analysis
of variance. British Journal of Mathematical and Statistical Psychology, 34(2):243–252, 1981.
[110] Toshiyuki Tanimizu, Justin W Kenney, Emiko Okano, Kazune Kadoma, Paul W Frankland, and Satoshi
Kida. Functional connectivity of multiple brain regions required for the consolidation of social recognition
memory. Journal of Neuroscience, 37(15):4103–4116, 2017. doi:10.1523/JNEUROSCI.3451-16.2017.
[111] Martin H Teicher, Kyoko Ohashi, and Alaptagin Khan. Additional insights into the relationship between
brain network architecture and susceptibility and resilience to the psychiatric sequelae of childhood
maltreatment. Adversity and Resilience Science, 1:49–64, 2020.
[112] Qawi K Telesford, Karen E Joyce, Satoru Hayasaka, Jonathan H Burdette, and Paul J Laurienti. The
ubiquity of small-world networks. Brain Connectivity, 1(5):367–375, 2011. doi:10.1089/brain.2011.0038.
[113] Dustin Tingley, Teppei Yamamoto, Kentaro Hirose, Luke Keele, and Kosuke Imai. mediaton: R package
for causal mediation analysis. Journal of Statistical Software, 59(5):1–38, 2014. doi:10.18637/jss.v059.i05.
[114] Basant K Tiwary. Computational medicine: quantitative modeling of complex diseases. Briefings in
Bioinformatics, 0:1–12, 01 2019. ISSN 1477-4054. doi:10.1093/bib/bbz005. URL https://doi.org/10.
1093/bib/bbz005.
[115] Nathalie Tzourio-Mazoyer, Brigitte Landeau, Dimitri Papathanassiou, Fabrice Crivello, Olivier Etard,
Nicolas Delcroix, Bernard Mazoyer, and Marc Joliot. Automated anatomical labeling of activations in
SPM using a macroscopic anatomical parcellation of the MNI MRI single-subject brain. NeuroImage,
15(1):273–289, 2002. doi:10.1006/nimg.2001.0978.
[116] Martijn van den Heuvel, Siemon de Lange, Andrew Zalesky, Caio Seguin, Thomas Yeo, and Ruben
Schmidt. Proportional thresholding in resting-state fMRI functional connectivity networks and con-
sequences for patient-control connectome studies: Issues and recommendations. NeuroImage, 2017.
doi:10.1016/j.neuroimage.2017.02.005.
[117] Martijn P. van den Heuvel, René C. W. Mandl, Cornelis J. Stam, René S. Kahn, and Hilleke E.
Hulshoff Pol. Aberrant frontal and temporal complex network structure in schizophrenia: a
graph theoretical analysis. Journal of Neuroscience, 30(47):15915–15926, 2010. ISSN 0270-6474.
doi:10.1523/JNEUROSCI.2874-10.2010. URL http://www.jneurosci.org/content/30/47/15915.
[118] Estefania Ruiz Vargas, Lindi M Wahl, et al. The gateway coefficient: a novel metric for identify-
ing critical connections in modular networks. The European Physical Journal B, 87(7):1–10, 2014.
doi:10.1140/epjb/e2014-40800-7.
[119] W. N. Venables and B. D. Ripley. Modern Applied Statistics with S. Springer, New York, fourth
edition, 2002. doi:10.1007/978-0-387-21706-2. URL http://www.stats.ox.ac.uk/pub/MASS4. ISBN
0-387-95457-0.
[120] Umesh M Venkatesan and Frank G Hillary. Functional connectivity within lateral posterior parietal
cortex in moderate to severe traumatic brain injury. Neuropsychology, 33(6):893, 2019.
[121] Fabien Viger and Matthieu Latapy. Efficient and simple generation of random simple con-
nected graphs with prescribed degree sequence. Journal of Complex Networks, 4(1):15–37, 2016.
doi:10.1093/comnet/cnv013.
[122] Defeng Wang, Lin Shi, Shangping Liu, Steve CN Hui, Yongjun Wang, Jack CY Cheng, and Winnie CW
Chu. Altered topological organization of cortical network in adolescent girls with idiopathic scoliosis.
PLoS One, 8:83767, 2013. doi:10.1371/journal.pone.0083767.
[123] Ruopeng Wang, Thomas Benner, Alma Gregory Sorensen, and Van Jay Wedeen. Diffusion toolkit: a
software package for diffusion imaging data processing and tractography. In Proc Intl Soc Mag Reson
Med, volume 15. Berlin, 2007.
BIBLIOGRAPHY 167
[124] Christopher G. Watson, Christian Stopp, Jane W. Newburger, and Michael J. Rivkin. Graph theory
analysis of cortical thickness networks in adolescents with d-transposition of the great arteries. Brain
and Behavior, 8(2):e00834, 2018. ISSN 2162-3279. doi:10.1002/brb3.834. URL http://dx.doi.org/
10.1002/brb3.834.
[125] Christopher G. Watson, Dana DeMaster, and Linda Ewing-Cobbs. Graph theory analysis of DTI
tractography in children with traumatic injury. NeuroImage. Clinical, 21:101673, 2019. ISSN 2213-
1582. doi:10.1016/j.nicl.2019.101673. URL http://www.sciencedirect.com/science/article/pii/
S2213158219300233.
[126] Duncan J Watts and Steven H Strogatz. Collective dynamics of ”small-world” networks. Nature, 393
(6684):440–442, 1998. doi:10.1515/9781400841356.301.
[127] Hadley Wickham. Tidy data. Journal of Statistical Software, 59(10), 2014. doi:10.18637/jss.v059.i10.
[128] Ben James Winer, Donald R Brown, and Kenneth M Michels. Statistical principles in experimental
design, volume 2. McGraw-Hill New York, 1971. doi:10.2307/3172747.
[129] Anderson M Winkler, Gerard R Ridgway, Matthew A Webster, Stephen M Smith, and Thomas E
Nichols. Permutation inference for the general linear model. NeuroImage, 92:381–397, 2014.
doi:10.1016/j.neuroimage.2014.01.060.
[130] Mingrui Xia, Jinhui Wang, Yong He, et al. Brainnet viewer: a network visualization tool for human
brain connectomics. PLoS One, 8(7):e68910, 2013. doi:10.1371/journal.pone.0068910.
[131] Yihui Xie. Dynamic Documents with R and knitr. Chapman and Hall/CRC, Boca Raton, Florida, 2nd
edition, 2015. doi:10.1201/b15166. URL http://yihui.name/knitr/. ISBN 978-1498716963.
[132] Chao-Gan Yan and Yu-Feng Zang. DPARSF: a MATLAB toolbox for ”pipeline” data analysis of
resting-state fMRI. Frontiers in Systems Neuroscience, 4:13, 2010. doi:10.3389/fnsys.2010.00013.
[133] Andrew Zalesky, Alex Fornito, and Edward T Bullmore. Network-based statistic: identifying differences
in brain networks. NeuroImage, 53(4):1197–1207, 2010. doi:10.1016/j.neuroimage.2010.06.041.
[134] Andrew Zalesky, Alex Fornito, and Ed Bullmore. On the use of correlation as a measure of network
connectivity. NeuroImage, 60(4):2096–2106, 2012. doi:10.1016/j.neuroimage.2012.02.001.
[135] Shi Zhou and Raúl J Mondragón. The rich-club phenomenon in the internet topology. IEEE Commu-
nications Letters, 8(3):180–182, 2004. doi:10.4018/978-1-59140-993-9.ch066.