Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alleninstitute/cocoframer
COmmon COordinate FRAMEwork in R
https://github.com/alleninstitute/cocoframer
3d ccf r rgl
Last synced: about 2 months ago
JSON representation
COmmon COordinate FRAMEwork in R
- Host: GitHub
- URL: https://github.com/alleninstitute/cocoframer
- Owner: AllenInstitute
- License: other
- Created: 2018-07-27T17:14:56.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-05-19T00:14:53.000Z (over 4 years ago)
- Last Synced: 2024-08-31T01:08:19.006Z (5 months ago)
- Topics: 3d, ccf, r, rgl
- Language: R
- Size: 34.8 MB
- Stars: 35
- Watchers: 17
- Forks: 9
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The cocoframer package
Functions for the Allen Institute's Mouse Common Coordinate Framework (CCF) in R.
### Functionality
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:
* Retrieving 3D, CCF aligned, gridded ISH data from the Allen Brain Atlas API
* Rendering 2D plots of slices of ISH data
* Retrieving the Mouse Brain Atlas structural ontology
* Generating 3D plots of brain structures like those presented in the Allen Brain Explorer
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
### Similar Tools
These tools also utilize the Allen Brain Atlas CCF to generate 3D rendering of mouse brains. They are not made by the Allen Institute for Brain Science, but provide additional funcitonality beyond what is currently available from `cocoframer`:
**In R:**
The `mouselightr` package generates 3D CCF mouse brain plots, along with MouseLight neuron reconstructions:
https://github.com/jefferis/nat.mouselight
It
**In Python:**
`BrainRender` generates 3D CCF mouse brain plots, along with both Allen Connectivity Atlas and MouseLight neuron reconstructions:
https://github.com/BrancoLab/BrainRender
### Installation
cocoframer can be installed with:
```
devtools::install_github("AllenInstitute/cocoframer")
```
### Citation
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/
### Internet connection requirements
Some functions in cocoframer retrieve data from the Allen Brain Atlas API, and so require an internet connection.
These functions are prefixed with `get_`.
### Examples
**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"))
```
Cocoframer also provides a few built-in RGL material styles. The default is "shiny":
```
structures <- c("root","MO","SS")
mesh_list <- map(structures, ccf_2017_mesh)
names(mesh_list) <- structures
plot_ccf_meshes(mesh_list,
fg_structure = c("MO","SS"),
bg_structure = "root",
style = "shiny")
```
This can be changed to "matte":
```
plot_ccf_meshes(mesh_list,
fg_structure = c("MO","SS"),
bg_structure = "root",
style = "matte")
```
Or "cartoon":
```
plot_ccf_meshes(mesh_list,
fg_structure = c("MO","SS"),
bg_structure = "root",
style = "cartoon")
```
**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")
```
### Animations in rgl
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"),
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")
```
### Common acronyms
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
### License
The license for this package is available on Github at: https://github.com/AllenInstitute/cocoframer/blob/master/LICENSE
### Level of Support
We are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests.
### Contribution Agreement
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