brainGraph (version 2.7.3)

create_mats: Create connection matrices for tractography or fMRI data

Description

create_mats will take a vector of filenames which contain connection matrices (e.g. the fdt_network_matrix files from FSL or the ROICorrelation.txt files from DPABI) and create arrays of this data. 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"),
  mat.thresh = 0, sub.thresh = 0.5, inds = list(1:length(A.files)),
  algo = c("probabilistic", "deterministic"), P = 5000, ...)

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_mats

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 3-d array of binarized connection matrices

A.bin.sums

A list of 2-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

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 lists of numeric matrices averaged for each group

Details

The argument threshold.by has 4 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.

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%).

References

Roberts JA, Perry A, Roberts G, Mitchell PB, Breakspear M (2017). Consistency-based thresholding of the human connectome. NeuroImage, 145:118-129.

See Also

Other Matrix functions: apply_thresholds, cor.diff.test, symmetrize_mats

Examples

# NOT RUN {
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)
# }