brainGraph (version 3.1.0)

create_mats: Create connection matrices for tractography or fMRI data

Description

create_mats creates arrays from connection matrices (e.g., fdt_network_matrix from FSL or ROICorrelation.txt from DPABI). You may choose to normalize these matrices by the waytotal or region size (tractography), or not at all.

Usage

create_mats(A.files, modality = c("dti", "fmri"), divisor = c("none",
  "waytotal", "size", "rowSums"), div.files = NULL,
  threshold.by = c("consensus", "density", "mean", "consistency", "raw"),
  mat.thresh = 0, sub.thresh = 0.5, inds = list(seq_along(A.files)),
  algo = c("probabilistic", "deterministic"), P = 5000, ...)

Value

A list containing:

A

A 3-d array of the raw connection matrices

A.norm

A 3-d array of the normalized connection matrices

A.bin

A list of 3-d arrays of binarized connection matrices, one array for each threshold

A.bin.sums

A list of 3-d arrays of connection matrices, with each entry signifying the number of subjects with a connection present; the number of list elements equals the length of mat.thresh, and the extent of the arrays equals the number of groups

A.inds

A list of arrays of binarized connection matrices, containing 1 if that entry is to be included

A.norm.sub

List of 3-d arrays of the normalized connection matrices for all given thresholds

A.norm.mean

List of 3-d arrays of connection matrices averaged for each group

Arguments

A.files

Character vector of the filenames with connection matrices

modality

Character string indicating data modality (default: dti)

divisor

Character string indicating how to normalize the connection matrices; either 'none' (default), 'waytotal', 'size', or 'rowSums' (ignored if modality equals fmri)

div.files

Character vector of the filenames with the data to normalize by (e.g. a list of waytotal files) (default: NULL)

threshold.by

Character string indicating how to threshold the data; choose density, mean, or consistency if you want all resulting matrices to have the same densities (default: consensus)

mat.thresh

Numeric (vector) for thresholding connection matrices (default: 0)

sub.thresh

Numeric (between 0 and 1) for thresholding by subject numbers (default: 0.5)

inds

List (length equal to number of groups) of integers; each list element should be a vector of length equal to the group sizes

algo

Character string of the tractography algorithm used (default: 'probabilistic'). Ignored if modality is fmri.

P

Integer; number of samples per seed voxel (default: 5000)

...

Arguments passed to symmetrize

Connection matrix files

The A.files argument is mandatory and may be specified in a few ways:

1. A character vector of the filenames (preferably with full path).

2. A single character string specifying the directory in which all connectivity matrices are located. This will load all files in the directory.

3. A named list in which the names match the arguments to list.files. This will load all files in path that match the pattern argument, if present, and will load all files in child directories if recursive=TRUE. See examples below.

The same options apply to div.files as well.

Thresholding methods

The argument threshold.by has 5 options:

1. consensus Threshold based on the raw (normalized, if selected) values in the matrices. If this is selected, it uses the sub.thresh value to perform “consensus” thresholding.

2. density Threshold the matrices to yield a specific graph density (given by the mat.thresh argument).

3. mean Keep only connections for which the cross-subject mean is at least 2 standard deviations higher than the threshold (specified by mat.thresh)

4. consistency Threshold based on the coefficient of variation to yield a graph with a specific density (given by mat.thresh). The edge weights will still represent those of the input matrices. See Roberts et al. (2017) for more on “consistency-based” thresholding.

5. raw Threshold each subject's matrix individually, irrespective of group membership. Ignores sub.thresh.

The argument mat.thresh allows you to choose a numeric threshold, below which the connections will be replaced with 0; this argument will also accept a numeric vector. The argument sub.thresh will keep only those connections for which at least X% of subjects have a positive entry (the default is 0.5, or 50%).

Author

Christopher G. Watson,

References

Roberts, JA and Perry, A and Roberts, G and Mitchell, PB and Breakspear, M (2017) Consistency-based thresholding of the human connectome. NeuroImage. 145, 118--129. tools:::Rd_expr_doi("10.1016/j.neuroimage.2016.09.053")

Examples

if (FALSE) {
thresholds <- seq(from=0.001, to=0.01, by=0.001)
fmri.mats <- create_mats(f.A, modality='fmri', threshold.by='consensus',
  mat.thresh=thresholds, sub.thresh=0.5, inds=inds)
dti.mats <- create_mats(f.A, divisor='waytotal', div.files=f.way,
  mat.thresh=thresholds, sub.thresh=0.5, inds=inds)

# Specify a directory and filename pattern
conn_files <- list(path='~/data', pattern='.*fdt_network_matrix')
dti.mats <- create_mats(conn_files, ...)
}