atlas_helpers: Atlas helper functions

In brainGraph: Graph Theory Analysis of Brain MRI Data

Description

guess_atlas tries to determine which atlas is being used based on the data; i.e., the number of vertices/regions.

as_atlas and create_atlas converts/coerces an object to a a data.table, or creates one, that is compatible with brainGraph.

Usage

guess_atlas(x)

as_atlas(object)

create_atlas(regions, coords, lobes, hemis, other = NULL)

Arguments

x, object	An object to test or convert to an atlas data.table
regions	Character vector of region names
coords	Numeric matrix of spatial coordinates; must have 3 columns
lobes	Character or factor vector of lobe membership
hemis	Character or factor vector of hemisphere membership. There should probably not be more than 3 unique elements (for left, right, and bi-hemispheric regions)
other	A named list of vectors with other data. The names of the list will become column names in the return object.

Value

guess_atlas - Character string; either the matched atlas or NA

as_atlas and create_atlas return a data.table that conforms to other atlases in the package, or exits with an error.

Guessing the atlas from an object

There are several valid inputs to guess_atlas:

data.table

The atlas will be guessed based on the number of columns (subtracting by 1 if a “Study ID” column is present). This is the same behavior as for data.frame objects, as well.

igraph

The vertex count

brainGraph

If there is a atlas graph-level attribute, it will return that. Otherwise, the vertex count.

matrix,array

The number of rows, which should equal the number of columns if the input is a connectivity matrix.

Note that this will only work properly for atlases that are currently in the package. If you are using a custom atlas and you receive errors, please open an issue on GitHub.

Coercing to an atlas

There are several things as_atlas tries to do to make it work without error:

• Coerce the object to data.table

• Add a column of integers named index

• Change columns named 'x', 'y', or 'z' to have .mni at the end

• Convert the lobe and hemi columns to be factors

Examples

my_atlas <- data.frame(name=paste('Region', 1:10), x.mni=rnorm(10),
  y.mni=rnorm(10), z.mni=rnorm(10),
  lobe=rep(c('Frontal', 'Parietal', 'Temporal', 'Occipital', 'Limbic'), 2),
  hemi=c(rep('L', 5), rep('R', 5)))
my_atlas2 <- as_atlas(my_atlas)
str(my_atlas)
str(my_atlas2)
regions <- paste('Region', 1:10)
xyz <- matrix(rnorm(30), nrow=10, ncol=3)
lobe <- rep(c('Frontal', 'Parietal', 'Temporal', 'Occipital', 'Limbic'), 2)
hemi <- c(rep('L', 5), rep('R', 5))
other <- list(network=rep(c('Default mode', 'Task positive'), 5))
my_atlas <- create_atlas(regions, xyz, lobe, hemi, other)
str(my_atlas)

Example output

sh: 1: cannot create /dev/null: Permission denied
Loading required package: igraph

Attaching package: ‘igraph’

The following objects are masked from ‘package:stats’:

    decompose, spectrum

The following object is masked from ‘package:base’:

    union

Warning messages:
1: In as_atlas(my_atlas) : Atlas is being coerced to "data.table"
2: In as_atlas(my_atlas) : Coercing "lobe" column to factor
3: In as_atlas(my_atlas) : Coercing "hemi" column to factor
'data.frame':	10 obs. of  6 variables:
 $ name : chr  "Region 1" "Region 2" "Region 3" "Region 4" ...
 $ x.mni: num  -1.633 0.708 -0.22 0.301 -0.346 ...
 $ y.mni: num  -0.937 -0.196 0.82 -1.192 -1.208 ...
 $ z.mni: num  1.033 -0.727 -0.48 -0.323 -2.056 ...
 $ lobe : chr  "Frontal" "Parietal" "Temporal" "Occipital" ...
 $ hemi : chr  "L" "L" "L" "L" ...
Classes ‘data.table’ and 'data.frame':	10 obs. of  7 variables:
 $ name : chr  "Region 1" "Region 2" "Region 3" "Region 4" ...
 $ x.mni: num  -1.633 0.708 -0.22 0.301 -0.346 ...
 $ y.mni: num  -0.937 -0.196 0.82 -1.192 -1.208 ...
 $ z.mni: num  1.033 -0.727 -0.48 -0.323 -2.056 ...
 $ lobe : Factor w/ 5 levels "Frontal","Limbic",..: 1 4 5 3 2 1 4 5 3 2
 $ hemi : Factor w/ 2 levels "L","R": 1 1 1 1 1 2 2 2 2 2
 $ index: int  1 2 3 4 5 6 7 8 9 10
 - attr(*, ".internal.selfref")=<externalptr> 
Classes ‘data.table’ and 'data.frame':	10 obs. of  8 variables:
 $ name   : chr  "Region 1" "Region 2" "Region 3" "Region 4" ...
 $ x.mni  : num  0.12 -1.319 -0.648 -0.6 -0.356 ...
 $ y.mni  : num  0.666 1.335 0.242 -1.853 0.275 ...
 $ z.mni  : num  -1.26 -0.659 -0.438 1.47 -1.33 ...
 $ lobe   : Factor w/ 5 levels "Frontal","Limbic",..: 1 4 5 3 2 1 4 5 3 2
 $ hemi   : Factor w/ 2 levels "L","R": 1 1 1 1 1 2 2 2 2 2
 $ index  : int  1 2 3 4 5 6 7 8 9 10
 $ network: chr  "Default mode" "Task positive" "Default mode" "Task positive" ...
 - attr(*, ".internal.selfref")=<externalptr> 

brainGraph documentation built on Oct. 23, 2020, 6:37 p.m.