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.

- Mediation analysis is now possible through
`brainGraph_mediate`

. - I have introduced some simple
*S3 classes*and*methods*. All of the classes have`plot`

(except`NBS`

) and`summary`

methods. The classes and corresponding “creation functions” are:

Class | Creation func. | Description |
---|---|---|

brainGraph | make_brainGraph | Any graph with certain attributes |

bg_GLM | brainGraph_GLM | Results of GLM analysis |

NBS | NBS | Results of NBS analysis |

mtpc | mtpc | Results of MTPC analysis |

brainGraph_GLM | make_glm_brainGraph | Graphs from GLM analysis |

brainGraph_NBS | make_nbs_brainGraph | Graphs from NBS analysis |

brainGraph_mtpc | make_glm_brainGraph | Graphs from MTPC analysis |

brainGraph_mediate | make_mediate_brainGraph | Graphs from mediation analysis |

brainGraph_boot | brainGraph_boot | Results of bootstrap analysis |

brainGraph_permute | brainGraph_permute | Results of permutation tests |

brainGraph_resids | get.resid | Residuals for covariance networks |

- Multiple contrasts (in the same function call), as well as F-contrasts, are now allowed in the GLM-based functions:
`brainGraph_GLM`

,`mtpc`

,`NBS`

, and`get.resid`

.- There is a new function argument,
`con.type`

, for this purpose. - Since both contrast types are now specified in the form of a
*contrast matrix*, the argument`con.vec`

has been replaced by`con.mat`

.

- There is a new function argument,
- Designs with 3-way interactions (e.g.,
`2 x 2 x 2`

) are now allowed for GLM-based analyses. - Permutations for GLM-based analyses are now done using the
*Freedman-Lane*method (the same as in FSL’s*randomise*and in*PALM*). - Plot the “diagnostics” from GLM analyses through the
`plot.bg_GLM`

method to the output of`brainGraph_GLM`

. - Plot the statistics from MTPC analyses through the
`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.- Removes the need to loop through patient groups in the console (if you have more than 1).

- Most of the GLM-based functions have a new argument,
`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`

:- Function was renamed to
`brainGraph_permute`

. - The arguments are slightly re-ordered
- Argument
`permSet`

was renamed to`perms`

. - New argument
`auc`

lets you explicitly define whether or not you want statistics for the*area under the curve (AUC)*.

- Function was renamed to
`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.- There is a new function argument,
`symm.by`

(which is the same as that for`create_mats`

) for this purpose.

- There is a new function argument,
`corr.matrix`

:- Now expects as its first input the residuals from
`get.resid`

. - You may specify multiple
`densities`

(or`thresholds`

), - Returns a
*list*including the binarized, thresholded matrices as an*array*(still named`r.thresh`

).

- Now expects as its first input the residuals from
`get.resid`

now allows for any design matrix for getting LM residuals (similar to`brainGraph_GLM`

).- Must supply a
`data.table`

of covariates. - You may pass on arguments to
`brainGraph_GLM_design`

for creating the correct design matrix.

- Must supply a
`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.- I now use the
`ggrepel`

package for any`ggplot`

objects with text labels.

2017-09-14

`brainGraph_init`

: fixed bug regarding the use of a custom atlas

- Some function arguments have been modified to reflect the object type (e.g., changing
`g`

to`g.list`

if the function requires a*list*object). `brainGraph_init`

:- New argument
`custom.atlas`

allows you to use an atlas that is not in the package (you must also specify`atlas="custom"`

). - This requires that the atlas you specify already be loaded into the R environment and meet the specifications of the package’s atlases
- It should be a
`data.table`

, and have columns*name*,*x.mni*,*y.mni*,*z.mni*,*lobe*,*hemi*(at a minimum).

- It should be a

- New argument
`permute.group`

: can now calculate`ev.cent`

2017-08-31

`boot_global`

: fixed bug in*modularity*calculation

`boot_global`

:- can omit display of the progress bar (by setting
`.progress=FALSE`

) - can now create weighted networks; to do so, you must choose a weighted metric in the function argument
`measure`

- added some weighted metrics as options for
`measure`

(*strength*,*mod.wt*,*E.global.wt*) - can specify the confidence level (for calculating confidence intervals) via the
`conf`

argument (default: 0.95)

- can omit display of the progress bar (by setting
`set_brainGraph_attr`

:- New argument
`xfm.type`

, which allows you to choose how edge weights should be transformed for calculating distance-based metrics. - The default is the
*reciprocal*(which is what was hard-coded in previous versions). - Other options are:
`1-w`

(subtract weights from 1); and`-log(w)`

(take the negative natural logarithm of weights).

- New argument

`symmetrize_array`

: a convenience function that applies`symmetrize_mats`

along the third dimension of an array`xfm.weights`

: utility function to transform edge weights (necessary when calculating distance-based metrics).

`graph_attr_dt`

and`vertex_attr_dt`

will now include`weighting`

, if present`set_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*argument

