Key Features:
- Uses modern browsers, easy to embed and share
- Displays MRI, surfaces, and electrodes in the same canvas
- Maps multiple subjects on template brains using
AFNI/SUMA
(standard 141) orMNI-305
locations - Electrode localization
- Volume rendering and surface/electrode animation
- Integration with interactive
R-shiny
framework
News | reference page | keyboard shortcuts
- Web Browsers: the viewer uses
WegGL2
to render in browsers. Please check this list to see compatible browsers. As of 2023, Chrome, Firefox, Safari, and Edge (not IE) have full supports.
R
andRStudio Desktop (Free Version)
- Open
RStudio
, enter from its console:
install.packages("threeBrain", repos = "https://rave-ieeg.r-universe.dev")
If you want to install dev
version from Github, then use:
install.packages("remotes")
remotes::install_github("dipterix/threeBrain")
- (Optional) Setups: after installation, in
RStudio
console, type the following command
threeBrain::brain_setup()
and follow the instructions.
Once finishing setting up of threeBrain
, there will be a template subject N27
(Collin's 27) created locally. The location is platform-related. You can find it by running the following command:
library(threeBrain)
default_template_directory()
#> [1] "/Users/dipterix/Library/Application Support/
#> org.R-project.R/R/threeBrain/templates"
N27 template folder resides inside of this directory.
Let's view this subject using the threeBrain
function.
- Import subject
library(threeBrain)
n27_path <- file.path(default_template_directory(), "N27")
x <- threeBrain( path = n27_path,
subject_code = 'N27', surface_types = 'pial')
- Visualize
plot(x) # alternatively, you can use x$plot()`
The sample subject (N27
) is a sample generated by FreeSurfer
(download). If you have any subjects processed by FreeSurfer
, use function threeBrain
to visualize.
If you have electrode file, you can import it before calling plot
function. Please make sure it's in csv
format.
x$set_electrodes(electrodes = "[PATH to ELECTRODE FILE]")
Here is an example of electrode csv file. Only the first five columns (case-sensitive) are mandatory: Electrode (integer)
, Coord_x
, Coord_y
, Coord_z
, and Label (character)
. Coord_*
is tkRAS
location from FreeSurfer
coordinates.
| Electrode| Coord_x| Coord_y| Coord_z|Label | MNI305_x| MNI305_y| MNI305_z|SurfaceElectrode |SurfaceType | Radius| VertexNumber|Hemisphere |
|---------:|-------:|-------:|-------:|:------|--------:|---------:|---------:|:----------------|:-----------|------:|------------:|:----------|
| 1| 29.0| -7.8| -34.6|RMHCH1 | 30.46817| -17.98119| -23.40022|FALSE |pial | 2| -1|left |
| 2| 33.8| -8.0| -34.2|RMHCH2 | 35.57109| -17.76624| -22.80131|FALSE |pial | 2| -1|left |
| 3| 38.0| -7.5| -33.5|RMHCH3 | 39.97102| -16.81249| -22.17986|FALSE |white | 2| -1|right |
| 4| 42.6| -6.8| -33.0|RMHCH4 | 44.79092| -15.73442| -21.82591|FALSE |smoothwm | 2| -1|right |
| 5| 47.0| -6.8| -32.6|RMHCH5 | 49.45370| -15.35431| -21.31272|FALSE |pial | 2| -1|right |
| ...
To assign values to electrodes, run
x$set_electrode_values(electrodes = "[PATH to ELECTRODE VALUE FILE]")
The electrode value file is also a csv like:
| Electrode| Subject| Project| Time| ValueName| ValueName2| ...|
|---------:|-------:|-------:|-------:|:---------|----------:|-----|
| 1| N27| Demo| 0|A | 30.46817| ...|
| 2| N27| Demo| 0|B | 35.57109| ...|
| 3| N27| Demo| 0|C | 39.97102| ...|
| 4| N27| Demo| 0|D | 44.79092| ...|
| 5| N27| Demo| 0|A | 49.45370| ...|
| ...
Project
and Time
are optional. However, if you are also using rave
, please make sure Project
exists. If you want to show animation, Time
is necessary and must be numeric. ValueName?
can be any characters containing letters (A-Z
, a-z
), letters (0-9
) and underscore (_
).
If you have your own subjects with FreeSurfer
output, for example, I have two subjects YAB
and YCQ
. To merge these two subjects and show them on N27
template,
library(threeBrain)
# yab = ... (see section B for import a single subject)
# ycq = ...
template_n27 = merge_brain(yab, ycq, template_subject = 'N27')
plot( template_n27 )
The viewer will be in N27
template, and electrodes of these two subjects can be mapped via MNI305
(for surface and stereo EEG) or std.141
(for surface-only).
YAEL ("Your Advanced Electrode Localizer) has been integrated into RAVE (R Analysis and Visualization of iEEG). Please check our website https://yael.wiki
To cite threeBrain
in publications use:
- Wang, Z., Magnotti, J. F., Zhang, X., & Beauchamp, M. S. (2023). YAEL: Your Advanced Electrode Localizer. Eneuro, 10(10).
- Magnotti, J. F., Wang, Z., & Beauchamp, M. S. (2020). RAVE: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data. NeuroImage, 223, 117341.
A BibTeX entry for LaTeX users:
@Article{,
title = {{YAEL}: Your Advanced Electrode Localizer},
author = {Zhengjia Wang and John F. Magnotti and Xiang Zhang and Michael S. Beauchamp},
journal = {Eneuro},
year = {2023},
volume = {10},
number = {10},
publisher = {Society for Neuroscience},
doi = {10.1523/ENEURO.0328-23.2023},
}
@Article{,
title = {{RAVE}: Comprehensive open-source software for reproducible analysis and visualization of intracranial EEG data},
author = {John F. Magnotti and Zhengjia Wang and Michael S. Beauchamp},
journal = {NeuroImage},
year = {2020},
volume = {223},
doi = {10.1016/j.neuroimage.2020.117341},
pages = {117341},
}
The front-end viewer (JavaScript) is licensed under MPL-2.0 free open-source license. Using the generated viewers or incorporating the existing viewers as a whole into your own work "as-is" is permissive.