A set of tools for performing graph theory analysis of brain MRI data. It works with data from a Freesurfer analysis (cortical thickness, volumes, local gyrification index, surface area), diffusion tensor tractography data (e.g., from FSL) and resting-state fMRI data (e.g., from DPABI). It contains a graphical user interface for graph visualization and data exploration, along with several functions for generating useful figures.
2018-05-28
RGtk2
and cairoDevice
to Suggests (from Depends) to allow installation on headless servers
@michaelhallquist
for the pull request!boot_global
, permute.group
, and plot_group_means
are no longer accessible (deprecated since v2.0.0)2018-05-03 (mostly changes to structural covariance network functionality)
mtpc
that was introduced in v2.0.1
brainGraph_GLM_design
has a new argument factorize
which specifies whether or not to convert all character columns (excluding Study.ID) to factor variables. The default is TRUE
. Previously, character columns were ignored.get.resid
method
argumentplot
method now returns a list of ggplot objects, and is similar to the plot
methods for bg_GLM
and mtpc
corr.matrix
resids
argument must be the output of get.resid
(not a data.table as before)get.resid
); you no longer need to loop (or lapply
) across groupswhat
argumentexclusions
argument was renamed to exclude.reg
to highlight that you should specify region names to be excluded (if any)type
argument (previously, this behavior was "hidden")brainGraph_init
: the modality
argument now will accept any character string; the default is still thickness. The files with the string you supply still must be present on your system.corr.matrix
expecting different input, the following functions also require, for their resids
argument, the output of get.resid
(instead of a data.table):
aop
brainGraph_boot
brainGraph_permute
loo
2018-04-28
gateway_coeff
: no longer throws an error for very sparse graphs; instead, it returns a vector with NaN
values for unconnected verticesmake_mediate_brainGraph
: did not return correct values (for the treatment condition) when INT=TRUE
(it recycled the values for the control condition)make_intersection_brainGraph
subgraph
conditionsubgraph
conditionNBS
:
alt='greater'
summary
method contained an errorsummary
methods now provide a DT.sum
element in the returned list; previously it was inconsistent2018-04-26
mtpc
, the stats table that is returned previously was not always uniquemtpc
did not return a list with a named element clust.size
(it was unnamed)plot.mtpc
, if the user selected a contrast other than the first, it would not plot the correct null statistics (green dots)2018-02-23
Release on CRAN; bugfix release.
create_mats
in which the ordering (along the 3rd dimension) of the arrays in A.norm.sub
did not match the ordering of the input matrix files (and therefore the ordering along the 3rd dimension of the arrays A
and A.norm
).
groups <- c('Control', 'Patient')
, and the matrix files are separated on the filesystem by group, there is no change in behavior.threshold.by='consistency'
or threshold.by='consensus'
(the default option).2018-02-07
mtpc
when creating the MTPC statistics data.table
2018-02-05
2nd major release; 6th CRAN release. (The previous CRAN release was at v1.0.0)
For other updates and bug fixes, see the minor release notes below.
brainGraph_mediate
.plot
(except NBS
) and summary
methods.
The classes and corresponding "creation functions" are:Class | Creation func. | Description |
---|---|---|
brainGraph | make_brainGraph | Any graph with certain attributes |
bg_GLM | brainGraph_GLM | Results of GLM analysis |
NBS | NBS | Results of NBS analysis |
mtpc | mtpc | Results of MTPC analysis |
brainGraph_GLM | make_glm_brainGraph | Graphs from GLM analysis |
brainGraph_NBS | make_nbs_brainGraph | Graphs from NBS analysis |
brainGraph_mtpc | make_glm_brainGraph | Graphs from MTPC analysis |
brainGraph_mediate | make_mediate_brainGraph | Graphs from mediation analysis |
brainGraph_boot | brainGraph_boot | Results of bootstrap analysis |
brainGraph_permute | brainGraph_permute | Results of permutation tests |
brainGraph_resids | get.resid | Residuals for covariance networks |
brainGraph_GLM
, mtpc
, NBS
, and get.resid
.
con.type
, for this purpose.con.vec
has been replaced by con.mat
.2 x 2 x 2
) are now allowed for GLM-based analyses.plot.bg_GLM
method to the output of brainGraph_GLM
.plot.mtpc
method for mtpc
results.aop
has a new argument control.value
allowing you to specify the control group; all comparisons will be to that group.
long
, which will not return all of the permutation results if long=FALSE
.boot_global
was renamed to brainGraph_boot
.check.resid
was removed; you now just call the plot
method to outputs of get.resid
.permute.group
:
brainGraph_permute
.permSet
was renamed to perms
.auc
lets you explicitly define whether or not you want statistics for the area under the curve (AUC).plot_boot
was removed; you now just call the plot
method to outputs of brainGraph_boot
.plot_brainGraph_mni
has been removed; this functionality can be changed by the mni
argument to plot.brainGraph
(i.e., the plot method for objects of class brainGraph
)plot_group_means
was renamed to plot_volumetric
, as it works specifically for structural covariance networks.plot_perm_diffs
was removed; you now just call the plot
method to outputs of brainGraph_permute
.NBS
now automatically symmetrizes the input matrices. This is partly for speed and partly because igraph
symmetrizes the matrices anyway.
symm.by
(which is the same as that for create_mats
) for this purpose.corr.matrix
:
get.resid
.densities
(or thresholds
),r.thresh
).get.resid
now allows for any design matrix for getting LM residuals (similar to brainGraph_GLM
).
data.table
of covariates.brainGraph_GLM_design
for creating the correct design matrix.mtpc
accepts 2 new arguments (in addition to explicitly naming required arguments that pass on to brainGraph_GLM
):
clust.size
lets you change the "cluster size", the number of consecutive thresholds needed to deem a result significant (default: 3
)res.glm
lets you input the res.glm
list element from a previous mtpc
run. This is only useful if you would like to compare results with different values for clust.size
.permute.group
(see above section for changes)rich_club_norm
now returns a data.table
, which simplifies working with the data (and plotting).set_brainGraph_attr
: multiple (explicit) arguments were removed; these are now passed on to make_brainGraph
and can still be specified in the function call.ggrepel
package for any ggplot
objects with text labels.2017-09-14
brainGraph_init
: fixed bug regarding the use of a custom atlasg
to g.list
if the function requires a list object).brainGraph_init
:
custom.atlas
allows you to use an atlas that is not in the package (you must also specify atlas="custom"
).data.table
, and have columns name, x.mni, y.mni, z.mni, lobe, hemi (at a minimum).permute.group
: can now calculate ev.cent
2017-08-31
boot_global
: fixed bug in modularity calculationboot_global
:
.progress=FALSE
)measure
measure
(strength, mod.wt, E.global.wt)conf
argument (default: 0.95)set_brainGraph_attr
:
xfm.type
, which allows you to choose how edge weights should be transformed for calculating distance-based metrics.1-w
(subtract weights from 1); and -log(w)
(take the negative natural logarithm of weights).symmetrize_array
: a convenience function that applies symmetrize_mats
along the third dimension of an arrayxfm.weights
: utility function to transform edge weights (necessary when calculating distance-based metrics).graph_attr_dt
and vertex_attr_dt
will now include weighting
, if presentset_brainGraph_attr
has 2 new arguments:
weighting
will create a graph-level attribute indicating how the edges are weighted (e.g., 'fa' for FA-weighted tractography networks)threshold
will create a graph-level attribute indicating the (numeric) threshold used to create the network (if applicable)2017-06-10
mtpc
: fixed a bug that would incorrectly calculate A.crit
apply_thresholds
: threshold an additional set of matrices (e.g., FA-weighted matrices in DTI tractography) based on a set of matrices that have already been thresholded (e.g., streamline-weighted matrices in DTI tractography)analysis_random_graphs
: no longer requires a covars argument2017-04-30
create_mats
threshold.by='density'
. Previously, it would keep the top X% for each subjectcreate_mats
threshold.by='consensus'
is the name of the new default, as this is what is called "consensus-based" thresholding in the literature.threshold.by='consistency'
is a new option, for performing consistency-based thresholding. See Roberts et al., 2017.set_brainGraph_attr
no longer calculates the graph's clique number, which takes exceedingly long in denser and/or larger graphs (e.g., craddock200
)2017-04-29
plot_brainGraph
: now returns NA
(instead of throwing an error) if the specified subgraph expression results in a network with 0 vertices.edge_asymmetry
fixed bug when the input graph had only one contralateral connection (usually only encountered in the GUI with neighborhood plots)create_mats
: you can specify threshold.by='mean'
, which will threshold the matrices such that a connection will be kept if mean(A_ij) + 2*sd(A_ij) > mat.thresh
, for each of mat.thresh
.make_empty_brainGraph
: this is not a new function, but rather was not exported in previous versionss_core
: calculate the s-core membership of a graph's vertices (Eidsaa & Almaas, 2013)
s.core
to the graph through set_brainGraph_attr
.coreness
to k.core
to distinguish these metrics.2017-04-22
plot_brainGraph_gui
had multiple issues and a few features have been changed:
Ctrl
and clicking, or by holding Shift
and moving the arrow keysgateway_coeff
returned an error if the number of communities equals 1; this has been fixedcentr_betw_comm
: calculate vertex communicability betweenness centrality (Estrada et al., 2009)communicability
: calculate network communicability (Estrada & Hatano, 2008)mtpc
: the multi-threshold permutation correction (MTPC) method for statistical inference of either vertex- or graph-level measures (Drakesmith et al., 2015)symmetrize_mats
: symmetrize a connectivity matrix by either the maximum, minimum, or average of the off-diagonal elements. You may select one of these as an argument to create_mats
.brainGraph_GLM
has 2 new function arguments:
level
allows you to perform inference for graph- or vertex-level measuresperms
lets you specify the permutation set explicitlycreate_mats
: All A.norm.sub
matrices will be symmetrized, regardless of the value of threshold.by
(previously they were only symmetrized if using threshold.by='density'
).
igraph
.get.resid
: no longer requires a covars argument, as it was redundantsim.rand.graph.par
: the argument clustering is no longer TRUE by default2017-04-10
First major release; Fifth CRAN release
plot_perm_diffs
previously didn't work with a low number of permutations, but now will work with any numbersim.rand.graph.par
previously didn't work with graphs lacking a degree
vertex attributeplot_brainGraph_GUI
when plotting in the sagittal view for neighborhood graphspermute.group.auc
has been removed, and now permute.group
accepts multiple densities and returns the same results. It can still take a single density for the old behaviorlobe
and network
vertex attributes are now character vectorsNBS
now handles more complex designs and contrasts through brainGraph_GLM_design
and brainGraph_GLM_fit
. The function arguments are different from previous versionsSPM
has been removed and is replaced by brainGraph_GLM
craddock200
(with coordinates from DPABI/DPARSF
)brainGraph_GLM
: replaces SPM
and allows for more complex designs and contrastsbrainGraph_GLM_design
: function that creates a design matrix from a data.table
brainGraph_GLM_fit
: function that calculates the statistics from a design matrix and response vectorcreate_mats
: replaces dti_create_mats
and adds functionality for resting-state fMRI data; also can create matrices that will have a specific graph densitygateway_coeff
: calculate the gateway coefficient (Vargas & Wahl, 2014); graphs will have vertex attributes GC
or GC.wt
(if weighted graph)plot_brainGraph_multi
: function to write a PNG file of 3-panel brain graphs (see User Guide for example)efficiency
replaces graph.efficiency
; the old function name is still accessible (but may be removed eventually)set_brainGraph_attr
replaces set.brainGraph.attributes
; the old function name is still accessible (but may be removed eventually)part_coeff
replaces part.coeff
rich.
functions have been renamed. The period/point/dot in each of those functions is replaced by the underscore. So, rich.club.norm
is now rich_club_norm
, etc.set_vertex_color
and set_edge_color
replace color.vertices
and color.edges
(these functions are not exported, in any case)contract_brainGraph
replaces graph.contract.brain
make_ego_brainGraph
replaces graph_neighborhood_multiple
(so it is a similar name to igraph's function make_ego_graph
)write_brainnet
replaces write.brainnet
2016-10-10
Fourth CRAN release
sim.rand.graph.clust
previously returned a list; now it correctly returns an
igraph
graph objectaop
and loo
: regional contributions were calculated incorrectly (without
an absolute value)rich.club.norm
: changed the p-value calculation again; this shouldn't affect
many results, particularly if N=1,000 (random graphs)NBS
:
t.stat
edge attribute was, under certain situations, incorrectly
assigning the values; this has been fixed in the latest versionSPM
:
NA
valuesvec.transform
: fixed bug which occurred when the input vector is the same
number repeated (i.e., when range(x) = 0
)dti_create_mats
: new function argument algo
can be used to specify either 'probabilistic' or 'deterministic'. In the case of the latter, when dividing streamline count by ROI size, you can supply absolute streamline counts with the mat.thresh
argument..parallel
to use.parallel
; also, added it as an
argument to set.brainGraph.attributes
to control all of the functions that
it calls; also added the argument to part.coeff
and
within_module_deg_z_score
aal2.94
, aal2.120
, and dosenbach160
plot_brainGraph
: can now specify the orientation plane, hemisphere to plot,
showing a legend, and a character string of logical expressions for plotting
subgraphs (previously was in plot_brainGraph_list
)auc_diff
: calculates the area-under-the-curve across densities for two
groupscor.diff.test
: calculates the significance of the difference between
correlation coefficientspermute.group.auc
: does permutation testing across all densities, and
returns the permutation distributions for the difference in AUC between two
groupsrich.club.attrs
: give a graph attributes based on rich-club analysisx
, y
, and z
columns from the atlas data files; now only the
MNI coordinates are used. This should simplify adding a personal atlas to use
with the packagename.full
to some of the atlas data filesNBS
:
p
, the p-value for that specific connectionp.init
value for record-keepingbrainGraph_init
: can now provide a covars
data table if you want to subset
certain variables yourself, or if the file is named differently from
covars.csv
plot_brainGraph
: can now manually specify a subtitle;plot_brainGraph_gui
:
plot_corr_mat
: color cells based on weighted community or networkplot_global
:
xvar
to be either "density" or "threshold"; if the latter, the
x-axis is reversedStudy.ID
column, the ggplot2
function stat_smooth
is used
and the statistic is based on a generalized additive modelplot_perm_diffs
: added argument auc
for using the area-under-the-curve
across densitiesplot_rich_norm
:
fdr
to choose whether or not to use FDR-adjusted p-valuesplot_vertex_measures
: can facet by different variables (e.g., lobe, community, network, etc.)set.brainGraph.attributes
:
strength
, which is the mean of vertex strength (weighted networks)write.brainnet
:
edge.wt
function argument2016-04-22
Third CRAN release
rich.club.norm
had a bug in calculating the p-values. If you have already
gone through the process of creating random graphs and the object phi.norm
,
you can fix with the following code: (add another loop if you have
single-subject graphs, e.g. DTI data)for (i in seq_along(groups)) {
for (j in seq_along(densities)) {
max.deg <- max(V(g[[i]][[j]])$degree)
phi.norm[[i]][[j]]$p <- sapply(seq_len(max.deg), function(x)
sum(phi.norm[[i]][[j]]$phi.rand[, x] >= phi.norm[[i]][[j]]$phi.orig[x]) / N)
}
}
where N
is the number of random graphs generated.
dti_create_mats
: there was a bug when sub.thresh equals 0; it would take
matrix entries, even if they were below the mat.thresh values. This has
been fixed. Argument checking has also been added.RcppEigen
for fast linear model calculations;
resulted in major speed improvementspermute
for the NBS
functiongroup.graph.diffs
:
fastLmPure
from RcppEigen
for speed/efficiencydestrieux.scgm
atlasSPM
: new function that replaces and improves upon both group.graph.diffs
and permute.vertex
NBS
: implements the network-based statisticanalysis_random_graphs
: perform all the steps for getting small-world
parameters and normalized rich-club coefficients and p-valuesplot_global
: create a line plot across all densities of global graph
measures in the same figurevertex_spatial_dist
: calculates the mean edge distance for all edges of a
given vertexdti_create_mats
: changed a few argumentsedge_spatial_dist
: re-named from spatial.dist
group.graph.diffs
: returns a graph w/ spatial coord's for plottingplot_brainGraph_list
:
hemi == "R"
will keep only right hemisphere vertices; includes complex logical
expressions (i.e., with multiple '&' and '|' conditions)Lp
(average path length for each vertex)plot_brainGraph_gui
:
plot_rich_norm
:
facet.by
to group the plots by either "density" (default) or
"threshold" (for multi-subject, e.g. DTI data)set.brainGraph.attributes
: New calculations for weighted graphs:
2015-12-24
Second CRAN release
aop
and loo
calculate measures of individual contribution (see Reference
within the function help)
ade4
plot_boot
: new function based on the removed plotting code from boot_global
plot_rich_norm
: function to plot normalized rich club coefficient curvesboot_global
:
corr.matrix
brainGraph_init
:
corr.matrix
:
count_interlobar
no longer takes atlas.dt
as an argument
dti_create_mats
now accepts argument P
for "number of samples"
edge_asymmetry
now works on Windows (changed from mclapply to foreach)
get.resid
:
use.mean=FALSE
but covars has columns
mean.lh and/or mean.rh; fixed minor bug w/ RH residual calculationuse.mean=TRUE
(syntax error for RH vertices)graph.efficiency
: now works on Windows (changed from mclapply to foreach)
part.coeff
: has a workaround to work on Windows
permute.group
:
corr.matrix
atlas.dt
as an argumentvertex_attr_dt
is now essentially a wrapper for igraph
's function
as_data_frame
Exported plot_perm_diffs
Added argument checking for most functions
2015-12-08
Initial CRAN release