2017-04-30

`create_mats`

- fixed bug for deterministic tractography when the user would like to normalize the matrices by
*ROI size*. - Fixed bug for when
`threshold.by='density'`

. Previously, it would keep the top*X*% for*each*subject

- fixed bug for deterministic tractography when the user would like to normalize the matrices by

`create_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 versions`s_core`

: calculate the*s-core*membership of a graph’s vertices (Eidsaa & Almaas, 2013)- Adds a vertex attributes called
`s.core`

to the graph through`set_brainGraph_attr`

. - Analogous to the
*k-core*but for weighted networks. - The vertex attribute for
*k-core*has been changed from`coreness`

to`k.core`

to distinguish these metrics.

- Adds a vertex attributes called

2017-04-22

`plot_brainGraph_gui`

had multiple issues and a few features have been changed:- Overall execution should be faster than in previous versions
*Lobe*,*neighborhood*, and*community*selection are now in “scrolled windows” instead of drop-down lists. Multiple selections can be made either by pressing`Ctrl`

and clicking, or by holding`Shift`

and moving the arrow keys- Fixed problem with vertex colors
- When choosing to plot
*neighborhoods*, you can color the vertices based on which neighborhood they belong to (useful if multiple vertices are selected)

`gateway_coeff`

returned an error if the number of communities equals 1; this has been fixed

`centr_betw_comm`

: calculate vertex*communicability betweenness centrality*(Estrada et al., 2009)`communicability`

: calculate network*communicability*(Estrada & Hatano, 2008)`mtpc`

: the*multi-threshold permutation correction (MTPC)*method for statistical inference of either vertex- or graph-level measures (Drakesmith et al., 2015)`symmetrize_mats`

: symmetrize a connectivity matrix by either the*maximum*,*minimum*, or*average*of the off-diagonal elements. You may select one of these as an argument to`create_mats`

.

`brainGraph_GLM`

has 2 new function arguments:`level`

allows you to perform inference for graph- or vertex-level measures`perms`

lets you specify the permutation set explicitly

`create_mats`

: All`A.norm.sub`

matrices will be symmetrized, regardless of the value of`threshold.by`

(previously they were only symmetrized if using`threshold.by='density'`

).- This should not pose a problem, as the default (to take the
*maximum*of the off-diagonal elements) is also the default when creating graphs in`igraph`

.

- This should not pose a problem, as the default (to take the

`get.resid`

: no longer requires a*covars*argument, as it was redundant`sim.rand.graph.par`

: the argument*clustering*is no longer TRUE by default

# brainGraph 1.0.0 |

2017-04-10 |

First major release; Fifth CRAN release |

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

## Major changes * Multiple functions now run significantly faster after I updated the code to be more efficient * `permute.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 behavior * The `lobe` and `network` vertex attributes are now character vectors * `NBS` now handles more complex designs and contrasts through `brainGraph_GLM_design` and `brainGraph_GLM_fit` . The function arguments are different from previous versions * `SPM` has been removed and is replaced by `brainGraph_GLM` * Added atlas `craddock200` (with coordinates from `DPABI/DPARSF` ) |

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

## Minor changes * `efficiency` replaces `graph.efficiency` ; the old function name is still accessible (but may be removed eventually) * `set_brainGraph_attr` replaces `set.brainGraph.attributes` ; the old function name is still accessible (but may be removed eventually) * `part_coeff` replaces `part.coeff` * All of the `rich.` functions have been renamed. The period/point/dot in each of those functions is replaced by the underscore. So, `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` * In the GUI, vertex order in circle plots now more closely reflect their anatomical position, being ordered by y- and x-coordinates (and within lobe) |

2016-10-10

*Fourth CRAN release*

`sim.rand.graph.clust`

previously returned a list; now it correctly returns an`igraph`

graph object`aop`

and`loo`

: regional contributions were calculated incorrectly (without an absolute value)`rich.club.norm`

: changed the p-value calculation again; this shouldn’t affect many results, particularly if N=1,000 (random graphs)`NBS`

:- the
`t.stat`

edge attribute was, under certain situations, incorrectly assigning the values; this has been fixed in the latest version - fixed bug when permutations didn’t result in any connected components
- fixed bug w/ data randomization; the bug didn’t seem to affect the results
`SPM`

