Make a group brain

Demo: Make Group-Level Visualization on a Template Brain

Here is an interactive demo showing two subjects mapped to a template MNI152 brain.

1. Create template brain

Function threeBrain::merge_brain provides high-level function to load individual subjects’ brain on a given template. See the following example:

b1 <- raveio::rave_brain("YAEL/PAV037")
b2 <- raveio::rave_brain("YAEL/PAV038")

template <- threeBrain::merge_brain(b1, b2)

Just like individual RAVE brain object, template also has method template$set_electrode_values to set electrode values and template$plot to visualize the group brain

csv_path <- "path/to/your/electrode_value.csv"
template$set_electrode_values(csv_path)

template$plot()

Alternatively, users can set electrode values for each individual subject

b1$set_electrode_values(table1)
b2$set_electrode_values(table2)
...

2. Choose a proper template

The default template is N27 Collin’s brain. RAVE offers other built-in templates that can be queried via function threeBrain::available_templates(). The following code downloads a MNI152 brain:

template_subject <- "cvs_avg35_inMNI152"
template_root <- threeBrain::default_template_directory()
if(!dir.exists(file.path(template_root, template_subject))) {
  threeBrain::download_template_subject(template_subject)
}

Now you can use this template

template <- threeBrain::merge_brain(
  b1, b2, 
  template_subject = template_subject
)
template$plot()

3. A full example with customized render options

# Using MNI152 template
template_subject <- "cvs_avg35_inMNI152"
template_root <- threeBrain::default_template_directory()
if(!dir.exists(file.path(template_root, template_subject))) {
  threeBrain::download_template_subject(template_subject)
}

# Load subject brain
b1 <- raveio::rave_brain("YAEL/PAV037")
b2 <- raveio::rave_brain("YAEL/PAV038")

# create template brain
template <- threeBrain::merge_brain(
  b1, b2, 
  template_subject = template_subject
)

# set electrode values
b1$set_electrode_values()
b2$set_electrode_values()

# plot with options
template$plot()

This is a screenshot of the output. Please scroll to the top to play with the 3D viewer demo

Key Documentations

Function merge_brain

Create Multi-subject Template

merge_brain

Description

Create Multi-subject Template

Usage

merge_brain(
  ...,
  .list = NULL,
  template_surface_types = NULL,
  template_subject = unname(getOption("threeBrain.template_subject", "N27")),
  template_dir = default_template_directory()
)

Arguments

…, .list	Brain2 objects
template_surface_types	which template surface types to load, default is auto-guess
template_subject	character, subject code to be treated as template, default is ‘N27’
template_dir	the parent directory where template subject is stored in

Author(s)

Zhengjia Wang

Function download_template_subject

Download and Manage Template Subjects

template_subject

Description

Download and Manage Template Subjects

Usage

download_template_subject(
  subject_code = "N27",
  url,
  template_dir = default_template_directory()
)

download_N27(make_default = FALSE, ...)

set_default_template(
  subject_code,
  view = TRUE,
  template_dir = default_template_directory()
)

threebrain_finalize_installation(
  upgrade = c("ask", "always", "never", "data-only", "config-only"),
  async = TRUE
)

available_templates()

Arguments

subject_code	character with only letters and numbers (Important); default is ‘N27’
url	zip file address; must be specified if subject_code is not from the followings: ‘bert’, ‘cvs_avg35’, ‘cvs_avg35_inMNI152’, ‘fsaverage’, ‘fsaverage_sym’, or ‘N27’
template_dir	parent directory where subject’s ‘FreeSurfer’ folder should be stored
make_default	logical, whether to make ‘N27’ default subject
…	more to pass to download_template_subject
view	whether to view the subject
upgrade	whether to check and download ‘N27’ brain interactively. Choices are ‘ask’, ‘always’, and ‘never’
async	whether to run the job in parallel to others; default is true

Details

To view electrodes implanted in multiple subjects, it’s highly recommended to view them in a template space The detail mapping method is discussed in function freesurfer_brain.

To map to a template space, one idea is to find someone whose brain is normal. In our case, the choice is subject ‘N27’, also known as ‘Colin 27’. function download_N27 provides a simple and easy way to download a partial version from the Internet.

If you have any other ideas about template brain, you can use function set_default_template(subject_code, template_dir) to redirect to your choice. If your template brain is a ‘Zip’ file on the Internet, we provide function download_template_subject to automatically install it.

Author(s)

Zhengjia Wang