Functions for the Allen Institute’s Mouse Common Coordinate Framework (CCF) in R.
cocoframer provides some limited funcitonality for using data from the Allen Brain Atlas that is registered to the Mouse Common Coordinate Framework.
It currently assists:
For additional data retrieval functionality beyond cocoframer, see the full Allen Brain Atlas API docs:
http://help.brain-map.org/display/mousebrain/API
For more information about the Allen Brain Atlas and the Common Coordinate Framework, see the Allen Brain Atlas website:
http://atlas.brain-map.org/
and the CCF documentation:
http://help.brain-map.org/download/attachments/2818171/Mouse_Common_Coordinate_Framework.pdf
An interactive, in-browser 3D structure viewer, the Allen Brain Explorer, is available here:
http://connectivity.brain-map.org/3d-viewer?v=1
cocoframer can be installed with:
devtools::install_github("AllenInstitute/cocoframer")If you use cocoframer to access Allen Brain Atlas ISH Data, please cite:
Lein, E.S. et al. (2007) Genome-wide atlas of gene expression in the adult mouse brain, Nature 445: 168-176. doi:10.1038/nature05453
If you use cocoframer to make your own 3D brain structure images and animations, please cite:
© 2018 Allen Institute for Brain Science. Allen Brain Explorer. Available from: connectivity.brain-map.org/3d-viewer/
For other general citation issues, please refer to the Allen Institute Citation Policy: https://alleninstitute.org/legal/citation-policy/
Some functions in cocoframer retrieve data from the Allen Brain Atlas API, and so require an internet connection.
These functions are prefixed with get_.
Plotting a 3D brain structure
cocoframer includes 3D mesh objects from version 3 of the CCF (2017). These can be retrieved with cocoframer and plotted using the rgl package.
In this example, we’ll retrieve and plot the Hippocampal Amon’s Horn (CA in the ABA structural ontology).
library(cocoframer)
library(rgl)
CA_mesh <- ccf_2017_mesh(acronym = "CA")
shapelist3d(CA_mesh)Plotting multiple 3D brain structures
To get some context, it’s sometimes helpful to plot multiple structures.
Here, we’ll use a helper function included in cocoframer to plot the shell of the CCF (called root in the ABA structural ontology) with the CA:
library(cocoframer)
library(purrr)
library(rgl)
structures <- c("root","CA")
mesh_list <- map(structures, ccf_2017_mesh)
names(mesh_list) <- structures
plot_ccf_meshes(mesh_list,
fg_structure = "CA",
bg_structure = "root")You can change the color and opacity of structures with additional parameters:
plot_ccf_meshes(mesh_list,
fg_structure = "CA",
fg_color = "orangered",
fg_alpha = 0.4,
bg_structure = "root",
bg_color = "yellow",
bg_alpha = 0.4)It’s straightforward to plot multiple structures, each with their own color:
library(cocoframer)
library(purrr)
structures <- c("root","TH","MOs","P")
mesh_list <- map(structures, ccf_2017_mesh)
names(mesh_list) <- structures
plot_ccf_meshes(mesh_list,
fg_structure = c("MOs","TH","P"),
fg_color = c("orangered","skyblue","purple"),
bg_structure = "root")
Of course, root doesn’t have to be the background structure. Suppose you wanted to see how structures within the thalamus were positioned relative to each other:
th_str <- c("TH","LGd","LP","LGv","RT")
th_meshes <- map(th_str, ccf_2017_mesh)
names(th_meshes) <- th_str
plot_ccf_meshes(th_meshes,
fg_structure = c("LGd","LGv","LP","RT"),
fg_color = c("orangered","skyblue","purple","darkgreen"),
bg_structure = c("TH"))
Saving 3D plot snapshots as images
Exporting an image for use in a figure is handled by the rgl package:
plot_ccf_meshes(mesh_list,
fg_structure = c("MOs","TH","P"),
fg_color = c("orangered","skyblue","purple"),
bg_structure = "root")
rgl.snapshot("secondary_motor_and_targets.png")And exporting each structure in a list can be accomplished with purrr::walk() :
library(cocoframer)
library(purrr)
structures <- c("root","TH","MOs","P")
mesh_list <- map(structures, ccf_2017_mesh)
names(mesh_list) <- structures
open3d()
walk(structures,
function(structure) {
clear3d()
if(structure == "root") {
plot_ccf_meshes(mesh_list,
main_structure = structure)
} else {
plot_ccf_meshes(mesh_list,
main_structure = structure,
background_structure = "root")
}
rgl.snapshot(paste0(structure,".png"))
})Saving 3D plot objects as interactive HTML widgets
You can also save the interactive plot to HTML for later viewing in a web browser, with the assistance of the htmlwidgets package:
library(cocoframer)
library(purrr)
library(rgl)
library(htmlwidgets)
th_str <- c("TH","LGd","LP","LGv","RT")
th_meshes <- map(th_str, ccf_2017_mesh)
names(th_meshes) <- th_str
plot_ccf_meshes(th_meshes,
fg_structure = c("LGd","LGv","LP","RT"),
fg_color = c("orangered","skyblue","purple","darkgreen"),
bg_structure = c("TH"))
th_widget <- rglwidget(scene3d(), # Captures the current 3D rgl plot
width = 600,
height = 600)
saveWidget(th_widget, "th_structure_widget.html")The rgl package provides a robust framework for 3D animations. A simple example is making a spinning GIF of your brain structures of interest:
library(cocoframer)
library(purrr)
structures <- c("root","TH","MOs","P")
mesh_list <- map(structures, ccf_2017_mesh)
names(mesh_list) <- structures
plot_ccf_meshes(mesh_list,
fg_structure = c("MOs","TH","P"),
fg_color = c("orangered","skyblue","purple"),
bg_structure = "root")
anim <- spin3d(axis=c(0,1,0), # Spin on the y-axis
rpm = 12)
movie3d(anim,
fps = 20, # 20 fps is fairly smooth
duration = 5, # 5 sec = 1 rotation at 12 rpm
movie = "brain_demo", # Save as brain_demo.gif
dir = "./", # Output directory - will make a lot of temporary files.
type = "gif")These acronyms are used repeatedly in function names in cocoframer:
aba: Allen Brain Atlas
ccf: Common Coordinate Framework
mba: Mouse Brain Atlas
ish: In-Situ Hybridization
The license for this package is available on Github at: https://github.com/AllenInstitute/cocoframer/blob/master/LICENSE
We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests.
If you contribute code to this repository through pull requests or other mechanisms, you are subject to the Allen Institute Contribution Agreement, which is available in full at: https://github.com/AllenInstitute/cocoframer/blob/master/CONTRIBUTION