Atlas Helpers {brainGraph}

Atlas helper functions

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)