Package: bgheatmap
This package has been renamed tobrainglobe-heatmap. Please install the
latest version withpip install brainglobe-heatmapBG HeatmapsRendering heatmaps with brainrender.bgheatmapmakes it easier to create beautiful heatmaps from anatomical data mapping a scalar values for each brain region (e.g., number of labelled cells in each region) to color and creating beautiful visualizations in 3D and 2D.installationpip install bgheatmapUser guideThe starting point for a heatmap visualization is adictassigning scalar values to a set of brain regions (identified by their acronym).
For example:regions=dict(# scalar values for each regionTH=1,RSP=0.2,AI=0.4,SS=-3,MO=2.6,...)bgheatmapcreates a brainrender 3DScenewith the given regions colored according the values in the dictionary.
Next, to create visualizations like the ones shown above, the three dimensional sceen needs to beslicedto expose
the relevant parts.
This is done by specifying the position and orientation of aPlanewhich cuts through the scene.The orientation is set by the direction of anormal vectorspecified by the user.Everything that is on the side opposite where the normal vector will be cut and discarded.
To keep a section of the 3D brain, two planes with normal vectors facing in opposite directions are used:and everything in-between the two planes is kept as a slice.Slicing plane positionFinding the right position and orientation to the plane can take some tweaking.bgheatmapprovides aplannerclass that makes the process easier by showing the position of the planes and how they intersect with the user provided regions (see image above).
Inexamples/plan.pythere's an example showing how to use theplanner:importbgheatmapasbghplanner=bgh.plan(regions,position=(8000,5000,5000,),orientation="frontal",# orientation, or 'sagittal', or 'horizontal' or a tuple (x,y,z)thickness=2000,# thickness of the slices used for rendering (in microns))The position of the center of the plane is given by a set of(x, y, z)coordinates. The orientation can be specified by a string (frontal,sagittal,horizontal) which will result in a standard orthogonal slice, or by a vector(x, y, z)with the orientation along the 3 axes.Whe using one of the named orientation, you don't need to pass a whole set of(x, y, z)coordinates for the plane center. A single value is sufficient as the other two won't affect the plane position:f=bgh.heatmap(values,position=1000,orientation="sagittal",# 'frontal' or 'sagittal', or 'horizontal' or a tuple (x,y,z)thickness=1000,atlas_name="allen_cord_20um",format='2D',).show()Also, you can create a slice with a plane centered in the brain by passingposition=None:f=bgh.heatmap(values,position=None,orientation="sagittal",# 'frontal' or 'sagittal', or 'horizontal' or a tuple (x,y,z)thickness=1000,atlas_name="mpin_zfish_1um",format='2D',title='zebra fish heatmap').show(xlabel='AP (μm)',ylabel='DV (μm)')VisualizationOnce happy with the position of the slicing planes, creating a visualization is as simple as:bgh.heatmap(values,position=(8000,5000,5000,),orientation="horizontal",# 'frontal' or 'sagittal', or 'horizontal' or a tuple (x,y,z)title="horizontal view",vmin=-5,vmax=3,cmap='Red',format="2D",).show()Here,formatspcifies if a 2D plot should be made (usingmatplotlib) or a 3D rendering instead (usingbrainrender). Thecmapparameter specifies the colormap used andvmin, vmaxthe color range.Regions coordinatesYou can usebgheatmapto get the coordinates of the 2D 'slices' (in the 2D plane's coordinates system):regions=['TH','RSP','AI','SS','MO','PVZ','LZ','VIS','AUD','RHP','STR','CB','FRP','HIP','PA']coordinates=bgh.get_plane_coordinates(regions,position=(8000,5000,5000,),orientation="frontal",# 'frontal' or 'sagittal', or 'horizontal' or a tuple (x,y,z))Usingbgheatmapwith other atlases.bgheatmapusesbrainrenderwhich, in turn, uses brainglobe'sAtlas APIunder the hood. That means that all ofbgheatmap's functionality is compatible with any of the atlases supported by the atlas API.bgh.heatmap,bgh.plannerandbgh.get_plane_coordinatesall accept aatlas_nameargument, pass the name of the atlas name you'd like to use!
For more information see the API'shttps://docs.brainglobe.info/bg-atlasapi/introduction.ContributingContributions to bg-heatmaps are more than welcome. Please see thecontributing guide.Citing bgheatmapIf you usebgheatmapin your work, please cite it as:Federico Claudi, & Luigi Petrucco. (2022). brainglobe/bg-heatmaps: (V0.2). Zenodo. https://doi.org/10.5281/zenodo.5891814Bgheatmap was developed by Federico Claudi and Luigi Petrucco, with the help of Marco Musy (the developer ofvedo)