Add brainmapper widget docs (#226)

* Add brainmapper widget docs structure * update tutorial text * Add to tutorial * Add full docs * Small updates * Update docs/source/blog/brainmapper-widget.md Co-authored-by: Alessandro Felder <alessandrofelder@users.noreply.github.com> * Update docs/source/documentation/brainglobe-utils/transform-widget.md Co-authored-by: Alessandro Felder <alessandrofelder@users.noreply.github.com> * Update docs/source/documentation/brainglobe-utils/transform-widget.md Co-authored-by: Alessandro Felder <alessandrofelder@users.noreply.github.com> * Update docs/source/documentation/brainglobe-utils/transform-widget.md Co-authored-by: Alessandro Felder <alessandrofelder@users.noreply.github.com> --------- Co-authored-by: Alessandro Felder <alessandrofelder@users.noreply.github.com>
brainglobe · Aug 1, 2024 · 33fc3c7 · 33fc3c7
1 parent 438b729
commit 33fc3c7
Show file tree

Hide file tree

Showing 10 changed files with 267 additions and 1 deletion.
diff --git a/docs/source/blog/brainmapper-widget.md b/docs/source/blog/brainmapper-widget.md
@@ -0,0 +1,65 @@
+---
+blogpost: true
+date: July 31, 2024
+author: Adam Tyson
+location: London, England
+category: brainglobe
+language: English
+---
+
+# New brainmapper napari widget released
+
+One common use of BrainGlobe tools is to analyse the distribution of cells in a whole brain image. This process 
+involves first detecting cells using [`cellfinder`](/documentation/cellfinder/index) and then registering (aligning) the 
+data to a BrainGlobe atlas using [`brainreg`](/documentation/brainreg/index). The detected cell positions must then be 
+transformed from the coordinate space of the raw data to the coordinate space of the atlas for analysis.
+
+This workflow has previously been implemented with the [`brainmapper`](/documentation/brainglobe-workflows/brainmapper/index) 
+command line tool, which runs brainreg, then cellfinder and then analyses the distribution of cells throughout 
+the brain. This tool is excellent for automated analyses, but using a command-line tool isn't very intuitive for many 
+users, and it is difficult to optimise parameters for a new application.
+
+`brainreg` and `cellfinder` both have napari plugins. This allows use within a graphical user interface, and makes 
+it easier to iteratively optimise parameters. However, to assign cells to a brain region, users had to use the 
+`brainmapper` command line tool. 
+
+To improve this **we have released a new [`brainmapper` napari widget](/documentation/brainglobe-utils/transform-widget)**. 
+This allows users to combine the results of 
+`brainreg` and `cellfinder` to analyse the distribution of cells across the brain.
+
+## What does it do?
+
+The plugin takes as input cell coordinates (from `cellfinder` or another tool) and a `brainreg` output directory. It 
+then transforms cells to the atlas space. A summary of the cellular distribution (i.e. cells per brain region) is 
+then displayed:
+
+| structure\_name | left\_cell\_count | right\_cell\_count |
+| :--- | :--- | :--- |
+| Retrosplenial area, ventral part, layer 5 | 1853 | 814 |
+| Lateral dorsal nucleus of thalamus | 1541 | 0 |
+| Retrosplenial area, ventral part, layer 2/3 | 163 | 686 | 
+| Retrosplenial area, dorsal part, layer 5 | 561 | 82 | 
+| Retrosplenial area, dorsal part, layer 2/3 | 194 | 245 |
+| Ventral anterior-lateral complex of the thalamus | 412 | 0 |
+
+**Example of the results displayed within napari after running the widget**
+
+Full analysis results (coordinates of every cell, and numbers of cells for every brain region) can be
+saved alongside the transformed cell coordinates.
+
+## How do I install it?
+The widget is part of the `brainglobe-utils` package. However, the easiest way to install it is to upgrade the 
+`brainglobe` package:
+
+```bash
+pip install brainglobe --upgrade
+```
+
+It can also be installed from the 
+[napari plugin manager](https://napari.org/stable/plugins/start_using_plugins/finding_and_installing_plugins.html#find-and-install-plugins) 
+by searching for `brainglobe-utils`.
+
+## How do I use it?
+Please see the [documentation](/documentation/brainglobe-utils/transform-widget) and the
+[analysing brainwide distribution of cells tutorial](/tutorials/transform-cells-atlas).
+
diff --git a/docs/source/documentation/brainglobe-utils/index.md b/docs/source/documentation/brainglobe-utils/index.md
@@ -6,8 +6,9 @@ also be used directly. For more details, please see the specific pages:
 ## User guide
 ```{toctree}
 :maxdepth: 1
-citation-module
+transform-widget
 image_io
+citation-module
 ```
 :::{note}  The majority of the `brainglobe-utils` package is not yet documented here.
 :::
diff --git a/docs/source/documentation/brainglobe-utils/transform-widget.md b/docs/source/documentation/brainglobe-utils/transform-widget.md
@@ -0,0 +1,118 @@
+# brainmapper cell transformation widget
+
+## Details
+The `brainmapper` widget allows the full [`brainmapper` workflow](/documentation/brainglobe-workflows/brainmapper/index) to be run within napari, i.e.:
+1. Detect cells using [cellfinder](/documentation/cellfinder/index)
+2. Register the brain to the atlas using [brainreg](/documentation/brainreg/index)
+3. Transform cells to the atlas and assign each one to an atlas region using this widget
+
+```{hint}
+To get started, it may be helpful to follow the [analysing brainwide distribution of cells tutorial](/tutorials/transform-cells-atlas).
+```
+
+## How to install
+The widget is part of `brainglobe-utils`. It can be installed in three ways:
+
+:::{admonition} Installing as part of the metapackage
+:class: dropdown
+```
+pip install brainglobe
+```
+:::
+
+:::{admonition} Installing within napari
+:class: dropdown
+* [Make sure you have napari installed](https://napari.org/stable/tutorials/fundamentals/installation.html)
+* Install the brainreg napari plugin from within napari (`Plugins` -> `Install/Uninstall Package(s)`, choosing `brainglobe-utils`)
+:::
+
+:::{admonition} Installing on its own via PyPI
+:class: dropdown
+```
+pip install brainglobe-utils[napari]
+```
+:::
+
+```{hint}
+If you're not sure, we recommend installing the metapackage
+```
+
+## How to use
+
+### Prerequisites 
+Before you use this widget you need three things:
+1. Your raw image data
+2. The [brainreg](/documentation/brainreg/index) output directory, generated by registering your raw data to a BrainGlobe atlas
+3. Some points defined in the raw data space, e.g. cells detected by [cellfinder](/documentation/cellfinder/index). 
+
+```{hint}
+This widget will support any points that can be loaded into napari. Many file formats (e.g. the BrainGlobe xml format) 
+can be loaded by dragging and dropping them onto the napari window. 
+```
+
+### Using the widget
+1. Load the raw data into napari
+2. Load the points data into napari
+3. Open the `brainmapper` widget by selecting `Plugins > brainmapper (BrainGlobe)`
+4. Select the `Points layer` and `Raw data layer`
+5. Click `Transform points` and when prompted, select your brainreg output directory
+
+## Results
+
+### Transformed points
+This widget will produce two new layers:
+- `Points in downsampled space` - this is the points layer, but each point is transformed to the same space as the 
+`downsampled.tiff` image generated by brainreg. This is the same coordinate space as the raw data, but resampled and 
+realigned to match the atlas. This is saved for completeness, but likely is not needed for most analyses. 
+- `Points in atlas space` - this is the points layer, but each point is transformed to the atlas space. 
+Importantly, this is defined at the resolution of the atlas. These points may need to be scaled up to micron space 
+(i.e. by multiplying the coordinates by the resolution) to visualise in tools such as 
+[brainrender](/documentation/brainrender/index).
+
+These layers can be saved to disk with any appropriate napari plugin, such as 
+[brainglobe-napari-io](https://www.napari-hub.org/plugins/brainglobe-napari-io).
+
+
+### Numerical results
+#### Points summary
+Each cell will be assigned an atlas region, and a summary of these results will be displayed within the widget:
+
+| structure\_name | left\_cell\_count | right\_cell\_count |
+| :--- | :--- | :--- |
+| Retrosplenial area, ventral part, layer 5 | 1853 | 814 |
+| Lateral dorsal nucleus of thalamus | 1541 | 0 |
+| Retrosplenial area, ventral part, layer 2/3 | 163 | 686 | 
+| Retrosplenial area, dorsal part, layer 5 | 561 | 82 | 
+| Retrosplenial area, dorsal part, layer 2/3 | 194 | 245 |
+| Ventral anterior-lateral complex of the thalamus | 412 | 0 |
+
+**Example of the results displayed within napari after running the widget**
+
+The full summary results can be saved to csv by clicking the `Save points summary` button and choosing a filename:
+
+
+| structure\_name | left\_cell\_count | right\_cell\_count | total\_cells | left\_volume\_mm3 | right\_volume\_mm3 | total\_volume\_mm3 | left\_cells\_per\_mm3 | right\_cells\_per\_mm3 |
+| :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- | :--- |
+| Retrosplenial area, ventral part, layer 5 | 1853 | 814 | 2667 | 0.952479 | 0.966508 | 1.918987 | 1945.44971595174 | 842.207203665153 |
+| Lateral dorsal nucleus of thalamus | 1541 | 0 | 1541 | 0.597768 | 0.534717 | 1.132485 | 2577.92320766585 | 0 |
+| Retrosplenial area, ventral part, layer 2/3 | 163 | 686 | 849 | 0.57638 | 0.614387 | 1.190767 | 282.79954196884 | 1116.56008346531 |
+| Retrosplenial area, dorsal part, layer 5 | 561 | 82 | 643 | 0.611487 | 0.644904 | 1.256391 | 917.435693645163 | 127.150707702232 |
+| Retrosplenial area, dorsal part, layer 2/3 | 194 | 245 | 439 | 0.460668 | 0.492384 | 0.953052 | 421.127579949117 | 497.579125235589 |
+| Ventral anterior-lateral complex of the thalamus | 412 | 0 | 412 | 0.397422 | 0.365181 | 0.762603 | 1036.6814116984 | 0 |
+
+**Example of full point summary results that can be saved to disk**
+
+#### All point information
+The details of every single point can be saved to csv by clicking on the `Save all points information` 
+button and choosing a filename:
+
+|coordinate_raw_axis_0|coordinate_raw_axis_1|coordinate_raw_axis_2|coordinate_atlas_axis_0|coordinate_atlas_axis_1|coordinate_atlas_axis_2|structure_name                             |hemisphere|
+|---------------------|---------------------|---------------------|-----------------------|-----------------------|-----------------------|-------------------------------------------|----------|
+|20                   |2441                 |1674                 |1208                   |348                    |586                    |arbor vitae                                |left      |
+|120                  |2810                 |2194                 |1154                   |444                    |690                    |Medulla                                    |left      |
+|122                  |1891                 |1634                 |1169                   |363                    |460                    |Fastigial nucleus                          |right     |
+|183                  |2528                 |3363                 |1121                   |723                    |663                    |Medulla                                    |left      |
+|187                  |2763                 |2158                 |1122                   |437                    |679                    |Medial vestibular nucleus                  |left      |
+|200                  |3150                 |1661                 |1128                   |313                    |733                    |arbor vitae                                |left      |
+
+**Example of the individual point data that can be saved to disk**
diff --git a/docs/source/documentation/brainglobe-workflows/brainmapper/index.md b/docs/source/documentation/brainglobe-workflows/brainmapper/index.md
@@ -8,6 +8,12 @@
 - Calculate the volume of each brain area, and the number of labelled cells within it
 - Transform everything into standard space for analysis and visualisation
 
+:::{note}
+It is possible to detect cells in a whole brain image and register this data to an atlas entirely within a graphical 
+user interface. If you have not used `brainmapper` before, we recommend you take a look at the 
+[analysing brainwide distribution of cells tutorial](/tutorials/transform-cells-atlas).
+:::
+
 ## User Guide
 
 ```{toctree}

diff --git a/docs/source/tutorials/brainmapper/index.md b/docs/source/tutorials/brainmapper/index.md
@@ -27,6 +27,12 @@ It is recommended that you try this tutorial out on the fastest machine you have
 The tutorial is quite long, and is split into a number of sections.
 Please be aware that downloading the data and running `brainmapper` may take a long time (e.g., overnight x2) if you don't have access to a particularly high-powered computer, or fast network connection.
 
+:::{note}
+It is possible to detect cells in a whole brain image and register this data to an atlas entirely within a graphical
+user interface. If you have not used `brainmapper` before, we recommend you take a look at the
+[analysing brainwide distribution of cells tutorial](/tutorials/transform-cells-atlas).
+:::
+
 Please go through the following sections in order:
 
 ```{toctree}

diff --git a/docs/source/tutorials/images/brainmapper-widget/brainmapper-results.png b/docs/source/tutorials/images/brainmapper-widget/brainmapper-results.png
diff --git a/docs/source/tutorials/images/brainmapper-widget/brainmapper-widget.png b/docs/source/tutorials/images/brainmapper-widget/brainmapper-widget.png
diff --git a/docs/source/tutorials/images/brainmapper-widget/cell-counts.png b/docs/source/tutorials/images/brainmapper-widget/cell-counts.png
diff --git a/docs/source/tutorials/index.md b/docs/source/tutorials/index.md
@@ -40,6 +40,13 @@ Manually segmenting a 3d structure
 Detecting cells in 3D with cellfinder in napari
 :::
 
+:::{grid-item-card} {fas}`brain;sd-text-primary` Analysing cell distributions
+:img-bottom: images/brainmapper-widget/cell-counts.png
+:link: transform-cells-atlas
+:link-type: doc
+Analysing cell distributions in the brain with napari
+:::
+
 :::{grid-item-card} {fas}`brain;sd-text-primary` Retraining cellfinder
 :img-bottom: images/cellfinder-retraining-icon.png
 :link: cellfinder-retraining
@@ -92,6 +99,7 @@ manage-atlases-in-GUI
 tutorial-whole-brain-registration
 segmenting-1d-tracks
 segmenting-3d-structures
+transform-cells-atlas
 cellfinder-detection
 cellfinder-retraining
 silicon-probe-tracking

diff --git a/docs/source/tutorials/transform-cells-atlas.md b/docs/source/tutorials/transform-cells-atlas.md
@@ -0,0 +1,62 @@
+# Analysing brainwide distribution of cells
+
+In this tutorial you will use the [`brainmapper` napari widget](/documentation/brainglobe-utils/transform-widget) 
+to analyse the position of some points in the context of a BrainGlobe atlas. 
+
+The aim of this tutorial is to illustrate how to use the widget on a small dataset. After completing this tutorial, 
+you could try using the widget with the outputs of the 
+[whole brain cell detection tutorial](/tutorials/brainmapper/index), or even analyse the data from start to finish 
+using [`cellfinder`](/documentation/cellfinder/index), [`brainreg`](/documentation/brainreg/index) and then this 
+`brainmapper` widget.
+
+:::{note}
+You will need napari installed on your machine, and also to have previously run `brainreg`. Before following the next
+steps, please ensure you have followed the
+[registering a whole-brain image to an atlas tutorial](/tutorials/tutorial-whole-brain-registration).
+:::
+
+
+1. Open `napari`.
+2. Install `brainglobe-utils` by selecting `Plugins > Install/Uninstall plugins` and searching for `brainglobe-utils` in the searchbox. Then click on the `Install` button.
+3. Open the `brainmapper` widget by selecting `Plugins > brainmapper (BrainGlobe)` in the napari menu bar near the top left of the window.
+   ![brainmapper widget](./images/brainmapper-widget/brainmapper-widget.png)
+
+**The brainmapper widget appears on the right-hand side of the window.**
+
+
+4. Open the same sample image from the [registering a whole-brain image to an atlas tutorial](/tutorials/tutorial-whole-brain-registration) by 
+selecting `File > Open Sample > Low resolution brain (brainreg)`.
+5. Make the image easier to see by adjusting the `contrast limits` in the top left section of the napari window. Moving
+   the right-hand slider to the left will make the image appear brighter.
+6. Create a new points layer by clicking the `New points layer` button (on the left, just above the list of napari layers).
+7. Select the `Add points` button from the top left of the napari window (you can also press `2` or `p` on your 
+keyboard to activate this mode).
+8. Create a few (10-20) points by clicking on various parts of the brain image. You can navigate in 3D 
+by using the slider at the bottom of the napari window.
+
+:::{hint}
+In this tutorial we are creating some points manually. In real usage, these could be any point feature in your image, 
+detected manually or automatically (e.g. [with cellfinder](/tutorials/cellfinder-detection)).
+:::
+
+9. In the `brainmapper` widget, select your new points layer (named `Points` by default) from the dropdown next to `Points layer`. 
+10. Select your image layer (named `Sample brain` by default) from the dropdown next to `Raw data layer`.
+11. Click `Transform points` and when prompted, select the brainreg output directory saved during the [registering a whole-brain image to an atlas tutorial](/tutorials/tutorial-whole-brain-registration).
+12. A new table will then appear in the widget, listing the number of cells in each atlas region, for each hemisphere. 
+Two new points layers will also be created.
+
+![brainmapper results](./images/brainmapper-widget/brainmapper-results.png)
+
+**The distribution of points is displayed in the widget, and two new layers are generated.**
+
+13. Click on `Save points summary`, choose a directory, and call the file `points_summary.csv`. This will save a file
+containing a more detailed version of the table.
+14. Click on `Save all points information`, choose a directory, and call the file `all_points.csv`. This will save a file
+    containing the coordinates (in image and atlas space) and atlas region for every point for use in other analyses.
+15. Select the `Points in atlas space` layer. This is the same as the `Points` layer, but each point has been moved to 
+its position within the atlas (in voxel space). This can be saved to disk using any compatible plugin.
+
+ :::{hint}
+Saving points layers with an `.xml` file extension will save the points layer to the BrainGlobe format, and these can 
+be loaded into other BrainGlobe tools. 
+ :::