├── .Rbuildignore ├── .gitattributes ├── .gitignore ├── .travis.yml ├── DESCRIPTION ├── NAMESPACE ├── NEWS.md ├── R ├── NBS.R ├── analysis_random_graphs.R ├── atlas.R ├── auc.R ├── boot_global.R ├── brainGraph_GLM.R ├── brainGraph_mediate.R ├── centr_lev.R ├── communicability.R ├── contract_brainGraph.R ├── corr_matrix.R ├── count_edges.R ├── create_graphs.R ├── create_mats.R ├── data.R ├── data_tables.R ├── distances.R ├── edge_asymmetry.R ├── get_resid.R ├── glm_design.R ├── glm_fit.R ├── glm_methods.R ├── glm_randomise.R ├── glm_stats.R ├── graph_efficiency.R ├── hubs.R ├── import.R ├── individ_contrib.R ├── list.R ├── method_helpers.R ├── methods.R ├── mtpc.R ├── permute_group.R ├── plot_brainGraph.R ├── plot_brainGraph_gui.R ├── plot_brainGraph_multi.R ├── plot_global.R ├── plot_group_means.R ├── plot_rich_norm.R ├── plot_vertex_measures.R ├── random_graphs.R ├── rich_club.R ├── robustness.R ├── s_core.R ├── set_brainGraph_attributes.R ├── small_world.R ├── spatial_dist.R ├── sysdata.rda ├── update_brainGraph_gui.R ├── utils.R ├── utils_matrix.R ├── vertex_roles.R ├── vulnerability.R ├── write_brainnet.R └── zzz.R ├── README.md ├── cran-comments.md ├── data ├── aal116.rda ├── aal2.120.rda ├── aal2.94.rda ├── aal90.rda ├── brainnetome.rda ├── brainsuite.rda ├── craddock200.rda ├── destrieux.rda ├── destrieux.scgm.rda ├── dk.rda ├── dk.scgm.rda ├── dkt.rda ├── dkt.scgm.rda ├── dosenbach160.rda ├── gordon333.rda ├── hcp_mmp1.0.rda ├── hoa112.rda ├── lpba40.rda └── power264.rda ├── inst └── extdata │ └── brainGraph_icon.png └── man ├── Bootstrapping.Rd ├── NBS.Rd ├── apply_thresholds.Rd ├── atlas_helpers.Rd ├── attributes.Rd ├── auc_diff.Rd ├── brainGraph-methods.Rd ├── brainGraph.Rd ├── brainGraphList.Rd ├── brainGraph_permute.Rd ├── brain_atlases.Rd ├── centr_betw_comm.Rd ├── centr_lev.Rd ├── check_attributes.Rd ├── choose.edges.Rd ├── coeff_var.Rd ├── communicability.Rd ├── contract_brainGraph.Rd ├── cor.diff.test.Rd ├── correlation_matrices.Rd ├── count_edges.Rd ├── create_mats.Rd ├── data_tables.Rd ├── delete_all_attr.Rd ├── dir2files.Rd ├── edge_asymmetry.Rd ├── efficiency.Rd ├── get_rand_attrs.Rd ├── glm.Rd ├── glm_brainGraphList.Rd ├── glm_design.Rd ├── glm_fit.Rd ├── glm_graph_plots.Rd ├── glm_helpers.Rd ├── glm_influence.Rd ├── glm_info.Rd ├── glm_model_select.Rd ├── glm_stats.Rd ├── hubness.Rd ├── import_scn.Rd ├── individ_contrib.Rd ├── inverse.Rd ├── make_auc_brainGraph.Rd ├── make_brainGraph.Rd ├── make_ego_brainGraph.Rd ├── make_intersection_brainGraph.Rd ├── matrix_utils.Rd ├── mean_distance_wt.Rd ├── mediation.Rd ├── mtpc.Rd ├── pad_zeros.Rd ├── plot.brainGraph.Rd ├── plot.brainGraphList.Rd ├── plot_brainGraph_gui.Rd ├── plot_brainGraph_multi.Rd ├── plot_global.Rd ├── plot_rich_norm.Rd ├── plot_vertex_measures.Rd ├── plot_volumetric.Rd ├── random_graphs.Rd ├── randomise.Rd ├── rename_levels.Rd ├── residuals.Rd ├── rich_club.Rd ├── rich_club_attrs.Rd ├── robustness.Rd ├── s_core.Rd ├── set_graph_colors.Rd ├── small.world.Rd ├── spatial_dist.Rd ├── subset_graph.Rd ├── update_fs_names.Rd ├── utils.Rd ├── vertex_roles.Rd ├── vif.bg_GLM.Rd ├── vulnerability.Rd └── write_brainnet.Rd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | cran-comments.md 2 | README.md 3 | ^\.travis\.yml$ 4 | ^appveyor\.yml$ 5 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * text=auto 2 | data/* binary 3 | src/* text=lf 4 | R/* text=lf 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.sw[pon] 2 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | # Sample .travis.yml for R projects 2 | 3 | language: r 4 | r: 5 | - oldrel 6 | - release 7 | - devel 8 | 9 | warnings_are_errors: true 10 | sudo: required 11 | 12 | r_binary_packages: 13 | - igraph 14 | 15 | addons: 16 | apt: 17 | packages: 18 | - libnlopt-dev 19 | 20 | env: 21 | global: 22 | - _R_CHECK_FORCE_SUGGESTS_=false 23 | 24 | before_install: 25 | echo "options(repos=c(CRAN='http://cran.rstudio.com'))" > ~/.Rprofile 26 | 27 | notifications: 28 | email: 29 | on_success: change 30 | on_failure: change 31 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: brainGraph 2 | Type: Package 3 | Version: 3.0.3 4 | Date: 2024-02-20 5 | Title: Graph Theory Analysis of Brain MRI Data 6 | Authors@R: person(given="Christopher G.", family="Watson", 7 | email="cgwatson@bu.edu", role=c("aut", "cre"), 8 | comment=c(ORCID="0000-0002-7082-7631")) 9 | Description: A set of tools for performing graph theory analysis of brain MRI 10 | data. It works with data from a Freesurfer analysis (cortical thickness, 11 | volumes, local gyrification index, surface area), diffusion tensor 12 | tractography data (e.g., from FSL) and resting-state fMRI data (e.g., from 13 | DPABI). It contains a graphical user interface for graph visualization and 14 | data exploration, along with several functions for generating useful 15 | figures. 16 | URL: https://github.com/cwatson/brainGraph 17 | BugReports: https://groups.google.com/forum/?hl=en#!forum/brainGraph-help 18 | LazyData: true 19 | Depends: 20 | R (>= 3.5.0), 21 | igraph (>= 1.2.4), 22 | Imports: 23 | abind, 24 | data.table (>= 1.12.4), 25 | doParallel, 26 | foreach, 27 | grid, 28 | lattice, 29 | MASS, 30 | Matrix, 31 | methods, 32 | permute, 33 | parallel 34 | Suggests: 35 | Hmisc, 36 | RGtk2, 37 | ade4, 38 | boot, 39 | cairoDevice, 40 | car, 41 | expm, 42 | ggplot2, 43 | ggrepel, 44 | gridExtra, 45 | mediation, 46 | oro.nifti, 47 | scales 48 | License: GPL-3 49 | RoxygenNote: 6.1.1 50 | Collate: 51 | 'glm_stats.R' 52 | 'brainGraph_GLM.R' 53 | 'glm_methods.R' 54 | 'NBS.R' 55 | 'analysis_random_graphs.R' 56 | 'atlas.R' 57 | 'auc.R' 58 | 'boot_global.R' 59 | 'brainGraph_mediate.R' 60 | 'centr_lev.R' 61 | 'communicability.R' 62 | 'contract_brainGraph.R' 63 | 'corr_matrix.R' 64 | 'count_edges.R' 65 | 'create_graphs.R' 66 | 'create_mats.R' 67 | 'data.R' 68 | 'data_tables.R' 69 | 'distances.R' 70 | 'edge_asymmetry.R' 71 | 'get_resid.R' 72 | 'glm_design.R' 73 | 'glm_fit.R' 74 | 'glm_randomise.R' 75 | 'graph_efficiency.R' 76 | 'hubs.R' 77 | 'import.R' 78 | 'individ_contrib.R' 79 | 'list.R' 80 | 'method_helpers.R' 81 | 'mtpc.R' 82 | 'methods.R' 83 | 'permute_group.R' 84 | 'plot_brainGraph.R' 85 | 'plot_brainGraph_gui.R' 86 | 'plot_brainGraph_multi.R' 87 | 'plot_global.R' 88 | 'plot_group_means.R' 89 | 'plot_rich_norm.R' 90 | 'plot_vertex_measures.R' 91 | 'random_graphs.R' 92 | 'rich_club.R' 93 | 'robustness.R' 94 | 's_core.R' 95 | 'set_brainGraph_attributes.R' 96 | 'small_world.R' 97 | 'spatial_dist.R' 98 | 'update_brainGraph_gui.R' 99 | 'utils.R' 100 | 'utils_matrix.R' 101 | 'vertex_roles.R' 102 | 'vulnerability.R' 103 | 'write_brainnet.R' 104 | 'zzz.R' 105 | -------------------------------------------------------------------------------- /R/auc.R: -------------------------------------------------------------------------------- 1 | #' Calculate the AUC across densities of given attributes 2 | #' 3 | #' Given a list of \code{brainGraphList} objects, this function will calculate 4 | #' the area under the curve (AUC) across all thresholds/densities for each 5 | #' subject or group. 6 | #' 7 | #' If the elements of the input list do not have a \code{threshold} element (or 8 | #' if it is \code{NULL}) then the AUC will be calculated on the interval 9 | #' \eqn{[0, 1]} (inclusive). This has the same effect as specifying 10 | #' \code{norm=TRUE} in the function call. 11 | #' 12 | #' @param g.list A list of \code{brainGraphList} objects 13 | #' @param g.attr A character vector of graph attribute name(s). Default: 14 | #' \code{NULL} 15 | #' @param v.attr A character vector of vertex attribute name(s). Default: 16 | #' \code{NULL} 17 | #' @param norm Logical indicating whether to normalize threshold values to be 18 | #' between 0 and 1 (inclusive). Default: \code{FALSE} 19 | #' @export 20 | #' @return A \code{brainGraphList} object with one graph for each subject 21 | #' @importFrom doParallel registerDoParallel 22 | #' @importFrom foreach getDoParRegistered 23 | #' 24 | #' @examples 25 | #' \dontrun{ 26 | #' g.auc <- make_auc_brainGraph(g.fa, g.attr='E.global.wt') 27 | #' } 28 | 29 | make_auc_brainGraph <- function(g.list, g.attr=NULL, v.attr=NULL, norm=FALSE) { 30 | i <- NULL 31 | # Check if components are 'brainGraphList' objects 32 | matches <- vapply(g.list, is.brainGraphList, logical(1L)) 33 | if (any(!matches)) stop("Input must be a list of 'brainGraphList' objects.") 34 | 35 | # Get the meta variables first 36 | attrs <- c('atlas', 'type', 'level', 'modality', 'weighting') 37 | out <- setNames(vector('list', length(attrs)), attrs) 38 | for (a in attrs) out[[a]] <- g.list[[1L]][[a]] 39 | 40 | if (!is.null(g.list[[1L]]$threshold)) { 41 | thresholds <- vapply(g.list, `[[`, numeric(1L), 'threshold') 42 | if (isTRUE(norm)) thresholds <- vec.transform(thresholds) 43 | } else { 44 | thresholds <- seq.int(from=0, to=1, length.out=length(g.list)) 45 | } 46 | subjects <- names(g.list[[1L]]$graphs) 47 | grps <- groups(g.list[[1L]]) 48 | 49 | if (!getDoParRegistered()) { 50 | cl <- makeCluster(getOption('bg.ncpus')) 51 | registerDoParallel(cl) 52 | } 53 | g.auc <- foreach(i=seq_along(subjects)) %dopar% { 54 | g.subj <- lapply(g.list, `[`, i) 55 | g.tmp <- with(out, 56 | make_empty_brainGraph(atlas, type, level, modality, weighting, 57 | name=subjects[i], Group=grps[i], subnet=g.subj[[1L]]$subnet)) 58 | if (!is.null(g.attr)) { 59 | for (k in g.attr) { 60 | y <- sapply(g.subj, graph_attr, k) 61 | g.tmp <- set_graph_attr(g.tmp, k, abs(auc_diff(thresholds, y))) 62 | } 63 | } 64 | if (!is.null(v.attr)) { 65 | for (k in v.attr) { 66 | y <- t(sapply(g.subj, vertex_attr, k)) 67 | g.tmp <- set_vertex_attr(g.tmp, k, value=abs(auc_diff(thresholds, y))) 68 | } 69 | } 70 | g.tmp 71 | } 72 | out <- get_metadata(out) 73 | out$graphs <- g.auc 74 | names(out$graphs) <- subjects 75 | class(out) <- c('brainGraphList', 'list') 76 | return(out) 77 | } 78 | 79 | #' Difference in the area-under-the-curve of two vectors 80 | #' 81 | #' This function takes two vectors, calculates the area-under-the-curve (AUC), 82 | #' and calculates the difference between the two (if applicable). 83 | #' 84 | #' There are 4 different behaviors for this function: 85 | #' \enumerate{ 86 | #' \item If \code{x} is a single numeric value, then \code{y} should be a 87 | #' vector of 2 values and the difference is returned. This generally should 88 | #' not occur and may be removed in the future. 89 | #' \item If \code{y} has 1 column (or is a vector), then the AUC of \code{y} 90 | #' is returned. 91 | #' \item If \code{y} has exactly 2 columns, then each column should contain 92 | #' the values of interest for each subject group, and the difference in 93 | #' AUC's for each group is returned. 94 | #' \item If \code{y} has multiple columns (e.g., equal to the number of 95 | #' vertices of a graph), it will calculate the AUC for each column. 96 | #' } 97 | #' 98 | #' @param x Numeric vector of the x-values 99 | #' @param y A numeric vector or matrix 100 | #' 101 | #' @keywords internal 102 | #' @return A numeric value of the difference between two groups, or a numeric 103 | #' vector of the AUC across vertices 104 | 105 | auc_diff <- function(x, y) { 106 | if (length(x) > 1L) { 107 | if (NCOL(y) == 1L) { # A single vector, for MTPC 108 | return(sum(-diff(x) * (head(y, -1L) + tail(y, -1L))) / 2) 109 | } else if (ncol(y) > 2L) { 110 | return(apply(y, 2L, function(z) auc_diff(x, z))) 111 | } else { 112 | return(auc_diff_perm(x, y)) 113 | } 114 | } else { 115 | return(y[1L] - y[2L]) 116 | } 117 | } 118 | 119 | #' @param x Numeric vector 120 | #' @param y Numeric matrix with 2 columns and number of rows equal to the length 121 | #' of \code{x} 122 | #' @return A single numeric value of the between-group AUC difference 123 | #' @noRd 124 | 125 | auc_diff_perm <- function(x, y) { 126 | -diff(apply(y, 2L, function(z) sum(diff(x) * (head(z, -1L) + tail(z, -1L))) / 2)) 127 | } 128 | -------------------------------------------------------------------------------- /R/centr_lev.R: -------------------------------------------------------------------------------- 1 | #' Calculate a vertex's leverage centrality 2 | #' 3 | #' Calculates the leverage centrality of each vertex in a graph. 4 | #' 5 | #' The leverage centrality relates a vertex's degree with the degree of its 6 | #' neighbors. The equation is: 7 | #' \deqn{l_i = \frac{1}{k_i} \sum_{j \in N_i} \frac{k_i - k_j}{k_i + k_j}} 8 | #' where \eqn{k_i} is the degree of the \eqn{i^{th}} vertex and \eqn{N_i} is the 9 | #' set of neighbors of \emph{i}. This function replaces \emph{NaN} with 10 | #' \emph{NA} (for functions that have the argument \emph{na.rm}). 11 | #' 12 | #' @inheritParams efficiency 13 | #' @export 14 | #' 15 | #' @return A vector of the leverage centrality for all vertices. 16 | #' 17 | #' @family Centrality functions 18 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 19 | #' @references Joyce, K.E. and Laurienti P.J. and Burdette J.H. and Hayasaka S. 20 | #' (2010) A new measure of centrality for brain networks. \emph{PLoS One}, 21 | #' \bold{5(8)}, e12200. \doi{10.1371/journal.pone.0012200} 22 | 23 | centr_lev <- function(g, A=NULL) { 24 | stopifnot(is_igraph(g)) 25 | 26 | if (is.null(A)) A <- as_adj(g, sparse=FALSE, names=FALSE) 27 | k <- colSums(A) 28 | lev.cent <- rep.int(NA, dim(A)[1L]) 29 | # This is a tiny bit slower for larger graphs 30 | # for (i in which(k > 0)) { 31 | # lev.cent[i] <- sum((k[i] - k[A[i, ] == 1]) / (k[i] + k[A[i, ] == 1])) / k[i] 32 | # } 33 | dd <- lapply(seq_along(k), function(x) k[A[x, ] == 1]) 34 | lev.cent[which(k > 0)] <- vapply(which(k > 0), function(x) sum((k[x] - dd[[x]]) / (k[x] + dd[[x]])) / k[x], numeric(1L)) 35 | 36 | lev.cent[is.nan(lev.cent)] <- NA 37 | return(lev.cent) 38 | } 39 | -------------------------------------------------------------------------------- /R/communicability.R: -------------------------------------------------------------------------------- 1 | #' Calculate communicability 2 | #' 3 | #' \code{communicability} calculates the communicability of a network, a measure 4 | #' which takes into account all possible paths (including non-shortest paths) 5 | #' between vertex pairs. 6 | #' 7 | #' The communicability \eqn{G_{pq}} is a weighted sum of the number of walks 8 | #' from vertex \emph{p} to \emph{q} and is calculated by taking the exponential 9 | #' of the adjacency matrix \emph{A}: 10 | #' \deqn{G_{pq} = \sum_{k=0}^{\infty} \frac{(\mathbf{A}^k)_{pq}}{k!} = 11 | #' (e^{\mathbf{A}})_{pq}} 12 | #' where \eqn{k} is \emph{walk} length. 13 | #' 14 | #' For weighted graphs with \eqn{D = diag(d_i)} a diagonal matrix of vertex 15 | #' strength, 16 | #' \deqn{G_{pq} = (e^{\mathbf{D}^{-1/2} \mathbf{A} \mathbf{D}^{-1/2}})_{pq}} 17 | #' 18 | #' @inheritParams efficiency 19 | #' @export 20 | #' 21 | #' @return A numeric matrix of the communicability 22 | #' 23 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 24 | #' @references Estrada, E. and Hatano, N. (2008) Communicability in complex 25 | #' networks. \emph{Physical Review E}. \bold{77}, 036111. 26 | #' \doi{10.1103/PhysRevE.77.036111} 27 | #' @references Crofts, J.J. and Higham, D.J. (2009) A weighted communicability 28 | #' measure applied to complex brain networks. \emph{J. R. Soc. Interface}. 29 | #' \bold{6}, 411--414. \doi{10.1098/rsif.2008.0484} 30 | 31 | communicability <- function(g, weights=NULL) { 32 | if (!requireNamespace('expm', quietly=TRUE)) stop('Must install the "expm" package.') 33 | stopifnot(is_igraph(g), is_connected(g)) 34 | if (is.null(weights) && 'weight' %in% edge_attr_names(g)) { 35 | d <- check_strength(g) 36 | S <- diag(1 / sqrt(d)) 37 | A <- as.matrix(as_adj(g, names=FALSE, attr='weight')) 38 | } else { 39 | S <- diag(vcount(g)) 40 | A <- as_adj(g, names=FALSE, sparse=FALSE) 41 | } 42 | 43 | C <- expm::expm(S %*% A %*% S) 44 | return(C) 45 | } 46 | 47 | #' Calculate communicability betweenness centrality 48 | #' 49 | #' \code{centr_betw_comm} calculates the \emph{communicability betweenness} of 50 | #' the vertices of a graph. The centrality for vertex \code{r} is 51 | #' \deqn{\omega_r = \frac{1}{C} \sum_p \sum_q \frac{(e^{\mathbf{A}})_{pq} - 52 | #' (e^{\mathbf{A} + \mathbf{E}(r)})_{pq}}{(e^{\mathbf{A}})_{pq}}} 53 | #' where \eqn{C = (n - 1)^2 - (n - 1)} is a normalization factor. 54 | #' 55 | #' @inheritParams efficiency 56 | #' @export 57 | #' 58 | #' @return A numeric vector of the centrality for each vertex 59 | #' 60 | #' @family Centrality functions 61 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 62 | #' @references Estrada, E. and Higham, D.J. and Hatano N. (2009) Communicability 63 | #' betweenness in complex networks. \emph{Physica A}, \bold{388}, 764--774. 64 | #' \doi{10.1016/j.physa.2008.11.011} 65 | 66 | centr_betw_comm <- function(g, A=NULL) { 67 | stopifnot(is_igraph(g), is_connected(g)) 68 | if (!requireNamespace('expm', quietly=TRUE)) stop('Must install the "expm" package.') 69 | if (is.null(A)) A <- as_adj(g, names=FALSE, sparse=FALSE) 70 | 71 | C <- expm::expm(A) 72 | N <- dim(A)[1L] 73 | n <- (N - 1)^2 - (N - 1) 74 | Wr <- rep.int(0, N) 75 | for (i in seq_len(N)) { 76 | Er <- A 77 | Er[i, ] <- Er[, i] <- 0 78 | G <- (C - expm::expm(Er)) / C 79 | Wr[i] <- (sum(G[-i, -i]) - sum(diag(G[-i, -i]))) / n 80 | } 81 | return(Wr) 82 | } 83 | -------------------------------------------------------------------------------- /R/contract_brainGraph.R: -------------------------------------------------------------------------------- 1 | #' Contract graph vertices based on brain lobe and hemisphere 2 | #' 3 | #' Create a new graph after merging vertices within specified groups. 4 | #' By default, groups are brain \emph{lobe} and \emph{hemisphere} membership. 5 | #' 6 | #' The \code{size} vertex-level attribute of the resultant graph is equal to the 7 | #' number of vertices in each group. The x-, y-, and z-coordinates of the new 8 | #' graph are equal to the mean coordinates of the vertices per group. 9 | #' The new edge weights are equal to the number of inter-group connections of 10 | #' the original graph. 11 | #' 12 | #' @param g A \code{brainGraph} graph object 13 | #' @param vgroup Character string; the name of the vertex attribute to use when 14 | #' contracting the graph. Default: \code{'lobe.hemi'} 15 | #' @export 16 | #' 17 | #' @return A new \code{brainGraph} graph object with vertex-level attributes 18 | #' representing the mean spatial coordinates, and vertex- and edge-level 19 | #' attributes of color names 20 | #' 21 | #' @seealso \code{\link[igraph]{contract}} 22 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 23 | 24 | contract_brainGraph <- function(g, vgroup='lobe.hemi') { 25 | stopifnot(is.brainGraph(g), vgroup %in% vertex_attr_names(g)) 26 | 27 | vattrs <- vertex_attr(g, vgroup) 28 | if (!is.numeric(vattrs)) vattrs <- as.numeric(factor(vattrs)) 29 | g.sub <- contract(g, vattrs, vertex.attr.comb='concat') 30 | E(g.sub)$count <- 1 31 | g.sub <- simplify(g.sub, edge.attr.comb=list(count='sum', 'concat')) 32 | 33 | # Simplify coordinate- and color-related vertex and edge attributes 34 | for (nam in c('x', 'y', 'z')) { 35 | val <- vapply(vertex_attr(g.sub, nam), mean, numeric(1L)) 36 | g.sub <- delete_vertex_attr(g.sub, nam) 37 | g.sub <- set_vertex_attr(g.sub, nam, value=val) 38 | } 39 | for (nam in grep('color', vertex_attr_names(g.sub), value=TRUE)) { 40 | vvals <- lapply(vertex_attr(g.sub, nam), unique) 41 | if (all(lengths(vvals) == 1L)) { 42 | g.sub <- delete_vertex_attr(g.sub, nam) 43 | g.sub <- set_vertex_attr(g.sub, nam, value=unlist(vvals)) 44 | } 45 | evals <- lapply(edge_attr(g.sub, nam), unique) 46 | if (all(lengths(evals) == 1L)) { 47 | g.sub <- delete_edge_attr(g.sub, nam) 48 | g.sub <- set_edge_attr(g.sub, nam, value=unlist(evals)) 49 | } 50 | } 51 | 52 | V(g.sub)$size <- vapply(V(g.sub), function(v) sum(E(g.sub)[v %--% V(g.sub)]$count), numeric(1L)) 53 | 54 | class(g.sub) <- c('brainGraph', class(g.sub)) 55 | return(g.sub) 56 | } 57 | -------------------------------------------------------------------------------- /R/count_edges.R: -------------------------------------------------------------------------------- 1 | #' Count number of edges of a brain graph 2 | #' 3 | #' \code{count_homologous} counts the number of edges between homologous regions 4 | #' in a brain graph (e.g. between L and R superior frontal). 5 | #' 6 | #' @param g A \code{brainGraph} graph object 7 | #' @export 8 | #' @return \code{count_homologous} - a named vector of the edge ID's connecting 9 | #' homologous regions 10 | #' 11 | #' @name Count Edges 12 | #' @rdname count_edges 13 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 14 | 15 | count_homologous <- function(g) { 16 | V1 <- V2 <- NULL 17 | stopifnot(is.brainGraph(g)) 18 | if (any(grepl('(\\.|_)L[0-9]*', V(g)$name)) && !grepl('destrieux', g$atlas)) { 19 | lh <- '(\\.|_)L[0-9]*' 20 | rh <- '(\\.|_)R[0-9]*' 21 | } else { 22 | lh <- '^l' 23 | rh <- '^r' 24 | } 25 | 26 | dt <- as.data.table(as_edgelist(g)) 27 | eids <- dt[, which(gsub(lh, '', V1) == gsub(rh, '', V2))] 28 | names(eids) <- dt[eids, V1] 29 | return(eids) 30 | } 31 | 32 | #' Count number of inter-group edges 33 | #' 34 | #' \code{count_inter} counts the number of edges between and within all vertices 35 | #' in one group (e.g. \emph{lobe}, \emph{hemi}, \emph{network}, etc.). 36 | #' 37 | #' @param group Character string specifying which grouping to calculate edge 38 | #' counts for. Default: \code{'lobe'} 39 | #' @export 40 | #' @return \code{count_inter} - a \code{data.table} of total, intra-, and 41 | #' inter-group edge counts 42 | #' 43 | #' @rdname count_edges 44 | #' @examples 45 | #' \dontrun{ 46 | #' g1.lobecounts <- count_inter(g[[1]][[N]], 'lobe') 47 | #' } 48 | 49 | count_inter <- function(g, group=c('lobe', 'hemi', 'network', 'class', 50 | 'gyrus', 'Yeo_7network', 'Yeo_17network', 51 | 'area', 'Brodmann')) { 52 | total <- intra <- inter <- NULL 53 | group <- match.arg(group) 54 | stopifnot(is.brainGraph(g), group %in% vertex_attr_names(g)) 55 | 56 | group.names <- get(g$atlas)[, levels(get(group))] 57 | A <- as_adj(g, names=FALSE, sparse=FALSE) 58 | Nm <- length(group.names) 59 | mat <- matrix(0, Nm, Nm) 60 | vattrs <- vertex_attr(g, group) 61 | matches <- lapply(group.names, function(x) which(vattrs == x)) 62 | for (i in seq_len(Nm)) { 63 | for (j in seq.int(i, Nm)) { 64 | mat[i, j] <- sum(A[matches[[i]], matches[[j]]]) 65 | } 66 | } 67 | mat[lower.tri(mat)] <- t(mat)[lower.tri(mat)] 68 | intra <- diag(mat) <- diag(mat) / 2 69 | rownames(mat) <- colnames(mat) <- group.names 70 | DT <- data.table(group=group.names, intra=intra, inter=rowSums(mat)-intra) 71 | DT[, total := intra + inter] 72 | setnames(DT, 'group', group) 73 | return(list(mat=mat, DT=DT)) 74 | } 75 | -------------------------------------------------------------------------------- /R/data_tables.R: -------------------------------------------------------------------------------- 1 | #' Create a data table with graph global and vertex measures 2 | #' 3 | #' \code{graph_attr_dt} is a helper function that takes a \code{brainGraphList} 4 | #' or a list of graphs and creates a \code{data.table} of global measures for 5 | #' each graph. Each row will be for a different graph. 6 | #' 7 | #' @param bg.list A \code{brainGraphList} object, or a list of graph objects 8 | #' @export 9 | #' @return A \code{data.table} 10 | #' 11 | #' @name Graph Data Tables 12 | #' @rdname data_tables 13 | #' 14 | #' @seealso \code{\link[igraph]{graph_attr}, \link[igraph]{graph_attr_names}} 15 | 16 | graph_attr_dt <- function(bg.list) { 17 | name <- NULL 18 | if (is.brainGraphList(bg.list)) { 19 | level <- bg.list$level 20 | bg.list <- bg.list$graphs 21 | } else { 22 | if (!inherits(bg.list, 'list')) bg.list <- list(bg.list) 23 | level <- 'subject' 24 | } 25 | N <- length(bg.list) 26 | inds <- which(vapply(graph_attr(bg.list[[1L]]), is.numeric, logical(1L))) 27 | g.attr.num <- names(inds) 28 | if ('subnet' %in% g.attr.num) g.attr.num <- setdiff(g.attr.num, 'subnet') 29 | dt.G <- as.data.table(vapply(g.attr.num, function(x) 30 | vapply(bg.list, graph_attr, numeric(1L), x), numeric(N))) 31 | 32 | if (N == 1L) { 33 | dt.G <- as.data.table(t(dt.G)) 34 | setnames(dt.G, g.attr.num) 35 | } 36 | 37 | g.attrs <- graph_attr_names(bg.list[[1L]]) 38 | g.attrs.char <- c('name', 'atlas', 'modality', 'weighting', 'Group') 39 | for (x in g.attrs.char) { 40 | if (x %in% g.attrs) dt.G[, eval(x) := vapply(bg.list, graph_attr, character(1L), x)] 41 | } 42 | if (level == 'subject') { 43 | setnames(dt.G, 'name', getOption('bg.subject_id')) 44 | } else if (level == 'group') { 45 | dt.G[, name := NULL] 46 | } 47 | setnames(dt.G, 'Group', getOption('bg.group')) 48 | 49 | return(dt.G) 50 | } 51 | 52 | #' Create a data table with graph vertex measures 53 | #' 54 | #' \code{vertex_attr_dt} is a helper function that creates a \code{data.table} 55 | #' in which each row is a vertex and each column is a different network measure 56 | #' (degree, centrality, etc.). 57 | #' 58 | #' @inheritParams graph_attr_dt 59 | #' @export 60 | #' 61 | #' @rdname data_tables 62 | #' 63 | #' @seealso \code{\link[igraph]{vertex_attr}, \link[igraph]{vertex_attr_names}, 64 | #' \link[igraph]{graph_from_data_frame}} 65 | 66 | vertex_attr_dt <- function(bg.list) { 67 | name <- NULL 68 | if (is.brainGraphList(bg.list)) { 69 | level <- bg.list$level 70 | atlas <- bg.list$atlas 71 | bg.list <- bg.list$graphs 72 | } else { 73 | if (!inherits(bg.list, 'list')) bg.list <- list(bg.list) 74 | atlas <- bg.list[[1L]]$atlas 75 | level <- 'subject' 76 | } 77 | 78 | dt.V <- rbindlist(lapply(bg.list, as_data_frame, what='vertices')) 79 | cols.char <- names(which(vapply(vertex_attr(bg.list[[1L]]), is.character, logical(1L)))) 80 | cols.keep <- c('name', 'lobe', 'hemi', 'class', 'network', 'area', 81 | 'Anatomy', 'gyrus', 'subregion', 'Yeo_7network', 'Yeo_17network') 82 | cols.rem <- setdiff(cols.char, cols.keep) 83 | cols.rem <- c(cols.rem, 'x', 'y', 'z', 'x.mni', 'y.mni', 'z.mni', 84 | 'lobe.hemi', 'circle.layout', 'circle.layout.comm') 85 | dt.V[, eval(cols.rem) := NULL] 86 | setnames(dt.V, 'name', 'region') 87 | 88 | # Add some important graph attributes, as well 89 | Nv <- vcount(bg.list[[1L]]) 90 | g.attrs <- graph_attr_names(bg.list[[1L]]) 91 | g.attrs.char <- c('name', 'atlas', 'modality', 'weighting', 'Group', 'density', 'threshold') 92 | for (x in g.attrs.char) { 93 | if (x %in% g.attrs) dt.V[, eval(x) := rep(sapply(bg.list, graph_attr, x), each=Nv)] 94 | } 95 | if (level == 'subject') { 96 | setnames(dt.V, 'name', getOption('bg.subject_id')) 97 | } else if (level == 'group') { 98 | dt.V[, name := NULL] 99 | } 100 | setcolorder(dt.V, 101 | c('density', 'region', 'lobe', 'hemi', 102 | names(dt.V[, !c('density', 'region', 'lobe', 'hemi'), with=FALSE]))) 103 | setnames(dt.V, 'Group', getOption('bg.group')) 104 | 105 | return(dt.V) 106 | } 107 | -------------------------------------------------------------------------------- /R/distances.R: -------------------------------------------------------------------------------- 1 | #' Calculate weighted shortest path lengths 2 | #' 3 | #' Calculate graph or vertex average shortest path lengths. For vertices, this 4 | #' is just the row means of the distance matrix. For the graph-level, it is the 5 | #' overall mean of the distance matrix. 6 | #' 7 | #' By default, edge weights are not transformed (e.g., inverted). However, if 8 | #' set to \code{TRUE}, then the input graph must have a graph-level attribute 9 | #' called \code{'xfm.type'} or you must supply a value in the function call. If 10 | #' you supply a distance matrix (the \code{D} argument), it is not necessary to 11 | #' transform edge weights, as it is assumed the the distance matrix was 12 | #' calculated from a graph with transformed edge weights already. 13 | #' 14 | #' @param level Character string indicating whether to calculate vertex- or 15 | #' graph-level shortest path length. Default: \code{'graph'} 16 | #' @inheritParams efficiency 17 | #' @inheritParams xfm.weights 18 | #' @export 19 | #' @return Numeric vector (if \code{level='vertex'}) of each vertex's shortest 20 | #' path length, or a single number for the graph-level average 21 | 22 | mean_distance_wt <- function(g, level=c('graph', 'vertex'), weights=NULL, 23 | xfm=FALSE, xfm.type=NULL, D=NULL) { 24 | if (isTRUE(xfm)) { 25 | if (is.null(xfm.type)) { 26 | xfm.type <- if ('xfm.type' %in% graph_attr_names(g)) g$xfm.type else '1/w' 27 | } 28 | g <- xfm.weights(g, xfm.type) 29 | } 30 | weights <- check_weights(g, weights) 31 | level <- match.arg(level) 32 | if (is.null(D)) D <- distances(g, weights=weights) 33 | D[is.infinite(D)] <- diag(D) <- NA 34 | Lp <- switch(level, 35 | vertex=rowMeans(D, na.rm=TRUE), 36 | graph=mean(D, na.rm=TRUE)) 37 | Lp[is.nan(Lp)] <- 0 38 | return(Lp) 39 | } 40 | -------------------------------------------------------------------------------- /R/edge_asymmetry.R: -------------------------------------------------------------------------------- 1 | #' Calculate an asymmetry index based on edge counts 2 | #' 3 | #' Calculate an \emph{asymmetry index}, a ratio of intra-hemispheric edges in 4 | #' the left to right hemisphere of a graph for brain MRI data. 5 | #' 6 | #' The equation is: 7 | #' \deqn{A = \frac{E_{lh} - E_{rh}}{0.5 \times (E_{lh} + E_{rh})}} 8 | #' where \emph{lh} and \emph{rh} are left and right hemispheres, respectively. 9 | #' The range of this measure is \eqn{[-2, 2]} (although the limits will only be 10 | #' reached if all edges are in one hemisphere), with negative numbers 11 | #' indicating more edges in the right hemisphere, and a value of 0 indicating 12 | #' equal number of edges in each hemisphere. 13 | #' 14 | #' The \code{level} argument specifies whether to calculate asymmetry for each 15 | #' vertex, or for the whole hemisphere. 16 | #' 17 | #' @inheritParams efficiency 18 | #' @param level Character string indicating whether to calculate asymmetry for 19 | #' each region, or the hemisphere as a whole (default: \code{'hemi'}) 20 | #' @export 21 | #' 22 | #' @return A data table with edge counts for both hemispheres and the asymmetry 23 | #' index; if \code{level} is \emph{vertex}, the data table will have 24 | #' \code{vcount(g)} rows. 25 | #' 26 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 27 | 28 | edge_asymmetry <- function(g, level=c('hemi', 'vertex'), A=NULL) { 29 | stopifnot(is_igraph(g), 'hemi' %in% vertex_attr_names(g)) 30 | 31 | level <- match.arg(level) 32 | if (is.null(A)) A <- as_adj(g, sparse=FALSE, names=FALSE) 33 | L <- which(V(g)$hemi == 'L') 34 | R <- which(V(g)$hemi == 'R') 35 | if (level == 'hemi') { 36 | lh <- sum(A[L, L]) / 2 37 | rh <- sum(A[R, R]) / 2 38 | regions <- 'all' 39 | 40 | } else if (level == 'vertex') { 41 | lh <- rowSums(A[, L, drop=FALSE]) 42 | rh <- rowSums(A[, R, drop=FALSE]) 43 | regions <- V(g)$name 44 | } 45 | asymm <- data.table(region=regions, lh=lh, rh=rh) 46 | asymm[, asymm := 2 * (lh - rh) / (lh + rh)] 47 | return(asymm) 48 | } 49 | -------------------------------------------------------------------------------- /R/graph_efficiency.R: -------------------------------------------------------------------------------- 1 | #' Calculate graph global, local, or nodal efficiency 2 | #' 3 | #' This function calculates the global efficiency of a graph or the local or 4 | #' nodal efficiency of each vertex of a graph. 5 | #' 6 | #' Local efficiency for vertex \emph{i} is: 7 | #' \deqn{E_{local}(i) = \frac{1}{N} \sum_{i \in G} E_{global}(G_i)} 8 | #' where \eqn{G_i} is the subgraph of neighbors of \emph{i}, and \emph{N} is the 9 | #' number of vertices in that subgraph. 10 | #' 11 | #' Nodal efficiency for vertex \emph{i} is: 12 | #' \deqn{E_{nodal}(i) = \frac{1}{N-1} \sum_{j \in G} \frac{1}{d_{ij}}} 13 | #' 14 | #' Global efficiency for graph \emph{G} with \emph{N} vertices is: 15 | #' \deqn{E_{global}(G) = \frac{1}{N(N-1)} \sum_{i \ne j \in G} \frac{1}{d_{ij}}} 16 | #' where \eqn{d_{ij}} is the shortest path length between vertices \emph{i} and 17 | #' \emph{j}. Alternatively, global efficiency is equal to the mean of all nodal 18 | #' efficiencies. 19 | #' 20 | #' @param g An \code{igraph} graph object 21 | #' @param type Character string; either \code{local}, \code{nodal}, or 22 | #' \code{global}. Default: \code{local} 23 | #' @param weights Numeric vector of edge weights; if \code{NULL} (the default), 24 | #' and if the graph has edge attribute \code{weight}, then that will be used. 25 | #' To avoid using weights, this should be \code{NA}. 26 | #' @param xfm Logical indicating whether to transform the edge weights. Default: 27 | #' \code{FALSE} 28 | #' @param use.parallel Logical indicating whether or not to use \code{foreach}. 29 | #' Default: \code{TRUE} 30 | #' @param A Numeric matrix; the adjacency matrix of the input graph. Default: 31 | #' \code{NULL} 32 | #' @param D Numeric matrix; the graph's \dQuote{distance matrix} 33 | #' @inheritParams xfm.weights 34 | #' @export 35 | #' @importFrom Matrix rowSums 36 | #' @importFrom foreach getDoParRegistered 37 | #' @importFrom doParallel registerDoParallel 38 | #' 39 | #' @return A numeric vector of the efficiencies for each vertex of the graph 40 | #' (if \emph{type} is \code{local|nodal}) or a single number (if \emph{type} 41 | #' is \code{global}). 42 | #' 43 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 44 | #' @references Latora, V. and Marchiori, M. (2001) Efficient behavior of 45 | #' small-world networks. \emph{Phys Rev Lett}, \bold{87.19}, 198701. 46 | #' \doi{10.1103/PhysRevLett.87.198701} 47 | #' @references Latora, V. and Marchiori, M. (2003) Economic small-world 48 | #' behavior in weighted networks. \emph{Eur Phys J B}, \bold{32}, 249--263. 49 | #' \doi{10.1140/epjb/e2003-00095-5} 50 | 51 | efficiency <- function(g, type=c('local', 'nodal', 'global'), weights=NULL, 52 | xfm=FALSE, xfm.type=NULL, use.parallel=TRUE, A=NULL, D=NULL) { 53 | stopifnot(is_igraph(g)) 54 | i <- NULL 55 | if (isTRUE(xfm)) { 56 | if (is.null(xfm.type)) { 57 | xfm.type <- if ('xfm.type' %in% graph_attr_names(g)) g$xfm.type else '1/w' 58 | } 59 | g <- xfm.weights(g, xfm.type) 60 | } 61 | weights <- check_weights(g, weights) 62 | 63 | type <- match.arg(type) 64 | if (type == 'local') { 65 | e.attr <- weighted <- NULL 66 | if (is.null(weights)) { 67 | e.attr <- 'weight' 68 | weighted <- TRUE 69 | } 70 | if (is.null(A)) A <- as_adj(g, names=FALSE, sparse=FALSE, attr=e.attr) 71 | eff <- rep.int(0, dim(A)[1L]) 72 | verts <- which(rowSums((A > 0) + 0) > 1) 73 | X <- apply(A, 1L, function(x) which(x > 0)) 74 | if (is.matrix(X)) X <- as.list(data.frame(X)) # If the graph is complete 75 | 76 | if (length(verts) > 0L) { 77 | `%d%` <- `%do%` 78 | if (isTRUE(use.parallel)) { 79 | if (!getDoParRegistered()) { 80 | cl <- makeCluster(getOption('bg.ncpus')) 81 | registerDoParallel(cl) 82 | } 83 | `%d%` <- `%dopar%` 84 | } 85 | eff[verts] <- foreach(i=verts, .combine='c') %d% { 86 | g.sub <- graph_from_adjacency_matrix(A[X[[i]], X[[i]]], mode='undirected', weighted=weighted) 87 | efficiency(g.sub, 'global', weights=weights) 88 | } 89 | } 90 | } else { 91 | Nv <- vcount(g) 92 | if (is.null(D)) { 93 | if (Nv > 650) { 94 | D <- foreach(i=seq_len(Nv), .combine=rbind) %dopar% { 95 | distances(g, v=i, weights=weights) 96 | } 97 | } else { 98 | D <- distances(g, weights=weights) 99 | } 100 | } 101 | Dinv <- 1 / D 102 | eff <- colSums(Dinv * is.finite(Dinv), na.rm=TRUE) / (Nv - 1L) 103 | if (type == 'global') eff <- sum(eff) / length(eff) 104 | } 105 | return(eff) 106 | } 107 | -------------------------------------------------------------------------------- /R/hubs.R: -------------------------------------------------------------------------------- 1 | #' Calculate vertex hubness 2 | #' 3 | #' \code{hubness} calculates the \dQuote{hubness} (see reference) of the 4 | #' vertices in a graph. These are vertices which meet at least two of the 5 | #' following four criteria: 6 | #' \enumerate{ 7 | #' \item Have high degree/strength 8 | #' \item Have high betweenness centrality 9 | #' \item Have low clustering coefficient 10 | #' \item Have low average path length 11 | #' } 12 | #' For each criterion, \dQuote{high} or \dQuote{low} means \dQuote{in the top 13 | #' 20\%} across all vertices. Vertices meeting any of the criteria get a value 14 | #' of 1 for that metric; these are summed to yield the hubness score which 15 | #' ranges from 0-4. As in the reference article, vertices with a score of 2 or 16 | #' higher are to be considered hubs, although that determination isn't made in 17 | #' this function. 18 | #' 19 | #' @param prop.keep Numeric (between 0 and 1) indicating the proportion of 20 | #' vertices to consider as having a high score. Default: 0.2 (20\%) 21 | #' @inheritParams efficiency 22 | #' @inheritParams xfm.weights 23 | #' @export 24 | #' 25 | #' @return A numeric vector with the vertices' hubness score 26 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 27 | #' @references van den Heuvel, M.P. and Mandl, R.C.W. and Stam, C.J. and Kahn, 28 | #' R.S. and Pol, H.E.H. (2010) Aberrant frontal and temporal complex network 29 | #' structure in schizophrenia: a graph theoretical analysis. \emph{The Journal 30 | #' of Neuroscience}, \bold{30(47)}, 15915--15926. 31 | #' \doi{10.1523/JNEUROSCI.2874-10.2010} 32 | 33 | hubness <- function(g, xfm.type=g$xfm.type, weights=NULL, prop.keep=0.2) { 34 | stopifnot(is_igraph(g), prop.keep <= 1, prop.keep >= 0) 35 | Nv <- vcount(g) 36 | cutoff <- round(prop.keep * Nv) 37 | weights <- check_weights(g, weights) 38 | 39 | S <- strength(g, weights=weights) 40 | Cp <- transitivity(g, type='weighted', isolates='zero', weights=weights) 41 | btwn <- centr_betw(g)$res 42 | 43 | vattr <- 'Lp' 44 | if (is_weighted(g)) { 45 | g <- xfm.weights(g, xfm.type) 46 | vattr <- 'Lp.wt' 47 | } 48 | if (vattr %in% vertex_attr_names(g)) { 49 | Lp <- vertex_attr(g, vattr) 50 | } else { 51 | Lp <- mean_distance_wt(g, 'vertex', weights=weights) 52 | } 53 | 54 | M <- matrix(c(-S, -btwn, Cp, Lp), nrow=Nv, ncol=4L) 55 | H <- matrix(0L, nrow=Nv, ncol=4L) 56 | for (i in 1L:4L) H[order(M[, i])[1L:cutoff], i] <- 1L 57 | hubs <- rowSums(H) 58 | return(hubs) 59 | } 60 | -------------------------------------------------------------------------------- /R/plot_group_means.R: -------------------------------------------------------------------------------- 1 | #' Plot group distributions of volumetric measures for a given brain region 2 | #' 3 | #' This function takes a \dQuote{tidied} dataset of cortical volumetric measures 4 | #' (thickness, volume, LGI, etc.) and plots a histogram or violin plot for 1 or 5 | #' more groups, and of 1 or more brain regions. 6 | #' 7 | #' @param dat A data table of volumetric data; needs columns for 'Group', 8 | #' 'region', and 'value' 9 | #' @param regions A vector of character strings or integers of the brain 10 | #' region(s) to plot; if integer, the region(s) is/are chosen from the input 11 | #' data table based on the index 12 | #' @param type A character string indicating the plot type; either 'histogram' 13 | #' or 'violin' 14 | #' @param all.vals A logical indicating whether or not to plot horizontal lines 15 | #' for all observations (only valid for 'violin' plots) (default: TRUE) 16 | #' @param modality A character string indicating the type of volumetric measure 17 | #' ('thickness', 'volume', 'lgi', or 'area') 18 | #' @export 19 | #' 20 | #' @return A \code{trellis} or \code{ggplot} object 21 | #' @family Structural covariance network functions 22 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 23 | 24 | plot_volumetric <- function(dat, regions, type=c('violin', 'histogram'), 25 | all.vals=TRUE, 26 | modality=c('thickness', 'volume', 'lgi', 'area')) { 27 | region <- value <- Group <- ..density.. <- avg <- group.mean <- bwidth <- 28 | breaks <- x <- width <- NULL 29 | if (!is.character(regions)) regions <- dat[, levels(region)][regions] 30 | stopifnot(all(regions %in% dat[, levels(region)])) 31 | 32 | modality <- match.arg(modality) 33 | ax.lab <- switch(modality, 34 | thickness='Thickness (mm)', 35 | volume=expression(paste('Volume (', mm^{3}, ')')), 36 | lgi='Local Gyrification Index', 37 | area=expression(paste('Surface area (', mm^{2}, ')'))) 38 | 39 | subDT <- dat[region %in% regions] 40 | type <- match.arg(type) 41 | if (type == 'histogram') { 42 | if (!all(vapply(c('scales', 'ggplot2'), requireNamespace, logical(1L), quietly=TRUE))) { 43 | stop('Please install the "scales" and "ggplot2" packages to plot with histograms.') 44 | } 45 | # Allow for variable bin widths 46 | groups <- subDT[, levels(Group)] 47 | setkey(subDT, region, Group) 48 | breaksdt <- subDT[, list(breaks=pretty(range(value), n=nclass.FD(value))), 49 | by=list(Group, region)] 50 | breaksdt[, bwidth := .SD[1L:2L, diff(breaks)], by=list(Group, region)] 51 | subDT[, bwidth := rep(breaksdt[, min(bwidth), by=region]$V1, 52 | times=subDT[, .N, by=region]$N)] 53 | # A partial recreation of Hadley's ggplot2:::bin function 54 | create_bins <- function(x, binwidth) { 55 | breaks <- sort(scales::fullseq(range(x), binwidth, pad=TRUE)) 56 | bins <- cut(x, breaks, include.lowest=TRUE, right=FALSE) 57 | left <- breaks[-length(breaks)] 58 | right <- breaks[-1L] 59 | x <- (left + right) / 2 60 | width <- diff(breaks) 61 | 62 | out <- data.frame(count=as.numeric(tapply(rep(1, length(bins)), bins, sum, 63 | na.rm=TRUE)), 64 | x=x, 65 | width=width) 66 | out$count[is.na(out$count)] <- 0 67 | out$density <- out$count / out$width / sum(abs(out$count), na.rm=TRUE) 68 | out$ndensity <- out$density / max(abs(out$density), na.rm=TRUE) 69 | out$ncount <- out$count / max(abs(out$count), na.rm=TRUE) 70 | return(out) 71 | } 72 | my.df <- subDT[, create_bins(value, unique(bwidth)), by=list(Group, region)] 73 | 74 | meandt <- subDT[, list(avg=mean(value)), by=list(Group, region)] 75 | vol.plot <- ggplot2::ggplot(my.df) + 76 | ggplot2::geom_histogram(ggplot2::aes(x, y=density, width=width, fill=Group), 77 | alpha=0.6, position='dodge', stat='identity') + 78 | ggplot2::geom_vline(data=meandt, ggplot2::aes(xintercept=avg, col=Group), lty=2, size=0.5) + 79 | ggplot2::geom_density(data=subDT, ggplot2::aes(x=value, col=Group), size=0.8) + 80 | ggplot2::facet_wrap(~ region, scales='free') + 81 | ggplot2::theme(legend.position=c(1, 1), legend.justification=c(1, 1), 82 | legend.background=ggplot2::element_rect(size=0.5)) + 83 | ggplot2::xlab(ax.lab) 84 | 85 | } else if (type == 'violin') { 86 | # 'base' plotting 87 | if (!requireNamespace('ggplot2', quietly=TRUE)) { 88 | gID <- getOption('bg.group') 89 | vol.plot <- bwplot(value ~ get(gID) | region, data=subDT, panel=panel.violin, xlab=gID, ylab=ax.lab) 90 | 91 | # 'ggplot2' plotting 92 | } else { 93 | vol.plot <- ggplot2::ggplot(subDT, ggplot2::aes(x=Group, y=value, fill=Group)) + 94 | ggplot2::geom_violin(trim=FALSE) + 95 | ggplot2::facet_wrap(~ region, scales='free_y') + 96 | ggplot2::theme(legend.position='none') + 97 | ggplot2::ylab(ax.lab) 98 | if (isTRUE(all.vals)) { 99 | subDT[, group.mean := mean(value), by=list(Group, region)] 100 | vol.plot <- vol.plot + 101 | ggplot2::geom_segment(ggplot2::aes(x=as.numeric(Group)-0.1, xend=as.numeric(Group)+0.1, 102 | y=value, yend=value), col='black') + 103 | ggplot2::geom_segment(ggplot2::aes(x=as.numeric(Group)-0.3, xend=as.numeric(Group)+0.3, 104 | y=group.mean, yend=group.mean), col='black') 105 | } else { 106 | vol.plot <- vol.plot + ggplot2::geom_boxplot(width=0.1) 107 | } 108 | } 109 | } 110 | return(vol.plot) 111 | } 112 | -------------------------------------------------------------------------------- /R/plot_vertex_measures.R: -------------------------------------------------------------------------------- 1 | #' Plot vertex-level graph measures at a single density or threshold 2 | #' 3 | #' Creates boxplots of a single vertex-level graph measure at a single density 4 | #' or threshold, grouped by the variable specified by \code{group.by} and 5 | #' optionally faceted by another variable (e.g., \emph{lobe} or \emph{network}). 6 | #' 7 | #' @param measure A character string of the graph measure to plot 8 | #' @param facet.by Character string indicating the variable to facet by (if 9 | #' any). Default: \code{NULL} 10 | #' @param group.by Character string indicating which variable to group the data 11 | #' by. Default: \code{getOption('bg.group')} 12 | #' @param type Character string indicating the plot type. Default: 13 | #' \code{'violin'} 14 | #' @param show.points Logical indicating whether or not to show individual data 15 | #' points (default: FALSE) 16 | #' @param ylabel A character string for the y-axis label 17 | #' @param ... Arguments passed to \code{geom_boxplot} or \code{geom_violin} 18 | #' @inheritParams plot_brainGraph_multi 19 | #' @export 20 | #' 21 | #' @return A \code{trellis} or \code{ggplot} object 22 | #' 23 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 24 | #' @examples 25 | #' \dontrun{ 26 | #' p.deg <- plot_vertex_measures(g[[1]], facet.by='network', measure='degree') 27 | #' } 28 | 29 | plot_vertex_measures <- function(g.list, measure, facet.by=NULL, group.by=getOption('bg.group'), 30 | type=c('violin', 'boxplot'), 31 | show.points=FALSE, ylabel=measure, ...) { 32 | variable <- value <- NULL 33 | gID <- getOption('bg.group') 34 | 35 | if (!is.brainGraphList(g.list)) try(g.list <- as_brainGraphList(g.list)) 36 | DT <- vertex_attr_dt(g.list) 37 | stopifnot(all(hasName(DT, c(measure, group.by)))) 38 | idvars <- c('atlas', 'modality', 'weighting', getOption('bg.subject_id'), gID, 'threshold', 39 | 'density', 'region', 'lobe', 'hemi', 'class', 'network') 40 | idvars <- idvars[which(hasName(DT, idvars))] 41 | DT.m <- melt(DT, id.vars=idvars) 42 | setnames(DT.m, group.by, 'group.by') 43 | 44 | type <- match.arg(type) 45 | 46 | # 'base' plotting 47 | if (!requireNamespace('ggplot2', quietly=TRUE)) { 48 | panelfun <- if (type == 'violin') panel.violin else panel.bwplot 49 | p <- bwplot(value ~ group.by | get(facet.by), data=DT.m[variable == measure], 50 | panel=panelfun, 51 | xlab=group.by, ylab=ylabel) 52 | 53 | # 'ggplot2' plotting 54 | } else { 55 | p <- ggplot2::ggplot(DT.m[variable == measure], ggplot2::aes(x=group.by, y=value, fill=group.by)) 56 | p <- if (type == 'violin') p + ggplot2::geom_violin(...) else p + ggplot2::geom_boxplot(...) 57 | 58 | if (!is.null(facet.by)) { 59 | stopifnot(hasName(DT, facet.by)) 60 | p <- p + ggplot2::facet_wrap(as.formula(paste('~', facet.by)), scales='free_y') 61 | } 62 | if (isTRUE(show.points)) { 63 | p <- p + ggplot2::geom_jitter(position=ggplot2::position_jitter(width=0.1, height=0)) 64 | } 65 | p <- p + ggplot2::labs(x=group.by, y=ylabel) + ggplot2::theme(legend.position='none') 66 | } 67 | 68 | return(p) 69 | } 70 | -------------------------------------------------------------------------------- /R/robustness.R: -------------------------------------------------------------------------------- 1 | #' Analysis of network robustness 2 | #' 3 | #' This function performs a \dQuote{targeted attack} of a graph or a 4 | #' \dQuote{random failure} analysis, calculating the size of the largest 5 | #' component after edge or vertex removal. 6 | #' 7 | #' In a targeted attack, it will sort the vertices by either degree or 8 | #' betweenness centrality (or sort edges by betweenness), and successively 9 | #' remove the top vertices/edges. Then it calculates the size of the largest 10 | #' component. 11 | #' 12 | #' In a random failure analysis, vertices/edges are removed in a random order. 13 | #' 14 | #' @param g An \code{igraph} graph object 15 | #' @param type Character string; either \code{'vertex'} or \code{'edge'} 16 | #' removals. Default: \code{vertex} 17 | #' @param measure Character string; sort by either \code{'btwn.cent'} or 18 | #' \code{'degree'}, or choose \code{'random'}. Default: \code{'btwn.cent'} 19 | #' @param N Integer; the number of iterations if \code{'random'} is chosen. 20 | #' Default: \code{1e3} 21 | #' @export 22 | #' @importFrom foreach getDoParRegistered 23 | #' @importFrom doParallel registerDoParallel 24 | #' 25 | #' @return Data table with elements: 26 | #' \item{type}{Character string describing the type of analysis performed} 27 | #' \item{measure}{The input argument \code{measure}} 28 | #' \item{comp.size}{The size of the largest component after edge/vertex 29 | #' removal} 30 | #' \item{comp.pct}{Numeric vector of the ratio of maximal component size after 31 | #' each removal to the observed graph's maximal component size} 32 | #' \item{removed.pct}{Numeric vector of the ratio of vertices/edges removed} 33 | #' \item{Group}{Character string indicating the subject group, if applicable} 34 | #' 35 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 36 | #' @references Albert, R. and Jeong, H. and Barabasi, A. (2000) Error and attack 37 | #' tolerance of complex networks. \emph{Nature}, \bold{406}, 378--381. 38 | #' \doi{10.1038/35019019} 39 | 40 | robustness <- function(g, type=c('vertex', 'edge'), 41 | measure=c('btwn.cent', 'degree', 'random'), N=1e3) { 42 | i <- NULL 43 | stopifnot(is_igraph(g)) 44 | type <- match.arg(type) 45 | measure <- match.arg(measure) 46 | orig_max <- max(components(g)$csize) 47 | n <- switch(type, vertex=vcount(g), edge=ecount(g)) 48 | removed.pct <- seq.int(0, 1, length.out=n+1L) 49 | if (measure == 'random') { 50 | otype <- paste('Random', type, 'removal') 51 | rand <- matrix(rep.int(seq_len(n), N), nrow=n, ncol=N) 52 | index <- apply(rand, 2L, sample) 53 | } else { 54 | otype <- paste('Targeted', type, 'attack') 55 | max.comp.removed <- rep.int(orig_max, n) 56 | } 57 | if (!getDoParRegistered()) { 58 | cl <- makeCluster(getOption('bg.ncpus')) 59 | registerDoParallel(cl) 60 | } 61 | if (type == 'vertex') { 62 | if (measure == 'random') { 63 | max.comp <- foreach(i=seq_len(N), .combine='cbind') %dopar% { 64 | ord <- V(g)$name[index[, i]] 65 | tmp <- rep.int(orig_max, n) 66 | for (j in seq_len(n - 1L)) { 67 | g <- delete_vertices(g, ord[j]) 68 | tmp[j + 1L] <- max(components(g)$csize) 69 | } 70 | tmp 71 | } 72 | max.comp.removed <- rowMeans(max.comp) 73 | 74 | } else { 75 | val <- if (measure == 'btwn.cent') centr_betw(g)$res else check_degree(g) 76 | ord <- V(g)$name[order(val, decreasing=TRUE)] 77 | for (j in seq_len(n - 1L)) { 78 | g <- delete_vertices(g, ord[j]) 79 | max.comp.removed[j + 1L] <- max(components(g)$csize) 80 | } 81 | } 82 | 83 | } else { 84 | if (measure == 'degree') { 85 | stop('For edge attacks, must choose "btwn.cent" or "random"!') 86 | } else if (measure == 'random') { 87 | max.comp <- foreach(i=seq_len(N), .combine='cbind') %dopar% { 88 | el <- as_edgelist(g, names=FALSE)[index[, i], ] 89 | tmp <- rep.int(orig_max, n) 90 | for (j in seq_len(n - 1L)) { 91 | g.rand <- graph_from_edgelist(el[-seq_len(j), , drop=FALSE], directed=FALSE) 92 | tmp[j + 1L] <- max(components(g.rand)$csize) 93 | } 94 | tmp 95 | } 96 | max.comp.removed <- rowMeans(max.comp) 97 | 98 | } else { 99 | ord <- order(E(g)$btwn, decreasing=TRUE) 100 | el <- as_edgelist(g, names=FALSE)[ord, ] 101 | for (j in seq_len(n - 1L)) { 102 | g <- graph_from_edgelist(el[-seq_len(j), , drop=FALSE], directed=FALSE) 103 | max.comp.removed[j + 1L] <- max(components(g)$csize) 104 | } 105 | } 106 | 107 | } 108 | max.comp.removed <- c(max.comp.removed, 0) 109 | comp.pct <- max.comp.removed / orig_max 110 | out <- data.table(type=otype, measure=measure, comp.size=max.comp.removed, 111 | comp.pct=comp.pct, removed.pct=removed.pct) 112 | if ('name' %in% graph_attr_names(g)) out[, eval(getOption('bg.group')) := g$name] 113 | return(out) 114 | } 115 | -------------------------------------------------------------------------------- /R/s_core.R: -------------------------------------------------------------------------------- 1 | #' Calculate the s-core of a network 2 | #' 3 | #' Calculates the \emph{s-core} decomposition of a network. This is analogous to 4 | #' the \emph{k-core} decomposition, but takes into account the \emph{strength} 5 | #' of vertices (i.e., in weighted networks). If an unweighted network is 6 | #' supplied, then the output of the function \code{\link[igraph]{coreness}} is 7 | #' returned. 8 | #' 9 | #' The \emph{s-core} consists of all vertices \eqn{i} with \eqn{s_i > s}, where 10 | #' \eqn{s} is some threshold value. The \eqn{s_0} core is the entire network, 11 | #' and the threshold value of the \eqn{s_{n}} core is 12 | #' \deqn{s_{n-1} = min_i s_i} 13 | #' for all vertices \eqn{i} in the \eqn{s_{n-1}} core. 14 | #' 15 | #' Note that in networks with a wide distribution of vertex strengths, in which 16 | #' there are almost as many unique values as there are vertices, then several 17 | #' separate cores will have a single vertex. See the reference provided below. 18 | #' 19 | #' @param W Numeric matrix of edge weights (default: \code{NULL}) 20 | #' @inheritParams efficiency 21 | #' @export 22 | #' 23 | #' @return Integer vector of the vertices' \emph{s-core} membership 24 | #' 25 | #' @seealso \code{\link[igraph]{coreness}} 26 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 27 | #' @references Eidsaa, M and Almaas, E. (2013) s-core network decomposition: a 28 | #' generalization of k-core analysis to weighted networks. \emph{Physical 29 | #' Review E}, \bold{88}, 062819. 30 | #' \doi{10.1103/PhysRevE.88.062819} 31 | 32 | s_core <- function(g, W=NULL) { 33 | stopifnot(is_igraph(g)) 34 | if (!is_weighted(g)) return(coreness(g)) 35 | 36 | if (is.null(W)) W <- as_adj(g, names=FALSE, sparse=FALSE, attr='weight') 37 | ct <- 1L 38 | s.core <- vector('integer', length=dim(W)[1L]) 39 | repeat { 40 | str.tmp <- colSums(W) 41 | s.thr <- min(str.tmp[which(str.tmp > 0)]) 42 | v.remove <- which(str.tmp <= s.thr & str.tmp > 0) 43 | if (length(v.remove) > 0L) { 44 | s.core[v.remove] <- ct 45 | W[v.remove, ] <- W[, v.remove] <- 0 46 | ct <- ct + 1L 47 | } 48 | if (sum(colSums(W) > 0) == 0L) break 49 | } 50 | return(s.core) 51 | } 52 | -------------------------------------------------------------------------------- /R/small_world.R: -------------------------------------------------------------------------------- 1 | #' Calculate graph small-worldness 2 | #' 3 | #' \code{small.world} calculates the normalized characteristic path length and 4 | #' clustering coefficient based on observed and random graphs, used to calculate 5 | #' the small-world coefficient \eqn{\sigma}. 6 | #' 7 | #' @param g.list A \code{brainGraphList} object or list of graphs 8 | #' @param rand List of (lists of) equivalent random graphs (output from 9 | #' \code{\link{sim.rand.graph.par}}) 10 | #' @export 11 | #' 12 | #' @return A \code{data.table} with the following components: 13 | #' \item{density}{The range of density thresholds used.} 14 | #' \item{N}{The number of random graphs that were generated.} 15 | #' \item{Lp,Lp.rand,Lp.norm}{The observed, average random, and normalized 16 | #' characteristic path length.} 17 | #' \item{Cp,Cp.rand,Cp.norm}{The observed, average random, and normalized 18 | #' clustering coefficient.} 19 | #' \item{sigma}{The small-world measure of the graph.} 20 | #' 21 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 22 | #' @references Watts, D.J. and Strogatz S.H. (1998) Collective dynamics of 23 | #' "small-world" networks. \emph{Nature}, \bold{393}, 440--442. 24 | #' \doi{10.1038/30918} 25 | 26 | small.world <- function(g.list, rand) { 27 | level <- NULL 28 | sID <- getOption('bg.subject_id') 29 | gID <- getOption('bg.group') 30 | 31 | if (is_igraph(g.list) || is.brainGraph(g.list)) { 32 | g.list <- list(g.list) 33 | } else if (is.brainGraphList(g.list)) { 34 | level <- g.list$level 35 | g.list <- g.list$graphs 36 | rand <- rand$graphs 37 | } else if (!is.list(g.list)) { 38 | stop('Input should be a list, igraph, brainGraph, or brainGraphList object.') 39 | } 40 | 41 | Lp <- vapply(g.list, graph_attr, numeric(1L), 'Lp') 42 | Cp <- vapply(g.list, graph_attr, numeric(1L), 'Cp') 43 | densities <- vapply(g.list, graph_attr, numeric(1L), 'density') 44 | 45 | N <- lengths(rand) 46 | Lp.rand <- colMeans(vapply(rand, vapply, numeric(N[1L]), graph_attr, numeric(1L), 'Lp')) 47 | Cp.rand <- colMeans(vapply(rand, vapply, numeric(N[1L]), graph_attr, numeric(1L), 'Cp')) 48 | 49 | Cp.norm <- Cp / Cp.rand 50 | Lp.norm <- Lp / Lp.rand 51 | sigma <- Cp.norm / Lp.norm 52 | DT <- data.table(density=densities, N, Lp, Cp, Lp.rand, Cp.rand, 53 | Lp.norm, Cp.norm, sigma) 54 | if (!is.null(names(g.list))) { 55 | DT[, eval(sID) := names(g.list)] 56 | } 57 | attrs <- c('Group', 'threshold') 58 | for (x in attrs) { 59 | if (x %in% graph_attr_names(g.list[[1L]])) { 60 | DT[, eval(x) := sapply(g.list, graph_attr, x)] 61 | } 62 | } 63 | if (hasName(DT, 'Group')) setnames(DT, 'Group', gID) 64 | if (level == 'group' && DT[, all(get(sID) == get(gID))]) DT[, eval(sID) := NULL] 65 | return(DT) 66 | } 67 | -------------------------------------------------------------------------------- /R/spatial_dist.R: -------------------------------------------------------------------------------- 1 | #' Calculate Euclidean distance of edges and vertices 2 | #' 3 | #' \code{edge_spatial_dist} calculates the Euclidean distance of an 4 | #' \code{igraph} graph object's edges. The distances are in \emph{mm} and based 5 | #' on MNI space. These distances are \emph{NOT} along the cortical surface, so 6 | #' can only be considered approximations, particularly concerning 7 | #' inter-hemispheric connections. The input graph must have \emph{atlas} as a 8 | #' graph-level attribute. 9 | #' 10 | #' @param g An \code{igraph} graph object 11 | #' @export 12 | #' 13 | #' @return \code{edge_spatial_dist} - a numeric vector with length equal to the 14 | #' edge count of the input graph, consisting of the Euclidean distance (in 15 | #' \emph{mm}) of each edge 16 | #' 17 | #' @name Graph Distances 18 | #' @rdname spatial_dist 19 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 20 | 21 | edge_spatial_dist <- function(g) { 22 | stopifnot(is_igraph(g), 'atlas' %in% graph_attr_names(g)) 23 | 24 | name <- x.mni <- y.mni <- z.mni <- NULL 25 | coords <- get(g$atlas)[, list(name, x.mni, y.mni, z.mni)] 26 | setkey(coords, name) 27 | es <- as_edgelist(g) 28 | dists <- sqrt(rowSums((coords[es[, 2L], list(x.mni, y.mni, z.mni)] - 29 | coords[es[, 1L], list(x.mni, y.mni, z.mni)])^2)) 30 | } 31 | 32 | #' Calculate average Euclidean distance for each vertex 33 | #' 34 | #' \code{vertex_spatial_dist} calculates, for each vertex of a graph, the 35 | #' average Euclidean distance across all of that vertex's connections. 36 | #' 37 | #' @inheritParams edge_spatial_dist 38 | #' @export 39 | #' @importFrom Matrix colSums 40 | #' 41 | #' @return \code{vertex_spatial_dist} - a named numeric vector with length equal 42 | #' to the number of vertices, consisting of the average distance (in 43 | #' \emph{mm}) for each vertex 44 | #' 45 | #' @rdname spatial_dist 46 | #' @references Alexander-Bloch, A.F. and Vertes, P.E. and Stidd, R. et al. 47 | #' (2013) The anatomical distance of functional connections predicts brain 48 | #' network topology in health and schizophrenia. \emph{Cerebral Cortex}, 49 | #' \bold{23}, 127--138. \doi{10.1093/cercor/bhr388} 50 | 51 | vertex_spatial_dist <- function(g) { 52 | stopifnot(is_igraph(g), 'dist' %in% edge_attr_names(g)) 53 | 54 | A <- as_adj(g, names=FALSE, attr='dist') 55 | dists <- colSums(A) / colSums(A != 0) 56 | return(dists) 57 | } 58 | -------------------------------------------------------------------------------- /R/sysdata.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/R/sysdata.rda -------------------------------------------------------------------------------- /R/vulnerability.R: -------------------------------------------------------------------------------- 1 | #' Calculate graph vulnerability 2 | #' 3 | #' This function calculates the \emph{vulnerability} of the vertices of a graph. 4 | #' Here, vulnerability is considered to be the proportional drop in global 5 | #' efficiency when a given vertex is removed from the graph. The vulnerability 6 | #' of the graph is considered the maximum across all vertices. 7 | #' 8 | #' @param g An \code{igraph} graph object 9 | #' @param use.parallel Logical indicating whether or not to use \emph{foreach} 10 | #' (default: \code{TRUE}) 11 | #' @param weighted Logical indicating whether weighted efficiency should be 12 | #' calculated (default: \code{FALSE}) 13 | #' @export 14 | #' @importFrom Matrix rowSums 15 | #' @importFrom foreach getDoParRegistered 16 | #' @importFrom doParallel registerDoParallel 17 | #' 18 | #' @return A numeric vector of length equal to the vertex count of \emph{g} 19 | #' 20 | #' @seealso \code{\link{efficiency}} 21 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 22 | #' @references Latora, V. and Marchiori, M. (2005) Variability and protection of 23 | #' infrastructure networks. \emph{Physical Review E}, \bold{71}, 015103. 24 | #' \doi{10.1103/physreve.71.015103} 25 | 26 | vulnerability <- function(g, use.parallel=TRUE, weighted=FALSE) { 27 | i <- NULL 28 | stopifnot(is_igraph(g)) 29 | if (isTRUE(weighted)) { 30 | weights <- NULL 31 | g.attr <- 'E.global.wt' 32 | e.attr <- 'weight' 33 | } else { 34 | weights <- NA 35 | g.attr <- 'E.global' 36 | e.attr <- NULL 37 | weighted <- NULL 38 | } 39 | A <- as_adj(g, sparse=FALSE, names=FALSE, attr=e.attr) 40 | calc <- g.attr %in% graph_attr_names(g) 41 | E.global <- if (calc) efficiency(g, 'global', weights) else graph_attr(g, g.attr) 42 | 43 | vuln <- rep.int(0, dim(A)[1L]) 44 | verts <- which(rowSums((A > 0) + 0L) != 0L) 45 | `%d%` <- `%do%` 46 | if (isTRUE(use.parallel)) { 47 | if (!getDoParRegistered()) { 48 | cl <- makeCluster(getOption('bg.ncpus')) 49 | registerDoParallel(cl) 50 | } 51 | `%d%` <- `%dopar%` 52 | } 53 | vuln[verts] <- foreach(i=verts, .combine='c') %d% { 54 | g.tmp <- graph_from_adjacency_matrix(A[-i, -i, drop=FALSE], mode='undirected', weighted=weighted) 55 | E.global.tmp <- efficiency(g.tmp, 'global', weights) 56 | 1 - (E.global.tmp / E.global) 57 | } 58 | return(vuln) 59 | } 60 | -------------------------------------------------------------------------------- /R/write_brainnet.R: -------------------------------------------------------------------------------- 1 | #' Write files to be used for visualization with BrainNet Viewer 2 | #' 3 | #' Write the \code{.node} and \code{.edge} files necessary for visualization 4 | #' with the BrainNet Viewer software. 5 | #' 6 | #' @details For the \code{.node} file, there are 6 columns: 7 | #' \itemize{ 8 | #' \item \emph{Columns 1-3}: Vertex x-, y-, and z-coordinates 9 | #' \item \emph{Column 4}: Vertex color 10 | #' \item \emph{Column 5}: Vertex size 11 | #' \item \emph{Column 6}: Vertex label 12 | #' } 13 | #' The \code{.edge} file is the graph's associated adjacency matrix; a weighted 14 | #' adjacency matrix can be returned by using the \code{edge.wt} argument. 15 | #' 16 | #' @param g The \code{igraph} graph object of interest 17 | #' @param vcolor Character string indicating how to color the vertices (default: 18 | #' \code{'none'}) 19 | #' @param vsize Character string indicating what size the vertices should be; 20 | #' can be any vertex-level attribute (default: \code{'constant'}) 21 | #' @param edge.wt Character string indicating the edge attribute to use to 22 | #' return a weighted adjacency matrix (default: \code{NULL}) 23 | #' @param file.prefix Character string for the basename of the \code{.node} and 24 | #' \code{.edge} files that are written 25 | #' @export 26 | #' 27 | #' @author Christopher G. Watson, \email{cgwatson@@bu.edu} 28 | #' @references Xia, M. and Wang, J. and He, Y. (2013). BrainNet Viewer: a 29 | #' network visualization tool for human brain connectomics. \emph{PLoS One}, 30 | #' \bold{8(7)}, e68910. \doi{10.1371/journal.pone.0068910} 31 | #' @examples 32 | #' \dontrun{ 33 | #' write_brainnet(g, vcolor='community', vsize='degree', edge.wt='t.stat') 34 | #' } 35 | 36 | write_brainnet <- function(g, vcolor='none', vsize='constant', edge.wt=NULL, file.prefix='') { 37 | x.mni <- y.mni <- z.mni <- NULL 38 | stopifnot(is.brainGraph(g)) 39 | 40 | atlas.dt <- get(g$atlas) 41 | coords <- round(atlas.dt[, cbind(x.mni, y.mni, z.mni)]) 42 | 43 | vnames <- vertex_attr_names(g) 44 | if (vcolor == 'none') { 45 | cols <- rep.int(1L, vcount(g)) 46 | } else { 47 | stopifnot(vcolor %in% vnames) 48 | cols <- as.integer(factor(vertex_attr(g, vcolor))) 49 | } 50 | 51 | if (vsize == 'constant') { 52 | size <- 5L 53 | } else { 54 | stopifnot(vsize %in% vnames) 55 | size <- vertex_attr(g, vsize) 56 | } 57 | 58 | if (file.prefix == '') { 59 | nodefile <- paste0(quote(g), '_', vsize, '_', vcolor, '.node') 60 | edgefile <- paste0(quote(g), '.edge') 61 | } else { 62 | nodefile <- paste0(file.prefix, '.node') 63 | edgefile <- paste0(file.prefix, '.edge') 64 | } 65 | fwrite(cbind(coords, cols, size, V(g)$name), 66 | file=nodefile, quote=FALSE, sep='\t', col.names=FALSE) 67 | 68 | fwrite(as_adj(g, sparse=FALSE, attr=edge.wt), 69 | file=edgefile, quote=FALSE, sep='\t', col.names=FALSE) 70 | } 71 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | #' Default options for brainGraph 2 | #' 3 | #' brainGraph is a package for performing \emph{graph theory analysis} of brain 4 | #' MRI data. 5 | #' 6 | #' @section Package options: 7 | #' 8 | #' brainGraph uses the following \code{\link{options}} to configure behavior: 9 | #' \itemize{ 10 | #' \item \code{bg.subject_id}: character string specifying the name your 11 | #' project/study uses as a subject identifier. All imported data (e.g., 12 | #' covariates tables) \emph{MUST} have a column matching this. One possible 13 | #' alternative is \code{'participant_id'}, recommended by BIDS. Default: 14 | #' \code{'Study.ID'} 15 | #' \item \code{bg.group}: character string specifying the name your 16 | #' project/study uses as a group identifier. All imported data (e.g., 17 | #' covariates tables) \emph{MUST} have a column matching this. One possible 18 | #' alternative is \code{'group'}, recommended by BIDS. Default: 19 | #' \code{'Group'} 20 | #' \item \code{bg.session}: character string specifying the name your 21 | #' project/study uses as a \dQuote{time} or session identifier, in the case 22 | #' of longitudinal studies. All imported data (e.g., covariates tables) 23 | #' \emph{MUST} have a column matching this. One possible alternative is 24 | #' \code{'session_id'}, recommended by BIDS. Default: \code{'Time'} 25 | #' \item \code{bg.progress}: logical indicating whether to show progress bars 26 | #' for functions that provide the option. Default: \code{TRUE} 27 | #' \item \code{bg.ncpus}: integer indicating the number of cores to use for 28 | #' parallel operations. Only used if you have not already registered a 29 | #' parallel backend (see Chapter 5 of the User Guide or 30 | #' \url{https://github.com/cwatson/brainGraph/blob/master/README.md} for 31 | #' examples). Default: \code{2L} 32 | #' } 33 | #' @docType package 34 | #' @name brainGraph 35 | #' @aliases brainGraph-options 36 | NULL 37 | 38 | # Default values for options 39 | bg.options <- list( 40 | bg.subject_id='Study.ID', 41 | bg.group='Group', 42 | bg.session='Time', 43 | bg.progress=TRUE, 44 | bg.ncpus=2L 45 | ) 46 | 47 | # Hack to avoid WARNING or NOTE w/ Rcheck 48 | # See https://github.com/Rdatatable/data.table/issues/4171 49 | patterns <- function(...) NULL 50 | 51 | .onLoad <- function(libname, pkgname) { 52 | op <- options() 53 | toset <- !(hasName(op, names(bg.options))) 54 | if (any(toset)) options(bg.options[toset]) 55 | 56 | invisible() 57 | } 58 | -------------------------------------------------------------------------------- /cran-comments.md: -------------------------------------------------------------------------------- 1 | ## Test environments 2 | * local 64-bit CentOS 7.9.2009 install, R version 3.6.0 (2019-04-26 r76424) 3 | * win-builder (Windows Server 2022 64-bit), R version 4.3.2 (2023-10-31 ucrt) 4 | 5 | ## R CMD check results 6 | There were no ERRORs or WARNINGs. 7 | 8 | There was 1 NOTE: 9 | 10 | * checking CRAN incoming feasibility ... NOTE 11 | Maintainer: 'Christopher G. Watson ' 12 | 13 | Suggests or Enhances not in mainstream repositories: 14 | RGtk2, cairoDevice 15 | 16 | These packages are only used for one optional function, and are not required. 17 | 18 | ## Downstream dependencies 19 | There are currently no downstream dependencies for this package. 20 | -------------------------------------------------------------------------------- /data/aal116.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/aal116.rda -------------------------------------------------------------------------------- /data/aal2.120.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/aal2.120.rda -------------------------------------------------------------------------------- /data/aal2.94.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/aal2.94.rda -------------------------------------------------------------------------------- /data/aal90.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/aal90.rda -------------------------------------------------------------------------------- /data/brainnetome.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/brainnetome.rda -------------------------------------------------------------------------------- /data/brainsuite.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/brainsuite.rda -------------------------------------------------------------------------------- /data/craddock200.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/craddock200.rda -------------------------------------------------------------------------------- /data/destrieux.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/destrieux.rda -------------------------------------------------------------------------------- /data/destrieux.scgm.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/destrieux.scgm.rda -------------------------------------------------------------------------------- /data/dk.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/dk.rda -------------------------------------------------------------------------------- /data/dk.scgm.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/dk.scgm.rda -------------------------------------------------------------------------------- /data/dkt.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/dkt.rda -------------------------------------------------------------------------------- /data/dkt.scgm.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/dkt.scgm.rda -------------------------------------------------------------------------------- /data/dosenbach160.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/dosenbach160.rda -------------------------------------------------------------------------------- /data/gordon333.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/gordon333.rda -------------------------------------------------------------------------------- /data/hcp_mmp1.0.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/hcp_mmp1.0.rda -------------------------------------------------------------------------------- /data/hoa112.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/hoa112.rda -------------------------------------------------------------------------------- /data/lpba40.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/lpba40.rda -------------------------------------------------------------------------------- /data/power264.rda: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/data/power264.rda -------------------------------------------------------------------------------- /inst/extdata/brainGraph_icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cwatson/brainGraph/a0d13aea831fbb708c9fb984816e9edda616bbdd/inst/extdata/brainGraph_icon.png -------------------------------------------------------------------------------- /man/Bootstrapping.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/boot_global.R 3 | \name{Bootstrapping} 4 | \alias{Bootstrapping} 5 | \alias{brainGraph_boot} 6 | \alias{summary.brainGraph_boot} 7 | \alias{plot.brainGraph_boot} 8 | \title{Bootstrapping for global graph measures} 9 | \usage{ 10 | brainGraph_boot(densities, resids, R = 1000, measure = c("mod", 11 | "E.global", "Cp", "Lp", "assortativity", "strength", "mod.wt", 12 | "E.global.wt"), conf = 0.95, .progress = getOption("bg.progress"), 13 | xfm.type = c("1/w", "-log(w)", "1-w", "-log10(w/max(w))", 14 | "-log10(w/max(w)+1)")) 15 | 16 | \method{summary}{brainGraph_boot}(object, ...) 17 | 18 | \method{plot}{brainGraph_boot}(x, ..., alpha = 0.4) 19 | } 20 | \arguments{ 21 | \item{densities}{Numeric vector of graph densities to loop through} 22 | 23 | \item{resids}{An object of class \code{brainGraph_resids} (the output from 24 | \code{\link{get.resid}})} 25 | 26 | \item{R}{Integer; the number of bootstrap replicates. Default: \code{1e3}} 27 | 28 | \item{measure}{Character string of the measure to test. Default: \code{mod}} 29 | 30 | \item{conf}{Numeric; the level for calculating confidence intervals. Default: 31 | \code{0.95}} 32 | 33 | \item{.progress}{Logical indicating whether or not to show a progress bar. 34 | Default: \code{getOption('bg.progress')}} 35 | 36 | \item{xfm.type}{Character string specifying how to transform the weights. 37 | Default: \code{1/w}} 38 | 39 | \item{object, x}{A \code{brainGraph_boot} object} 40 | 41 | \item{...}{Unused} 42 | 43 | \item{alpha}{A numeric indicating the opacity for the confidence bands} 44 | } 45 | \value{ 46 | \code{brainGraph_boot} -- an object of class \code{brainGraph_boot} 47 | containing some input variables, in addition to a list of 48 | \code{\link[boot]{boot}} objects (one for each group). 49 | 50 | \code{plot} -- \emph{list} with the following elements: 51 | \item{se}{A ggplot object with ribbon representing standard error} 52 | \item{ci}{A ggplot object with ribbon representing confidence intervals} 53 | } 54 | \description{ 55 | Perform bootstrapping to obtain groupwise standard error estimates of a 56 | global graph measure. 57 | 58 | The \code{plot} method returns two \code{ggplot} objects: one with shaded 59 | regions based on the standard error, and the other based on confidence 60 | intervals (calculated using the normal approximation). 61 | } 62 | \details{ 63 | The confidence intervals are calculated using the \emph{normal approximation} 64 | at the \eqn{100 \times conf}\% level (by default, 95\%). 65 | 66 | For getting estimates of \emph{weighted global efficiency}, a method for 67 | transforming edge weights must be provided. The default is to invert them. 68 | See \code{\link{xfm.weights}}. 69 | } 70 | \examples{ 71 | \dontrun{ 72 | boot.E.global <- brainGraph_boot(densities, resids.all, 1e3, 'E.global') 73 | } 74 | } 75 | \seealso{ 76 | \code{\link[boot]{boot}}, \code{\link[boot]{boot.ci}} 77 | 78 | Other Group analysis functions: \code{\link{GLM}}, 79 | \code{\link{Mediation}}, \code{\link{NBS}}, 80 | \code{\link{brainGraph_permute}}, \code{\link{mtpc}} 81 | 82 | Other Structural covariance network functions: \code{\link{IndividualContributions}}, 83 | \code{\link{Residuals}}, 84 | \code{\link{brainGraph_permute}}, 85 | \code{\link{corr.matrix}}, \code{\link{import_scn}}, 86 | \code{\link{plot_volumetric}} 87 | } 88 | \author{ 89 | Christopher G. Watson, \email{cgwatson@bu.edu} 90 | } 91 | \concept{Group analysis functions} 92 | \concept{Structural covariance network functions} 93 | -------------------------------------------------------------------------------- /man/NBS.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/NBS.R, R/methods.R 3 | \name{NBS} 4 | \alias{NBS} 5 | \alias{summary.NBS} 6 | \alias{nobs.NBS} 7 | \alias{terms.NBS} 8 | \alias{formula.NBS} 9 | \alias{labels.NBS} 10 | \alias{case.names.NBS} 11 | \alias{variable.names.NBS} 12 | \alias{df.residual.NBS} 13 | \alias{nregions.NBS} 14 | \title{Network-based statistic for brain MRI data} 15 | \usage{ 16 | NBS(A, covars, contrasts, con.type = c("t", "f"), X = NULL, 17 | con.name = NULL, p.init = 0.001, perm.method = c("freedmanLane", 18 | "terBraak", "smith", "draperStoneman", "manly", "stillWhite"), 19 | part.method = c("beckmann", "guttman", "ridgway"), N = 1000, 20 | perms = NULL, symm.by = c("max", "min", "avg"), 21 | alternative = c("two.sided", "less", "greater"), long = FALSE, ...) 22 | 23 | \method{summary}{NBS}(object, contrast = NULL, digits = max(3L, 24 | getOption("digits") - 2L), ...) 25 | 26 | \method{nobs}{NBS}(object, ...) 27 | 28 | \method{terms}{NBS}(x, ...) 29 | 30 | \method{formula}{NBS}(x, ...) 31 | 32 | \method{labels}{NBS}(object, ...) 33 | 34 | \method{case.names}{NBS}(object, ...) 35 | 36 | \method{variable.names}{NBS}(object, ...) 37 | 38 | \method{df.residual}{NBS}(object, ...) 39 | 40 | \method{nregions}{NBS}(object) 41 | } 42 | \arguments{ 43 | \item{A}{Three-dimensional array of all subjects' connectivity matrices} 44 | 45 | \item{covars}{A \code{data.table} of covariates} 46 | 47 | \item{contrasts}{Numeric matrix (for T statistics) or list of matrices (for F 48 | statistics) specifying the contrast(s) of interest; if only one contrast is 49 | desired, you can supply a vector (for T statistics)} 50 | 51 | \item{con.type}{Character string; either \code{'t'} or \code{'f'} (for t or 52 | F-statistics). Default: \code{'t'}} 53 | 54 | \item{X}{Numeric matrix, if you wish to supply your own design matrix. 55 | Ignored if \code{outcome != measure}.} 56 | 57 | \item{con.name}{Character vector of the contrast name(s); if \code{contrasts} 58 | has row/list names, those will be used for reporting results} 59 | 60 | \item{p.init}{Numeric; the initial p-value threshold (default: \code{0.001})} 61 | 62 | \item{perm.method}{Character string indicating the permutation method. 63 | Default: \code{'freedmanLane'}} 64 | 65 | \item{part.method}{Character string; the method of partitioning the design 66 | matrix into covariates of interest and nuisance. Default: \code{'beckmann'}} 67 | 68 | \item{N}{Integer; number of permutations to create. Default: \code{5e3}} 69 | 70 | \item{perms}{Matrix of permutations, if you would like to provide your own. 71 | Default: \code{NULL}} 72 | 73 | \item{symm.by}{Character string; how to create symmetric off-diagonal 74 | elements. Default: \code{max}} 75 | 76 | \item{alternative}{Character string, whether to do a two- or one-sided test. 77 | Default: \code{'two.sided'}} 78 | 79 | \item{long}{Logical indicating whether or not to return all permutation 80 | results. Default: \code{FALSE}} 81 | 82 | \item{...}{Arguments passed to \code{\link{brainGraph_GLM_design}}} 83 | 84 | \item{object, x}{A \code{NBS} object} 85 | 86 | \item{contrast}{Integer specifying the contrast to plot/summarize; defaults 87 | to showing results for all contrasts} 88 | 89 | \item{digits}{Integer specifying the number of digits to display for P-values} 90 | } 91 | \value{ 92 | An object of class \code{NBS} with some input arguments in addition 93 | to: 94 | \item{X}{The design matrix} 95 | \item{removed.subs}{Character vector of subject ID's removed due to 96 | incomplete data (if any)} 97 | \item{T.mat}{3-d array of (symmetric) numeric matrices containing the 98 | statistics for each edge} 99 | \item{p.mat}{3-d array of (symmetric) numeric matrices containing the 100 | P-values} 101 | \item{components}{List containing data tables of the observed and permuted 102 | connected component sizes and P-values} 103 | \item{rank,df.residual,qr,cov.unscaled}{The rank, residual degrees of 104 | freedom, QR decomposition, and unscaled covariance matrix of the design 105 | matrix} 106 | } 107 | \description{ 108 | Calculates the \emph{network-based statistic (NBS)}, which allows for 109 | family-wise error (FWE) control over network data, introduced for brain MRI 110 | data by Zalesky et al. Requires a three-dimensional array of all subjects' 111 | connectivity matrices and a \code{data.table} of covariates, in addition to a 112 | contrast matrix or list. A null distribution of the largest connected 113 | component size is created by fitting a GLM to permuted data. For details, see 114 | \code{\link{GLM}}. 115 | } 116 | \details{ 117 | When printing a \code{summary}, you can include arguments to 118 | \code{\link[stats]{printCoefmat}}. 119 | } 120 | \note{ 121 | It is assumed that the order of the subjects in \code{covars} matches 122 | that of the input array \code{A}. You will need to ensure that this is the 123 | case. Prior to \code{v3.0.0}, the \code{covars} table was sorted by 124 | \code{Study.ID} before creating the design matrix. 125 | } 126 | \examples{ 127 | \dontrun{ 128 | max.comp.nbs <- NBS(A.norm.sub[[1]], covars.dti, N=5e3) 129 | } 130 | } 131 | \references{ 132 | Zalesky, A. and Fornito, A. and Bullmore, E.T. (2010) 133 | Network-based statistic: identifying differences in brain networks. 134 | \emph{NeuroImage}, \bold{53(4)}, 1197--1207. 135 | \doi{10.1016/j.neuroimage.2010.06.041} 136 | } 137 | \seealso{ 138 | Other Group analysis functions: \code{\link{Bootstrapping}}, 139 | \code{\link{GLM}}, \code{\link{Mediation}}, 140 | \code{\link{brainGraph_permute}}, \code{\link{mtpc}} 141 | } 142 | \author{ 143 | Christopher G. Watson, \email{cgwatson@bu.edu} 144 | } 145 | \concept{Group analysis functions} 146 | -------------------------------------------------------------------------------- /man/apply_thresholds.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/create_mats.R 3 | \name{apply_thresholds} 4 | \alias{apply_thresholds} 5 | \title{Threshold additional set of matrices} 6 | \usage{ 7 | apply_thresholds(sub.mats, group.mats, W.files, inds) 8 | } 9 | \arguments{ 10 | \item{sub.mats}{List (length equal to number of thresholds) of numeric arrays 11 | (3-dim) for all subjects} 12 | 13 | \item{group.mats}{List (length equal to number of thresholds) of numeric 14 | arrays (3-dim) for group-level data} 15 | 16 | \item{W.files}{Character vector of the filenames of the files with 17 | connectivity matrices} 18 | 19 | \item{inds}{List (length equal to number of groups) of integers; each list 20 | element should be a vector of length equal to the group sizes} 21 | } 22 | \value{ 23 | List containing: 24 | \item{W}{A 3-d array of the raw connection matrices} 25 | \item{W.norm.sub}{List of 3-d arrays of the normalized connection matrices 26 | for all given thresholds} 27 | \item{W.norm.mean}{List of 3-d arrays of the normalized connection matrices 28 | averaged for each group} 29 | } 30 | \description{ 31 | \code{apply_thresholds} thresholds an additional set of matrices (e.g., 32 | FA-weighted matrices for DTI tractography) based on the matrices that have 33 | been returned from \code{\link{create_mats}}. This ensures that the same 34 | connections are present in both sets of matrices. 35 | } 36 | \details{ 37 | The argument \code{W.files} accepts the same formats as \code{A.files}; see 38 | \code{\link{create_mats}} for details. 39 | } 40 | \examples{ 41 | \dontrun{ 42 | W.mats <- apply_thresholds(A.norm.sub, A.norm.mean, f.W, inds) 43 | } 44 | } 45 | \author{ 46 | Christopher G. Watson, \email{cgwatson@bu.edu} 47 | } 48 | -------------------------------------------------------------------------------- /man/atlas_helpers.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/atlas.R 3 | \name{Atlas Helpers} 4 | \alias{Atlas Helpers} 5 | \alias{guess_atlas} 6 | \alias{as_atlas} 7 | \alias{create_atlas} 8 | \title{Atlas helper functions} 9 | \usage{ 10 | guess_atlas(x) 11 | 12 | as_atlas(object) 13 | 14 | create_atlas(regions, coords, lobes, hemis, other = NULL) 15 | } 16 | \arguments{ 17 | \item{x, object}{An object to test or convert to an atlas data.table} 18 | 19 | \item{regions}{Character vector of region names} 20 | 21 | \item{coords}{Numeric matrix of spatial coordinates; must have 3 columns} 22 | 23 | \item{lobes}{Character or factor vector of lobe membership} 24 | 25 | \item{hemis}{Character or factor vector of hemisphere membership. There 26 | should probably not be more than 3 unique elements (for left, right, and 27 | bi-hemispheric regions)} 28 | 29 | \item{other}{A \emph{named list} of vectors with other data. The names of the 30 | list will become column names in the return object.} 31 | } 32 | \value{ 33 | \code{guess_atlas} - Character string; either the matched atlas or 34 | \code{NA} 35 | 36 | \code{as_atlas} and \code{create_atlas} return a \code{data.table} 37 | that conforms to other atlases in the package, or exits with an error. 38 | } 39 | \description{ 40 | \code{guess_atlas} tries to determine which atlas is being used based on the 41 | data; i.e., the number of vertices/regions. 42 | 43 | \code{as_atlas} and \code{create_atlas} converts/coerces an object to a 44 | a \code{data.table}, or creates one, that is compatible with 45 | \code{brainGraph}. 46 | } 47 | \section{Guessing the atlas from an object}{ 48 | 49 | There are several valid inputs to \code{guess_atlas}: 50 | \describe{ 51 | \item{data.table}{The atlas will be guessed based on the number of columns 52 | (subtracting by 1 if a \dQuote{Study ID} column is present). This is the 53 | same behavior as for \code{data.frame} objects, as well.} 54 | \item{igraph}{The vertex count} 55 | \item{brainGraph}{If there is a \code{atlas} graph-level attribute, it will 56 | return that. Otherwise, the vertex count.} 57 | \item{matrix,array}{The number of rows, which should equal the number of 58 | columns if the input is a connectivity matrix.} 59 | } 60 | 61 | Note that this will only work properly for atlases that are currently in the 62 | package. If you are using a custom atlas and you receive errors, please open 63 | an issue on \emph{GitHub}. 64 | } 65 | 66 | \section{Coercing to an atlas}{ 67 | 68 | There are several things \code{as_atlas} tries to do to make it work without 69 | error: 70 | \itemize{ 71 | \item Coerce the object to \code{data.table} 72 | \item Add a column of integers named \code{index} 73 | \item Change columns named \code{'x'}, \code{'y'}, or \code{'z'} to have 74 | \code{.mni} at the end 75 | \item Convert the \code{lobe} and \code{hemi} columns to be \emph{factors} 76 | } 77 | } 78 | 79 | \examples{ 80 | my_atlas <- data.frame(name=paste('Region', 1:10), x.mni=rnorm(10), 81 | y.mni=rnorm(10), z.mni=rnorm(10), 82 | lobe=rep(c('Frontal', 'Parietal', 'Temporal', 'Occipital', 'Limbic'), 2), 83 | hemi=c(rep('L', 5), rep('R', 5))) 84 | my_atlas2 <- as_atlas(my_atlas) 85 | str(my_atlas) 86 | str(my_atlas2) 87 | regions <- paste('Region', 1:10) 88 | xyz <- matrix(rnorm(30), nrow=10, ncol=3) 89 | lobe <- rep(c('Frontal', 'Parietal', 'Temporal', 'Occipital', 'Limbic'), 2) 90 | hemi <- c(rep('L', 5), rep('R', 5)) 91 | other <- list(network=rep(c('Default mode', 'Task positive'), 5)) 92 | my_atlas <- create_atlas(regions, xyz, lobe, hemi, other) 93 | str(my_atlas) 94 | } 95 | -------------------------------------------------------------------------------- /man/attributes.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/set_brainGraph_attributes.R 3 | \name{Attributes} 4 | \alias{Attributes} 5 | \alias{set_brainGraph_attr} 6 | \alias{xfm.weights} 7 | \title{Set graph, vertex, and edge attributes common in MRI analyses} 8 | \usage{ 9 | set_brainGraph_attr(g, type = c("observed", "random"), 10 | use.parallel = TRUE, A = NULL, xfm.type = c("1/w", "-log(w)", 11 | "1-w", "-log10(w/max(w))", "-log10(w/max(w)+1)"), 12 | clust.method = "louvain") 13 | 14 | xfm.weights(g, xfm.type = c("1/w", "-log(w)", "1-w", "-log10(w/max(w))", 15 | "-log10(w/max(w)+1)"), invert = FALSE) 16 | } 17 | \arguments{ 18 | \item{g}{A graph object} 19 | 20 | \item{type}{Character string indicating the type of graphs. Default: 21 | \code{observed}} 22 | 23 | \item{use.parallel}{Logical indicating whether to use \emph{foreach}. 24 | Default: \code{TRUE}} 25 | 26 | \item{A}{Numeric matrix; the (weighted) adjacency matrix, which can be used 27 | for faster calculation of local efficiency. Default: \code{NULL}} 28 | 29 | \item{xfm.type}{Character string specifying how to transform the weights. 30 | Default: \code{1/w}} 31 | 32 | \item{clust.method}{Character string indicating which method to use for 33 | community detection. Default: \code{'louvain'}} 34 | 35 | \item{invert}{Logical indicating whether or not to invert the transformation. 36 | Default: \code{FALSE}} 37 | } 38 | \value{ 39 | A graph object with the following attributes: 40 | \item{Graph-level}{Density, connected component sizes, diameter, # of 41 | triangles, transitivity, average path length, assortativity, global & 42 | local efficiency, modularity, vulnerability, hub score, rich-club 43 | coefficient, # of hubs, edge asymmetry} 44 | \item{Vertex-level}{Degree, strength; betweenness, eigenvector, and 45 | leverage centralities; hubs; transitivity (local); k-core, s-core; local 46 | & nodal efficiency; color (community, lobe, component); membership 47 | (community, lobe, component); gateway and participation coefficients, 48 | within-module degree z-score; vulnerability; and coordinates (x, y, and 49 | z)} 50 | \item{Edge-level}{Color (community, lobe, component), edge betweenness, 51 | Euclidean distance (in mm), weight (if weighted)} 52 | 53 | \code{xfm.weights} returns the same graph object, with transformed 54 | edge weights plus a graph attribute (\code{xfm.type}) recording the method 55 | of transformation 56 | } 57 | \description{ 58 | \code{set_brainGraph_attr} is a convenience function that sets a number of 59 | graph, vertex, and edge attributes for a given graph object. Specifically, it 60 | calculates measures that are common in MRI analyses of brain networks. 61 | } 62 | \details{ 63 | Including \code{type='random'} in the function call will reduce the number of 64 | attributes calculated. It will only add graph-level attributes for: 65 | clustering coefficient, characteristic path length, rich club coefficient, 66 | global efficiency, and modularity. 67 | } 68 | \section{Negative edge weights}{ 69 | 70 | If there are any negative edge weights in the graph, several of the 71 | distance-based metrics will \emph{not} be calculated, because they can throw 72 | errors which is undesirable when processing a large dataset. The metrics are: 73 | local and nodal efficiency, diameter, characteristic path length, and 74 | hubness. 75 | } 76 | 77 | \section{Transforming edge weights}{ 78 | 79 | For distance-based measures, it is important to transform the edge weights so 80 | that the \emph{strongest} connections are re-mapped to having the 81 | \emph{lowest} weights. Then you may calculate e.g., the \emph{shortest path 82 | length} which will include the strongest connections. 83 | 84 | \code{xfm.type} allows you to choose from 5 options for transforming edge 85 | weights when calculating distance-based metrics (e.g., shortest paths). There 86 | is no \dQuote{best-practice} for choosing one over the other, but the reciprocal is 87 | probably most common. 88 | \describe{ 89 | \item{\code{1/w}}{reciprocal (default)} 90 | \item{\code{-log(w)}}{the negative (natural) logarithm} 91 | \item{\code{1-w}}{subtract weights from 1} 92 | \item{\code{-log10(w/max(w))}}{negative (base-10) log of normalized 93 | weights} 94 | \item{\code{-log10(w/max(w)+1)}}{same as above, but add 1 before taking 95 | the log} 96 | } 97 | 98 | To transform the weights back to original values, specify \code{invert=TRUE}. 99 | } 100 | 101 | \section{Community detection}{ 102 | 103 | \code{clust.method} allows you to choose from any of the clustering 104 | (community detection) functions available in \code{igraph}. These functions 105 | begin with \code{cluster_}; the function argument should not include this 106 | leading character string. There are a few possibilities, depending on the 107 | value and the type of input graph: 108 | \enumerate{ 109 | \item By default, \code{louvain} is used, calling 110 | \code{\link[igraph]{cluster_louvain}} 111 | \item Uses \code{spinglass} if there are any negative edges and/or the 112 | selected method is \code{spinglass} 113 | \item Uses \code{walktrap} if there are any negative edge weights and any 114 | other method (besides \code{spinglass}) is selected 115 | \item Automatically transforms the edge weights if \code{edge_betweenness} 116 | is selected and the graph is weighted, because the algorithm considers 117 | edges as \emph{distances} 118 | } 119 | } 120 | 121 | \seealso{ 122 | \code{\link[igraph]{components}}, \code{\link[igraph]{diameter}}, 123 | \code{\link[igraph]{centr_betw}}, \code{\link[igraph]{betweenness}}, 124 | \code{\link[igraph]{centr_eigen}}, \code{\link[igraph]{transitivity}}, 125 | \code{\link[igraph]{distances}}, \code{\link[igraph]{assortativity}}, 126 | \code{\link[igraph]{coreness}}, \code{\link[igraph]{communities}}, 127 | \code{\link[igraph]{knn}} 128 | } 129 | \author{ 130 | Christopher G. Watson, \email{cgwatson@bu.edu} 131 | } 132 | -------------------------------------------------------------------------------- /man/auc_diff.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/auc.R 3 | \name{auc_diff} 4 | \alias{auc_diff} 5 | \title{Difference in the area-under-the-curve of two vectors} 6 | \usage{ 7 | auc_diff(x, y) 8 | } 9 | \arguments{ 10 | \item{x}{Numeric vector of the x-values} 11 | 12 | \item{y}{A numeric vector or matrix} 13 | } 14 | \value{ 15 | A numeric value of the difference between two groups, or a numeric 16 | vector of the AUC across vertices 17 | } 18 | \description{ 19 | This function takes two vectors, calculates the area-under-the-curve (AUC), 20 | and calculates the difference between the two (if applicable). 21 | } 22 | \details{ 23 | There are 4 different behaviors for this function: 24 | \enumerate{ 25 | \item If \code{x} is a single numeric value, then \code{y} should be a 26 | vector of 2 values and the difference is returned. This generally should 27 | not occur and may be removed in the future. 28 | \item If \code{y} has 1 column (or is a vector), then the AUC of \code{y} 29 | is returned. 30 | \item If \code{y} has exactly 2 columns, then each column should contain 31 | the values of interest for each subject group, and the difference in 32 | AUC's for each group is returned. 33 | \item If \code{y} has multiple columns (e.g., equal to the number of 34 | vertices of a graph), it will calculate the AUC for each column. 35 | } 36 | } 37 | \keyword{internal} 38 | -------------------------------------------------------------------------------- /man/brainGraph-methods.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/methods.R 3 | \name{brainGraph-methods} 4 | \alias{brainGraph-methods} 5 | \alias{groups.brainGraphList} 6 | \alias{groups.corr_mats} 7 | \alias{region.names} 8 | \alias{region.names.data.table} 9 | \alias{nregions} 10 | \title{brainGraph generic methods} 11 | \usage{ 12 | \method{groups}{brainGraphList}(x) 13 | 14 | \method{groups}{corr_mats}(x) 15 | 16 | region.names(object) 17 | 18 | \method{region.names}{data.table}(object) 19 | 20 | nregions(object) 21 | } 22 | \arguments{ 23 | \item{x, object}{An object} 24 | } 25 | \description{ 26 | These functions are S3 \emph{generics} for various \code{brainGraph}-defined 27 | objects. 28 | 29 | \code{groups} returns the \dQuote{Group} graph attribute for each graph or 30 | observation in the object. 31 | 32 | \code{region.names} is a generic method for extracting region names from 33 | various \code{brainGraph} objects. These are generally convenience functions. 34 | 35 | \code{nregions} is a generic method for extracting the number of regions from 36 | various \code{brainGraph} objects. 37 | } 38 | \details{ 39 | For a \code{data.table}, \code{region.names} assumes that it contains a 40 | \emph{factor} column named \code{region}. 41 | } 42 | -------------------------------------------------------------------------------- /man/brainGraph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/zzz.R 3 | \docType{package} 4 | \name{brainGraph} 5 | \alias{brainGraph} 6 | \alias{brainGraph-options} 7 | \alias{brainGraph-package} 8 | \title{Default options for brainGraph} 9 | \description{ 10 | brainGraph is a package for performing \emph{graph theory analysis} of brain 11 | MRI data. 12 | } 13 | \section{Package options}{ 14 | 15 | 16 | brainGraph uses the following \code{\link{options}} to configure behavior: 17 | \itemize{ 18 | \item \code{bg.subject_id}: character string specifying the name your 19 | project/study uses as a subject identifier. All imported data (e.g., 20 | covariates tables) \emph{MUST} have a column matching this. One possible 21 | alternative is \code{'participant_id'}, recommended by BIDS. Default: 22 | \code{'Study.ID'} 23 | \item \code{bg.group}: character string specifying the name your 24 | project/study uses as a group identifier. All imported data (e.g., 25 | covariates tables) \emph{MUST} have a column matching this. One possible 26 | alternative is \code{'group'}, recommended by BIDS. Default: 27 | \code{'Group'} 28 | \item \code{bg.session}: character string specifying the name your 29 | project/study uses as a \dQuote{time} or session identifier, in the case 30 | of longitudinal studies. All imported data (e.g., covariates tables) 31 | \emph{MUST} have a column matching this. One possible alternative is 32 | \code{'session_id'}, recommended by BIDS. Default: \code{'Time'} 33 | \item \code{bg.progress}: logical indicating whether to show progress bars 34 | for functions that provide the option. Default: \code{TRUE} 35 | \item \code{bg.ncpus}: integer indicating the number of cores to use for 36 | parallel operations. Only used if you have not already registered a 37 | parallel backend (see Chapter 5 of the User Guide or 38 | \url{https://github.com/cwatson/brainGraph/blob/master/README.md} for 39 | examples). Default: \code{2L} 40 | } 41 | } 42 | 43 | -------------------------------------------------------------------------------- /man/brainGraph_permute.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/permute_group.R 3 | \name{brainGraph_permute} 4 | \alias{brainGraph_permute} 5 | \alias{summary.brainGraph_permute} 6 | \alias{plot.brainGraph_permute} 7 | \title{Permutation test for group difference of graph measures} 8 | \usage{ 9 | brainGraph_permute(densities, resids, N = 5000, perms = NULL, 10 | auc = FALSE, level = c("graph", "vertex", "other"), 11 | measure = c("btwn.cent", "coreness", "degree", "eccentricity", 12 | "clo.cent", "communicability", "ev.cent", "lev.cent", "pagerank", 13 | "subg.cent", "E.local", "E.nodal", "knn", "Lp", "transitivity", 14 | "vulnerability"), .function = NULL) 15 | 16 | \method{summary}{brainGraph_permute}(object, measure = object$measure, 17 | alternative = c("two.sided", "less", "greater"), alpha = 0.05, 18 | p.sig = c("p", "p.fdr"), ...) 19 | 20 | \method{plot}{brainGraph_permute}(x, measure = x$measure, 21 | alternative = c("two.sided", "less", "greater"), alpha = 0.05, 22 | p.sig = c("p", "p.fdr"), ptitle = NULL, ...) 23 | } 24 | \arguments{ 25 | \item{densities}{Numeric vector of graph densities} 26 | 27 | \item{resids}{An object of class \code{brainGraph_resids} (the output from 28 | \code{\link{get.resid}})} 29 | 30 | \item{N}{Integer; the number of permutations (default: 5e3)} 31 | 32 | \item{perms}{Numeric matrix of permutations, if you would like to provide 33 | your own (default: \code{NULL})} 34 | 35 | \item{auc}{Logical indicating whether or not to calculate differences in the 36 | area-under-the-curve of metrics (default: \code{FALSE})} 37 | 38 | \item{level}{A character string for the attribute \dQuote{level} to calculate 39 | differences (default: \code{graph})} 40 | 41 | \item{measure}{A character string specifying the vertex-level metric to 42 | calculate, only used if \code{level='vertex'} (default: \code{btwn.cent}). 43 | For the \code{summary} method, this is to focus on a single 44 | \emph{graph-level} measure (since multiple are calculated at once).} 45 | 46 | \item{.function}{A custom function you can pass if \code{level='other'}} 47 | 48 | \item{object, x}{A \code{brainGraph_permute} object (output by 49 | \code{\link{brainGraph_permute}}).} 50 | 51 | \item{alternative}{Character string, whether to do a two- or one-sided test. 52 | Default: \code{'two.sided'}} 53 | 54 | \item{alpha}{Numeric; the significance level. Default: 0.05} 55 | 56 | \item{p.sig}{Character string specifying which p-value to use for displaying 57 | significant results (default: \code{p})} 58 | 59 | \item{...}{Unused} 60 | 61 | \item{ptitle}{Character string specifying a title for the plot (default: 62 | \code{NULL})} 63 | } 64 | \value{ 65 | An object of class \code{brainGraph_permute} with input arguments in 66 | addition to: 67 | \item{DT}{A data table with permutation statistics} 68 | \item{obs.diff}{A data table of the observed group differences} 69 | \item{Group}{Group names} 70 | 71 | The \code{plot} method returns a \emph{list} of \code{ggplot} objects 72 | } 73 | \description{ 74 | \code{brainGraph_permute} draws permutations from linear model residuals to 75 | determine the significance of between-group differences of a global or 76 | vertex-wise graph measure. It is intended for structural covariance networks 77 | (in which there is only one graph per group), but can be extended to other 78 | types of data. 79 | } 80 | \details{ 81 | If you would like to calculate differences in the area-under-the-curve (AUC) 82 | across densities, then specify \code{auc=TRUE}. 83 | 84 | There are three possible \dQuote{levels}: 85 | \enumerate{ 86 | \item \emph{graph} Calculate modularity (Louvain algorithm), clustering 87 | coefficient, characteristic path length, degree assortativity, and global 88 | efficiency. 89 | \item \emph{vertex} Choose one of: centrality metrics (betweenness, 90 | closeness, communicability, eigenvector, leverage, pagerank, subgraph); 91 | k-core; degree; eccentricity; nodal or local efficiency; k-nearest neighbor 92 | degree; shortest path length; transitivity; or vulnerability. 93 | \item \emph{other} Supply your own function. This is useful if you want to 94 | calculate something that I haven't hard-coded. It must take as its own 95 | arguments: \code{g} (a list of lists of \code{igraph} graph objects); and 96 | \code{densities} (numeric vector). 97 | } 98 | } 99 | \examples{ 100 | \dontrun{ 101 | myResids <- get.resid(lhrh, covars) 102 | myPerms <- shuffleSet(n=nrow(myResids$resids.all), nset=1e3) 103 | out <- brainGraph_permute(densities, m, perms=myPerms) 104 | out <- brainGraph_permute(densities, m, perms=myPerms, level='vertex') 105 | out <- brainGraph_permute(densities, m, perms=myPerms, 106 | level='other', .function=myFun) 107 | } 108 | } 109 | \seealso{ 110 | Other Group analysis functions: \code{\link{Bootstrapping}}, 111 | \code{\link{GLM}}, \code{\link{Mediation}}, 112 | \code{\link{NBS}}, \code{\link{mtpc}} 113 | 114 | Other Structural covariance network functions: \code{\link{Bootstrapping}}, 115 | \code{\link{IndividualContributions}}, 116 | \code{\link{Residuals}}, \code{\link{corr.matrix}}, 117 | \code{\link{import_scn}}, \code{\link{plot_volumetric}} 118 | } 119 | \author{ 120 | Christopher G. Watson, \email{cgwatson@bu.edu} 121 | } 122 | \concept{Group analysis functions} 123 | \concept{Structural covariance network functions} 124 | -------------------------------------------------------------------------------- /man/centr_betw_comm.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/communicability.R 3 | \name{centr_betw_comm} 4 | \alias{centr_betw_comm} 5 | \title{Calculate communicability betweenness centrality} 6 | \usage{ 7 | centr_betw_comm(g, A = NULL) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{A}{Numeric matrix; the adjacency matrix of the input graph. Default: 13 | \code{NULL}} 14 | } 15 | \value{ 16 | A numeric vector of the centrality for each vertex 17 | } 18 | \description{ 19 | \code{centr_betw_comm} calculates the \emph{communicability betweenness} of 20 | the vertices of a graph. The centrality for vertex \code{r} is 21 | \deqn{\omega_r = \frac{1}{C} \sum_p \sum_q \frac{(e^{\mathbf{A}})_{pq} - 22 | (e^{\mathbf{A} + \mathbf{E}(r)})_{pq}}{(e^{\mathbf{A}})_{pq}}} 23 | where \eqn{C = (n - 1)^2 - (n - 1)} is a normalization factor. 24 | } 25 | \references{ 26 | Estrada, E. and Higham, D.J. and Hatano N. (2009) Communicability 27 | betweenness in complex networks. \emph{Physica A}, \bold{388}, 764--774. 28 | \doi{10.1016/j.physa.2008.11.011} 29 | } 30 | \seealso{ 31 | Other Centrality functions: \code{\link{centr_lev}} 32 | } 33 | \author{ 34 | Christopher G. Watson, \email{cgwatson@bu.edu} 35 | } 36 | \concept{Centrality functions} 37 | -------------------------------------------------------------------------------- /man/centr_lev.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/centr_lev.R 3 | \name{centr_lev} 4 | \alias{centr_lev} 5 | \title{Calculate a vertex's leverage centrality} 6 | \usage{ 7 | centr_lev(g, A = NULL) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{A}{Numeric matrix; the adjacency matrix of the input graph. Default: 13 | \code{NULL}} 14 | } 15 | \value{ 16 | A vector of the leverage centrality for all vertices. 17 | } 18 | \description{ 19 | Calculates the leverage centrality of each vertex in a graph. 20 | } 21 | \details{ 22 | The leverage centrality relates a vertex's degree with the degree of its 23 | neighbors. The equation is: 24 | \deqn{l_i = \frac{1}{k_i} \sum_{j \in N_i} \frac{k_i - k_j}{k_i + k_j}} 25 | where \eqn{k_i} is the degree of the \eqn{i^{th}} vertex and \eqn{N_i} is the 26 | set of neighbors of \emph{i}. This function replaces \emph{NaN} with 27 | \emph{NA} (for functions that have the argument \emph{na.rm}). 28 | } 29 | \references{ 30 | Joyce, K.E. and Laurienti P.J. and Burdette J.H. and Hayasaka S. 31 | (2010) A new measure of centrality for brain networks. \emph{PLoS One}, 32 | \bold{5(8)}, e12200. \doi{10.1371/journal.pone.0012200} 33 | } 34 | \seealso{ 35 | Other Centrality functions: \code{\link{centr_betw_comm}} 36 | } 37 | \author{ 38 | Christopher G. Watson, \email{cgwatson@bu.edu} 39 | } 40 | \concept{Centrality functions} 41 | -------------------------------------------------------------------------------- /man/check_attributes.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils.R 3 | \name{check_weights} 4 | \alias{check_weights} 5 | \alias{check_degree} 6 | \alias{check_strength} 7 | \title{Check for vertex or edge attributes} 8 | \usage{ 9 | check_weights(g, weights) 10 | 11 | check_degree(g) 12 | 13 | check_strength(g) 14 | } 15 | \value{ 16 | \code{check_weights} - If \code{weights=NULL} and the graph has a 17 | \code{'weight'} attribute, then \code{NULL} will be returned. If 18 | \code{weights=NA}, then \code{NA} is returned. 19 | } 20 | \description{ 21 | \code{check_weights} is a helper function for dealing with edge weights that 22 | get passed to different \code{igraph} functions. 23 | 24 | \code{check_degree} is a helper function to check if \code{degree} is a 25 | vertex attribute of the input graph. Returns a numeric vector of the degree 26 | values. 27 | 28 | \code{check_strength} is a helper function to check if \code{strength} is a 29 | vertex attribute of the input graph. Returns a numeric vector of the strength 30 | values. 31 | } 32 | \keyword{internal} 33 | -------------------------------------------------------------------------------- /man/choose.edges.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/random_graphs.R 3 | \name{choose.edges} 4 | \alias{choose.edges} 5 | \title{Select edges for re-wiring} 6 | \usage{ 7 | choose.edges(A, degs.large) 8 | } 9 | \arguments{ 10 | \item{A}{Numeric (adjacency) matrix} 11 | 12 | \item{degs.large}{Integer vector of vertex numbers with degree greater than 13 | one} 14 | } 15 | \value{ 16 | A data frame with four elements; two edges \code{(y1, z1)} and 17 | \code{(y2, z2)} will be removed, and two edges \code{(y1, y2)} and 18 | \code{(z1, z2)} will be added between the four vertices. 19 | } 20 | \description{ 21 | \code{choose.edges} selects edges to be re-wired when simulating random 22 | graphs while controlling for \emph{clustering}. It is based on the algorithm 23 | by Bansal et al. (2009), BMC Bioinformatics. 24 | } 25 | \author{ 26 | Christopher G. Watson, \email{cgwatson@bu.edu} 27 | } 28 | \keyword{internal} 29 | -------------------------------------------------------------------------------- /man/coeff_var.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/methods.R 3 | \name{coeff_var} 4 | \alias{coeff_var} 5 | \alias{coeff_var.default} 6 | \title{Calculate coefficient of variation} 7 | \usage{ 8 | coeff_var(x, na.rm = FALSE, ...) 9 | 10 | \method{coeff_var}{default}(x, na.rm = FALSE, ...) 11 | } 12 | \arguments{ 13 | \item{x}{Numeric vector, matrix, or array} 14 | 15 | \item{na.rm}{Logical indicating whether \code{NA} values should be stripped 16 | when calculating sums. Default: \code{FALSE}} 17 | 18 | \item{...}{Unused} 19 | } 20 | \value{ 21 | A numeric vector or matrix 22 | } 23 | \description{ 24 | \code{coeff_var} is a S3 generic that calculates the \emph{coefficient of 25 | variation}, defined as 26 | \deqn{CV(x) = \frac{sd(x)}{mean(x)}} 27 | } 28 | \details{ 29 | If \code{x} is a matrix, it will calculate the CV for each \emph{column}. If 30 | \code{x} is a 3D array, it will calculate the coefficient of variation for 31 | each \emph{row-column} combination. If the input dimensions are \eqn{n \times 32 | n \times r}, a matrix with size \eqn{n \times n} will be returned. 33 | } 34 | -------------------------------------------------------------------------------- /man/communicability.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/communicability.R 3 | \name{communicability} 4 | \alias{communicability} 5 | \title{Calculate communicability} 6 | \usage{ 7 | communicability(g, weights = NULL) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{weights}{Numeric vector of edge weights; if \code{NULL} (the default), 13 | and if the graph has edge attribute \code{weight}, then that will be used. 14 | To avoid using weights, this should be \code{NA}.} 15 | } 16 | \value{ 17 | A numeric matrix of the communicability 18 | } 19 | \description{ 20 | \code{communicability} calculates the communicability of a network, a measure 21 | which takes into account all possible paths (including non-shortest paths) 22 | between vertex pairs. 23 | } 24 | \details{ 25 | The communicability \eqn{G_{pq}} is a weighted sum of the number of walks 26 | from vertex \emph{p} to \emph{q} and is calculated by taking the exponential 27 | of the adjacency matrix \emph{A}: 28 | \deqn{G_{pq} = \sum_{k=0}^{\infty} \frac{(\mathbf{A}^k)_{pq}}{k!} = 29 | (e^{\mathbf{A}})_{pq}} 30 | where \eqn{k} is \emph{walk} length. 31 | 32 | For weighted graphs with \eqn{D = diag(d_i)} a diagonal matrix of vertex 33 | strength, 34 | \deqn{G_{pq} = (e^{\mathbf{D}^{-1/2} \mathbf{A} \mathbf{D}^{-1/2}})_{pq}} 35 | } 36 | \references{ 37 | Estrada, E. and Hatano, N. (2008) Communicability in complex 38 | networks. \emph{Physical Review E}. \bold{77}, 036111. 39 | \doi{10.1103/PhysRevE.77.036111} 40 | 41 | Crofts, J.J. and Higham, D.J. (2009) A weighted communicability 42 | measure applied to complex brain networks. \emph{J. R. Soc. Interface}. 43 | \bold{6}, 411--414. \doi{10.1098/rsif.2008.0484} 44 | } 45 | \author{ 46 | Christopher G. Watson, \email{cgwatson@bu.edu} 47 | } 48 | -------------------------------------------------------------------------------- /man/contract_brainGraph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/contract_brainGraph.R 3 | \name{contract_brainGraph} 4 | \alias{contract_brainGraph} 5 | \title{Contract graph vertices based on brain lobe and hemisphere} 6 | \usage{ 7 | contract_brainGraph(g, vgroup = "lobe.hemi") 8 | } 9 | \arguments{ 10 | \item{g}{A \code{brainGraph} graph object} 11 | 12 | \item{vgroup}{Character string; the name of the vertex attribute to use when 13 | contracting the graph. Default: \code{'lobe.hemi'}} 14 | } 15 | \value{ 16 | A new \code{brainGraph} graph object with vertex-level attributes 17 | representing the mean spatial coordinates, and vertex- and edge-level 18 | attributes of color names 19 | } 20 | \description{ 21 | Create a new graph after merging vertices within specified groups. 22 | By default, groups are brain \emph{lobe} and \emph{hemisphere} membership. 23 | } 24 | \details{ 25 | The \code{size} vertex-level attribute of the resultant graph is equal to the 26 | number of vertices in each group. The x-, y-, and z-coordinates of the new 27 | graph are equal to the mean coordinates of the vertices per group. 28 | The new edge weights are equal to the number of inter-group connections of 29 | the original graph. 30 | } 31 | \seealso{ 32 | \code{\link[igraph]{contract}} 33 | } 34 | \author{ 35 | Christopher G. Watson, \email{cgwatson@bu.edu} 36 | } 37 | -------------------------------------------------------------------------------- /man/cor.diff.test.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils.R 3 | \name{cor.diff.test} 4 | \alias{cor.diff.test} 5 | \title{Calculate the p-value for differences in correlation coefficients} 6 | \usage{ 7 | cor.diff.test(r1, r2, n, alternative = c("two.sided", "less", "greater")) 8 | } 9 | \arguments{ 10 | \item{r1, r2}{Numeric (vector or matrix) of correlation coefficients for both 11 | groups} 12 | 13 | \item{n}{Integer vector; number of observations for both groups} 14 | 15 | \item{alternative}{Character string, whether to do a two- or one-sided test. 16 | Default: \code{'two.sided'}} 17 | } 18 | \value{ 19 | A list with elements \code{p} and \code{z}, the p-values 20 | and z-scores for the difference in correlations. 21 | } 22 | \description{ 23 | Given two sets of correlation coefficients and sample sizes, this function 24 | calculates and returns the \emph{z-scores} and \emph{p-values} associated 25 | with the difference between correlation coefficients. This function was 26 | adapted from \url{https://stackoverflow.com/a/14519007/3357706}. 27 | } 28 | \examples{ 29 | \dontrun{ 30 | kNumSubjs <- summary(covars$Group) 31 | corr.diffs <- cor.diff.test(corrs$R[, , 1], corrs$R[, , 2], kNumSubjs) 32 | edge.diffs <- t(sapply(which(corr.diffs$p < .05), function(x) 33 | mapply('[[', 34 | dimnames(corr.diffs$p), 35 | arrayInd(x, dim(corr.diffs$p))) 36 | )) 37 | } 38 | } 39 | \author{ 40 | Christopher G. Watson, \email{cgwatson@bu.edu} 41 | } 42 | -------------------------------------------------------------------------------- /man/count_edges.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/count_edges.R 3 | \name{Count Edges} 4 | \alias{Count Edges} 5 | \alias{count_homologous} 6 | \alias{count_inter} 7 | \title{Count number of edges of a brain graph} 8 | \usage{ 9 | count_homologous(g) 10 | 11 | count_inter(g, group = c("lobe", "hemi", "network", "class", "gyrus", 12 | "Yeo_7network", "Yeo_17network", "area", "Brodmann")) 13 | } 14 | \arguments{ 15 | \item{g}{A \code{brainGraph} graph object} 16 | 17 | \item{group}{Character string specifying which grouping to calculate edge 18 | counts for. Default: \code{'lobe'}} 19 | } 20 | \value{ 21 | \code{count_homologous} - a named vector of the edge ID's connecting 22 | homologous regions 23 | 24 | \code{count_inter} - a \code{data.table} of total, intra-, and 25 | inter-group edge counts 26 | } 27 | \description{ 28 | \code{count_homologous} counts the number of edges between homologous regions 29 | in a brain graph (e.g. between L and R superior frontal). 30 | 31 | \code{count_inter} counts the number of edges between and within all vertices 32 | in one group (e.g. \emph{lobe}, \emph{hemi}, \emph{network}, etc.). 33 | } 34 | \examples{ 35 | \dontrun{ 36 | g1.lobecounts <- count_inter(g[[1]][[N]], 'lobe') 37 | } 38 | } 39 | \author{ 40 | Christopher G. Watson, \email{cgwatson@bu.edu} 41 | } 42 | -------------------------------------------------------------------------------- /man/data_tables.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/data_tables.R 3 | \name{Graph Data Tables} 4 | \alias{Graph Data Tables} 5 | \alias{graph_attr_dt} 6 | \alias{vertex_attr_dt} 7 | \title{Create a data table with graph global and vertex measures} 8 | \usage{ 9 | graph_attr_dt(bg.list) 10 | 11 | vertex_attr_dt(bg.list) 12 | } 13 | \arguments{ 14 | \item{bg.list}{A \code{brainGraphList} object, or a list of graph objects} 15 | } 16 | \value{ 17 | A \code{data.table} 18 | } 19 | \description{ 20 | \code{graph_attr_dt} is a helper function that takes a \code{brainGraphList} 21 | or a list of graphs and creates a \code{data.table} of global measures for 22 | each graph. Each row will be for a different graph. 23 | 24 | \code{vertex_attr_dt} is a helper function that creates a \code{data.table} 25 | in which each row is a vertex and each column is a different network measure 26 | (degree, centrality, etc.). 27 | } 28 | \seealso{ 29 | \code{\link[igraph]{graph_attr}, \link[igraph]{graph_attr_names}} 30 | 31 | \code{\link[igraph]{vertex_attr}, \link[igraph]{vertex_attr_names}, 32 | \link[igraph]{graph_from_data_frame}} 33 | } 34 | -------------------------------------------------------------------------------- /man/delete_all_attr.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/set_brainGraph_attributes.R 3 | \name{delete_all_attr} 4 | \alias{delete_all_attr} 5 | \title{Delete all attributes of a graph} 6 | \usage{ 7 | delete_all_attr(g, keep.names = FALSE) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{keep.names}{Logical indicating whether to keep the \code{name} vertex 13 | attribute (default: \code{FALSE})} 14 | } 15 | \value{ 16 | An \code{igraph} graph object 17 | } 18 | \description{ 19 | Deletes all graph-, vertex-, and edge-level attributes of an \code{igraph} 20 | graph object. 21 | } 22 | \seealso{ 23 | \code{\link[igraph]{delete_graph_attr}, 24 | \link[igraph]{delete_vertex_attr}, \link[igraph]{delete_edge_attr}} 25 | } 26 | \author{ 27 | Christopher G. Watson, \email{cgwatson@bu.edu} 28 | } 29 | \keyword{internal} 30 | -------------------------------------------------------------------------------- /man/dir2files.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/create_mats.R 3 | \name{dir2files} 4 | \alias{dir2files} 5 | \title{Return a vector of filenames based on a directory name or options list} 6 | \usage{ 7 | dir2files(x) 8 | } 9 | \arguments{ 10 | \item{x}{Either a character string specifying a directory or a list of 11 | arguments to be passed to \code{\link{list.files}}} 12 | } 13 | \description{ 14 | Return a vector of filenames based on a directory name or options list 15 | } 16 | \keyword{internal} 17 | -------------------------------------------------------------------------------- /man/edge_asymmetry.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/edge_asymmetry.R 3 | \name{edge_asymmetry} 4 | \alias{edge_asymmetry} 5 | \title{Calculate an asymmetry index based on edge counts} 6 | \usage{ 7 | edge_asymmetry(g, level = c("hemi", "vertex"), A = NULL) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{level}{Character string indicating whether to calculate asymmetry for 13 | each region, or the hemisphere as a whole (default: \code{'hemi'})} 14 | 15 | \item{A}{Numeric matrix; the adjacency matrix of the input graph. Default: 16 | \code{NULL}} 17 | } 18 | \value{ 19 | A data table with edge counts for both hemispheres and the asymmetry 20 | index; if \code{level} is \emph{vertex}, the data table will have 21 | \code{vcount(g)} rows. 22 | } 23 | \description{ 24 | Calculate an \emph{asymmetry index}, a ratio of intra-hemispheric edges in 25 | the left to right hemisphere of a graph for brain MRI data. 26 | } 27 | \details{ 28 | The equation is: 29 | \deqn{A = \frac{E_{lh} - E_{rh}}{0.5 \times (E_{lh} + E_{rh})}} 30 | where \emph{lh} and \emph{rh} are left and right hemispheres, respectively. 31 | The range of this measure is \eqn{[-2, 2]} (although the limits will only be 32 | reached if all edges are in one hemisphere), with negative numbers 33 | indicating more edges in the right hemisphere, and a value of 0 indicating 34 | equal number of edges in each hemisphere. 35 | 36 | The \code{level} argument specifies whether to calculate asymmetry for each 37 | vertex, or for the whole hemisphere. 38 | } 39 | \author{ 40 | Christopher G. Watson, \email{cgwatson@bu.edu} 41 | } 42 | -------------------------------------------------------------------------------- /man/efficiency.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/graph_efficiency.R 3 | \name{efficiency} 4 | \alias{efficiency} 5 | \title{Calculate graph global, local, or nodal efficiency} 6 | \usage{ 7 | efficiency(g, type = c("local", "nodal", "global"), weights = NULL, 8 | xfm = FALSE, xfm.type = NULL, use.parallel = TRUE, A = NULL, 9 | D = NULL) 10 | } 11 | \arguments{ 12 | \item{g}{An \code{igraph} graph object} 13 | 14 | \item{type}{Character string; either \code{local}, \code{nodal}, or 15 | \code{global}. Default: \code{local}} 16 | 17 | \item{weights}{Numeric vector of edge weights; if \code{NULL} (the default), 18 | and if the graph has edge attribute \code{weight}, then that will be used. 19 | To avoid using weights, this should be \code{NA}.} 20 | 21 | \item{xfm}{Logical indicating whether to transform the edge weights. Default: 22 | \code{FALSE}} 23 | 24 | \item{xfm.type}{Character string specifying how to transform the weights. 25 | Default: \code{1/w}} 26 | 27 | \item{use.parallel}{Logical indicating whether or not to use \code{foreach}. 28 | Default: \code{TRUE}} 29 | 30 | \item{A}{Numeric matrix; the adjacency matrix of the input graph. Default: 31 | \code{NULL}} 32 | 33 | \item{D}{Numeric matrix; the graph's \dQuote{distance matrix}} 34 | } 35 | \value{ 36 | A numeric vector of the efficiencies for each vertex of the graph 37 | (if \emph{type} is \code{local|nodal}) or a single number (if \emph{type} 38 | is \code{global}). 39 | } 40 | \description{ 41 | This function calculates the global efficiency of a graph or the local or 42 | nodal efficiency of each vertex of a graph. 43 | } 44 | \details{ 45 | Local efficiency for vertex \emph{i} is: 46 | \deqn{E_{local}(i) = \frac{1}{N} \sum_{i \in G} E_{global}(G_i)} 47 | where \eqn{G_i} is the subgraph of neighbors of \emph{i}, and \emph{N} is the 48 | number of vertices in that subgraph. 49 | 50 | Nodal efficiency for vertex \emph{i} is: 51 | \deqn{E_{nodal}(i) = \frac{1}{N-1} \sum_{j \in G} \frac{1}{d_{ij}}} 52 | 53 | Global efficiency for graph \emph{G} with \emph{N} vertices is: 54 | \deqn{E_{global}(G) = \frac{1}{N(N-1)} \sum_{i \ne j \in G} \frac{1}{d_{ij}}} 55 | where \eqn{d_{ij}} is the shortest path length between vertices \emph{i} and 56 | \emph{j}. Alternatively, global efficiency is equal to the mean of all nodal 57 | efficiencies. 58 | } 59 | \references{ 60 | Latora, V. and Marchiori, M. (2001) Efficient behavior of 61 | small-world networks. \emph{Phys Rev Lett}, \bold{87.19}, 198701. 62 | \doi{10.1103/PhysRevLett.87.198701} 63 | 64 | Latora, V. and Marchiori, M. (2003) Economic small-world 65 | behavior in weighted networks. \emph{Eur Phys J B}, \bold{32}, 249--263. 66 | \doi{10.1140/epjb/e2003-00095-5} 67 | } 68 | \author{ 69 | Christopher G. Watson, \email{cgwatson@bu.edu} 70 | } 71 | -------------------------------------------------------------------------------- /man/get_rand_attrs.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/analysis_random_graphs.R 3 | \name{get_rand_attrs} 4 | \alias{get_rand_attrs} 5 | \title{Convenience function to get attributes for lists of random graphs} 6 | \usage{ 7 | get_rand_attrs(bg.list, level) 8 | } 9 | \arguments{ 10 | \item{bg.list}{A \code{brainGraphList} object, created in 11 | \code{\link{analysis_random_graphs}}} 12 | } 13 | \value{ 14 | A \code{data.table} 15 | } 16 | \description{ 17 | Convenience function to get attributes for lists of random graphs 18 | } 19 | \keyword{internal} 20 | -------------------------------------------------------------------------------- /man/glm_brainGraphList.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/list.R 3 | \name{Creating_Graphs_GLM} 4 | \alias{Creating_Graphs_GLM} 5 | \alias{make_brainGraphList.bg_GLM} 6 | \alias{make_brainGraphList.mtpc} 7 | \alias{make_brainGraphList.NBS} 8 | \title{Create a graph list with GLM-specific attributes} 9 | \usage{ 10 | \method{make_brainGraphList}{bg_GLM}(x, atlas = x$atlas, 11 | type = "observed", level = "contrast", set.attrs = FALSE, 12 | modality = NULL, weighting = NULL, threshold = NULL, 13 | gnames = x$con.name, ...) 14 | 15 | \method{make_brainGraphList}{mtpc}(x, atlas = x$atlas, 16 | type = "observed", level = "contrast", set.attrs = FALSE, 17 | modality = NULL, weighting = NULL, threshold = NULL, 18 | gnames = x$con.name, ...) 19 | 20 | \method{make_brainGraphList}{NBS}(x, atlas, type = "observed", 21 | level = "contrast", set.attrs = TRUE, modality = NULL, 22 | weighting = NULL, threshold = NULL, gnames = x$con.name, 23 | mode = "undirected", weighted = TRUE, diag = FALSE, ...) 24 | } 25 | \arguments{ 26 | \item{x}{A \code{bg_GLM}, \code{mtpc}, or \code{NBS} object} 27 | 28 | \item{atlas}{Character string specifying the brain atlas to use} 29 | 30 | \item{type}{Character string indicating the type of graphs. Default: 31 | \code{observed}} 32 | 33 | \item{level}{Character string indicating whether the graphs are subject-, 34 | group-, or contrast-specific. Default: \code{'subject'}} 35 | 36 | \item{set.attrs}{Logical indicating whether to assign all graph-, vertex-, 37 | and edge-level attributes (via \code{\link{set_brainGraph_attr}}). Default: 38 | \code{TRUE}} 39 | 40 | \item{modality}{Character string indicating imaging modality (e.g. 'dti'). 41 | Default: \code{NULL}} 42 | 43 | \item{weighting}{Character string indicating how the edges are weighted 44 | (e.g., 'fa', 'pearson', etc.). Default: \code{NULL}} 45 | 46 | \item{threshold}{Integer or number indicating the threshold used when 47 | \dQuote{sparsifying} the connectivity matrix (if any). Default: \code{NULL}} 48 | 49 | \item{gnames}{Character vector of graph names (e.g., study IDs if 50 | \code{level='subject'}). Default: \code{NULL}} 51 | 52 | \item{...}{Other arguments passed to \code{\link{set_brainGraph_attr}}} 53 | 54 | \item{mode}{Character string defining how the matrix should be interpreted. 55 | Default: \code{'undirected'}} 56 | 57 | \item{weighted}{Logical specifying whether to create a weighted network} 58 | 59 | \item{diag}{Logical indicating whether to include the diagonal of the 60 | connectivity matrix. Default: \code{FALSE}} 61 | } 62 | \value{ 63 | A \code{brainGraphList} object, with a graph object for each contrast 64 | with additional attributes: 65 | \item{Graph}{\emph{name} (contrast name), \emph{outcome} (the outcome 66 | variable), \emph{alpha} (the significance level); for MTPC: 67 | \emph{tau.mtpc}, \emph{S.mtpc}, \emph{S.crit}, \emph{A.crit}} 68 | \item{Vertex}{\emph{size2} (t-statistic); \emph{size} (the t-stat 69 | transformed for visualization purposes); \emph{p} (equal to \eqn{1-p}); 70 | \emph{p.fdr} (equal to \eqn{1-p_{FDR}}, the FDR-adjusted p-value); 71 | \emph{effect.size} (the contrast of parameter estimates for t-contrasts; 72 | the extra sum of squares for F-contrasts); \emph{se} (the 73 | standard error of \emph{gamma}); \emph{A.mtpc}, \emph{sig} (binary 74 | indicating whether \code{A.mtpc > A.crit}) (for MTPC)} 75 | 76 | \code{make_brainGraphList.NBS} returns graphs with additional 77 | attributes: 78 | \item{Vertex}{\emph{comp} (integer vector indicating connected component 79 | membership), \emph{p.nbs} (P-value for each component)} 80 | \item{Edge}{\emph{stat} (the test statistic for each connection), \emph{p} 81 | (the P-value)} 82 | } 83 | \description{ 84 | These methods create a \code{brainGraphList} with attributes specific to the 85 | results of \code{\link{brainGraph_GLM}}, \code{\link{mtpc}}, or 86 | \code{\link{NBS}}. The \code{graphs} element of the returned object will 87 | contain one graph for each contrast. 88 | } 89 | \note{ 90 | Only valid for \emph{vertex}-level and \emph{NBS} analyses. 91 | } 92 | \seealso{ 93 | \code{\link{brainGraph_GLM}, \link{mtpc}, \link{NBS}} 94 | 95 | Other Graph creation functions: \code{\link{Creating_Graphs}}, 96 | \code{\link{brainGraphList}}, 97 | \code{\link{make_ego_brainGraph}} 98 | } 99 | \concept{Graph creation functions} 100 | -------------------------------------------------------------------------------- /man/glm_design.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/glm_design.R 3 | \name{GLM design} 4 | \alias{GLM design} 5 | \alias{brainGraph_GLM_design} 6 | \title{Create a design matrix for linear model analysis} 7 | \usage{ 8 | brainGraph_GLM_design(covars, coding = c("dummy", "effects", 9 | "cell.means"), factorize = TRUE, binarize = NULL, int = NULL, 10 | mean.center = FALSE, center.how = c("all", "within-groups"), 11 | center.by = getOption("bg.group")) 12 | } 13 | \arguments{ 14 | \item{covars}{A \code{data.table} of covariates} 15 | 16 | \item{coding}{Character string indicating how factor variables will be coded. 17 | Default: \code{'dummy'}} 18 | 19 | \item{factorize}{Logical indicating whether to convert \emph{character} 20 | columns into \emph{factor}. Default: \code{TRUE}} 21 | 22 | \item{binarize}{Character vector specifying the column name(s) of the 23 | covariate(s) to be converted from type \code{factor} to \code{numeric}. 24 | Default: \code{NULL}} 25 | 26 | \item{int}{Character vector specifying the column name(s) of the 27 | covariate(s) to test for an interaction. Default: \code{NULL}} 28 | 29 | \item{mean.center}{Logical indicating whether to mean center non-factor 30 | variables. Default: \code{FALSE}} 31 | 32 | \item{center.how}{Character string indicating whether to use the grand mean 33 | or groupwise means. Default: \code{'all'}} 34 | 35 | \item{center.by}{Character string indicating which grouping variable to use 36 | for calculating means (if applicable). Default: \code{'Group'}} 37 | } 38 | \value{ 39 | A numeric matrix. Rownames are subject ID's and column names are the 40 | variable names. There will be additional attributes recording the 41 | \code{coding}, \code{factorize}, and \code{mean.center} function arguments. 42 | There will also be attributes for \code{binarize} and \code{int} if they 43 | are not \code{NULL}, and \code{center.how} and \code{center.by} if 44 | \code{mean.center=TRUE}. 45 | } 46 | \description{ 47 | \code{brainGraph_GLM_design} takes a \code{data.table} of covariates and 48 | returns a \emph{design matrix} to be used in linear model analysis. 49 | } 50 | \details{ 51 | There are three different ways to code factors: \emph{dummy}, \emph{effects}, 52 | or \emph{cell-means} (chosen by the argument \code{coding}). \emph{Effects} 53 | coding is sometimes referred to as \emph{deviation} coding. \emph{Dummy} 54 | coding is the default when calling \code{lm}. To understand the difference 55 | between these, see Chapter 8 of the User Guide. 56 | } 57 | \section{Character variables}{ 58 | 59 | The default behavior is to convert all character columns (excluding the Study 60 | ID column and any that you list in the \code{binarize} argument) to factor 61 | variables. To change this, set \code{factorize=FALSE}. So, if your covariates 62 | include multiple character columns, but you want to convert \emph{Scanner} to 63 | binary instead of a factor, you may still specify \code{binarize='Scanner'} 64 | and get the expected result. \code{binarize} will convert the given factor 65 | variable(s) into numeric variable(s), which is performed \emph{before} 66 | centering (if applicable). 67 | } 68 | 69 | \section{Centering}{ 70 | 71 | The argument \code{mean.center} will mean-center (i.e., subtract the mean of 72 | from each variable) any non-factor variables (including any dummy/indicator 73 | covariates). This is done \emph{after} \dQuote{factorizing} and 74 | \dQuote{binarizing}. If \code{center.how='all'}, then the \dQuote{grand mean} 75 | will be used; otherwise, the groupwise means will be used. The grouping 76 | variable is determined by \code{center.by} and is by default \code{'Group'}. 77 | } 78 | 79 | \section{Interactions}{ 80 | 81 | \code{int} specifies which variables should interact with one another. This 82 | argument accepts both numeric/continuous (e.g., \emph{Age}) and factor 83 | variables (e.g., \emph{Sex}). All interaction combinations will be generated: 84 | if you supply 3 variables, all two-way and the single three-way interaction 85 | will be generated. This variable \emph{must} have at least two elements; it 86 | is otherwise ignored. It is generally recommended that centering be performed 87 | when including interaction terms. 88 | } 89 | 90 | \examples{ 91 | \dontrun{ 92 | # Recreate design matrix when "outcome == measure" 93 | DT <- res.glm$DT.Xy[region == levels(region)[1L], 94 | !c('region', res.glm$outcome), 95 | with=FALSE] 96 | X <- do.call(brainGraph_GLM_design, c(list(covars=DT), 97 | attributes(res.glm$X)[-c(1L, 2L)])) 98 | all.equal(X, res.glm$X) 99 | } 100 | } 101 | \seealso{ 102 | Other GLM functions: \code{\link{GLM fits}}, 103 | \code{\link{GLM}}, \code{\link{mtpc}} 104 | } 105 | \author{ 106 | Christopher G. Watson, \email{cgwatson@bu.edu} 107 | } 108 | \concept{GLM functions} 109 | -------------------------------------------------------------------------------- /man/glm_graph_plots.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_brainGraph.R 3 | \name{Plotting GLM graphs} 4 | \alias{Plotting GLM graphs} 5 | \alias{plot.brainGraph_NBS} 6 | \alias{plot.brainGraph_GLM} 7 | \alias{plot.brainGraph_mtpc} 8 | \alias{plot.brainGraph_mediate} 9 | \title{Plot a graph with results from GLM-based analyses} 10 | \usage{ 11 | \method{plot}{brainGraph_NBS}(x, alpha = 0.05, 12 | subgraph = paste("p.nbs >", 1 - alpha), vertex.label = NA, 13 | vertex.color = "color.comp", edge.color = "color.comp", 14 | subtitle = NULL, main = paste0("NBS: ", x$name), cex.main = 2, ...) 15 | 16 | \method{plot}{brainGraph_GLM}(x, p.sig = c("p", "p.fdr", "p.perm"), 17 | subgraph = NULL, main = paste0(x$outcome, ": ", x$name), 18 | subtitle = NULL, cex.main = 2, ...) 19 | 20 | \method{plot}{brainGraph_mtpc}(x, subgraph = "sig == 1", 21 | main = paste0(x$outcome, ": ", x$name), subtitle = NULL, 22 | cex.main = 2, ...) 23 | 24 | \method{plot}{brainGraph_mediate}(x, subgraph = "p.acme > 0.95", 25 | main = sprintf("Effect of \\"\%s\\" on\\n\\"\%s\\"\\nmediated by \\"\%s\\"", 26 | x$treat, x$outcome, x$mediator), subtitle = NULL, cex.main = 1, ...) 27 | } 28 | \arguments{ 29 | \item{x}{A \code{brainGraph_GLM}, \code{brainGraph_mtpc}, 30 | \code{brainGraph_mediate}, or \code{brainGraph_NBS} object} 31 | 32 | \item{alpha}{Numeric; the significance level. Default: \code{0.05}} 33 | 34 | \item{subgraph}{Character string specifying the condition for subsetting the 35 | graph.} 36 | 37 | \item{vertex.label}{Character vector of the vertex labels to be displayed.} 38 | 39 | \item{vertex.color}{Character string specifying the vertex attribute to color 40 | the vertices by.} 41 | 42 | \item{edge.color}{Character string specifying the edge attribute to color 43 | the edges by.} 44 | 45 | \item{subtitle}{Character string; the subtitle. Default: \code{'default'}} 46 | 47 | \item{main}{Character string; the main title. Default: \code{NULL}} 48 | 49 | \item{cex.main}{Numeric; the scaling factor for text size; see 50 | \code{\link[graphics]{par}}} 51 | 52 | \item{...}{Other arguments passed to \code{\link{plot.brainGraph}}} 53 | 54 | \item{p.sig}{Character string indicating which p-value to use for determining 55 | significance (default: \code{p})} 56 | } 57 | \description{ 58 | These methods are convenience functions for plotting a graph based on results 59 | from GLM-based analyses (i.e., \code{\link{brainGraph_GLM}, 60 | \link{brainGraph_mediate}, \link{mtpc}, \link{NBS}}). There are several 61 | default arguments which differ depending on the input object. 62 | } 63 | \details{ 64 | The default arguments are specified so that the user only needs to type 65 | \code{plot(x)} at the console, if desired. For all methods, the plot's 66 | \emph{subtitle} will be omitted. 67 | } 68 | \section{NBS}{ 69 | 70 | By default, a subgraph will be plotted consisting of only those vertices 71 | which are part of a significant connected component. Vertex/edge colors will 72 | correspond to connected component membership. Vertex names will be omitted. 73 | Finally, the plot title will contain the contrast name. 74 | } 75 | 76 | \section{brainGraph_GLM}{ 77 | 78 | By default, a subgraph will be plotted consisting of only those vertices for 79 | which \eqn{p < \alpha}. It will also include a plot title with the outcome 80 | measure and contrast name. 81 | } 82 | 83 | \section{mtpc}{ 84 | 85 | By default, a subgraph will be plotted consisting of only those vertices for 86 | which \eqn{A_{mtpc} > A_{crit}}. It will also include a plot title with the 87 | outcome measure and contrast name. 88 | } 89 | 90 | \section{brainGraph_mediate}{ 91 | 92 | By default, a subgraph will be plotted consisting of only those vertices for 93 | which \eqn{P_{acme} < \alpha}. It will also include a plot title with the 94 | treatment, mediator, and outcome variable names. 95 | } 96 | 97 | \seealso{ 98 | Other Plotting functions: \code{\link{plot.brainGraphList}}, 99 | \code{\link{plot.brainGraph}}, 100 | \code{\link{plot_brainGraph_gui}}, 101 | \code{\link{plot_brainGraph_multi}} 102 | } 103 | \concept{Plotting functions} 104 | -------------------------------------------------------------------------------- /man/glm_influence.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/glm_stats.R 3 | \name{GLM influence measures} 4 | \alias{GLM influence measures} 5 | \alias{rstandard.bg_GLM} 6 | \alias{rstudent.bg_GLM} 7 | \alias{hatvalues.bg_GLM} 8 | \alias{cooks.distance.bg_GLM} 9 | \alias{dffits.bg_GLM} 10 | \alias{dfbeta.bg_GLM} 11 | \alias{dfbetas.bg_GLM} 12 | \alias{covratio.bg_GLM} 13 | \alias{influence.bg_GLM} 14 | \title{Influence measures for a bg_GLM object} 15 | \usage{ 16 | \method{rstandard}{bg_GLM}(model, type = c("sd.1", "predictive"), ...) 17 | 18 | \method{rstudent}{bg_GLM}(model, ...) 19 | 20 | \method{hatvalues}{bg_GLM}(model, ...) 21 | 22 | \method{cooks.distance}{bg_GLM}(model, ...) 23 | 24 | dffits.bg_GLM(model) 25 | 26 | \method{dfbeta}{bg_GLM}(model, ...) 27 | 28 | \method{dfbetas}{bg_GLM}(model, ...) 29 | 30 | covratio.bg_GLM(model) 31 | 32 | \method{influence}{bg_GLM}(model, do.coef = TRUE, region = NULL, ...) 33 | } 34 | \arguments{ 35 | \item{model}{A \code{bg_GLM} object} 36 | 37 | \item{type}{The type of standardized residuals. Default: \code{'sd.1'}} 38 | 39 | \item{...}{Unused} 40 | 41 | \item{do.coef}{Logical indicating whether to calculate \code{dfbeta}} 42 | 43 | \item{region}{Character string of the region(s) to return results for. 44 | Default is to calculate for all regions} 45 | } 46 | \value{ 47 | Most influence functions return a numeric matrix in which rownames 48 | are Study ID's and column names are regions. \code{dfbeta} and 49 | \code{dfbetas} return a numeric array in which each column is a parameter 50 | estimate and the 3rd dimension is for each region. \code{influence} returns 51 | a list with class \code{infl.bg_GLM} and elements: 52 | \item{infmat}{Numeric array (like \code{dfbeta}) with DFBETAs, DFFITs, 53 | covratios, Cook's distance, and hat values} 54 | \item{is.inf}{Logical array of the same data as \code{infmat}; values of 55 | \code{TRUE} indicate the subject-variable-region combination is an 56 | outlier value} 57 | \item{f}{The model \emph{formula}} 58 | \item{sigma}{The leave-one-out residual standard deviation} 59 | \item{wt.res}{Model residuals} 60 | } 61 | \description{ 62 | These functions compute common (leave-one-out) diagnostics for the models in 63 | a \code{bg_GLM} object. 64 | } 65 | \details{ 66 | The \code{influence} method calculates all diagnostics present in 67 | \code{\link[stats]{lm.influence}} and 68 | \code{\link[stats]{influence.measures}}, consisting of the following 69 | functions: 70 | \describe{ 71 | \item{rstandard}{Standardized residuals. Choosing \code{type='predictive'} 72 | returns leave-one-out cross validation residuals. The \dQuote{PRESS} 73 | statistic can be calculated as \code{colSums(resids.p^2)}} 74 | \item{rstudent}{Studentized residuals} 75 | \item{hatvalues}{The \emph{leverage}, or the diagonal of the 76 | \emph{hat/projection matrix}} 77 | \item{cooks.distance}{Cook's distance} 78 | \item{dffits.bg_GLM}{The change in fitted values when deleting 79 | observations} 80 | \item{dfbeta}{The change in parameter estimates (coefficients) when 81 | deleting observations} 82 | \item{dfbetas}{The \emph{scaled} change in parameter estimates} 83 | \item{covratio.bg_GLM}{The covariance ratios, or the change in the 84 | determinant of the covariance matrix of parameter estimates when deleting 85 | observations} 86 | } 87 | } 88 | \section{Outlier values}{ 89 | 90 | Each variable has a different criterion for determining outliers. In the 91 | following: \code{x} is the influence variable (for \code{DFBETA}, the 92 | criterion applies to all DFBETAs); \code{k} is the number of columns of the 93 | design matrix; \code{dfR} is the residual degrees of freedom; and \code{n} is 94 | the number of observations. 95 | \describe{ 96 | \item{DFBETAs}{If \eqn{|x| > 1}} 97 | \item{DFFITs}{If \eqn{|x| > 3 \sqrt{k / dfR}}} 98 | \item{covratio}{If \eqn{|1 - x| > (3k / dfR)}} 99 | \item{cook}{If \eqn{F_{k, dfR}(x) > 0.5}} 100 | \item{hat}{If \eqn{x > 3k / n}} 101 | } 102 | The return object of \code{influence} has a \code{print} method which will 103 | list the subjects/variables/regions for which an outlier was detected. 104 | } 105 | 106 | \seealso{ 107 | \code{\link{GLM}} 108 | } 109 | \author{ 110 | Christopher G. Watson, \email{cgwatson@bu.edu} 111 | } 112 | -------------------------------------------------------------------------------- /man/glm_info.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/glm_methods.R 3 | \name{GLM basic info} 4 | \alias{GLM basic info} 5 | \alias{nobs.bg_GLM} 6 | \alias{terms.bg_GLM} 7 | \alias{formula.bg_GLM} 8 | \alias{labels.bg_GLM} 9 | \alias{case.names.bg_GLM} 10 | \alias{variable.names.bg_GLM} 11 | \alias{region.names.bg_GLM} 12 | \alias{nregions.bg_GLM} 13 | \title{Extract basic information from a bg_GLM object} 14 | \usage{ 15 | \method{nobs}{bg_GLM}(object, ...) 16 | 17 | \method{terms}{bg_GLM}(x, ...) 18 | 19 | \method{formula}{bg_GLM}(x, ...) 20 | 21 | \method{labels}{bg_GLM}(object, ...) 22 | 23 | \method{case.names}{bg_GLM}(object, ...) 24 | 25 | \method{variable.names}{bg_GLM}(object, ...) 26 | 27 | \method{region.names}{bg_GLM}(object) 28 | 29 | \method{nregions}{bg_GLM}(object) 30 | } 31 | \arguments{ 32 | \item{...}{Unused} 33 | 34 | \item{x, object}{A \code{bg_GLM} object} 35 | } 36 | \value{ 37 | \code{terms} returns a named integer list in which the names are the 38 | term labels and the list elements are the column(s) of the design matrix 39 | for each term. \code{nobs} returns an integer. The other functions return 40 | character vectors. 41 | } 42 | \description{ 43 | These functions return the \code{terms}, \emph{term labels}, \emph{model 44 | formula}, \dQuote{case names}, \dQuote{variable names}, \emph{region names}, 45 | and number of observations for a \code{bg_GLM} object. The term labels are 46 | used for ANOVA tables. 47 | } 48 | \note{ 49 | \code{formula} returns a character string, not a \code{formula} 50 | object. 51 | } 52 | -------------------------------------------------------------------------------- /man/glm_model_select.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/glm_stats.R 3 | \name{GLM model selection} 4 | \alias{GLM model selection} 5 | \alias{logLik.bg_GLM} 6 | \alias{extractAIC.bg_GLM} 7 | \title{Model selection for bg_GLM objects} 8 | \usage{ 9 | \method{logLik}{bg_GLM}(object, REML = FALSE, ...) 10 | 11 | \method{extractAIC}{bg_GLM}(fit, scale = 0, k = 2, ...) 12 | } 13 | \arguments{ 14 | \item{object, fit}{A \code{bg_GLM} object} 15 | 16 | \item{REML}{Logical indicating whether to return the \emph{restricted} 17 | log-likelihood. Default: \code{FALSE}} 18 | 19 | \item{...}{Unused} 20 | 21 | \item{scale}{Should be left at its default} 22 | 23 | \item{k}{Numeric; the weight of the equivalent degrees of freedom} 24 | } 25 | \value{ 26 | \code{logLik} returns an object of class \code{logLik} with several 27 | attributes. \code{extractAIC} returns a numeric vector in which the first 28 | element is the \emph{equivalent degrees of freedom} and the remaining are 29 | the AIC's for each region 30 | } 31 | \description{ 32 | These functions compute the log-likelihood and Akaike's \emph{An Information 33 | Criterion (AIC)} of a \code{bg_GLM} object. See 34 | \code{\link[stats]{logLik.lm}} and \code{\link[stats]{extractAIC}} for 35 | details. 36 | } 37 | \details{ 38 | The functions \code{\link[stats]{AIC}} and \code{\link[stats]{BIC}} will also 39 | work for \code{bg_GLM} objects because they each call \code{logLik}. 40 | } 41 | -------------------------------------------------------------------------------- /man/glm_stats.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/glm_stats.R 3 | \name{GLM statistics} 4 | \alias{GLM statistics} 5 | \alias{coef.bg_GLM} 6 | \alias{confint.bg_GLM} 7 | \alias{fitted.bg_GLM} 8 | \alias{residuals.bg_GLM} 9 | \alias{deviance.bg_GLM} 10 | \alias{coeff_determ} 11 | \alias{df.residual.bg_GLM} 12 | \alias{sigma.bg_GLM} 13 | \alias{vcov.bg_GLM} 14 | \alias{coeff_table} 15 | \alias{anova.bg_GLM} 16 | \title{Extract model fit statistics from a bg_GLM object} 17 | \usage{ 18 | \method{coef}{bg_GLM}(object, ...) 19 | 20 | \method{confint}{bg_GLM}(object, parm, level = 0.95, ...) 21 | 22 | \method{fitted}{bg_GLM}(object, ...) 23 | 24 | \method{residuals}{bg_GLM}(object, type = c("response", "partial"), ...) 25 | 26 | \method{deviance}{bg_GLM}(object, ...) 27 | 28 | coeff_determ(object, adjusted = FALSE) 29 | 30 | \method{df.residual}{bg_GLM}(object, ...) 31 | 32 | \method{sigma}{bg_GLM}(object, ...) 33 | 34 | \method{vcov}{bg_GLM}(object, ...) 35 | 36 | coeff_table(object, CI = FALSE, level = 0.95) 37 | 38 | \method{anova}{bg_GLM}(object, region = NULL, ...) 39 | } 40 | \arguments{ 41 | \item{object}{A \code{bg_GLM} object} 42 | 43 | \item{...}{Unused} 44 | 45 | \item{parm}{Vector of parameters to calculate confidence intervals for. 46 | Default is to use all parameters} 47 | 48 | \item{level}{The confidence level. Default: \code{0.95}} 49 | 50 | \item{type}{Character string specifying the type of residuals to return. 51 | Default: \code{'response'}} 52 | 53 | \item{adjusted}{Logical indicating whether to calculate the adjusted 54 | R-squared. Default: \code{FALSE}} 55 | 56 | \item{CI}{Logical indicating whether to include confidence intervals of 57 | parameter estimates in the coefficient summary table. Default: \code{FALSE}} 58 | 59 | \item{region}{Character vector indicating the region(s) to calculate ANOVA 60 | statistics for. Default: \code{NULL} (use all regions)} 61 | } 62 | \value{ 63 | A named numeric vector, matrix, or array, depending on the function: 64 | \item{coef}{Matrix in which rownames are parameter names and column names 65 | are regions} 66 | \item{fitted,residuals}{Matrix in which rownames are Study ID's and column 67 | names are regions. If \code{type='partial'}, an array is returned in 68 | which columns are \emph{terms} and the 3rd dimension are regions} 69 | \item{deviance,coeff_determ,sigma}{Numeric vector with elements for each 70 | region} 71 | \item{df.residual}{Single integer; the degrees of freedom} 72 | \item{confint,vcov,coeff_table}{Numeric array; the extent of the third 73 | dimension equals the number of regions} 74 | 75 | \code{anova} returns a \emph{list} of tables of class \code{anova} 76 | } 77 | \description{ 78 | These functions extract or calculate model fit statistics of a 79 | \code{bg_GLM} object. These can be found in the output from 80 | \code{\link[stats]{summary.lm}}. 81 | } 82 | \details{ 83 | These mimic the same functions that operate on \code{\link{lm}} objects, and 84 | include: 85 | \describe{ 86 | \item{coef}{Regression coefficients (parameter estimates)} 87 | \item{confint}{Confidence intervals (by default, 95\%) for parameter 88 | estimates} 89 | \item{fitted}{Fitted (mean) values; i.e., the design matrix multiplied by 90 | the parameter estimates, \eqn{X \hat{\beta}}} 91 | \item{residuals}{Model residuals; i.e., the response/outcome variable minus 92 | the \emph{fitted} values. Partial residuals can also be calculated} 93 | \item{deviance}{Model deviance, or the \emph{residual sum of squares}} 94 | \item{coeff_determ}{Calculate the \emph{coefficient of determination} (or 95 | \eqn{R^2}), adjusted or unadjusted} 96 | \item{df.residual}{Residual degrees of freedom} 97 | \item{sigma}{Residual standard deviation, sometimes called the \emph{root 98 | mean squared error (RMSE)}} 99 | \item{vcov}{Variance-covariance matrix of the model parameters} 100 | } 101 | 102 | \code{coeff_table} returns model coefficients, standard errors, T-statistics, 103 | and P-values for all model terms and regions in a \code{bg_GLM} object. This 104 | is the same as running \code{summary(x)$coefficients} for a \code{lm} object. 105 | } 106 | \note{ 107 | \code{sigma} -- The denominator is \emph{not} the number of 108 | observations, but rather the model's \emph{residual degrees of freedom}. 109 | 110 | When calculating \emph{partial residuals}, the parameter estimates are 111 | \emph{not} re-calculated after removing one of the model terms. 112 | } 113 | \section{ANOVA tables}{ 114 | 115 | The \code{anova} method calculates the so-called \emph{Type III} test 116 | statistics for a \code{bg_GLM} object. These standard ANOVA statistics 117 | include: sum of squares, mean squares, degrees of freedom, F statistics, and 118 | P-values. Additional statistics calculated are: \eqn{\eta^2}, partial 119 | \eqn{\eta^2}, \eqn{\omega^2}, and partial \eqn{\omega^2} as measures of 120 | \emph{effect size}. 121 | } 122 | 123 | \seealso{ 124 | \code{\link{GLM}}, \code{\link[car]{Anova}} 125 | } 126 | \author{ 127 | Christopher G. Watson, \email{cgwatson@bu.edu} 128 | } 129 | -------------------------------------------------------------------------------- /man/hubness.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/hubs.R 3 | \name{hubness} 4 | \alias{hubness} 5 | \title{Calculate vertex hubness} 6 | \usage{ 7 | hubness(g, xfm.type = g$xfm.type, weights = NULL, prop.keep = 0.2) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{xfm.type}{Character string specifying how to transform the weights. 13 | Default: \code{1/w}} 14 | 15 | \item{weights}{Numeric vector of edge weights; if \code{NULL} (the default), 16 | and if the graph has edge attribute \code{weight}, then that will be used. 17 | To avoid using weights, this should be \code{NA}.} 18 | 19 | \item{prop.keep}{Numeric (between 0 and 1) indicating the proportion of 20 | vertices to consider as having a high score. Default: 0.2 (20\%)} 21 | } 22 | \value{ 23 | A numeric vector with the vertices' hubness score 24 | } 25 | \description{ 26 | \code{hubness} calculates the \dQuote{hubness} (see reference) of the 27 | vertices in a graph. These are vertices which meet at least two of the 28 | following four criteria: 29 | \enumerate{ 30 | \item Have high degree/strength 31 | \item Have high betweenness centrality 32 | \item Have low clustering coefficient 33 | \item Have low average path length 34 | } 35 | For each criterion, \dQuote{high} or \dQuote{low} means \dQuote{in the top 36 | 20\%} across all vertices. Vertices meeting any of the criteria get a value 37 | of 1 for that metric; these are summed to yield the hubness score which 38 | ranges from 0-4. As in the reference article, vertices with a score of 2 or 39 | higher are to be considered hubs, although that determination isn't made in 40 | this function. 41 | } 42 | \references{ 43 | van den Heuvel, M.P. and Mandl, R.C.W. and Stam, C.J. and Kahn, 44 | R.S. and Pol, H.E.H. (2010) Aberrant frontal and temporal complex network 45 | structure in schizophrenia: a graph theoretical analysis. \emph{The Journal 46 | of Neuroscience}, \bold{30(47)}, 15915--15926. 47 | \doi{10.1523/JNEUROSCI.2874-10.2010} 48 | } 49 | \author{ 50 | Christopher G. Watson, \email{cgwatson@bu.edu} 51 | } 52 | -------------------------------------------------------------------------------- /man/import_scn.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/import.R 3 | \name{import_scn} 4 | \alias{import_scn} 5 | \title{Import data for structural connectivity analysis} 6 | \usage{ 7 | import_scn(datadir, atlas, modality = "thickness", exclude.subs = NULL, 8 | custom.atlas = NULL) 9 | } 10 | \arguments{ 11 | \item{datadir}{The path name of the directory containing the data files} 12 | 13 | \item{atlas}{Character string specifying the atlas in use. For a custom 14 | atlas, please specify \code{'custom'}, and provide the name to the 15 | \code{custom.atlas} argument} 16 | 17 | \item{modality}{The structural imaging measure (default: \code{'thickness'})} 18 | 19 | \item{exclude.subs}{Vector indicating the subjects to exclude, if any 20 | (default: \code{NULL})} 21 | 22 | \item{custom.atlas}{Character string specifying the name of the R object for 23 | the atlas in use, if \code{atlas='custom'} was also supplied (default: 24 | \code{NULL})} 25 | } 26 | \value{ 27 | A list containing: 28 | \item{atlas}{Character string} 29 | \item{modality}{Character string} 30 | \item{lhrh}{A \code{data.table} of structural MRI measures for both 31 | hemispheres} 32 | \item{aseg}{A \code{data.table} of structural MRI measures for subcortical 33 | gray matter, if applicable} 34 | \item{subs.excluded}{Vector of subject ID's that were excluded} 35 | \item{subs.missing}{Vector of subject ID's that are not present in \emph{both} 36 | the cortical and subcortical tables (if applicable)} 37 | } 38 | \description{ 39 | Given a directory, atlas name, and imaging modality/structural metric, this 40 | function imports data for structural connectivity analysis. It expects files 41 | containing a table of region-wise structural MRI measures (e.g., mean 42 | cortical thickness), with one file for each hemisphere. The first column of 43 | all files should contain the \emph{subject ID}; the column name will be 44 | changed to the value of \code{getOption('bg.subject_id')}. 45 | } 46 | \details{ 47 | The files should have specific names; the second in the following list is 48 | only required for atlases/parcellations that include \emph{subcortical gray 49 | matter} (e.g., \code{dk.scgm}). 50 | \itemize{ 51 | \item \code{${parcellation}_${hemi}_${modality}.csv} for cortical volume, 52 | thickness, surface area, or local gyrification index (LGI). Here, 53 | \code{${parcellation}} can be \code{aparc}, \code{aparc.DKTatlas40}, 54 | or \code{aparc.a2009s}. For example, for cortical thickness with the 55 | \emph{Desikan-Killiany} atlas, the filename should be 56 | \code{aparc_lh_thickness.csv}. If you are using a custom atlas, see the 57 | \emph{Note} below. The \code{${hemi}} variable is either \code{lh} or 58 | \code{rh}. Finally, \code{${modality}} should be either \code{volume}, 59 | \code{thickness}, \code{area}, or \code{lgi}. 60 | \item \code{asegstats.csv} for SCGM volume 61 | } 62 | } 63 | \note{ 64 | When using a custom atlas, the name of the atlas's data.table should 65 | match the \code{${parcellation}} portion of the filename (specification 66 | shown above). Furthermore, it must conform to the output of Freesurfer's 67 | \code{aparcstats2table} (and \code{asegstats2table}, if applicable). 68 | Otherwise, please contact me for inclusion of a different data type. 69 | 70 | The subject ID column will be zero-padded (to the left) to avoid issues 71 | when the variable is numeric; this ensures that all ID's will have the same 72 | number of characters and sorting will be done properly. 73 | } 74 | \examples{ 75 | \dontrun{ 76 | raw_data <- import_scn('/home/cwatson/data', atlas='dkt', 77 | exclude.subs=c('con07', 'con23', 'pat15')) 78 | } 79 | } 80 | \seealso{ 81 | Other Structural covariance network functions: \code{\link{Bootstrapping}}, 82 | \code{\link{IndividualContributions}}, 83 | \code{\link{Residuals}}, 84 | \code{\link{brainGraph_permute}}, 85 | \code{\link{corr.matrix}}, \code{\link{plot_volumetric}} 86 | } 87 | \author{ 88 | Christopher G. Watson, \email{cgwatson@bu.edu} 89 | } 90 | \concept{Structural covariance network functions} 91 | -------------------------------------------------------------------------------- /man/individ_contrib.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/individ_contrib.R 3 | \name{IndividualContributions} 4 | \alias{IndividualContributions} 5 | \alias{loo} 6 | \alias{aop} 7 | \alias{summary.IC} 8 | \alias{plot.IC} 9 | \title{Approaches to estimate individual network contribution} 10 | \usage{ 11 | loo(resids, corrs, level = c("global", "regional")) 12 | 13 | aop(resids, corrs, level = c("global", "regional"), control.value = 1L) 14 | 15 | \method{summary}{IC}(object, region = NULL, digits = max(3L, 16 | getOption("digits") - 2L), ...) 17 | 18 | \method{plot}{IC}(x, plot.type = c("mean", "smooth", "boxplot"), 19 | region = NULL, ids = TRUE, ...) 20 | } 21 | \arguments{ 22 | \item{resids}{An object of class \code{brainGraph_resids} (the output from 23 | \code{\link{get.resid}})} 24 | 25 | \item{corrs}{List of lists of correlation matrices (as output by 26 | \code{\link{corr.matrix}}).} 27 | 28 | \item{level}{Character string; the level at which you want to calculate 29 | contributions (either \code{global} or \code{regional})} 30 | 31 | \item{control.value}{Integer or character string specifying the control group 32 | (default: 1L)} 33 | 34 | \item{object, x}{A \code{IC} object} 35 | 36 | \item{region}{Character vector specifying which regions' IC's to print. Only 37 | relevant if \code{method='Leave one out'}} 38 | 39 | \item{digits}{Integer specifying the number of digits to display for P-values} 40 | 41 | \item{...}{Unused} 42 | 43 | \item{plot.type}{Character string indicating the type of plot; the default is 44 | to plot the mean (along with standard errors)} 45 | 46 | \item{ids}{Logical indicating whether to plot Study ID's for outliers. 47 | Otherwise plots the integer index} 48 | } 49 | \value{ 50 | A \code{data.table} with columns for 51 | \item{Study.ID}{Subject identifier} 52 | \item{Group}{Group membership} 53 | \item{region}{If \code{level='regional'}} 54 | \item{IC,RC}{The value of the individual/regional contributions} 55 | } 56 | \description{ 57 | \code{loo} calculates the individual contribution to group network data for 58 | each subject in each group using a \dQuote{leave-one-out} approach. The 59 | residuals of a single subject are excluded, and a correlation matrix is 60 | created. This is compared to the original correlation matrix using the Mantel 61 | test. 62 | 63 | \code{aop} calculates the individual contribution using an 64 | \dQuote{add-one-patient} approach. The residuals of a single patient are 65 | added to those of a control group, and a correlation matrix is created. This 66 | is repeated for all individual patients and each patient group. 67 | 68 | The \code{summary} method prints the group/region-wise means and standard 69 | deviations. 70 | 71 | The \code{plot} method is only valid for \emph{regional} contribution 72 | estimates, and plots the average regional contribution for each 73 | vertex/region. 74 | } 75 | \note{ 76 | For \code{aop}, it is assumed by default that the control group is the 77 | first group. 78 | } 79 | \examples{ 80 | \dontrun{ 81 | IC <- loo(resids.all, corrs) 82 | RC <- loo(resids.all, corrs, level='regional') 83 | } 84 | \dontrun{ 85 | IC <- aop(resids.all, corrs) 86 | RC <- aop(resids.all, corrs, level='regional') 87 | } 88 | } 89 | \references{ 90 | Saggar, M. and Hosseini, S.M.H. and Buno, J.L. and Quintin, E. 91 | and Raman, M.M. and Kesler, S.R. and Reiss, A.L. (2015) Estimating 92 | individual contributions from group-based structural correlations networks. 93 | \emph{NeuroImage}, \bold{120}, 274--284. 94 | \doi{10.1016/j.neuroimage.2015.07.006} 95 | } 96 | \seealso{ 97 | Other Structural covariance network functions: \code{\link{Bootstrapping}}, 98 | \code{\link{Residuals}}, 99 | \code{\link{brainGraph_permute}}, 100 | \code{\link{corr.matrix}}, \code{\link{import_scn}}, 101 | \code{\link{plot_volumetric}} 102 | } 103 | \author{ 104 | Christopher G. Watson, \email{cgwatson@bu.edu} 105 | } 106 | \concept{Structural covariance network functions} 107 | -------------------------------------------------------------------------------- /man/inverse.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/methods.R, R/utils_matrix.R 3 | \name{Inverse} 4 | \alias{Inverse} 5 | \alias{inv} 6 | \alias{inv.matrix} 7 | \alias{inv.array} 8 | \alias{inv.qr} 9 | \alias{inv.list} 10 | \alias{pinv} 11 | \title{Calculate the inverse of the cross product of a design matrix} 12 | \usage{ 13 | inv(x, ...) 14 | 15 | \method{inv}{matrix}(x, y = NULL, transpose = FALSE, ...) 16 | 17 | \method{inv}{array}(x, y = NULL, transpose = FALSE, ...) 18 | 19 | \method{inv}{qr}(x, p = x$rank, ...) 20 | 21 | \method{inv}{list}(x, p = x[[1L]]$rank, r = length(x), 22 | vnames = dimnames(x[[1L]]$qr)[[2L]], nms = names(x), ...) 23 | 24 | pinv(x) 25 | } 26 | \arguments{ 27 | \item{x}{A numeric matrix or array, a \code{qr} object, or a list of 28 | \code{qr} objects} 29 | 30 | \item{...}{Unused} 31 | 32 | \item{y}{A numeric matrix or vector (for the \code{matrix} and \code{array} 33 | methods). If supplied, this will be multiplied by \code{x} before the 34 | inverse is calculated. Default: \code{NULL}} 35 | 36 | \item{transpose}{Logical. If \code{FALSE} (the default), take the cross 37 | product of the arguments. If \code{TRUE}, use \code{\link{tcrossprod}}} 38 | 39 | \item{p}{The rank of the original matrix} 40 | 41 | \item{r}{The number of design matrices; i.e., the length of the input list} 42 | 43 | \item{vnames}{Character vector of the design matrix's variable names} 44 | 45 | \item{nms}{The region names; i.e., the names of the input list} 46 | } 47 | \value{ 48 | A numeric matrix or array 49 | 50 | \code{pinv} returns the input matrix's pseudoinverse 51 | } 52 | \description{ 53 | \code{inv} is a \code{S3} generic that calculates the inverse of the cross 54 | product of a design matrix, also referred to as the \dQuote{unscaled 55 | covariance matrix}. 56 | 57 | \code{pinv} calculates \eqn{M^{+} = (M^T M)^{-1} M^T} for full (column) rank 58 | matrices. However, it does not verify the matrix's rank. 59 | } 60 | \details{ 61 | If \code{x} is a matrix, the Cholesky decomposition of the cross product is 62 | calculated (or using \code{\link{tcrossprod}} if \code{transpose=TRUE}), and 63 | the inverse is calculated from that result. That is, 64 | \deqn{inv(X) = (X^T X)^{-1}} 65 | \deqn{inv(X, transpose=TRUE) = (X X^T)^{-1}} 66 | \deqn{inv(X, y) = (X^T y)^{-1}} 67 | 68 | If \code{x} is a 3-dimensional array, then the inverse will be calculated for 69 | each matrix along the 3rd dimension, with the same input arguments for each. 70 | 71 | Finally, there is a method for objects with class \code{qr}, and lists of QR 72 | decomposition objects. 73 | } 74 | \note{ 75 | These methods should only be used on \emph{full-rank} matrices, as 76 | there is no error checking being performed. 77 | } 78 | -------------------------------------------------------------------------------- /man/make_auc_brainGraph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/auc.R 3 | \name{make_auc_brainGraph} 4 | \alias{make_auc_brainGraph} 5 | \title{Calculate the AUC across densities of given attributes} 6 | \usage{ 7 | make_auc_brainGraph(g.list, g.attr = NULL, v.attr = NULL, 8 | norm = FALSE) 9 | } 10 | \arguments{ 11 | \item{g.list}{A list of \code{brainGraphList} objects} 12 | 13 | \item{g.attr}{A character vector of graph attribute name(s). Default: 14 | \code{NULL}} 15 | 16 | \item{v.attr}{A character vector of vertex attribute name(s). Default: 17 | \code{NULL}} 18 | 19 | \item{norm}{Logical indicating whether to normalize threshold values to be 20 | between 0 and 1 (inclusive). Default: \code{FALSE}} 21 | } 22 | \value{ 23 | A \code{brainGraphList} object with one graph for each subject 24 | } 25 | \description{ 26 | Given a list of \code{brainGraphList} objects, this function will calculate 27 | the area under the curve (AUC) across all thresholds/densities for each 28 | subject or group. 29 | } 30 | \details{ 31 | If the elements of the input list do not have a \code{threshold} element (or 32 | if it is \code{NULL}) then the AUC will be calculated on the interval 33 | \eqn{[0, 1]} (inclusive). This has the same effect as specifying 34 | \code{norm=TRUE} in the function call. 35 | } 36 | \examples{ 37 | \dontrun{ 38 | g.auc <- make_auc_brainGraph(g.fa, g.attr='E.global.wt') 39 | } 40 | } 41 | -------------------------------------------------------------------------------- /man/make_ego_brainGraph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/create_graphs.R 3 | \name{make_ego_brainGraph} 4 | \alias{make_ego_brainGraph} 5 | \title{Create a graph of the union of multiple vertex neighborhoods} 6 | \usage{ 7 | make_ego_brainGraph(g, vs) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{vs}{Either a character or integer vector (vertex names or indices, 13 | respectively) for the vertices of interest} 14 | } 15 | \value{ 16 | An \code{igraph} graph object containing the union of all edges and 17 | vertices in the neighborhoods of the input vertices; only the vertex 18 | attribute \emph{name} will be present 19 | } 20 | \description{ 21 | This function accepts multiple vertices, creates graphs of their 22 | neighborhoods (of order 1), and returns the union of those graphs. 23 | } 24 | \examples{ 25 | \dontrun{ 26 | subg <- make_ego_brainGraph(g1[[N]], c(24, 58)) 27 | subg <- make_ego_brainGraph(g1[[N]], c('lPCUN', 'rPCUN')) 28 | } 29 | } 30 | \seealso{ 31 | \code{\link[igraph]{ego}} 32 | 33 | Other Graph creation functions: \code{\link{Creating_Graphs_GLM}}, 34 | \code{\link{Creating_Graphs}}, 35 | \code{\link{brainGraphList}} 36 | } 37 | \author{ 38 | Christopher G. Watson, \email{cgwatson@bu.edu} 39 | } 40 | \concept{Graph creation functions} 41 | -------------------------------------------------------------------------------- /man/make_intersection_brainGraph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/create_graphs.R 3 | \name{make_intersection_brainGraph} 4 | \alias{make_intersection_brainGraph} 5 | \title{Create the intersection of graphs based on a logical condition} 6 | \usage{ 7 | make_intersection_brainGraph(..., subgraph, keep.all.vertices = FALSE) 8 | } 9 | \arguments{ 10 | \item{...}{Graph objects or lists of graph objects} 11 | 12 | \item{subgraph}{Character string specifying an equation (logical condition) 13 | for the vertices to subset} 14 | 15 | \item{keep.all.vertices}{Logical indicating whether to keep all vertices that 16 | meet the criteria in at least 1 input graph. Default: \code{FALSE}} 17 | } 18 | \value{ 19 | An \code{igraph} graph object 20 | } 21 | \description{ 22 | Returns a graph object with vertices that meet certain criteria. By default, 23 | only vertices that meet these criteria for \emph{all} input graphs will be 24 | retained. 25 | } 26 | \details{ 27 | If no vertices meet criteria for all input graphs, then an \code{igraph} 28 | graph object with 0 vertices is returned. If \code{keep.all.vertices=TRUE}, 29 | this is essentially performing a \emph{union} of vertex sets that meet the 30 | criteria. In any case, the return graph will have 0 edges. 31 | } 32 | \examples{ 33 | \dontrun{ 34 | res.mtpc <- mtpc(g, covars, ...) 35 | g.mtpc <- make_glm_brainGraph(res.mtpc, atlas) 36 | 37 | ## All vertices with a significant MTPC result for all contrasts: 38 | g.mtpc.int <- make_intersection_brainGraph(g.mtpc, subgraph='sig == 1') 39 | 40 | ## Return graphs with vertices with degree > 0 for each group separately 41 | tapply(g.list, groups(g.list), make_intersection_brainGraph, 42 | subgraph='degree > 0') 43 | } 44 | } 45 | \author{ 46 | Christopher G. Watson, \email{cgwatson@bu.edu} 47 | } 48 | -------------------------------------------------------------------------------- /man/matrix_utils.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils_matrix.R 3 | \name{Matrix utilities} 4 | \alias{Matrix utilities} 5 | \alias{colMax} 6 | \alias{colMaxAbs} 7 | \alias{colMin} 8 | \alias{diag_sq} 9 | \alias{get_thresholds} 10 | \alias{is_binary} 11 | \alias{qr.array} 12 | \alias{qr_Q2} 13 | \alias{qr_R2} 14 | \alias{symm_mean} 15 | \alias{symmetrize} 16 | \alias{symmetrize.matrix} 17 | \alias{symmetrize.array} 18 | \title{Matrix/array utility functions} 19 | \usage{ 20 | colMax(x, n = dim(x)[1L]) 21 | 22 | colMaxAbs(x, n = dim(x)[1L]) 23 | 24 | colMin(x, n = dim(x)[1L]) 25 | 26 | diag_sq(x, n = dim(x)[1L], inds = 1L + 0L:(n - 1L) * (n + 1L)) 27 | 28 | get_thresholds(x, densities, emax = dim(x)[1L] * (dim(x)[1L] - 1L)/2, 29 | ...) 30 | 31 | is_binary(x) 32 | 33 | \method{qr}{array}(x, ...) 34 | 35 | qr_Q2(QR, y = diag(1, n, p), n = dim(QR$qr)[1L], p = QR$rank) 36 | 37 | qr_R2(QR, p = QR$rank) 38 | 39 | symm_mean(x) 40 | 41 | symmetrize(x, ...) 42 | 43 | \method{symmetrize}{matrix}(x, symm.by = c("max", "min", "avg"), ...) 44 | 45 | \method{symmetrize}{array}(x, symm.by = c("max", "min", "avg"), ...) 46 | } 47 | \arguments{ 48 | \item{x}{Numeric matrix or array (the latter, for \code{qr.array} and 49 | \code{symmetrize.array})} 50 | 51 | \item{n, p}{Integer; the number of rows or rank (respectively) of 52 | the input matrix or QR decomposition} 53 | 54 | \item{inds}{Vector-based indices of the diagonal} 55 | 56 | \item{densities}{Numeric vector of densities} 57 | 58 | \item{emax}{Integer; the maximum number of edges} 59 | 60 | \item{...}{Arguments passed to either \code{\link{sort}} (for 61 | \code{get_thresholds}) or \code{\link{qr.default}} (for \code{qr.array}). 62 | For the former, this will typically only be \code{decreasing=TRUE}, if that 63 | is the desired behavior} 64 | 65 | \item{QR}{A \code{qr} object} 66 | 67 | \item{y}{A numeric matrix with \code{1} along the diagonal, of the same size 68 | as the input matrix (i.e., \code{QR$qr})} 69 | 70 | \item{symm.by}{Character string; how to create symmetric off-diagonal 71 | elements. Default: \code{max}} 72 | } 73 | \value{ 74 | \code{diag_sq} returns an unnamed numeric vector with the values 75 | along the diagonal of the input matrix 76 | 77 | \code{get_thresholds} returns a numeric vector of the thresholds 78 | 79 | \code{is_binary} returns a logical of length 1 80 | 81 | \code{qr.array} returns a \emph{list} in which each element is the QR 82 | decomposition of each matrix along \code{x}'s 3rd dimension 83 | } 84 | \description{ 85 | These functions are utility/helper functions when working with matrices or 86 | arrays. 87 | 88 | \code{diag_sq} is a pared-down version of \code{\link{diag}} for square 89 | matrices. It does not return any dimnames, does not check if \code{x} is a 90 | square matrix, and it cannot be used to \emph{create} a matrix with a given 91 | value along the diagonal. Meant to be used in code that is called repeatedly 92 | (thousands of times). 93 | 94 | \code{get_thresholds} calculates the threshold values that would result in a 95 | specific graph density. These depend, necessarily on the values in the matrix 96 | themselves. 97 | 98 | \code{qr.array} will calculate the QR decomposition for each matrix in a 3D 99 | array. 100 | 101 | \code{qr_Q2} and \code{qr_R2} are simplified versions of \code{\link{qr.Q}} 102 | and \code{\link{qr.R}}. 103 | 104 | \code{symm_mean} returns a symmetric matrix in which the off-diagonal 105 | elements \eqn{A[i, j]} and \eqn{A[j, i]} are set to the mean of the values 106 | in the input matrix. 107 | 108 | \code{symmetrize} will symmetrize a numeric matrix (or each matrix in an 109 | array) by assigning to the off-diagonal elements either the \code{max} 110 | (default), \code{min}, or \code{average} of \eqn{\{A(i, j), A(j, i)\}}. 111 | } 112 | \details{ 113 | Given a vector of densities, \code{get_thresholds} returns the numeric values 114 | that will result in graphs of the given densities after thresholding by those 115 | values. In the \emph{Examples} section, the thresholds should result in 116 | graphs with densities of \eqn{5, 15, \dots, 55} percent. 117 | } 118 | \examples{ 119 | x <- matrix(runif(25 * 25), 25, 25) 120 | x <- symmetrize(x) 121 | diag(x) <- 0 122 | densities <- seq(0.05, 0.55, by=0.1) 123 | threshes <- get_thresholds(x, densities) 124 | ## Verify that the densities are correct 125 | graphs <- lapply(threshes, function(th) { 126 | graph_from_adjacency_matrix(x * (x > th), mode='undirected', 127 | diag=FALSE, weighted=TRUE) 128 | }) 129 | sapply(graphs, graph.density) 130 | } 131 | -------------------------------------------------------------------------------- /man/mean_distance_wt.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/distances.R 3 | \name{mean_distance_wt} 4 | \alias{mean_distance_wt} 5 | \title{Calculate weighted shortest path lengths} 6 | \usage{ 7 | mean_distance_wt(g, level = c("graph", "vertex"), weights = NULL, 8 | xfm = FALSE, xfm.type = NULL, D = NULL) 9 | } 10 | \arguments{ 11 | \item{g}{An \code{igraph} graph object} 12 | 13 | \item{level}{Character string indicating whether to calculate vertex- or 14 | graph-level shortest path length. Default: \code{'graph'}} 15 | 16 | \item{weights}{Numeric vector of edge weights; if \code{NULL} (the default), 17 | and if the graph has edge attribute \code{weight}, then that will be used. 18 | To avoid using weights, this should be \code{NA}.} 19 | 20 | \item{xfm}{Logical indicating whether to transform the edge weights. Default: 21 | \code{FALSE}} 22 | 23 | \item{xfm.type}{Character string specifying how to transform the weights. 24 | Default: \code{1/w}} 25 | 26 | \item{D}{Numeric matrix; the graph's \dQuote{distance matrix}} 27 | } 28 | \value{ 29 | Numeric vector (if \code{level='vertex'}) of each vertex's shortest 30 | path length, or a single number for the graph-level average 31 | } 32 | \description{ 33 | Calculate graph or vertex average shortest path lengths. For vertices, this 34 | is just the row means of the distance matrix. For the graph-level, it is the 35 | overall mean of the distance matrix. 36 | } 37 | \details{ 38 | By default, edge weights are not transformed (e.g., inverted). However, if 39 | set to \code{TRUE}, then the input graph must have a graph-level attribute 40 | called \code{'xfm.type'} or you must supply a value in the function call. If 41 | you supply a distance matrix (the \code{D} argument), it is not necessary to 42 | transform edge weights, as it is assumed the the distance matrix was 43 | calculated from a graph with transformed edge weights already. 44 | } 45 | -------------------------------------------------------------------------------- /man/pad_zeros.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils.R 3 | \name{check_sID} 4 | \alias{check_sID} 5 | \alias{pad_zeros} 6 | \title{Test if an object is a character vector of numbers} 7 | \usage{ 8 | check_sID(x) 9 | 10 | pad_zeros(x) 11 | } 12 | \arguments{ 13 | \item{x}{\code{pad_zeros} accepts either a vector (numeric or character) or a 14 | single integer. \code{check_sID} accepts a character, numeric, or factor 15 | vector} 16 | } 17 | \value{ 18 | \code{check_sID} returns either the input vector or a character 19 | vector padded with \code{0} 20 | 21 | A character vector with zero-padded values 22 | } 23 | \description{ 24 | \code{check_sID} is a convenience function to test if a vector (typically the 25 | \emph{subject ID} column in a \code{data.table}) is a character vector of 26 | numbers, a factor vector of numbers, or a numeric vector. If so, it will 27 | zero-pad the variable to have equal width. 28 | 29 | \code{pad_zeros} pads a vector with zeros to avoid issues with ordering a 30 | column of integers or integers converted to \code{character}. 31 | } 32 | \details{ 33 | This function is meant to avoid issues that arise when sorting a vector of 34 | numbers that have been converted to \code{character}. For example, 35 | \code{\link{import_scn}} automatically reads in the first column (with 36 | \emph{FreeSurfer} outputs this is the column of subject IDs) as a 37 | \code{character} variable. If the subject IDs had been all numbers/integers, 38 | then sorting (i.e., setting the \code{key} in a \code{data.table}) would be 39 | incorrect: e.g., it might be \code{'1', '10', '2', ...}. 40 | 41 | If \dQuote{x} is a numeric vector, then the resultant string width will be 42 | determined by \code{max(x)} or \code{x} itself if the input is a single 43 | integer. For example, if \code{x=10}, it will return \code{'01', '02', ..., 44 | '10'}. If \dQuote{x} is a character vector, then the output's string width 45 | will be \code{max(nchar(x))}. For example, if \code{x} includes both 46 | \code{'1'} and \code{'1000'}, it will return \code{'0001'}, etc. 47 | } 48 | \examples{ 49 | pad_zeros(10) # '01' '02' ... '10' 50 | x <- c(1, 10, 100) 51 | pad_zeros(x) # '001' '010' '100' 52 | x <- as.character(x) 53 | pad_zeros(x) # '001' '010' '100' 54 | } 55 | -------------------------------------------------------------------------------- /man/plot.brainGraph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_brainGraph.R 3 | \name{plot.brainGraph} 4 | \alias{plot.brainGraph} 5 | \title{Plot a brain graph with a specific spatial layout} 6 | \usage{ 7 | \method{plot}{brainGraph}(x, plane = c("axial", "sagittal", "circular"), 8 | hemi = c("both", "L", "R"), mni = TRUE, subgraph = NULL, 9 | main = NULL, subtitle = "default", label = NULL, side = 1, 10 | line = -2, adj = 0.025, cex = 2.5, col = "white", font = 2, 11 | show.legend = FALSE, rescale = FALSE, asp = 0, ...) 12 | } 13 | \arguments{ 14 | \item{x}{A \code{brainGraph} graph object} 15 | 16 | \item{plane}{Character string indicating which orientation to plot. 17 | Default: \code{'axial'}} 18 | 19 | \item{hemi}{Character string indicating which hemisphere to plot. Default: 20 | \code{'both'}} 21 | 22 | \item{mni}{Logical indicating whether or not to plot over a slice of the 23 | brain. Default: \code{TRUE}} 24 | 25 | \item{subgraph}{Character string specifying a logical condition for vertices 26 | to plot. Default: \code{NULL}} 27 | 28 | \item{main}{Character string; the main title. Default: \code{NULL}} 29 | 30 | \item{subtitle}{Character string; the subtitle. Default: \code{'default'}} 31 | 32 | \item{label}{Character string specifying text to display in one corner of the 33 | plot (e.g., \code{'A.'}). Default: NULL} 34 | 35 | \item{side}{Label placement. Default: \code{1} (bottom)} 36 | 37 | \item{line}{Which margin line to place the text.} 38 | 39 | \item{adj}{If \code{side=1}, a value closer to 0 places the text closer to 40 | the left margin. Default: \code{0.025}} 41 | 42 | \item{cex}{Amount of character expansion of the label text. Default: 43 | \code{2.5}} 44 | 45 | \item{col}{Label font color. Default: \code{'white'}} 46 | 47 | \item{font}{Integer specifying the font type. Default: \code{2} (bold face)} 48 | 49 | \item{show.legend}{Logical indicating whether or not to show a legend. 50 | Default: \code{FALSE}} 51 | 52 | \item{rescale}{Logical, whether to rescale the coordinates. Default: 53 | \code{FALSE}} 54 | 55 | \item{asp}{Numeric constant; the aspect ratio. Default: 0} 56 | 57 | \item{...}{Other parameters (passed to \code{\link[igraph]{plot.igraph}}). 58 | See \code{\link[igraph]{plot.common}} for details.} 59 | } 60 | \description{ 61 | \code{plot.brainGraph} plots a graph in which the spatial layout of the nodes 62 | is important. The network itself is plotted over a brain MRI slice from the 63 | MNI152 template by default (when \code{mni=TRUE}). 64 | } 65 | \section{Selecting specific vertices to display}{ 66 | 67 | With the argument \code{subgraph}, you can supply a simple logical expression 68 | specifying which vertices to show. For example, \emph{'degree > 10'} will 69 | plot only vertices with a \emph{degree} greater than 10. Combinations of 70 | \emph{AND} (i.e., \code{&}) and \emph{OR} (i.e., \code{|}) are allowed. This 71 | requires that any vertex attribute in the expression must be present in the 72 | graph; e.g., \code{V(g)$degree} must exist. 73 | } 74 | 75 | \section{Title, subtitle, and label}{ 76 | 77 | By default, a \emph{title} (i.e., text displayed at the top of the figure) is 78 | not included. You can include one by passing a character string to 79 | \code{main}, and control the size with \code{cex.main}. A \emph{subtitle} 80 | (i.e., text at the bottom), is included by default and displays the number of 81 | vertices and edges along with the graph density. To exclude this, specify 82 | \code{subtitle=NULL}. A \dQuote{label} can be included in one corner of the 83 | figure (for publications). For example, you can choose \code{label='A.'} or 84 | \code{label='a)'}. Arguments controlling the location and appearance can be 85 | changed, but the default values are optimal for bottom-left placement. See 86 | \code{\link[graphics]{mtext}} for more details. The label-specific arguments 87 | are: 88 | \describe{ 89 | \item{side}{The location. \code{1} is for bottom placement.} 90 | \item{line}{If \code{side=1} (bottom), a negative number places the text 91 | \emph{above} the bottom of the figure; a higher number could result in 92 | the bottom part of the text to be missing. This can differ if 93 | \code{plane='circular'}, in which case you may want to specify a positive 94 | number.} 95 | \item{adj}{Seems to be the percentage away from the margin. So, for 96 | example, \code{adj=0.1} would place the text closer to the center than 97 | the default value, and \code{adj=0.5} places it in the center.} 98 | \item{cex}{The degree of \dQuote{character expansion}. A value of 1 would 99 | not increase the text size.} 100 | \item{col}{The text color.} 101 | \item{font}{The font type. The default \code{font=2} is bold face. See 102 | \code{\link[graphics]{par}} for details.} 103 | } 104 | } 105 | 106 | \examples{ 107 | \dontrun{ 108 | plot(g[[1]], hemi='R') 109 | plot(g[[1]], subgraph='degree > 10 | btwn.cent > 50') 110 | 111 | ## Place label in upper-left 112 | plot(g.ex, label='A)', side=3, line=-2.5) 113 | } 114 | } 115 | \seealso{ 116 | Other Plotting functions: \code{\link{Plotting GLM graphs}}, 117 | \code{\link{plot.brainGraphList}}, 118 | \code{\link{plot_brainGraph_gui}}, 119 | \code{\link{plot_brainGraph_multi}} 120 | } 121 | \author{ 122 | Christopher G. Watson, \email{cgwatson@bu.edu} 123 | } 124 | \concept{Plotting functions} 125 | -------------------------------------------------------------------------------- /man/plot.brainGraphList.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/list.R 3 | \name{plot.brainGraphList} 4 | \alias{plot.brainGraphList} 5 | \title{Plot a brainGraphList and write to PDF} 6 | \usage{ 7 | \method{plot}{brainGraphList}(x, plane, hemi, filename.base, 8 | diffs = FALSE, ...) 9 | } 10 | \arguments{ 11 | \item{x}{A \code{brainGraphList} object} 12 | 13 | \item{plane}{Character string indicating which orientation to plot. 14 | Default: \code{'axial'}} 15 | 16 | \item{hemi}{Character string indicating which hemisphere to plot. Default: 17 | \code{'both'}} 18 | 19 | \item{filename.base}{Character string specifying the base of the filename} 20 | 21 | \item{diffs}{Logical, indicating whether edge differences should be 22 | highlighted. Default: \code{FALSE}} 23 | 24 | \item{...}{Other parameters (passed to \code{\link{plot.brainGraph}})} 25 | } 26 | \description{ 27 | The \code{plot} method will write a PDF file containing plots for all graphs 28 | in the given object. 29 | } 30 | \details{ 31 | You can choose to highlight edge differences between subsequent list 32 | elements; in this case, new/different edges are colored pink. This is useful 33 | mostly for a list of group-level graphs. 34 | } 35 | \seealso{ 36 | Other Plotting functions: \code{\link{Plotting GLM graphs}}, 37 | \code{\link{plot.brainGraph}}, 38 | \code{\link{plot_brainGraph_gui}}, 39 | \code{\link{plot_brainGraph_multi}} 40 | } 41 | \author{ 42 | Christopher G. Watson, \email{cgwatson@bu.edu} 43 | } 44 | \concept{Plotting functions} 45 | -------------------------------------------------------------------------------- /man/plot_brainGraph_gui.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_brainGraph_gui.R 3 | \name{plot_brainGraph_gui} 4 | \alias{plot_brainGraph_gui} 5 | \title{GUI for plotting graphs overlaid on an MNI152 image or in a circle} 6 | \usage{ 7 | plot_brainGraph_gui() 8 | } 9 | \description{ 10 | This function creates a GUI for plotting graphs over an image from the MNI152 11 | template. It gives the user control over several plotting parameters. Also 12 | possible is a circular plot (in addition to the axial and sagittal views). It 13 | is necessary for the graphs to have an \emph{atlas} attribute, and several 14 | vertex- and edge-level attributes (set by 15 | \code{\link{set_brainGraph_attr}}). 16 | } 17 | \seealso{ 18 | Other Plotting functions: \code{\link{Plotting GLM graphs}}, 19 | \code{\link{plot.brainGraphList}}, 20 | \code{\link{plot.brainGraph}}, 21 | \code{\link{plot_brainGraph_multi}} 22 | } 23 | \concept{Plotting functions} 24 | -------------------------------------------------------------------------------- /man/plot_brainGraph_multi.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_brainGraph_multi.R 3 | \name{plot_brainGraph_multi} 4 | \alias{plot_brainGraph_multi} 5 | \alias{slicer} 6 | \title{Save PNG of one or three views for all graphs in a brainGraphList} 7 | \usage{ 8 | plot_brainGraph_multi(g.list, filename = "orthoview.png", 9 | subgraph = NULL, main = NULL, label = NULL, cex.main = 1, ...) 10 | 11 | slicer(g.list, nrows, ncols, plane = "axial", hemi = "both", 12 | filename = "all.png", main = NULL, cex.main = 1, ...) 13 | } 14 | \arguments{ 15 | \item{g.list}{A \code{brainGraphList} or a list of \code{brainGraph} objects} 16 | 17 | \item{filename}{Character string of the filename of the PNG to be written.} 18 | 19 | \item{subgraph}{A vector or list of character strings to (optionally) subset 20 | the graph(s), possibly by multiple conditions} 21 | 22 | \item{main}{A vector or list of character strings to be placed in the main 23 | title of the center (axial) plot for each graph} 24 | 25 | \item{label}{A vector or list of character strings to be placed in one of the 26 | corners of the left plot (sagittal) in each row} 27 | 28 | \item{cex.main}{Numeric specifying the level of character expansion for the 29 | plot titles. Default: \code{1} (no expansion)} 30 | 31 | \item{...}{Other arguments passed to \code{\link{plot.brainGraph}}} 32 | 33 | \item{nrows}{Integer; the number of rows in the figure} 34 | 35 | \item{ncols}{Integer; the number of columns in the figure} 36 | 37 | \item{plane}{Character string indicating which orientation to plot. 38 | Default: \code{'axial'}} 39 | 40 | \item{hemi}{Character string indicating which hemisphere to plot. Default: 41 | \code{'both'}} 42 | } 43 | \description{ 44 | \code{plot_brainGraph_multi} writes a PNG file to disk containing three views 45 | (columns) of 1 or more \code{brainGraph} objects (from left-to-right): left 46 | sagittal, axial, and right sagittal. The number of rows in the figure will 47 | equal the number of graphs to plot. 48 | 49 | \code{slicer} writes a PNG file to disk containing a single view (i.e., 50 | either sagittal, axial, or circular) of all \code{brainGraph} objects in the 51 | input list/\code{brainGraphList}. 52 | } 53 | \details{ 54 | Whether the first input is a \code{brainGraphList} object or a \code{list} of 55 | \code{brainGraph} objects, \emph{all} graphs in the object will be displayed 56 | in the figure. For \code{plot_brainGraph_multi}, this may be undesirable if 57 | you have more than 4 or 5 graphs in one object. You can choose fewer by using 58 | simple subsetting operations (see Examples below). 59 | } 60 | \note{ 61 | All other arguments (passed to \code{\link{plot.brainGraph}}) will be 62 | applied to \emph{all} graphs. For example, if you include 63 | \code{vertex.label=NA} in the function call, vertex labels will be omitted 64 | for all graphs. 65 | } 66 | \section{Using subgraphs, titles, and labels}{ 67 | 68 | There are three arguments that can differ for each graph to be displayed. 69 | Each follows the same \dQuote{rules}. If you would like the same value 70 | applied to all graphs, you can specify a \code{character} string. If you 71 | would like a different value for each group, you must supply a \code{vector} 72 | or \code{list} with length equal to the number of graphs. If its length is 73 | less than the number of graphs, values will be recycled. To \dQuote{skip} 74 | applying a value to one (or more) graph(s), you can use the \code{NULL} value 75 | only within a list (see the Examples below). 76 | \describe{ 77 | \item{subgraph}{Can be used to apply one or more conditions for subsetting 78 | the graph(s).} 79 | \item{main}{Controls the main plot title, which appears in the \emph{axial} 80 | view along with each graph's \code{name} attribute. Depending on the 81 | \code{level} of the \code{brainGraphList}, this will either be a Study 82 | ID, Group name, or contrast name.} 83 | \item{label}{Can be used to print a text label in a corner for each 84 | group/graph. For example, you can print a letter if you will refer to, 85 | e.g., \dQuote{Figure 1A}, \dQuote{Figure 1B}, etc.} 86 | } 87 | } 88 | 89 | \examples{ 90 | \dontrun{ 91 | ## "g.hubs" contains 2 groups; apply same subset to both 92 | plot_brainGraph_multi(g.hubs, filename='Figure01_hubs.png', 93 | subgraph='N > 0', vertex.color='color.lobe', vertex.size=15, 94 | show.legend=TRUE, vertex.label.cex=1.5) 95 | 96 | ## Single group, different subgraphs for both plots 97 | ## "g" is a "brainGraphList" object 98 | gg <- g[rep(1, 3), drop=FALSE] 99 | plot_brainGraph_multi(gg, filename='group1_5-6-7core.png', 100 | vertex.color='color.lobe', edge.color='color.lobe', vertex.label=NA, 101 | subgraph=as.list(paste('coreness >', 5:7)), 102 | main=as.list(paste('k-core', 5:7))) 103 | 104 | ## Apply different subset for groups 1 & 3; no subset for group 2 105 | plot_brainGraph_multi(g, groups=1:3, vertex.label=NA, 106 | subgraph=list('degree > 5', NULL, 'degree > 4')) 107 | } 108 | } 109 | \seealso{ 110 | Other Plotting functions: \code{\link{Plotting GLM graphs}}, 111 | \code{\link{plot.brainGraphList}}, 112 | \code{\link{plot.brainGraph}}, 113 | \code{\link{plot_brainGraph_gui}} 114 | } 115 | \author{ 116 | Christopher G. Watson, \email{cgwatson@bu.edu} 117 | } 118 | \concept{Plotting functions} 119 | -------------------------------------------------------------------------------- /man/plot_global.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_global.R 3 | \name{plot_global} 4 | \alias{plot_global} 5 | \title{Plot global graph measures across densities} 6 | \usage{ 7 | plot_global(g.list, xvar = c("density", "threshold"), vline = NULL, 8 | level.names = "default", exclude = NULL, perms = NULL, 9 | alt = "two.sided") 10 | } 11 | \arguments{ 12 | \item{g.list}{List of \code{brainGraphList} objects; the length of this list 13 | should equal the number of thresholds/densities in the study} 14 | 15 | \item{xvar}{A character string indicating whether the variable of 16 | interest is \dQuote{density} or \dQuote{threshold} (e.g. with DTI data)} 17 | 18 | \item{vline}{Numeric of length 1 specifying the x-intercept if you would like 19 | to plot a vertical dashed line (e.g., if there is a particular density of 20 | interest). Default: \code{NULL}} 21 | 22 | \item{level.names}{Character vector of variable names, which are displayed as 23 | facet labels. If you do not want to change them, specify \code{NULL}. By 24 | default, they are changed to pre-set values.} 25 | 26 | \item{exclude}{Character vector of variables to exclude. Default: \code{NULL}} 27 | 28 | \item{perms}{A \code{\link{data.table}} of permutation group differences} 29 | 30 | \item{alt}{Character vector of alternative hypotheses; required if 31 | \emph{perms} is provided, but defaults to \dQuote{two.sided} for all 32 | variables} 33 | } 34 | \value{ 35 | Either a \code{trellis} or \code{ggplot} object 36 | } 37 | \description{ 38 | Create a faceted line plot of global graph measures across a range of graph 39 | densities, calculated from a list of \code{brainGraphList} objects. This 40 | requires that the variables of interest are graph-level attributes of the 41 | input graphs. 42 | } 43 | \details{ 44 | You can choose to insert a dashed vertical line at a specific 45 | density/threshold of interest, rename the variable levels (which become the 46 | facet titles), exclude variables, and include a \code{brainGraph_permute} 47 | object of permutation data to add asterisks indicating significant group 48 | differences. 49 | } 50 | \author{ 51 | Christopher G. Watson, \email{cgwatson@bu.edu} 52 | } 53 | -------------------------------------------------------------------------------- /man/plot_rich_norm.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_rich_norm.R 3 | \name{plot_rich_norm} 4 | \alias{plot_rich_norm} 5 | \title{Plot normalized rich club coefficients against degree threshold} 6 | \usage{ 7 | plot_rich_norm(rich.dt, facet.by = c("density", "threshold"), densities, 8 | alpha = 0.05, fdr = TRUE, g.list = NULL, smooth = TRUE) 9 | } 10 | \arguments{ 11 | \item{rich.dt}{A \code{data.table} with rich-club coefficients} 12 | 13 | \item{facet.by}{A character string indicating whether the variable of 14 | interest is \dQuote{density} or \dQuote{threshold} (e.g. with DTI data)} 15 | 16 | \item{densities}{A numeric vector of the densities to plot} 17 | 18 | \item{alpha}{The significance level. Default: \code{0.05}} 19 | 20 | \item{fdr}{A logical, indicating whether or not to use the FDR-adjusted 21 | p-value for determining significance. Default: \code{TRUE}} 22 | 23 | \item{g.list}{A list \code{brainGraphList} objects; required if you want to 24 | plot a shaded region demarcating the \code{\link{rich_core}}} 25 | 26 | \item{smooth}{Logical indicating whether or not to plot a smooth curve when 27 | data from multiple subjects (per group) are present. Default: \code{TRUE}. 28 | Ignored for group-level data.} 29 | } 30 | \value{ 31 | A \code{trellis} or \code{ggplot} object 32 | } 33 | \description{ 34 | Returns a line plot of the normalized rich club coefficient. Optionally, can 35 | include a shaded region demarcating the \code{\link{rich_core}} cutoff (if 36 | you supply a list of graph objects to the \code{g} argument). 37 | } 38 | \examples{ 39 | \dontrun{ 40 | plot_rich_norm(rich.dt, facet.by='density', densities[N:(N+1)], g=g) 41 | } 42 | } 43 | \seealso{ 44 | Other Rich-club functions: \code{\link{Rich Club}}, 45 | \code{\link{rich_club_attrs}} 46 | } 47 | \author{ 48 | Christopher G. Watson, \email{cgwatson@bu.edu} 49 | } 50 | \concept{Rich-club functions} 51 | -------------------------------------------------------------------------------- /man/plot_vertex_measures.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_vertex_measures.R 3 | \name{plot_vertex_measures} 4 | \alias{plot_vertex_measures} 5 | \title{Plot vertex-level graph measures at a single density or threshold} 6 | \usage{ 7 | plot_vertex_measures(g.list, measure, facet.by = NULL, 8 | group.by = getOption("bg.group"), type = c("violin", "boxplot"), 9 | show.points = FALSE, ylabel = measure, ...) 10 | } 11 | \arguments{ 12 | \item{g.list}{A \code{brainGraphList} or a list of \code{brainGraph} objects} 13 | 14 | \item{measure}{A character string of the graph measure to plot} 15 | 16 | \item{facet.by}{Character string indicating the variable to facet by (if 17 | any). Default: \code{NULL}} 18 | 19 | \item{group.by}{Character string indicating which variable to group the data 20 | by. Default: \code{getOption('bg.group')}} 21 | 22 | \item{type}{Character string indicating the plot type. Default: 23 | \code{'violin'}} 24 | 25 | \item{show.points}{Logical indicating whether or not to show individual data 26 | points (default: FALSE)} 27 | 28 | \item{ylabel}{A character string for the y-axis label} 29 | 30 | \item{...}{Arguments passed to \code{geom_boxplot} or \code{geom_violin}} 31 | } 32 | \value{ 33 | A \code{trellis} or \code{ggplot} object 34 | } 35 | \description{ 36 | Creates boxplots of a single vertex-level graph measure at a single density 37 | or threshold, grouped by the variable specified by \code{group.by} and 38 | optionally faceted by another variable (e.g., \emph{lobe} or \emph{network}). 39 | } 40 | \examples{ 41 | \dontrun{ 42 | p.deg <- plot_vertex_measures(g[[1]], facet.by='network', measure='degree') 43 | } 44 | } 45 | \author{ 46 | Christopher G. Watson, \email{cgwatson@bu.edu} 47 | } 48 | -------------------------------------------------------------------------------- /man/plot_volumetric.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_group_means.R 3 | \name{plot_volumetric} 4 | \alias{plot_volumetric} 5 | \title{Plot group distributions of volumetric measures for a given brain region} 6 | \usage{ 7 | plot_volumetric(dat, regions, type = c("violin", "histogram"), 8 | all.vals = TRUE, modality = c("thickness", "volume", "lgi", "area")) 9 | } 10 | \arguments{ 11 | \item{dat}{A data table of volumetric data; needs columns for 'Group', 12 | 'region', and 'value'} 13 | 14 | \item{regions}{A vector of character strings or integers of the brain 15 | region(s) to plot; if integer, the region(s) is/are chosen from the input 16 | data table based on the index} 17 | 18 | \item{type}{A character string indicating the plot type; either 'histogram' 19 | or 'violin'} 20 | 21 | \item{all.vals}{A logical indicating whether or not to plot horizontal lines 22 | for all observations (only valid for 'violin' plots) (default: TRUE)} 23 | 24 | \item{modality}{A character string indicating the type of volumetric measure 25 | ('thickness', 'volume', 'lgi', or 'area')} 26 | } 27 | \value{ 28 | A \code{trellis} or \code{ggplot} object 29 | } 30 | \description{ 31 | This function takes a \dQuote{tidied} dataset of cortical volumetric measures 32 | (thickness, volume, LGI, etc.) and plots a histogram or violin plot for 1 or 33 | more groups, and of 1 or more brain regions. 34 | } 35 | \seealso{ 36 | Other Structural covariance network functions: \code{\link{Bootstrapping}}, 37 | \code{\link{IndividualContributions}}, 38 | \code{\link{Residuals}}, 39 | \code{\link{brainGraph_permute}}, 40 | \code{\link{corr.matrix}}, \code{\link{import_scn}} 41 | } 42 | \author{ 43 | Christopher G. Watson, \email{cgwatson@bu.edu} 44 | } 45 | \concept{Structural covariance network functions} 46 | -------------------------------------------------------------------------------- /man/rename_levels.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot_global.R 3 | \name{rename_levels} 4 | \alias{rename_levels} 5 | \title{Rename the levels of global metrics in a data.table} 6 | \usage{ 7 | rename_levels(DT) 8 | } 9 | \arguments{ 10 | \item{DT}{A \code{data.table}} 11 | } 12 | \value{ 13 | The levels of the \code{variable} column after being changed 14 | } 15 | \description{ 16 | Rename the levels of global metrics in a data.table 17 | } 18 | \keyword{internal} 19 | -------------------------------------------------------------------------------- /man/rich_club.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rich_club.R 3 | \name{Rich Club} 4 | \alias{Rich Club} 5 | \alias{rich_club_coeff} 6 | \alias{rich_club_all} 7 | \alias{rich_club_norm} 8 | \alias{rich_core} 9 | \title{Rich club calculations} 10 | \usage{ 11 | rich_club_coeff(g, k = 1, weighted = FALSE, A = NULL) 12 | 13 | rich_club_all(g, weighted = FALSE, A = NULL) 14 | 15 | rich_club_norm(g, N = 100, rand = NULL, ...) 16 | 17 | rich_core(g, weighted = FALSE, A = NULL) 18 | } 19 | \arguments{ 20 | \item{g}{An \code{igraph} graph object} 21 | 22 | \item{k}{Integer; the minimum degree for including a vertex. Default: 1} 23 | 24 | \item{weighted}{Logical indicating whether or not edge weights should be 25 | used. Default: \code{FALSE}} 26 | 27 | \item{A}{Numeric matrix; the adjacency matrix of the input graph. Default: 28 | \code{NULL}} 29 | 30 | \item{N}{Integer; the number of random graphs to generate. Default: 100} 31 | 32 | \item{rand}{A list of \code{igraph} graph objects, if random graphs have 33 | already been generated. Default: \code{NULL}} 34 | 35 | \item{...}{Other parameters (passed to \code{\link{sim.rand.graph.par}})} 36 | } 37 | \value{ 38 | \code{\link{rich_club_coeff}} - a list with components: 39 | \item{phi}{The rich club coefficient, \eqn{\phi}.} 40 | \item{graph}{A subgraph containing only the rich club vertices.} 41 | \item{Nk,Ek}{The number of vertices/edges in the rich club graph.} 42 | 43 | \code{\link{rich_club_all}} - a \code{data.table} with components: 44 | \item{k}{A vector of all vertex degrees present in the original graph} 45 | \item{phi}{The rich-club coefficient} 46 | \item{Nk,Ek}{The number of vertices/edges in the rich club for each 47 | successive \emph{k}} 48 | 49 | \code{\link{rich_club_norm}} - a data table with columns: 50 | \item{k}{Sequence of degrees} 51 | \item{rand}{Rich-club coefficients for the random graphs} 52 | \item{orig}{Rich-club coefficients for the original graph.} 53 | \item{norm}{Normalized rich-club coefficients.} 54 | \item{p}{P-values based on the distribution of \code{rand}} 55 | \item{p.fdr}{The FDR-adjusted P-values} 56 | \item{density}{The observed graph's density} 57 | \item{threshold,Group,name}{} 58 | 59 | \code{\link{rich_core}} - a data table with columns: 60 | \item{density}{The density of the graph.} 61 | \item{rank}{The rank of the boundary for the rich core.} 62 | \item{k.r}{The degree/strength of the vertex at the boundary.} 63 | \item{core.size}{The size of the core relative to the graph size.} 64 | \item{weighted}{Whether or not weights were used} 65 | } 66 | \description{ 67 | \code{rich_club_coeff} calculates the \emph{rich club} of a graph, returning 68 | the rich-club coefficient, \eqn{\phi}, and the subgraph of rich club 69 | vertices. 70 | 71 | \code{rich_club_all} is a wrapper for \code{\link{rich_club_coeff}} that 72 | calculates the rich-club coefficient for all degrees present in the graph. It 73 | returns a \code{data.table} with the coefficients and vertex and edge counts 74 | for each successive rich club. 75 | 76 | \code{rich_club_norm} will (optionally) generate a number of random graphs, 77 | calculate their rich club coefficients (\eqn{\phi}), and return 78 | \eqn{\phi_{norm}} of the graph of interest, which is the observed rich-club 79 | coefficient divided by the mean across the random graphs. 80 | 81 | \code{rich_core} finds the boundary of the rich core of a graph, based on the 82 | decreasing order of vertex degree. It also calculates the degree that 83 | corresponds to that rank, and the core size relative to the total number of 84 | vertices in the graph. 85 | } 86 | \details{ 87 | If random graphs have already been generated, you can supply a list as an 88 | argument. 89 | 90 | For weighted graphs, the degree is substituted by a normalized weight: 91 | \deqn{ceiling(A / w_{min})} 92 | where \eqn{w_{min}} is the minimum weight (that is greater than 0), and 93 | \eqn{ceiling()} is the \emph{ceiling} function that rounds up to the nearest 94 | integer. 95 | } 96 | \references{ 97 | Zhou, S. and Mondragon, R.J. (2004) The rich-club phenomenon 98 | in the internet topology. \emph{IEEE Comm Lett}, \bold{8}, 180--182. 99 | \doi{10.4018/978-1-59140-993-9.ch066} 100 | 101 | Opsahl, T. and Colizza, V. and Panzarasa, P. and Ramasco, J.J. 102 | (2008) Prominence and control: the weighted rich-club effect. \emph{Physical 103 | Review Letters}, \bold{101.16}, 168702. 104 | \doi{10.1103/PhysRevLett.101.168702} 105 | 106 | Colizza, V. and Flammini, A. and Serrano, M.A. and Vespignani, A. 107 | (2006) Detecting rich-club ordering in complex networks. \emph{Nature 108 | Physics}, \bold{2}, 110--115. \doi{10.1038/nphys209} 109 | 110 | Ma, A and Mondragon, R.J. (2015) Rich-cores in networks. 111 | \emph{PLoS One}, \bold{10(3)}, e0119678. 112 | \doi{10.1371/journal.pone.0119678} 113 | } 114 | \seealso{ 115 | Other Rich-club functions: \code{\link{plot_rich_norm}}, 116 | \code{\link{rich_club_attrs}} 117 | 118 | Other Random graph functions: \code{\link{Random Graphs}} 119 | } 120 | \author{ 121 | Christopher G. Watson, \email{cgwatson@bu.edu} 122 | } 123 | \concept{Random graph functions} 124 | \concept{Rich-club functions} 125 | -------------------------------------------------------------------------------- /man/rich_club_attrs.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/rich_club.R 3 | \name{rich_club_attrs} 4 | \alias{rich_club_attrs} 5 | \title{Assign graph attributes based on rich-club analysis} 6 | \usage{ 7 | rich_club_attrs(g, deg.range = NULL, adj.vsize = FALSE) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{deg.range}{Numeric vector of the range of degrees indicating 13 | inclusion in the rich-club; if the default \emph{NULL}, it will be from 1 14 | to the maximum degree in the graph} 15 | 16 | \item{adj.vsize}{Logical indicating whether to adjust vertex size 17 | proportional to degree. Default: \code{FALSE}} 18 | } 19 | \value{ 20 | An \code{igraph} graph object with additional attributes: 21 | \item{rich}{Binary indicating membership in the rich-club} 22 | \item{type.rich}{Edge attribute indicating the type of connection} 23 | \item{color.rich}{Edge and vertex attributes} 24 | \item{size.rich}{Edge and vertex attributes} 25 | } 26 | \description{ 27 | Assigns vertex- and edge-level attributes based on the results of a 28 | \emph{rich-club} analysis, based on a range of vertex degrees in which the 29 | rich-club coefficient was determined to be significantly greater than that of 30 | a set of random graphs (see \code{\link{rich_club_norm}}). 31 | } 32 | \details{ 33 | Vertices which are in the rich club will be assigned an attribute 34 | \code{rich}, taking on a binary value. Their colors (attribute 35 | \code{color.rich}) will be either \emph{red} or \emph{gray}. Their sizes 36 | (attribute \code{size.rich}) will either be 10 or will be proportional to 37 | their degree. 38 | 39 | Edge attribute \code{type.rich} takes on three values: \emph{rich-club} (if 40 | it connects two rich-club vertices), \emph{feeder} (if it connects a rich- to 41 | a non-rich-club vertex), and \emph{local} (if it connects two non-rich-club 42 | vertices). The \code{color.rich} attribute is \emph{red}, \emph{orange}, or 43 | \emph{green}. Edge sizes (\code{size.rich}) will be largest for 44 | \emph{rich-club} connections, then smaller for \emph{feeder}, and smallest 45 | for \emph{local}. 46 | } 47 | \examples{ 48 | \dontrun{ 49 | g <- rich_club_attrs(g, rich.dt[density == densities[N] & p.fdr < .01, 50 | range(k)]) 51 | } 52 | } 53 | \seealso{ 54 | Other Rich-club functions: \code{\link{Rich Club}}, 55 | \code{\link{plot_rich_norm}} 56 | } 57 | \author{ 58 | Christopher G. Watson, \email{cgwatson@bu.edu} 59 | } 60 | \concept{Rich-club functions} 61 | -------------------------------------------------------------------------------- /man/robustness.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/robustness.R 3 | \name{robustness} 4 | \alias{robustness} 5 | \title{Analysis of network robustness} 6 | \usage{ 7 | robustness(g, type = c("vertex", "edge"), measure = c("btwn.cent", 8 | "degree", "random"), N = 1000) 9 | } 10 | \arguments{ 11 | \item{g}{An \code{igraph} graph object} 12 | 13 | \item{type}{Character string; either \code{'vertex'} or \code{'edge'} 14 | removals. Default: \code{vertex}} 15 | 16 | \item{measure}{Character string; sort by either \code{'btwn.cent'} or 17 | \code{'degree'}, or choose \code{'random'}. Default: \code{'btwn.cent'}} 18 | 19 | \item{N}{Integer; the number of iterations if \code{'random'} is chosen. 20 | Default: \code{1e3}} 21 | } 22 | \value{ 23 | Data table with elements: 24 | \item{type}{Character string describing the type of analysis performed} 25 | \item{measure}{The input argument \code{measure}} 26 | \item{comp.size}{The size of the largest component after edge/vertex 27 | removal} 28 | \item{comp.pct}{Numeric vector of the ratio of maximal component size after 29 | each removal to the observed graph's maximal component size} 30 | \item{removed.pct}{Numeric vector of the ratio of vertices/edges removed} 31 | \item{Group}{Character string indicating the subject group, if applicable} 32 | } 33 | \description{ 34 | This function performs a \dQuote{targeted attack} of a graph or a 35 | \dQuote{random failure} analysis, calculating the size of the largest 36 | component after edge or vertex removal. 37 | } 38 | \details{ 39 | In a targeted attack, it will sort the vertices by either degree or 40 | betweenness centrality (or sort edges by betweenness), and successively 41 | remove the top vertices/edges. Then it calculates the size of the largest 42 | component. 43 | 44 | In a random failure analysis, vertices/edges are removed in a random order. 45 | } 46 | \references{ 47 | Albert, R. and Jeong, H. and Barabasi, A. (2000) Error and attack 48 | tolerance of complex networks. \emph{Nature}, \bold{406}, 378--381. 49 | \doi{10.1038/35019019} 50 | } 51 | \author{ 52 | Christopher G. Watson, \email{cgwatson@bu.edu} 53 | } 54 | -------------------------------------------------------------------------------- /man/s_core.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/s_core.R 3 | \name{s_core} 4 | \alias{s_core} 5 | \title{Calculate the s-core of a network} 6 | \usage{ 7 | s_core(g, W = NULL) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{W}{Numeric matrix of edge weights (default: \code{NULL})} 13 | } 14 | \value{ 15 | Integer vector of the vertices' \emph{s-core} membership 16 | } 17 | \description{ 18 | Calculates the \emph{s-core} decomposition of a network. This is analogous to 19 | the \emph{k-core} decomposition, but takes into account the \emph{strength} 20 | of vertices (i.e., in weighted networks). If an unweighted network is 21 | supplied, then the output of the function \code{\link[igraph]{coreness}} is 22 | returned. 23 | } 24 | \details{ 25 | The \emph{s-core} consists of all vertices \eqn{i} with \eqn{s_i > s}, where 26 | \eqn{s} is some threshold value. The \eqn{s_0} core is the entire network, 27 | and the threshold value of the \eqn{s_{n}} core is 28 | \deqn{s_{n-1} = min_i s_i} 29 | for all vertices \eqn{i} in the \eqn{s_{n-1}} core. 30 | 31 | Note that in networks with a wide distribution of vertex strengths, in which 32 | there are almost as many unique values as there are vertices, then several 33 | separate cores will have a single vertex. See the reference provided below. 34 | } 35 | \references{ 36 | Eidsaa, M and Almaas, E. (2013) s-core network decomposition: a 37 | generalization of k-core analysis to weighted networks. \emph{Physical 38 | Review E}, \bold{88}, 062819. 39 | \doi{10.1103/PhysRevE.88.062819} 40 | } 41 | \seealso{ 42 | \code{\link[igraph]{coreness}} 43 | } 44 | \author{ 45 | Christopher G. Watson, \email{cgwatson@bu.edu} 46 | } 47 | -------------------------------------------------------------------------------- /man/set_graph_colors.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/set_brainGraph_attributes.R 3 | \name{set_graph_colors} 4 | \alias{set_graph_colors} 5 | \title{Color graph vertices and edges} 6 | \usage{ 7 | set_graph_colors(g, name, memb) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{name}{Character string of the name of the attribute to add} 13 | 14 | \item{memb}{An integer vector representing membership of e.g. a community} 15 | } 16 | \value{ 17 | The same graph with additional vertex and edge attributes 18 | } 19 | \description{ 20 | \code{set_graph_colors} takes an integer vector representing membership of 21 | some grouping (e.g., a community or connected component) and creates a 22 | character vector of colors for each grouping. Isolated vertices will be 23 | colored \emph{gray}. Edges are assigned the same color if connected to 24 | vertices in the same group, and assigned \emph{gray} otherwise. 25 | } 26 | \keyword{internal} 27 | -------------------------------------------------------------------------------- /man/small.world.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/small_world.R 3 | \name{small.world} 4 | \alias{small.world} 5 | \title{Calculate graph small-worldness} 6 | \usage{ 7 | small.world(g.list, rand) 8 | } 9 | \arguments{ 10 | \item{g.list}{A \code{brainGraphList} object or list of graphs} 11 | 12 | \item{rand}{List of (lists of) equivalent random graphs (output from 13 | \code{\link{sim.rand.graph.par}})} 14 | } 15 | \value{ 16 | A \code{data.table} with the following components: 17 | \item{density}{The range of density thresholds used.} 18 | \item{N}{The number of random graphs that were generated.} 19 | \item{Lp,Lp.rand,Lp.norm}{The observed, average random, and normalized 20 | characteristic path length.} 21 | \item{Cp,Cp.rand,Cp.norm}{The observed, average random, and normalized 22 | clustering coefficient.} 23 | \item{sigma}{The small-world measure of the graph.} 24 | } 25 | \description{ 26 | \code{small.world} calculates the normalized characteristic path length and 27 | clustering coefficient based on observed and random graphs, used to calculate 28 | the small-world coefficient \eqn{\sigma}. 29 | } 30 | \references{ 31 | Watts, D.J. and Strogatz S.H. (1998) Collective dynamics of 32 | "small-world" networks. \emph{Nature}, \bold{393}, 440--442. 33 | \doi{10.1038/30918} 34 | } 35 | \author{ 36 | Christopher G. Watson, \email{cgwatson@bu.edu} 37 | } 38 | -------------------------------------------------------------------------------- /man/spatial_dist.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/spatial_dist.R 3 | \name{Graph Distances} 4 | \alias{Graph Distances} 5 | \alias{edge_spatial_dist} 6 | \alias{vertex_spatial_dist} 7 | \title{Calculate Euclidean distance of edges and vertices} 8 | \usage{ 9 | edge_spatial_dist(g) 10 | 11 | vertex_spatial_dist(g) 12 | } 13 | \arguments{ 14 | \item{g}{An \code{igraph} graph object} 15 | } 16 | \value{ 17 | \code{edge_spatial_dist} - a numeric vector with length equal to the 18 | edge count of the input graph, consisting of the Euclidean distance (in 19 | \emph{mm}) of each edge 20 | 21 | \code{vertex_spatial_dist} - a named numeric vector with length equal 22 | to the number of vertices, consisting of the average distance (in 23 | \emph{mm}) for each vertex 24 | } 25 | \description{ 26 | \code{edge_spatial_dist} calculates the Euclidean distance of an 27 | \code{igraph} graph object's edges. The distances are in \emph{mm} and based 28 | on MNI space. These distances are \emph{NOT} along the cortical surface, so 29 | can only be considered approximations, particularly concerning 30 | inter-hemispheric connections. The input graph must have \emph{atlas} as a 31 | graph-level attribute. 32 | 33 | \code{vertex_spatial_dist} calculates, for each vertex of a graph, the 34 | average Euclidean distance across all of that vertex's connections. 35 | } 36 | \references{ 37 | Alexander-Bloch, A.F. and Vertes, P.E. and Stidd, R. et al. 38 | (2013) The anatomical distance of functional connections predicts brain 39 | network topology in health and schizophrenia. \emph{Cerebral Cortex}, 40 | \bold{23}, 127--138. \doi{10.1093/cercor/bhr388} 41 | } 42 | \author{ 43 | Christopher G. Watson, \email{cgwatson@bu.edu} 44 | } 45 | -------------------------------------------------------------------------------- /man/subset_graph.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils.R 3 | \name{subset_graph} 4 | \alias{subset_graph} 5 | \title{Subset graphs based on a given logical condition} 6 | \usage{ 7 | subset_graph(g, condition) 8 | } 9 | \arguments{ 10 | \item{g}{A graph object} 11 | 12 | \item{condition}{Character string specifying an equation for which vertices to 13 | keep} 14 | } 15 | \value{ 16 | A graph object 17 | } 18 | \description{ 19 | \code{subset_graph} will subset a given graph based on the given logical 20 | condition(s). This can be a \dQuote{simple} logical equation, or can include 21 | combinations of \emph{AND} and \emph{OR} (i.e., \code{&} and \code{|}). 22 | } 23 | \keyword{internal} 24 | -------------------------------------------------------------------------------- /man/update_fs_names.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/import.R 3 | \name{update_fs_names} 4 | \alias{update_fs_names} 5 | \title{Update column names in a Freesurfer table} 6 | \usage{ 7 | update_fs_names(filename, modality, parcellation, hemi, exclude.subs) 8 | } 9 | \description{ 10 | Updates column names by abbreviating to match with the names in the 11 | \code{brainGraph} atlases. 12 | } 13 | \keyword{internal} 14 | -------------------------------------------------------------------------------- /man/utils.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/utils.R 3 | \name{Utility functions} 4 | \alias{Utility functions} 5 | \alias{get_metadata} 6 | \alias{outer_vec} 7 | \alias{split_string} 8 | \alias{vec.transform} 9 | \title{Utility functions} 10 | \usage{ 11 | get_metadata(object) 12 | 13 | outer_vec(x, y) 14 | 15 | split_string(x, max_len = 80L, delim = "\\\\+", sep = "\\n") 16 | 17 | vec.transform(x, min.val = 0, max.val = 1) 18 | } 19 | \arguments{ 20 | \item{object}{A list-like object} 21 | 22 | \item{x}{A character string} 23 | 24 | \item{max_len}{Integer; the max length of one line. Default: 80} 25 | 26 | \item{delim}{Character specifying where to end a line if it is longer than 27 | \code{max_len}. Default: \code{'+'}} 28 | 29 | \item{sep}{Character specifying what to split by. Default: \code{'\n'} (a 30 | newline character)} 31 | 32 | \item{min.val}{the minimum value of the new range} 33 | 34 | \item{max.val}{the maximum value of the new range} 35 | } 36 | \value{ 37 | \code{get_metadata} - the same object with version, system, and date 38 | information added 39 | 40 | A vector of the transformed input. 41 | } 42 | \description{ 43 | \code{get_metadata} adds metadata to a list-like object. 44 | 45 | \code{outer_vec} simply performs the cross-product, specifically \code{x %*% 46 | t(y)}, and assigns dimnames to the resulting matrix. 47 | 48 | \code{split_string} inserts separator characters in a character string to 49 | truncate strings for printing. 50 | 51 | \code{vec.transform} takes a vector and transforms it to have a new range, 52 | given the input, or the default values of [0, 1]. 53 | } 54 | \details{ 55 | If the object is a graph, graph-level attributes will be added. The 56 | elements added are: 57 | \describe{ 58 | \item{version}{A list with R, brainGraph, and igraph versions} 59 | \item{sys}{Character vector of system information} 60 | \item{date}{The date and time of creation} 61 | } 62 | 63 | The \code{delim} argument determines \emph{where} to insert the separator. 64 | For example, given the default, it will attempt to insert newline characters 65 | only following a plus sign. 66 | } 67 | \keyword{internal} 68 | -------------------------------------------------------------------------------- /man/vertex_roles.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/vertex_roles.R 3 | \name{Vertex Roles} 4 | \alias{Vertex Roles} 5 | \alias{gateway_coeff} 6 | \alias{part_coeff} 7 | \alias{within_module_deg_z_score} 8 | \title{Gateway coefficient, participation coefficient, and within-mod degree z-score} 9 | \usage{ 10 | gateway_coeff(g, memb, centr = c("btwn.cent", "degree", "strength"), 11 | A = NULL, weighted = FALSE) 12 | 13 | part_coeff(g, memb, A = NULL, weighted = FALSE) 14 | 15 | within_module_deg_z_score(g, memb, A = NULL, weighted = FALSE) 16 | } 17 | \arguments{ 18 | \item{g}{An \code{igraph} graph object} 19 | 20 | \item{memb}{A numeric vector of membership indices of each vertex} 21 | 22 | \item{centr}{Character string; the type of centrality to use in calculating 23 | GC. Default: \code{btwn.cent}} 24 | 25 | \item{A}{Numeric matrix; the adjacency matrix of the input graph. Default: 26 | \code{NULL}} 27 | 28 | \item{weighted}{Logical indicating whether to calculate metrics using edge 29 | weights. Default: \code{FALSE}} 30 | } 31 | \value{ 32 | A vector of the participation coefficients, within-module degree 33 | z-scores, or gateway coefficients for each vertex of the graph. 34 | } 35 | \description{ 36 | \code{gateway_coeff} calculates the gateway coefficient of each vertex, 37 | based on community membership. 38 | 39 | \code{part_coeff} calculates the participation coefficient of each vertex, 40 | based on community membership. 41 | 42 | \code{within_module_deg_z_score} is a measure of the connectivity from a 43 | given vertex to other vertices in its module/community. 44 | } 45 | \details{ 46 | The gateway coefficient \eqn{G_i} of vertex \emph{i} is: 47 | \deqn{G_i = 1 - \sum_{S=1}^{N_M} \left ( \frac{\kappa_{iS}}{\kappa_i} \right 48 | )^2 (g_{iS})^2} 49 | where \eqn{\kappa_{iS}} is the number of edges from vertex \emph{i} to 50 | vertices in module \emph{S}, and \eqn{\kappa_i} is the degree of vertex 51 | \emph{i}. \eqn{N_M} equals the number of modules. \eqn{g_{ii}} is a weight, 52 | defined as: 53 | \deqn{g_{iS} = 1 - \bar{\kappa_{iS}} \bar{c_{iS}}} 54 | where 55 | \deqn{\bar{\kappa_{iS}} = \frac{\kappa_{iS}}{\sum_j \kappa_{jS}}} 56 | for all nodes \eqn{j} in node \eqn{i}'s module, and 57 | \deqn{\bar{c_{iS}} = c_{iS} / max(c_n)} 58 | 59 | The participation coefficient \eqn{P_i} of vertex \emph{i} is: 60 | \deqn{P_i = 1 - \sum_{s=1}^{N_M} \left ( \frac{\kappa_{is}}{\kappa_i} \right )^2} 61 | where \eqn{\kappa_{is}} is the number of edges from vertex \emph{i} to 62 | vertices in module \emph{s}, and \eqn{\kappa_s} is the degree of vertex 63 | \emph{i}. \eqn{N_M} equals the number of modules. 64 | 65 | As discussed in Guimera et al., \eqn{P_i = 0} if vertex \emph{i} is connected 66 | only to vertices in the same module, and \eqn{P_i = 1} if vertex \emph{i} is 67 | equally connected to all other modules. 68 | 69 | The within-module degree z-score is: 70 | \deqn{z_i = \frac{\kappa_i - \bar{\kappa}_{s_i}}{\sigma_{\kappa_{s_i}}}} 71 | where \eqn{\kappa_i} is the number of edges from vertex \emph{i} to vertices 72 | in the same module \eqn{s_i}, \eqn{\bar{\kappa}_{s_i}} is the average of 73 | \eqn{\kappa} over all vertices in \eqn{s_i}, and \eqn{\sigma_{\kappa_{s_i}}} 74 | is the standard deviation. 75 | } 76 | \references{ 77 | Vargas, E.R. and Wahl, L.M. (2014) The gateway coefficient: a 78 | novel metric for identifying critical connections in modular networks. 79 | \emph{Eur Phys J B}, \bold{87}, 161--170. 80 | \doi{10.1140/epjb/e2014-40800-7} 81 | 82 | Guimera, R. and Amaral, L.A.N. (2005) Cartography of complex 83 | networks: modules and universal roles. \emph{Journal of Statistical 84 | Mechanics: Theory and Experiment}, \bold{02}, P02001. 85 | \doi{10.1088/1742-5468/2005/02/P02001} 86 | } 87 | \author{ 88 | Christopher G. Watson, \email{cgwatson@bu.edu} 89 | } 90 | -------------------------------------------------------------------------------- /man/vif.bg_GLM.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/glm_stats.R 3 | \name{vif.bg_GLM} 4 | \alias{vif.bg_GLM} 5 | \title{Variance inflation factors for \code{bg_GLM} objects} 6 | \usage{ 7 | vif.bg_GLM(mod, ...) 8 | } 9 | \arguments{ 10 | \item{mod}{A \code{bg_GLM} object} 11 | 12 | \item{...}{Unused} 13 | } 14 | \value{ 15 | A named array of VIFs; names of the 3rd dimension are regions 16 | } 17 | \description{ 18 | Variance inflation factors for \code{bg_GLM} objects 19 | } 20 | -------------------------------------------------------------------------------- /man/vulnerability.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/vulnerability.R 3 | \name{vulnerability} 4 | \alias{vulnerability} 5 | \title{Calculate graph vulnerability} 6 | \usage{ 7 | vulnerability(g, use.parallel = TRUE, weighted = FALSE) 8 | } 9 | \arguments{ 10 | \item{g}{An \code{igraph} graph object} 11 | 12 | \item{use.parallel}{Logical indicating whether or not to use \emph{foreach} 13 | (default: \code{TRUE})} 14 | 15 | \item{weighted}{Logical indicating whether weighted efficiency should be 16 | calculated (default: \code{FALSE})} 17 | } 18 | \value{ 19 | A numeric vector of length equal to the vertex count of \emph{g} 20 | } 21 | \description{ 22 | This function calculates the \emph{vulnerability} of the vertices of a graph. 23 | Here, vulnerability is considered to be the proportional drop in global 24 | efficiency when a given vertex is removed from the graph. The vulnerability 25 | of the graph is considered the maximum across all vertices. 26 | } 27 | \references{ 28 | Latora, V. and Marchiori, M. (2005) Variability and protection of 29 | infrastructure networks. \emph{Physical Review E}, \bold{71}, 015103. 30 | \doi{10.1103/physreve.71.015103} 31 | } 32 | \seealso{ 33 | \code{\link{efficiency}} 34 | } 35 | \author{ 36 | Christopher G. Watson, \email{cgwatson@bu.edu} 37 | } 38 | -------------------------------------------------------------------------------- /man/write_brainnet.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/write_brainnet.R 3 | \name{write_brainnet} 4 | \alias{write_brainnet} 5 | \title{Write files to be used for visualization with BrainNet Viewer} 6 | \usage{ 7 | write_brainnet(g, vcolor = "none", vsize = "constant", 8 | edge.wt = NULL, file.prefix = "") 9 | } 10 | \arguments{ 11 | \item{g}{The \code{igraph} graph object of interest} 12 | 13 | \item{vcolor}{Character string indicating how to color the vertices (default: 14 | \code{'none'})} 15 | 16 | \item{vsize}{Character string indicating what size the vertices should be; 17 | can be any vertex-level attribute (default: \code{'constant'})} 18 | 19 | \item{edge.wt}{Character string indicating the edge attribute to use to 20 | return a weighted adjacency matrix (default: \code{NULL})} 21 | 22 | \item{file.prefix}{Character string for the basename of the \code{.node} and 23 | \code{.edge} files that are written} 24 | } 25 | \description{ 26 | Write the \code{.node} and \code{.edge} files necessary for visualization 27 | with the BrainNet Viewer software. 28 | } 29 | \details{ 30 | For the \code{.node} file, there are 6 columns: 31 | \itemize{ 32 | \item \emph{Columns 1-3}: Vertex x-, y-, and z-coordinates 33 | \item \emph{Column 4}: Vertex color 34 | \item \emph{Column 5}: Vertex size 35 | \item \emph{Column 6}: Vertex label 36 | } 37 | The \code{.edge} file is the graph's associated adjacency matrix; a weighted 38 | adjacency matrix can be returned by using the \code{edge.wt} argument. 39 | } 40 | \examples{ 41 | \dontrun{ 42 | write_brainnet(g, vcolor='community', vsize='degree', edge.wt='t.stat') 43 | } 44 | } 45 | \references{ 46 | Xia, M. and Wang, J. and He, Y. (2013). BrainNet Viewer: a 47 | network visualization tool for human brain connectomics. \emph{PLoS One}, 48 | \bold{8(7)}, e68910. \doi{10.1371/journal.pone.0068910} 49 | } 50 | \author{ 51 | Christopher G. Watson, \email{cgwatson@bu.edu} 52 | } 53 | --------------------------------------------------------------------------------