brainGraphList {brainGraph}

Create a list of brainGraph graphs

Description

make_brainGraphList creates a brainGraphList object, a list containing a set of graphs for all subjects (or group-average graphs) in a study at a specific threshold (or density), in addition to some graph-level attributes common to those graphs.

The [ method will let you subset/slice the graphs for individual subjects and/or groups.

as_brainGraphList coerces a list of graphs to a brainGraphList object. It is assumed that certain metadata attributes – threshold, package version, atlas, imaging modality, edge weighting, and whether they are random graphs – are identical for all graphs in the list.

Usage

make_brainGraphList(x, atlas, type = c("observed", "random"),
  level = c("subject", "group", "contrast"), set.attrs = TRUE,
  modality = NULL, weighting = NULL, threshold = NULL,
  gnames = NULL, ...)

## S3 method for class 'array'
make_brainGraphList(x, atlas, type = c("observed",
  "random"), level = c("subject", "group", "contrast"),
  set.attrs = TRUE, modality = NULL, weighting = NULL,
  threshold = NULL, gnames = NULL, grpNames = NULL, subnet = NULL,
  mode = "undirected", weighted = NULL, diag = FALSE,
  .progress = getOption("bg.progress"), ...)

## S3 method for class 'corr_mats'
make_brainGraphList(x, atlas = x$atlas,
  type = "observed", level = "group", set.attrs = TRUE,
  modality = NULL, weighting = NULL, threshold = x$densities,
  gnames = names(x$r.thresh), grpNames = gnames, mode = "undirected",
  weighted = NULL, diag = FALSE,
  .progress = getOption("bg.progress"), ...)

## S3 method for class 'brainGraphList'
x[i, g = NULL, drop = TRUE]

## S3 method for class 'brainGraphList'
print(x, ...)

is.brainGraphList(x)

## S3 method for class 'brainGraphList'
nobs(object, ...)

as_brainGraphList(g.list, type = c("observed", "random"),
  level = c("subject", "group", "contrast"))

Arguments

x

3-D numeric array of all subjects' connectivity matrices (for a single threshold) or a corr_mats object

atlas

Character string specifying the brain atlas

type

Character string indicating the type of graphs. Default: observed

level

Character string indicating whether the graphs are subject-, group-, or contrast-specific. Default: 'subject'

set.attrs

Logical indicating whether to assign all graph-, vertex-, and edge-level attributes (via set_brainGraph_attr). Default: TRUE

modality

Character string indicating imaging modality (e.g. 'dti'). Default: NULL

weighting

Character string indicating how the edges are weighted (e.g., 'fa', 'pearson', etc.). Default: NULL

threshold

Integer or number indicating the threshold used when “sparsifying” the connectivity matrix (if any). Default: NULL

gnames

Character vector of graph names (e.g., study IDs if level='subject'). Default: NULL

...

Other arguments passed to set_brainGraph_attr

grpNames

Character (or factor) vector of group names. If level == 'group', then you do not need to include this argument (the group names will be the same as gnames). Default: NULL)

subnet

Integer or character vector indicating the vertices to keep, if you are interested in working with a subset of an atlas. By default, all vertices are used.

mode

Character string defining how the matrix should be interpreted. Default: 'undirected'

weighted

Logical specifying whether to create a weighted network

diag

Logical indicating whether to include the diagonal of the connectivity matrix. Default: FALSE

.progress

Logical indicating whether to print a progress bar. Default: getOption('bg.progress')

i

Integer, character, or logical vector for subsetting by subject, or by group (if x$level='group')

g

Integer, character, or logical vector for subsetting by group (if x$level='subject')

drop

If TRUE (the default), then return only the list of graphs; otherwise, subset the graphs and return the entire object

object

A brainGraphList object

g.list

List of graph objects

Details

In addition to creating the initial igraph graphs from the connectivity matrices, then attributes will be calculated and assigned for each graph via set_brainGraph_attr if set.attrs=TRUE. Other arguments can be passed to that function. You may display a progress bar by setting .progress=TRUE.

This object can be considered comparable to a 4-D NIfTI file, particularly that returned by FSL's TBSS “prestats” step since that file contains the FA volumes for all study subjects.

To convert an object with 3 “levels” (i.e., subject-level lists from an older brainGraph version), see the code in the Examples below.

Value

make_brainGraphList returns an object of class brainGraphList with elements:

threshold

The specified threshold/density

version

The versions of R, igraph, and brainGraph used when creating the graphs

atlas

The atlas common to all the graphs

modality

The imaging modality (if supplied)

weighting

A string indicating what edge weights represent (if applicable)

graphs

A named list of brainGraph graphs; the names correspond to the individual graphs' Study IDs

[ – A brainGraphList object (if drop=FALSE) or a list of graphs

Subsetting/extracting

The first index is for subsetting the individual graphs. The second index is for subsetting by group membership and requires that the graphs have a Group graph attribute. When both are included, the first index cannot have length or numeric value greater than the number of remaining subjects after subsetting by group.

If the indexing vector(s) is (are) character, the vector(s) must contain one (or more) of the subject or group names. If logical, its length must equal the number of subjects or groups.

Note

If the input is a corr_mats object, and the extent of the 3-D array is greater than 1, then only the first will be converted to a graph.

Author(s)

Christopher G. Watson, [e-mail]

See Also

Other Graph creation functions: Creating_Graphs_GLM, Creating_Graphs, make_ego_brainGraph

Examples

## Not run: 
# Create a list, one for each threshold
g <- vector('list', length(thresholds))
for (i in seq_along(thresholds)) {
  g[[i]] <- make_brainGraphList(A.norm.sub[[i]], thresholds[i], atlas,
      covars.dti$Study.ID, covars.dti$Group, modality='dti', weighting='fa')
}

## End(Not run)
## Not run: 
# Subset the first 10 subjects, irrespective of group
my.bgl[1:10]

# Return object for only 'Control' subjects
my.bgl[, 'Control']

# Return object with graphs from groups 1 and 3
my.bgl[g=c(1, 3), drop=FALSE]

# Subset the first 10 subjects of group 2
my.bgl[1:10, 2]

## End(Not run)
## Not run: 
## Convert old version single-subject graph lists
## g[[1]] is group 1, g[[1]][[1]] is threshold 1, g[[1]][[1]][[1]] is subj. 1
kNumThresholds <- length(g[[1]])
g.l <- vector('list', kNumThresholds)
for (i in seq_len(kNumThresholds)) {
  g.l[[i]] <- as_brainGraphList(do.call(Map, c(c, g))[[i]])
}

## End(Not run)