:- the permutation p-values were previously incorrect; has been fixed
- added an argument to remove
`NA`

values `vec.transform`

: fixed bug which occurred when the input vector is the same number repeated (i.e., when`range(x) = 0`

)

`dti_create_mats`

: new function argument`algo`

can be used to specify either ‘probabilistic’ or ‘deterministic’. In the case of the latter, when dividing streamline count by ROI size, you can supply absolute streamline counts with the`mat.thresh`

argument.- Changed instances of
`.parallel`

to`use.parallel`

; also, added it as an argument to`set.brainGraph.attributes`

to control all of the functions that it calls; also added the argument to`part.coeff`

and`within_module_deg_z_score`

- Added atlases
`aal2.94`

,`aal2.120`

, and`dosenbach160`

`plot_brainGraph`

: can now specify the orientation plane, hemisphere to plot, showing a legend, and a character string of logical expressions for plotting subgraphs (previously was in`plot_brainGraph_list`

)

`auc_diff`

: calculates the area-under-the-curve across densities for two groups`cor.diff.test`

: calculates the significance of the difference between correlation coefficients`permute.group.auc`

: does permutation testing across all densities, and returns the permutation distributions for the difference in AUC between two groups`rich.club.attrs`

: give a graph attributes based on rich-club analysis

- Removed the
`x`

,`y`

, and`z`

columns from the atlas data files; now only the MNI coordinates are used. This should simplify adding a personal atlas to use with the package - Added a column,
`name.full`

to some of the atlas data files `NBS`

:- New edge attribute
`p`

, the p-value for that specific connection - Returns the
`p.init`

value for record-keeping `brainGraph_init`

: can now provide a`covars`

data table if you want to subset certain variables yourself, or if the file is named differently from`covars.csv`

`plot_brainGraph`

: can now manually specify a subtitle;`plot_brainGraph_gui`

:- Option for specifying maximum values for edge widths
`plot_corr_mat`

: color cells based on weighted community or network`plot_global`

:- legend position is now “bottom” by default
- can specify
`xvar`

to be either “density” or “threshold”; if the latter, the x-axis is reversed - If data has a
`Study.ID`

column, the`ggplot2`

function`stat_smooth`

is used and the statistic is based on a generalized additive model `plot_perm_diffs`

: added argument`auc`

for using the area-under-the-curve across densities`plot_rich_norm`

:- Added argument
`fdr`

to choose whether or not to use FDR-adjusted p-values - Should work for more than 2 groups
- Now works with multi-subject data; collapses by
*Group*and plots the group mean `plot_vertex_measures`

: can facet by different variables (e.g., lobe, community, network, etc.)`set.brainGraph.attributes`

:- calculate graph
`strength`

, which is the mean of vertex strength (weighted networks) - Invert edge weights for distance-based measures
`write.brainnet`

:- Now allows for writing weighted adjacency matrices, using the
`edge.wt`

function argument - Can color vertices by multiple variables

# brainGraph 0.62.0 |

2016-04-22 |

Third CRAN release |

## Bug fix * `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. |

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

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

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

2015-12-24

*Second CRAN release*

`aop`

and`loo`

calculate measures of*individual contribution*(see Reference within the function help)- Now requires the package
`ade4`

`plot_boot`

: new function based on the removed plotting code from`boot_global`

`plot_rich_norm`

: function to plot normalized rich club coefficient curves

`boot_global`

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

`brainGraph_init`

:- does a better job of dealing with subcortical gray matter data
- now also returns the “tidied” dataset
`corr.matrix`

:- was basically reverted back for speed purposes
- minor syntax change
`count_interlobar`

no longer takes`atlas.dt`

as an argument`dti_create_mats`

now accepts argument`P`

for “number of samples”`edge_asymmetry`

now works on Windows (changed from*mclapply*to*foreach*)`get.resid`

:- got a complete overhaul; now works with
*data.table*syntax - now returns
*data.table*of residuals with a*Study.ID*column - fixed minor bug when
`use.mean=FALSE`

but*covars*has columns*mean.lh*and/or*mean.rh*; fixed minor bug w/ RH residual calculation - fixed bug when
`use.mean=TRUE`

(syntax error for RH vertices) `graph.efficiency`

: now works on Windows (changed from*mclapply*to*foreach*)`part.coeff`

: has a workaround to work on Windows`permute.group`

:- updated to work with new version of
`corr.matrix`

- no longer takes
`atlas.dt`

as an argument `vertex_attr_dt`

is now essentially a wrapper for`igraph`

’s function`as_data_frame`

- Exported
`plot_perm_diffs`

Added argument checking for most functions

2015-12-08

*Initial CRAN release*