{"id":22632066,"url":"https://github.com/alleninstitute/cocoframer","last_synced_at":"2025-07-08T08:05:11.235Z","repository":{"id":92584072,"uuid":"142604447","full_name":"AllenInstitute/cocoframer","owner":"AllenInstitute","description":"COmmon COordinate FRAMEwork in R ","archived":false,"fork":false,"pushed_at":"2020-05-19T00:14:53.000Z","size":36510,"stargazers_count":36,"open_issues_count":5,"forks_count":9,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-11T20:11:27.740Z","etag":null,"topics":["3d","ccf","r","rgl"],"latest_commit_sha":null,"homepage":null,"language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AllenInstitute.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-07-27T17:14:56.000Z","updated_at":"2024-10-25T05:07:02.000Z","dependencies_parsed_at":"2023-04-24T02:31:48.150Z","dependency_job_id":null,"html_url":"https://github.com/AllenInstitute/cocoframer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/AllenInstitute/cocoframer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fcocoframer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fcocoframer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fcocoframer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fcocoframer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AllenInstitute","download_url":"https://codeload.github.com/AllenInstitute/cocoframer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AllenInstitute%2Fcocoframer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264229252,"owners_count":23576239,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d","ccf","r","rgl"],"created_at":"2024-12-09T02:15:19.635Z","updated_at":"2025-07-08T08:05:11.210Z","avatar_url":"https://github.com/AllenInstitute.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The cocoframer package\nFunctions for the Allen Institute's Mouse Common Coordinate Framework (CCF) in R.\n\n### Functionality\ncocoframer provides some limited funcitonality for using data from the Allen Brain Atlas that is registered to the Mouse Common Coordinate Framework.  \n\nIt currently assists:  \n* Retrieving 3D, CCF aligned, gridded ISH data from the Allen Brain Atlas API  \n* Rendering 2D plots of slices of ISH data  \n* Retrieving the Mouse Brain Atlas structural ontology  \n* Generating 3D plots of brain structures like those presented in the Allen Brain Explorer  \n\nFor additional data retrieval functionality beyond cocoframer, see the full Allen Brain Atlas API docs:  \nhttp://help.brain-map.org/display/mousebrain/API  \n\nFor more information about the Allen Brain Atlas and the Common Coordinate Framework, see the Allen Brain Atlas website:  \nhttp://atlas.brain-map.org/  \n\nand the CCF documentation:  \nhttp://help.brain-map.org/download/attachments/2818171/Mouse_Common_Coordinate_Framework.pdf  \n\nAn interactive, in-browser 3D structure viewer, the Allen Brain Explorer, is available here:  \nhttp://connectivity.brain-map.org/3d-viewer?v=1\n\n### Similar Tools\n\nThese 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`:\n\n**In R:**  \nThe `mouselightr` package generates 3D CCF mouse brain plots, along with MouseLight neuron reconstructions:  \nhttps://github.com/jefferis/nat.mouselight  \nIt \n\n**In Python:**  \n`BrainRender` generates 3D CCF mouse brain plots, along with both Allen Connectivity Atlas and MouseLight neuron reconstructions:  \nhttps://github.com/BrancoLab/BrainRender\n\n### Installation\n\ncocoframer can be installed with:\n```\ndevtools::install_github(\"AllenInstitute/cocoframer\")\n```\n\n### Citation\n\nIf you use cocoframer to access Allen Brain Atlas ISH Data, please cite:  \nLein, E.S. et al. (2007) Genome-wide atlas of gene expression in the adult mouse brain, Nature 445: 168-176. doi:10.1038/nature05453\n\nIf you use cocoframer to make your own 3D brain structure images and animations, please cite:  \n© 2018 Allen Institute for Brain Science. Allen Brain Explorer. Available from: connectivity.brain-map.org/3d-viewer/\n\nFor other general citation issues, please refer to the Allen Institute Citation Policy: https://alleninstitute.org/legal/citation-policy/  \n\n### Internet connection requirements\n\nSome functions in cocoframer retrieve data from the Allen Brain Atlas API, and so require an internet connection.  \n\nThese functions are prefixed with `get_`.\n\n### Examples\n\n**Plotting a 3D brain structure**  \n\ncocoframer includes 3D mesh objects from version 3 of the CCF (2017). These can be retrieved with cocoframer and plotted using the rgl package.  \n\nIn this example, we'll retrieve and plot the Hippocampal Amon's Horn (CA in the ABA structural ontology).\n```\nlibrary(cocoframer)\nlibrary(rgl)\n\nCA_mesh \u003c- ccf_2017_mesh(acronym = \"CA\")\n\nshapelist3d(CA_mesh)\n```\n\n**Plotting multiple 3D brain structures**  \n\nTo get some context, it's sometimes helpful to plot multiple structures.  \n\nHere, 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:  \n```\nlibrary(cocoframer)\nlibrary(purrr)\nlibrary(rgl)\n\nstructures \u003c- c(\"root\",\"CA\")\nmesh_list \u003c- map(structures, ccf_2017_mesh)\n\nnames(mesh_list) \u003c- structures\n\nplot_ccf_meshes(mesh_list,\n                fg_structure = \"CA\",\n                bg_structure = \"root\")\n```\n![](man/figures/readme_ca.png?raw=true)\n\nYou can change the color and opacity of structures with additional parameters:\n\n```\nplot_ccf_meshes(mesh_list,\n                fg_structure = \"CA\",\n                fg_color = \"orangered\",\n                fg_alpha = 0.4,\n                bg_structure = \"root\",\n                bg_color = \"yellow\",\n                bg_alpha = 0.4)\n```\n![](man/figures/readme_ca_colors.png?raw=true)\n\nIt's straightforward to plot multiple structures, each with their own color:\n```\nlibrary(cocoframer)\nlibrary(purrr)\n\nstructures \u003c- c(\"root\",\"TH\",\"MOs\",\"P\")\nmesh_list \u003c- map(structures, ccf_2017_mesh)\n\nnames(mesh_list) \u003c- structures\n\nplot_ccf_meshes(mesh_list,\n                fg_structure = c(\"MOs\",\"TH\",\"P\"),\n                fg_color = c(\"orangered\",\"skyblue\",\"purple\"),\n                bg_structure = \"root\")\n\n```\n![](man/figures/readme_mo_th_p.png?raw=true)\n\nOf 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:\n```\nth_str \u003c- c(\"TH\",\"LGd\",\"LP\",\"LGv\",\"RT\")\nth_meshes \u003c- map(th_str, ccf_2017_mesh)\n\nnames(th_meshes) \u003c- th_str\n\nplot_ccf_meshes(th_meshes,\n                fg_structure = c(\"LGd\",\"LGv\",\"LP\",\"RT\"),\n                fg_color = c(\"orangered\",\"skyblue\",\"purple\",\"darkgreen\"),\n                bg_structure = c(\"TH\"))\n\n```\n![](man/figures/readme_within_th.png?raw=true)\n\nCocoframer also provides a few built-in RGL material styles. The default is \"shiny\":\n```\nstructures \u003c- c(\"root\",\"MO\",\"SS\")\nmesh_list \u003c- map(structures, ccf_2017_mesh)\nnames(mesh_list) \u003c- structures\n\nplot_ccf_meshes(mesh_list,\n                fg_structure = c(\"MO\",\"SS\"),\n                bg_structure = \"root\",\n                style = \"shiny\")\n```\n![](man/figures/readme_shiny.png?raw=true)\n\n\nThis can be changed to \"matte\":\n```\nplot_ccf_meshes(mesh_list,\n                fg_structure = c(\"MO\",\"SS\"),\n                bg_structure = \"root\",\n                style = \"matte\")\n```\n![](man/figures/readme_matte.png?raw=true)\n\n\nOr \"cartoon\":\n```\nplot_ccf_meshes(mesh_list,\n                fg_structure = c(\"MO\",\"SS\"),\n                bg_structure = \"root\",\n                style = \"cartoon\")\n```\n![](man/figures/readme_cartoon.png?raw=true)\n\n\n**Saving 3D plot snapshots as images**  \n\nExporting an image for use in a figure is handled by the rgl package:\n```\nplot_ccf_meshes(mesh_list,\n                fg_structure = c(\"MOs\",\"TH\",\"P\"),\n                fg_color = c(\"orangered\",\"skyblue\",\"purple\"),\n                bg_structure = \"root\")\n\nrgl.snapshot(\"secondary_motor_and_targets.png\")\n```\n\n\nAnd exporting each structure in a list can be accomplished with purrr::walk() :\n```\nlibrary(cocoframer)\nlibrary(purrr)\n\nstructures \u003c- c(\"root\",\"TH\",\"MOs\",\"P\")\nmesh_list \u003c- map(structures, ccf_2017_mesh)\n\nnames(mesh_list) \u003c- structures\n\nopen3d()\nwalk(structures,\n     function(structure) {\n     \n       clear3d()\n       \n       if(structure == \"root\") {\n         plot_ccf_meshes(mesh_list,\n                         main_structure = structure)\n       } else {\n         plot_ccf_meshes(mesh_list,\n                         main_structure = structure,\n                         background_structure = \"root\")\n       }\n       \n       rgl.snapshot(paste0(structure,\".png\"))\n     })\n```\n**Saving 3D plot objects as interactive HTML widgets**  \n\nYou can also save the interactive plot to HTML for later viewing in a web browser, with the assistance of the htmlwidgets package:\n```\nlibrary(cocoframer)\nlibrary(purrr)\nlibrary(rgl)\nlibrary(htmlwidgets)\n\nth_str \u003c- c(\"TH\",\"LGd\",\"LP\",\"LGv\",\"RT\")\nth_meshes \u003c- map(th_str, ccf_2017_mesh)\n\nnames(th_meshes) \u003c- th_str\n\nplot_ccf_meshes(th_meshes,\n                fg_structure = c(\"LGd\",\"LGv\",\"LP\",\"RT\"),\n                fg_color = c(\"orangered\",\"skyblue\",\"purple\",\"darkgreen\"),\n                bg_structure = c(\"TH\"))\n                \nth_widget \u003c- rglwidget(scene3d(), # Captures the current 3D rgl plot\n                       width = 600, \n                       height = 600)\n\nsaveWidget(th_widget, \"th_structure_widget.html\")\n```\n\n### Animations in rgl\n\nThe rgl package provides a robust framework for 3D animations. A simple example is making a spinning GIF of your brain structures of interest:\n```\nlibrary(cocoframer)\nlibrary(purrr)\n\nstructures \u003c- c(\"root\",\"TH\",\"MOs\",\"P\")\nmesh_list \u003c- map(structures, ccf_2017_mesh)\n\nnames(mesh_list) \u003c- structures\n\nplot_ccf_meshes(mesh_list,\n                fg_structure = c(\"MOs\",\"TH\",\"P\"),\n                bg_structure = \"root\")\n\nanim \u003c- spin3d(axis=c(0,1,0), # Spin on the y-axis\n               rpm = 12)\n\nmovie3d(anim, \n        fps = 20, # 20 fps is fairly smooth\n        duration = 5, # 5 sec = 1 rotation at 12 rpm\n        movie = \"brain_demo\", # Save as brain_demo.gif\n        dir = \"./\", # Output directory - will make a lot of temporary files.\n        type = \"gif\")\n```\n![](man/figures/rotate_demo.gif?raw=true)\n\n### Common acronyms\n\nThese acronyms are used repeatedly in function names in cocoframer:  \n\naba: Allen Brain Atlas  \nccf: Common Coordinate Framework  \nmba: Mouse Brain Atlas  \nish: In-Situ Hybridization  \n\n### License\n\nThe license for this package is available on Github at: https://github.com/AllenInstitute/cocoframer/blob/master/LICENSE\n\n### Level of Support\n\nWe are planning on occasional updating this tool with no fixed schedule. Community involvement is encouraged through both issues and pull requests.\n\n### Contribution Agreement\n\nIf 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\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleninstitute%2Fcocoframer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falleninstitute%2Fcocoframer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falleninstitute%2Fcocoframer/lists"}