Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update readme to reflect new name, fix typos and update links #24

Merged
merged 2 commits into from
Dec 14, 2023
Merged

Update readme to reflect new name, fix typos and update links #24

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bb5a81f
Update readme to reflect new name, fix typos and update links
adamltyson Dec 14, 2023
676838a
Update README.md
adamltyson Dec 14, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 20 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,16 @@
# brainglobe-heatmap
Rendering anatomical heatmaps with brainrender and matplotlib.
`brainglobe-heatmap` allows you to create heatmaps, mapping scalar values for each brain region (e.g., number of labelled cells in each region) to a color and creating beautiful visualizations in 2D (using [matplotlib](https://matplotlib.org/) or 3D (using [brainrender](https://brainglobe.info/documentation/brainrender/index.html)).

![2D heatmap generated using matplotlib](images/hm_2d.png)

**2D heatmap generated using matplotlib**

[![DOI](https://zenodo.org/badge/442271642.svg)](https://zenodo.org/badge/latestdoi/442271642)
![3D heatmap generated using brainrender](images/hm_3d.png)

**3D heatmap generated using brainrender**


`bgheatmap` makes 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.

![](images/hm_2d.png)
![](images/hm_3d.png)

### installation
`pip install bgheatmap`
## Installation
`pip install brainglobe-heatmap`


## User guide
Expand All @@ -31,8 +28,8 @@ For example:
)
```

`bgheatmap` creates a brainrender 3D `Scene` with 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 be **sliced** to expose
`brainglobe-heatmap` creates a brainrender 3D `Scene` with the given regions colored according the values in the dictionary.
Next, to create visualizations like the ones shown above, the three dimensional scene needs to be **sliced** to expose
the relevant parts.
This is done by specifying the position and orientation of a `Plane` which cuts through the scene.

Expand All @@ -50,11 +47,11 @@ To keep a section of the 3D brain, two planes with normal vectors facing in oppo
and everything in-between the two planes is kept as a slice.

### Slicing plane position
Finding the right position and orientation to the plane can take some tweaking. `bgheatmap` provides a `planner` class that makes the process easier by showing the position of the planes and how they intersect with the user provided regions (see image above).
Finding the right position and orientation to the plane can take some tweaking. `brainglobe-heatmap` provides a `planner` class that makes the process easier by showing the position of the planes and how they intersect with the user provided regions (see image above).
In `examples/plan.py` there's an example showing how to use the `planner`:

```python
import bgheatmap as bgh
import brainglobe_heatmap as bgh


planner = bgh.plan(
Expand Down Expand Up @@ -119,10 +116,10 @@ bgh.heatmap(
).show()
```

Here, `format` spcifies if a 2D plot should be made (using `matplotlib`) or a 3D rendering instead (using `brainrender`). The `cmap` parameter specifies the colormap used and `vmin, vmax` the color range.
Here, `format` specifies if a 2D plot should be made (using `matplotlib`) or a 3D rendering instead (using `brainrender`). The `cmap` parameter specifies the colormap used and `vmin, vmax` the color range.

### Regions coordinates
You can use `bgheatmap` to get the coordinates of the 2D 'slices' (in the 2D plane's coordinates system):
You can use `brainglobe-heatmap` to get the coordinates of the 2D 'slices' (in the 2D plane's coordinates system):


```python
Expand All @@ -141,20 +138,19 @@ coordinates = bgh.get_plane_coordinates(
)
```

## Using `bgheatmap` with other atlases.
## Using `brainglobe-heatmap` with other atlases.

`bgheatmap` uses `brainrender` which, in turn, uses brainglobe's `Atlas API` under the hood. That means that all of `bgheatmap`'s functionality is compatible with any of the atlases supported by the atlas API.
`bgh.heatmap`, `bgh.planner` and `bgh.get_plane_coordinates` all accept a `atlas_name` argument, pass the name of the atlas name you'd like to use!
For more information see the API's [https://docs.brainglobe.info/bg-atlasapi/introduction](documentation).
`brainglobe-heatmap` uses `brainrender` which, in turn, uses brainglobe's `Atlas API` under the hood. That means that all of `brainglobe-heatmap`'s functionality is compatible with any of the atlases supported by the atlas API. `bgh.heatmap`, `bgh.planner` and `bgh.get_plane_coordinates` all accept a `atlas_name` argument, pass the name of the atlas name you'd like to use!
For more information see the API's [documentation](https://brainglobe.info/documentation/bg-atlasapi/index.html).

## Contributing
Contributions to bg-heatmaps are more than welcome. Please see the [contributing guide](https://github.com/brainglobe/.github/blob/main/CONTRIBUTING.md).
Contributions to `brainglobe-heatmap` are more than welcome. Please see the [Developer's guide](https://github.com/brainglobe/.github/blob/main/CONTRIBUTING.md).

# Citing bgheatmap
If you use `bgheatmap` in your work, please cite it as:
## Citing `brainglobe-heatmap`
If you use `brainglobe-heatmap` in your work, please cite it as:

```
Federico Claudi, & Luigi Petrucco. (2022). brainglobe/bg-heatmaps: (V0.2). Zenodo. https://doi.org/10.5281/zenodo.5891814
```

Bgheatmap was developed by Federico Claudi and Luigi Petrucco, with the help of Marco Musy (the developer of [`vedo`](https://github.com/marcomusy/vedo))
`brainglobe-heatmap` was originally developed by Federico Claudi and Luigi Petrucco, with the help of Marco Musy (the developer of [`vedo`](https://github.com/marcomusy/vedo))