Histological E-data Registration in rodent Brain Spaces
- Kavli Institute for Systems Neuroscience, Norwegian University of Science and Technology (NTNU), Norway
Abstract
Recording technologies for rodents have seen huge advances in the last decade, allowing users to sample thousands of neurons simultaneously from multiple brain regions. This has prompted the need for digital tool kits to aid in curating anatomical data, however, existing tools either provide limited functionalities or require users to be proficient in coding to use them. To address this we created HERBS (Histological E-data Registration in rodent Brain Spaces), a comprehensive new tool for rodent users that offers a broad range of functionalities through a user-friendly graphical user interface. Prior to experiments, HERBS can be used to plan coordinates for implanting electrodes, targeting viral injections or tracers. After experiments, users can register recording electrode locations (e.g. Neuropixels and tetrodes), viral expression, or other anatomical features, and visualize the results in 2D or 3D. Additionally, HERBS can delineate labeling from multiple injections across tissue sections and obtain individual cell counts.Regional delineations in HERBS are based either on annotated 3D volumes from the Waxholm Space Atlas of the Sprague Dawley Rat Brain or the Allen Mouse Brain Atlas, though HERBS can work with compatible volume atlases from any species users wish to install. HERBS allows users to scroll through the digital brain atlases and provides custom-angle slice cuts through the volumes, and supports free-transformation of tissue sections to atlas slices. Furthermore, HERBS allows users to reconstruct a 3D brain mesh with tissue from individual animals. HERBS is a multi-platform open-source Python package that is available on PyPI and GitHub, and is compatible with Windows, macOS, and Linux operating systems.
Editor's evaluation
This paper provides the field with a new and important Python-based tool to assist neurosurgery both before and after a wide range of interventions. In its present form, the software comes as a convincing toolbox that may be helpful for researchers relying on neurosurgery in rodents (both mice and rats).
https://doi.org/10.7554/eLife.83496.sa0Introduction
Understanding the structure, function, or physiology of neural circuits requires the ability to consistently target brain regions prior to experiments and, afterward, to maintain an accessible, objective record of the areas studied (Simmons and Swanson, 2009). Traditionally, post hoc anatomical record-keeping has relied on histological approaches where users delineate anatomical features in tissue sections, then register them manually with a reference atlas. While these and other approaches are critical for grounding experiments anatomically, doing them has become increasingly challenging with the emergence of large-scale recordings spanning multiple brain regions.
Several software tools have been developed in recent years which use computer vision technology to accelerate and systematize the mapping of experimental results in various model species (e.g., Shamash et al., 2018; Song et al., 2020; Claudi et al., 2021; Andy, 2022). When combined with the appropriate reference atlases (e.g., Franklin and Paxinos, 2008; Wang et al., 2020; Claudi et al., 2020), these tool kits give users the ability to reconstruct electrode tracks, viral expression, anatomical projections (Oh et al., 2014; Zingg et al., 2014; Winnubst et al., 2019), cell types (Fürth et al., 2018), or to detect cells (Tyson et al., 2021), gene expression patterns, or functional nodes (Lein et al., 2007; Ortiz et al., 2020) in the brain.
Different types of tool kits have been developed for different brain preparations, including volumetric whole-brain data or sliced tissue sections, with each approach bringing its own strengths and limitations. Whole-brain volume analyses have the advantage of readily conveying the 3D spatial relationships between neuronal pathways and neighboring structures. For instance, ITK-SNAP (Yushkevich et al., 2006) is a popular biomedical software used for automatic image segmentation and delineation of regions of interest in human brain imaging data. For animal models, there is Brainrender (Claudi et al., 2021), which displays any of several atlases incorporated from the BrainGlobe Atlas API in 3D. It provides fast visualization for user-defined data sets, such as reconstructed electrode tracks, viral expression, or anatomical projections. These can be obtained when Brainrender is combined with sibling software, Brainreg (Tyson et al., 2020), which maps whole-brain data sets to atlases using supervised automatic image registration. While whole-brain data sets provide a holistic quantitative dimension to analyses, generating them is time and resource intensive, requiring either a light sheet scanning microscope or magnetic resonance imaging.
Because of the comparatively lower cost and simplicity, anatomical mapping using histological tissue sectioning still dominates in most labs (e.g., Clancy et al., 2019; Zutshi et al., 2022; Lagartos-Donate et al., 2022; Gardner et al., 2022). This, however, also has its own challenges. One common issue lies in matching a given tissue slice correctly to a reference atlas template. Previous studies have sought to solve this problem using multiple software platforms, like ImageJ (Schneider et al., 2012), Adobe Illustrator (Adobe Inc, 2023b), or Adobe Photoshop (Adobe Inc, 2023a), which can be time consuming for manual curation and is not systematic. Software packages have been developed to address this issue, including the electrode reconstruction tool kit, SHARP-TRACK (Shamash et al., 2018). This software uses a global warping transformation method to fit histological images back to a mouse atlas. Afterward, it provides a read-out of the estimated number of channels in each brain region as well as 3D visualizations. As currently configured, the tool kit works only with mouse atlases and is MATLAB-based, which requires a paid license and some programming knowledge.
Despite the number of tool kits available, there currently is no single software that combines functionalities spanning the gamut of pre-surgical planning and post-experiment registration without requiring programming. To help fill this methodological gap, we developed HERBS, an open-source Python package which brings together a range of functionalities in a user-friendly graphical front-end interface. HERBS can generate pre-surgical coordinates, reconstruct electrode tracks after recordings, mark viral expression volumes, or single cells; delineate regional boundaries in brain slices, and view post hoc anatomical reconstructions in 2D or 3D. There is no upper limit for the number of electrodes that it can reconstruct, so it can be used with microelectrode arrays or multi-tetrode bundles. To serve both rat and mouse users, HERBS has the in-built function to download and run the Waxholm Space (WHS) Atlas of the Sprague Dawley Rat Brain (Papp et al., 2014) or the Allen Mouse Brain Atlas (Wang et al., 2020). The software also contains an atlas explorer that can scroll freely through either rat or mouse atlases to display coronal, sagittal, and horizontal planar surfaces in 2D, as well as the corresponding mesh or volume of the atlas in 3D.
For accurate and robust image registration, HERBS provides rigid registration as well as interactive, non-rigid registration using triangulation-based piece-wise affine transformation. It is compatible with most tissue staining methods and image formats, as long as the regions of interest are visible and can be delineated by the user. For users who wish to augment or add functionalities of their own in Python, we provide a standalone Python pipeline tool kit, TRACER (Toolkit for Reconstructing Anatomical CoorindatEs in Rats), in parallel with HERBS (see Materials and methods for more information). To maximize general accessibility, HERBS requires minimal programming knowledge and is compatible with Windows, macOS, and Linux systems. It is intended as an open community resource available for further expansion and refinement. We hope it offers a valuable addition to the anatomical methods available for the neuroscience community.
Results
General outline
HERBS was designed as an intuitive, generic software tool to provide rodent users with four core functionalities, shown in Figure 1A. These include (a) generating anatomical target coordinates when planning a surgery; (b) processing and editing raw histological data; (c) registering and reconstructing objects implanted in the brain; and (d) visualizing annotated brain volumes in 3D. Users can carry out each functionality by following a series of steps described in the HERBS Cookbook using a keyboard and mouse. The layout of the user interface for HERBS, including color-coded panels used to execute its functionalities, are shown in Figure 1B.
Figure 1
The core functionalities and user interface of HERBS.
(A) HERBS can be used to (a) plan electrode insertions or viral injections before surgery, (b) process and edit histological images, (c) register objects such as probes, virus, cells, and slice boundaries from histological images, and (d) visualize the brain in 3D with defined functions. (B) The user interface of HERBS consists of the Menu Bar (outlined in blue) for navigating through the functions, the Tool Bar (outlined in red) from which users select actions to perform in the Plot Window (magenta), such as registering or reconstruct objects. The Side Bar (geen) provides tools for visually editing objects or layers. The Status Bar (in purple at bottom) shows the brain regions and coordinates displayed in the Plot Window. The WHS or Allen Mouse Brain atlases can be downloaded and loaded directly through HERBS from the Menu Bar with a click of a button.
When installing HERBS, users can choose whether to use the WHS Atlas of the Sprague Dawley Rat Brain (Papp et al., 2014) or the Allen Mouse Brain Atlas (Wang et al., 2020) as the anatomical reference (see Cookbook, chapter 6.1). Either atlas can be downloaded through HERBS, as they are both integrated as parts of the software package. We point users wishing to employ other volumetric atlases, including for other species, to section 6.1.3 of the HERBS CookBook for links to illustrated instructions on uploading and installing additional atlases.
Generating pre-surgical coordinates
One of the essential steps in planning a surgery is defining the stereotaxic coordinates to reach specific brain areas of interest. HERBS facilitates this process by allowing users to determine the insertion parameters required to target one or several regions along a linear trajectory. This is done by simply clicking the start point and end point of the desired path on a 2D brain slice image, and there is no limit to the number of trajectories (e.g. recording probes) that can be planned. HERBS then automatically computes the insertion angle and length needed to reach the target brain region, as well as the location of the trajectory relative to Bregma defined in the atlas. The user can print and bring the read-out to the surgery room or save for record keeping. The planning functionality is equally applicable for targeting imaging lenses, injection pipettes for tracer or virus injections, or making focal lesions.
The working steps for generating pre-surgical coordinates are illustrated in Figure 2, in which we plan the insertion of a multi-shank Neuropixels 2.0 probe through retrosplenial cortex, visual cortex, and the intermediate hippocampus in the right hemisphere of a rat. The step-by-step protocol is described in the HERBS Cookbook, Chapter 6.4. Neuropixels users should note that estimates of probe length include the 175-µm channel-less shank tip, and that HERBS eliminates it when estimating the number of recording channels in the brain. In the first step, the user scrolls to the brain slice of interest (Figure 2A). This is aided by the color coding of each brain area in the atlas, which provides visual landmarks for defining boundaries between regions. Next, the probe trajectory is defined in the region(s) of interest with clicks of the mouse (Figure 2B). Once completed, the probe trajectory is saved as a layer in the Side Bar, after which it is saved to a 3D representation showing the trajectory of the probe in a WHS brain volume (Figure 2C). After the probe is merged on the Side Bar, a read-out is generated for a 4-shank probe (Figure 2D) that includes the location and regions traversed. A more detailed read-out table for each shank of the 4-shank probe can also be made (Figure 2E) which includes inclination, length of probe inserted, number of recording channels per region, and entry and exit coordinates of the probe. Either or both read-outs can be saved per the user’s desire. As there is no limit to the number of probes that can be planned for insertion, the user simply repeats the steps above for each probe. Users can also apply this functionality to target multiple regions using multi-probe implants with user-defined spacing and geometries. Users can define the recording site layout on individual probes as well (see section 6.6 of the CookBook for instructions and links to illustrated tutorials).
Figure 2
Using HERBS to plan a Neuropixels 2.0 probe implant before surgery.
(A) Once the plane of choice is set (coronal in this example), 2D atlas brain sections with regional delineations appear and the user scrolls to the slice with the region(s) they wish to target. (B) The user defines the trajectory of the probe by clicking the desired start and end-points (the insertion angle here is 40.8° lateral tilt at Bremga –6.8 mm). (C) A linear probe trajectory is projected into the Waxholm Space in 3D. (D) A read-out table for all four probes shows the regions the probe has traversed and the number of channels in each region. (E) A detailed read-out for a single probe provides the entry position, probe angle, and insertion length to reach the target regions, as well as an estimation of the number of recording channels in each region in the experiments.
Reconstructing electrode tracks
Another core functionality of HERBS is reconstructing electrode paths after surgeries or in vivo recordings, and there is no upper limit on the number of electrodes that can be reconstructed. Prior to reconstructing probe trajectories, histological images can be pre-processed before they are overlaid on their corresponding atlas images. Pre-processing can include rotating the section to an optimal plane, changing brightness, gamma curves, and so forth, and can be done using the image view controller in the Side Bar, or the Edit option in the Menu Bar, as indicated in the interface panel in Figure 1B (see HERBS Cookbook, chapter 6.6).
After the image has been loaded and adjusted, the user can begin the steps of the reconstruction pipeline shown in Figure 3, which uses an example section with a track from a Dil-stained Neuropixels 1.0 probe (red) progressing laterally from visual to auditory cortex (an example image for probe reconstruction is provided in Figure 3—figure supplement 1). The first step is choosing the plane of sectioning (coronal, sagittal, and horizontal) and scrolling to the corresponding atlas brain slice. Once the corresponding slice is located, the user defines anchor points to warp the histological section onto the atlas section (Figure 3A) (see Cookbook, chapters 6.4 and 6.5). Once the anchor points are defined and the matching step is complete, the user then clicks a minimum of 4 points along the probe track in the tissue, after which a 3D rendering is generated showing how the probe is situated in the volume of the brain (Figure 3B) (Cookbook, chapter 6.6.1). A detailed read-out table showing the inclination and length of the probe, regions traversed and number of recording channels per region are generated automatically (Figure 3C). In cases where histological sections are cut out of plane, HERBS allows the user to tilt the atlas brain up to 30° to facilitate template matching. We also note that electrode track reconstructions can be performed for any type of electrodes, tetrodes, or recording arrays, as well as with different sizes of sections. HERBS facilitates this by allowing users to build user-defined geometry and channel layouts of linear silicon probes (see the subfolder "HERBS/image/probe_related" on the HERBS GitHub page, linked in "Data availability, software, and citation policy" below).
Figure 3 with 1 supplement see all
Reconstructing a recording probe trajectory from histological sections.
(A) The initial steps include scrolling to the atlas brain slice (left) that best matches the user’s histological section (middle). User-defined anchor points are then used to stretch and conform the histological section onto the atlas section; once they are merged a new image is generated with the histology warped to overlay the atlas slice (right panel). (B) The user then generates an estimate of probe placement and length by clicking at least four points spanning from the entry of the probe in the brain to the distal tip (left). The 3D reconstructed placement of the probe is shown in the sagittal plane (middle panel) and viewed from the top (right panel) in the WHS volume. (C) A read-out from the merged probe shows details of the probe insertion, the coordinates, as well as the brain regions the probe traversed in different colors. WHS, Waxholm Space.
Reconstruction of viral expression
Beyond electrode reconstructions, HERBS can be used for anatomical applications including visualization of virus expression, tracer labeling, or marking lesions or neurodegeneration. Here, we provide a brief overview of the procedure for reconstructing a spatial volume of adenovirus (AAV) expression (see Cookbook, chapter 6.7 for this and related protocols). The procedure for reconstructing viral expresion volumes is similar to that for probe reconstruction, but the regions defined in each slice are two-dimensional, and the volume to delineate will likely extend over multiple slices (Figure 4). As with reconstructing a probe track, the first step in reconstructing a viral volume is matching the starting histology section with the corresponding slice in the atlas brain and overlaying the two. The initial slice from an example viral reconstruction is shown in Figure 4A, and the same image is provided for user practice in Figure 4—figure supplement 1. The user then defines the perimeter of virus expression by selecting the magic wand tool from the Tool Bar and clicking on a fluorescent region of tissue in the histological section (Figure 4B). Note that the granularity of the selected region will depend on the magic wand tolerance set by the user. These steps are repeated for each slice included in the visualization. Finally, the marked fluorescent regions from several 2D sections are combined and projected into a 3D brain volume (Figure 4C), and the list of brain regions in contact with the virus are shown in the read-out with color-coded labels (Figure 4D). The same functions and steps are used for similar tasks such as labeling single cells, marking fibers of passage, or visualizing lesions. Note also that the resolution of the 3D reconstruction will depend on how many sections the user includes in the reconstruction; the example in Figure 4C consisted of 11 tissue slices. It is also possible to load cell point data generated from other programs, such as CellFinder (Tyson et al., 2021), and to visualize those data in 3D brain volumes. Instructions for importing external cell point data can be found in section 6.8.3 of the HERBS Cookbook.
Figure 4 with 1 supplement see all
3D visualization of virus expression across multiple tissue sections.
(A) Shows the spatial extent of AAV-mediated mCherry expression in a coronal section from the frontal cortex of an adult rat. (B) The region of viral expression is defined by clicking the fluorescent region of tissue with the magic wand tool; areal boundaries are included at this stage. (C) A volumetric rendering of the brain shows the extent of viral expression in cingulate cortex and surrounding areas, with the volume of virus spread (based on the 11 slices used here) expressed in voxels, and the proportion of each region expressing the virus show as a percentage. (D) A read-out of the regions in which the virus was expressed.
Discussion
With HERBS, we seek to furnish rodent users with a user-friendly, click-button GUI that simplifies the process of curating histological data. The functionalities include planning coordinates ahead of surgeries as well as registering and visualizing anatomical data in 2D or 3D after experiments are completed. The GUI can be used to delineate a range of features such as recording locations, lesions or viral expression and is compatible with potentially any histological staining method. With HERBS, the user marks regions of interest on tissue images directly and each slice is mapped to a template, which should greatly reduce subjective judgement and variability across samples and brains. For rat users, HERBS references the newest version (v4) of the WHS rat brain atlas (Papp et al., 2014), which contains over 200 labeled cortical and sub-cortical regions at sub-millimeter scales, and for mouse users it references the widely-adopted Allen Mouse Brain Atlas (Wang et al., 2020).
Novelty and utility of HERBS in relation to other tool kits
Although several software packages with similar functionalities have been released in recent years (see Supplementary file 1), there are a number of features that distinguish HERBS from them. Foremost is its simplicity, since it works via a visually intuitive, click-button interface designed to minimize user effort, and it requires minimal coding and no added software. It is also unique in that it brings together both pre- and post-surgical registration and mapping functionalities in one program. The fact that it specifically includes rats also stands out among the many high-quality rendering and digital atlas resources for mice, such as Brain Mesh (Yaoyao-Hao, 2020), SHARPTRACK (Shamash et al., 2018), cocoframer (Lein et al., 2007), and others (e.g. Jin et al., 2019, Chon et al., 2019).
Another recently available anatomical tool kit is Brainrender (Claudi et al., 2021), which produces visually appealing anatomical renderings from a variety of source atlases through the BrainAtlasglobe API, but differs from HERBS in important ways. The most essential difference is that Brainrender was designed as a visualization tool. As such, it renders anatomical data in 3D volumes, but it cannot register anatomical data in a reference atlas on its own. Registration must be done beforehand with separate software such as Brainreg (Tyson et al., 2022) or CellFinder (Tyson et al., 2021). HERBS, in contrast, was designed primarily as a registration tool, which comes configured to work with primary source atlases for rats or mice. The HERBS GUI can both download and load these reference atlases, whereas Brainrender relies on separate software and plugins which require programming knowledge in Python. The output from HERBS could be used as input for Brainrender if formatted appropriately, though HERBS offers some of its own visualization functionalities for simplicity. Finally, Brainreg and Brainrender use whole-brain data from light sheet imaging, whereas HERBS works with commonly used histological tissue sectioning methods.
The Allen Institute recently released the Neuropixels Trajectory Explorer (Andy, 2022.), a MATLAB-based platform which can be used to plan coordinates for electrophysiological probes prior to surgery in mice and rats. Currently, the pre-surgical registration step is the only functionality available, as it does not yet have the option to load histology for post hoc processing of probe tracks or viral expression. Unlike Brainrender and HERBS, it runs in MATLAB, which typically requires a paid software license. Thus, the main features that distinguish HERBS from other tools are that it (i) offers a combination of functionalities found separately in Brainrender and Neuropixels trajectory explorer, (ii) all functionalities in HERBS are accessible with button clicks and keystrokes. It includes reconstructing probe tracks of neuropixel 1.0 and 2.0, tetrodes and linear silicon probes (with user defined geometry and channel layout); along with registering virus expressed with a read-out of the spread in brain regions in volume and percentage, and (iii) it can be used immediately with the WHS Rat Brain Atlas or the Allen Mouse Brain Atlas without requiring additional plugins. Beyond these features, HERBS, similar to Brainreg (Tyson et al., 2022), can incorporate other atlases given the correctly formatted files, such as the Paxinos and Watson atlases for rats or mice, provided the user has the appropriate licensing permissions.
Sources of error and future improvements
While we hope that HERBS proves useful in its current form, there are areas where it can be improved and expanded in the future. For example, the template matching step can be time consuming if data sets contain a large number of histological slices, as with virus expression or tracer labeling. We aim to streamline these processes by implementing machine vision-based algorithms for pre-processing user images and matching them to template slices automatically in future versions of HERBS. Furthermore, although we designed HERBS to minimize the need for programming, installing it could be challenging for users who have not installed Python before.
In developing HERBS we also encountered sources of error which appear general to working with anatomical tissue that has been preserved with fixatives. For instance, we found that probe length estimates can be less consistent when larger numbers of histological slices are used for reconstructions. We suspect these errors could arise from averaging across clicked points defining the probe trajectory, and it is possible that misalignment of clicked points between slices can add to this. Another issue is that fixing tissue with paraformaldehyde causes non-uniform shrinking of the tissue. We found this could lead to small discrepancies when comparing Neuropixels channel counts from HERBS, which uses fixed tissue, against LFP measures taken while the animals were still alive. Although tissue shrinkage is inherent to histological processing and cannot be removed mathematically, HERBS offers a solution by fitting warped tissue to the atlas template using multiple anchor points per slice, which should substantially reduce inconsistencies due to shrinkage.
Accurately registering raw neuroanatomical data in a reference atlas framework, though critically important, is time consuming, tedious and variable from user to user. HERBS was developed to expedite, simplify, and systematize this process by providing a single tool for generating anatomical coordinates, as well as annotated 2D and 3D visualizations and data tables summarizing its outputs. We wish to emphasize that HERBS is a completely open-source software with which we aim to help our fellow research community. We therefore welcome users to submit suggestions for improvements and to report bugs on our GitHub page, as this will help us continually improve the software and user experience.
Materials and methods
Key resources table
| Reagent type (species) or resource | Designation | Source or reference | Identifiers | Additional information |
|---|---|---|---|---|
| Software, algorithm | Numpy | Harris et al., 2020 | RRID:SCR_008633 | |
| Software, algorithm | Scipy | Virtanen et al., 2020 | RRID:SCR_008058 | |
| Software, algorithm | OpenCV | Bradski, 2000 | RRID:SCR_01552 | |
| Software, algorithm | PyOpenGL | Woo et al., 1999 | ||
| Software, algorithm | PyQT5 | PyQT, 2012 |
Python packages and resources
Request a detailed protocolHERBS is written entirely in Python version three using basic Python packages, such as numpy, opencv, and scipy, as mentioned in the table below. Details on the specific dependencies used in HERBS can be found in HERBS Cookbook (chapter 3). Documentation and step-wise instructions for installing and implementing HERBS can be found in the HERBS Cookbook (chapter 4). HERBS is an open-source software with hard-coded Python scripts. Should a user wish to customize Python-pipeline, one can use the code of TRACER—which is open-source and available at the Github repository (Paglia et al., 2021). To use HERBS, we recommend users to create a PyCharm project with Python installation (version 3.8.10) and other supporting packages which are specified in the dependencies section in the HERBS Cookbook (chapter 4).
Neuropixels and virus expression
All experiments were performed in accordance with the Norwegian Animal Welfare Act and the European Convention for the Protection of Vertebrate Animals used for Experimental and Other Scientific Purposes. All procedures were approved by the Norwegian Food Safety Authority (Mattilsynet; protocol IDs 27175 and 25094). All tissue for in-house testing came from adult (>15 weeks) Long-Evans hooded rats. Detailed steps of the surgical preparation and post-operative care are described in Mimica et al., 2018.
Neuropixels
Request a detailed protocolThe probes (version 1.0 Neuropixels, IMEC, Belgium) were coated with DiI (Vybrant DiI, catalog no. V22888, Thermo Fisher Scientific, USA) by repeatedly drawing a 2 µL droplet of DiI solution at the tip of a micropipette up and down the length of the probe shank until all DiI had dried onto the shank, causing the shank to appear pink. The probes were angled in the arm of a stereotaxic frame and inserted at a rate of 100–300 µm per min. The chronically implanted animal was kept <1 week following surgery, after which it was perfused with 4% paraformaldehyde and the brains were removed.
The brain was transferred to 2% dimethyl sulfoxide (DMSO; VWR, USA) solution for cryoprotection for 1–2 days, after which the Neuropixel shank was removed, the brain was frozen and sectioned in 50 µm slices with a sliding microtome (Microm HM430, Thermo Fisher Scientific). The tissue sections then underwent fluorescent immunostaining against NeuN (catalog no. ABN90P, Sigma-Alrich, USA), followed by secondary antibody-staining with Alexa 647-tagged goat anti-guinea pig antibody (catalog no. A21450, Thermo Fisher Scientific), after which the sections were rinsed, mounted, coverslipped, and stored at 40C. The detailed immunostaining protocol is available per request. Next, the sections were digitized using an automated scanner for fluorescence and brightfield images at the appropriate illumination wavelengths (Zeiss Axio Scan.Z1, Jena, Germany), and were saved in .jpeg format for processing in TRACER.
Virus expression
Request a detailed protocolPulled glass pipettes were used to inject 500 nL of AAV5-mDIx-Chr2-mCherry-Fishell-3 (plasmid no. 83898, Addgene, USA; AAV produced at Kavli Viral Vector Core Facility, NTNU) at a rate of 50 nL per min. Bilateral injections were targeted to the cingulate cortex (Cg1; +2.0 AP, ±0.5 ML, –2.0DV). Five weeks after surgery, the animal was killed and perfused with 4% paraformaldehyde. The brain was removed, post-fixed overnight in 4% paraformaldehyde at 40C, then cryoprotected for 24 hr in 2% DMSO. The brain was then frozen in dry ice and 40 µm sections were collected as described above. Fluorescent signal from the virus was amplified by immunostaining against Red Fluorescent Protein (catalog no. 5F8, Chromotek GmbH, Germany), followed by secondary antibody-staining with Alexa 546-tagged Goat anti-rat IgG (catalog no. A-11081, Thermo Fisher Scientific). The detailed immunostaining protocol is available upon request.
Data availability, software, and citation policy
The software described in this manuscript is an open-source software written completely in Python. HERBS is fully supported by Windows, macOS, and Linux. Source code is available on https://github.com/Whitlock-Group/HERBS (Fuglstad, 2022). HERBS Cookbook and documents are available on the Whitlock group Github page.
The WHS rat brain atlas files can be found here on the NITRC website (https://www.nitrc.org/projects/whs-sd-atlas). The required atlas files to run HERBS (downloaded upon installation of HERBS) and TRACER are cited below:
WHS rat brain atlas v4:
WHS_SD_rat_atlas_v4.nii.gz (Kleven et al., in preparation)
WHS_SD_rat_atlas_v4.label (Kleven et al., in preparation)
Previous version of the WHS rat brain atlas (v1.01):
WHS_SD_rat_T2star_v1.01.nii.gz (Papp et al., 2014)
WHS_SD_rat_brainmask_v1.01.nii.gz (Papp et al., 2014)
Citation policy
Request a detailed protocolWe kindly ask users to cite this paper when using HERBS or TRACER in their studies, and to cite the appropriate version of the WHS rat brain atlas.
Refer to the WHS Atlas by its RRID: SCR_017124, and cite the first publication (Papp et al., 2014) along with the version of the atlas that is used. For example, cite Kjonigsen et al., 2015, v2 of the atlas if the user’s work makes particular use of delineations of the hippocampal region. Or cite Osen et al., 2019, v3 of the atlas if the user’s work makes particular use of delineations of the auditory system.
License
Request a detailed protocolThe WHS Atlas of the Sprague Dawley rat brain is licensed under the Creative Commons Attribution ShareAlike (CC BY-SA) 4.0 license: https://creativecommons.org/licenses/by-sa/4.0/.
The Allen Mouse Brain Atlas software and wiki are freely available at https://github.com/cortex-lab/allenCCF (Shamash et al., 2022).
Data availability
The software described in this manuscript is an open-source software written completely in Python 3.8. HERBS is fully supported by Windows, macOS and Linux. Source code, HERBS Cookbook and documentation are available on the Whitlock group Github page: https://github.com/Whitlock-Group/HERBS. The Waxholm Space rat brain atlas files can be found here from the NITRC website: https://www.nitrc.org/projects/whs-sd-atlas. The Allen Mouse Brain Atlas software and wiki are freely available at: https://github.com/cortex-lab/allenCCF.
References
-
The opencv libraryDr Dobb’s Journal: Software Tools for the Professional Programmer 25:120–123.
-
Enhanced and unified anatomical labeling for a common mouse brain atlasNature Communications 10:5067.https://doi.org/10.1038/s41467-019-13057-w
-
Locomotion-dependent remapping of distributed cortical networksNature Neuroscience 22:778–786.https://doi.org/10.1038/s41593-019-0357-8
-
BrainGlobe atlas API: a common interface for neuroanatomical atlasesJournal of Open Source Software 5:2668.https://doi.org/10.21105/joss.02668
-
An interactive framework for whole-brain maps at cellular resolutionNature Neuroscience 21:139–149.https://doi.org/10.1038/s41593-017-0027-7
-
Molecular atlas of the adult mouse brainScience Advances 6:eabb3446.https://doi.org/10.1126/sciadv.abb3446
-
Nih image to imagej: 25 years of image analysisNature Methods 9:671–675.https://doi.org/10.1038/nmeth.2089
-
A deep learning algorithm for 3D cell detection in whole mouse brain image datasetsPLOS Computational Biology 17:e1009074.https://doi.org/10.1371/journal.pcbi.1009074
-
BookOpenGL Programming Guide: The Official Guide to Learning OpenGL, Version 1.2Addison-Wesley Longman Publishing Co., Inc.
Decision letter
-
Mathieu WolffReviewing Editor; CNRS, University of Bordeaux, France
-
Laura L ColginSenior Editor; University of Texas at Austin, United States
-
Mathieu WolffReviewer; CNRS, University of Bordeaux, France
In the interests of transparency, eLife publishes the most substantive revision requests and the accompanying author responses.
Decision letter after peer review:
[Editors’ note: the authors submitted for reconsideration following the decision after peer review. What follows is the decision letter after the first round of review.]
Thank you for submitting the paper "TRACER: A toolkit to register and visualize anatomical coordinates in the rat brain" for consideration by eLife. Your article has been reviewed by 3 peer reviewers, including Mathieu Wolff as the Reviewing Editor and Reviewer #3, and the evaluation has been overseen by a Senior Editor.
Comments to the Authors:
We are sorry to say that, after consultation with the reviewers, we have decided that this work will not be considered further for publication by eLife.
In short, all reviewers found the tool described of this study with a clear value but it really needs further polishing to be widely used within the neuroscience community. At present the installation process is by itself an obstacle for any user with only moderate familiarity with Python-based environment. So this would need to be considerably enhanced to consider a new examination of this tool. In addition a more thorough description of its specific value versus other tools already available including for rats is warranted to understand the added value that TRACER brings.
Reviewer #1 (Recommendations for the authors):
General comments:
It seems like a lot of work to go through all sections and match to the digital atlas. Incorporating matching between pre-processed images and reference sections seems crucial for widespread use of the tool. If this is something that cannot be done in short order, a widespread use of the tool may be limited.
More extensive comments should be made about Brainrender, which was published in eLife in March 2021. This tool is only mentioned and no extensive comparison with TRACER is made.
Software issues:
In evaluating the package (on a machine with Linux Mint 20 Cinnamon, version 4.6.7. Linux Kernel, 5.4.0-89-generic), there were issues with getting the atlas to load. It was an issue with an xcf library, so perhaps this is very specific to this setup, but perhaps is worth noting that some Linux users may have a similar issue.
More generally, there were issues with getting the latest atlas (v4) to work. An error was received that the process was "Killed" and then a message stating that the atlas v3 couldn't be found. Downloading atlas v3 resolved the issue.
It would be useful to know if this software allow for localization of microelectrode arrays? The paper states that TRACER can place trajectory of 6 probes for prediction or reconstruction, so does this mean it can only be used for single point trajectories (such as those from single shank electrodes, fiber optic cannula, or a drug infusion cannula)? A statement should be included about the utility of TRACER for array probes. (If it is not capable of mapping arrays, perhaps this is a modification to consider for the future).
The text in Figure 5 as a bit small and maybe the axis labels could also be shortened and bounding boxes removed.
Potential issue with tissue processing:
How was shrinkage dealt with in processing the brain tissue? Was any estimate done? This might matter for the specific experiment reported in the manuscript, which involved staining with several antibodies. This could also be a major issue for users, especially in cases where histochemical or immunohistochemical stains might be combined in a study.
Reviewer #2 (Recommendations for the authors):
Strengths
– The tool and user manual both appear excellent. The authors have put a lot of effort into making this tool.
– Prior tools were focused on mice, while this one is optimized for rat histology.
– The "surgery planning" aspects were interesting and very useful, particularly for deciding how many recording sites would end up in various brain regions with different insertion angles, etc.
Weaknesses
– There were files from the Waxholm Space rat brain atlas that needed to be downloaded. I clicked on the provided link but it wasn't clear how to find the relevant files, they appear to come from multiple different releases. Unless it violates licensing, can these be automatically included in TRACER? Extra steps like this can confuse and trip up new users (like me!), and potentially create obsolete instructions if the external links change their organization or content.
– The authors correctly note that installing and running TRACER requires some knowledge of Python and the command line. I see this as the biggest weakness of the package. They say they are working on a stand-alone GUI to run it, but in the meantime I suggest they develop instructional videos to talk a new user through a standard installation and example case.
– Both myself and a grad student in our lab tried to install the tool but ultimately failed to do so. We are moderately experienced with Python and we worked through some errors and felt like we were getting closer, but after ~3 hours we finally gave up. While I'm sure the fault is on our end to some degree, we were motivated to test the tool out and we are experienced in Python but we could not get it installed on our system. I suggest the author's β test the tool with novice users with no instruction other than what is on the Github, and see if they can discover any pain points in the installation process. I believe this is addressable, but is a critical weakness of the tool as it currently stands.
Suggestions for improving the user experience
– Strongly encourage the authors to upload the package to Pypi or conda package repository. This will make the installation of the dependencies and the package itself much easier.
– At the bare minimum, instructions should be expanded and clarified starting from the creation of the environment. If the terminal will be used anyway for installing the dependencies, it is much easier to create the environment using the Anaconda prompt from scratch.
– Downloading packages from Github can be confusing for people who are not experienced with this. Where the instructions say they need "TRACER package downloaded on your local computer…" I think the user manual should explicitly walk them through each step – What does a user do when they're looking at the Github page? Click download as Zip? Does it matter where this is saved? Should this be unzipped? Getting tripped up on these early steps can be deal breakers for new users.
– In the user manual, some screenshots would be helpful to orient the user, instead of things like "open the terminal by clicking the arrow near the name of your environment".
– After downloading the zip file from Github and extracting the package, the name of the folder is TRACER_main (or TRACER_master) and not just TRACER. So when trying to run it on Spyder (or wherever), it doesn't find the module.
– To run the package, the working directory has to be inside the first TRACER_main folder, since there is another TRACER_main folder inside the first. This tripped us up for a while.
Reviewer #3 (Recommendations for the authors):
The authors propose here a new open-source, python-based toolkit to reconstruct the trajectories of recording electrodes in the rat brain. Other possible applications include to visualize virus spread or to provide candidates stereotaxic coordinates before starting a surgery. At first glance, the tool is promising and may effectively fill a gap as many existing tools have been designed for mice primarily although rats continue to be highly relevant for behavioral studies. Installing and using the tool is not trivial for users with no Python experience though and the added value by comparison with other tools recently developed is unclear as detailed below.
Installing/running TRACER
The authors acknowledge in the short discussion that using TRACER may be challenging for users with no experience in Python-based environments. I can concur with that comment. I have asked a few trainees in the lab (with no coding experience) to try to install it and none of them was able to go through the entire process alone. So I think getting a GUI as stand-alone is really needed to impact on the field. Otherwise it is hard to appreciate why this could be more useful than any other tools. I would really encourage the authors to develop this GUI early on rather than only suggesting it's a possible future direction.
Added value versus other existing tools
Earlier this year, another paper was published at eLife documenting Brainrender, which is potentially suitable across species, including rats (Claudi et al., 2021). There are multiple other resources that are also available. I think a greater effort to explain how the present tool is positioned by respect with these other options is needed. This is very important for the field; while we can appreciate the value of having diverse tools to rely on, there is also some merit in adopting standards and splitting the community around multiple tools may not be beneficial in the long run. I think a much more thorough discussion is needed to present the PROs and CONs of TRACER versus Brainrender and other tools.
To address my general comments, I think the authors should really answer the following question: Considering that Brainrender is available in multiple species, what is the added value of TRACER?
I do not intend at all to minimize the work produced by the authors, I just want to make my point clearer from the end-user viewpoint: as many potentially equivalent tools exist, why choosing a specific one over the others?
[Editors’ note: further revisions were suggested prior to acceptance, as described below.]
Thank you for resubmitting your work entitled "HERBS: Histological E-data Registration in rodent Brain Spaces" for further consideration by eLife. Your revised article has been evaluated by Laura Colgin (Senior Editor) and a Reviewing Editor.
The manuscript has been improved but there are some remaining issues that need to be addressed, as outlined below:
All reviewers recognized the value of HERB to process brain histology data and think it could be particularly useful for people working with rats, for which very little tools are currently available. The reviewers also identified a number of points that, if adequately addressed, may considerably improve the impact of HERB for the field. The authors are encouraged to implement these points or at least to provide a thorough discussion on their will and ability to carry further developments of the software in the future.
1) There is a need for clearer plans for long term sustainability of the software following future releases of Python. The authors should indicate with more details if they have the manpower necessary to ensure the maintenance of all packages in the long run, and possibly to implement further features (see other points below)
2) Being able to incorporate other brain atlases and other packages (e.g. CellFinder) would enhance its value and the potential for HERB to be widely adopted.
3) Viral reconstruction could benefit from a more quantitative assessment: since the user is provided with a list of brain structures affected by the viral spread, it would be incredibly helpful to provide the volume estimates (or %) affected for each of these brain regions.
4) Automatic registration of sections is not available, and therefore requires extensive manual work to use the software. Perhaps the authors have plans to improve on this front.
Reviewer #2 (Recommendations for the authors):
We gave HERBS some testing in the team and we found that it could really be very helpful for many researchers.
One potential caveat will be to ensure that maintenance of the main packages is being covered as new versions of Python are being developed. Recommending older Python versions for HERB may not be a realistic option in the long run as this is currently suggested in the Cooking book (which currently do not point on the right page for Python 3.9.9 – p.10, section 3.4.2).
We do have a major suggestion for viral spread reconstruction as we think this particular option may be particularly useful. Since the user is provided with a list of brain structures affected by the viral spread, it would be incredibly helpful to provide the volume estimates (or %) affected for each of these brain regions. This would thus open the way for relatively unbiased quantitative analyses (specificity of viral spread, but also lesions, or any infusion). This is much needed in the field to encourage researchers to better report histology data and I strongly believe it will really make HERB reaching another level.
Reviewer #3 (Recommendations for the authors):
It would be useful to specify whether this toolkit covers the following features, and if so, how?
– Designing multi-area implants: does the first section (generating surgical coordinates) include the possibility to design multi-probe implants that could target different brain areas? this can be a great value to those who'd like prototype headstages for targeting multiple areas.
– Adaptable to other atlases: is it possible to upload brain atlas for similar animals (e.g. naked mole rats or tree shrews)? How about other available rat brain atlases?
– Integrating other available packages: it would be great if one could easily integrate e.g. CellFinder with HERBS.
https://doi.org/10.7554/eLife.83496.sa1Author response
[Editors’ note: the authors resubmitted a revised version of the paper for consideration. What follows is the authors’ response to the first round of review.]
Reviewer #1 (Recommendations for the authors):
General comments:
It seems like a lot of work to go through all sections and match to the digital atlas. Incorporating matching between pre-processed images and reference sections seems crucial for widespread use of the tool. If this is something that cannot be done in short order, a widespread use of the tool may be limited.
We agree that automatic template matching would be an extremely convenient functionality to include. We explored this possibility but found that it will require substantial development of machine vision algorithms to automatically match input images to a template. It is a difficult computer vision problem for several reasons, including (i) that histological input images can be stained in various ways which differ qualitatively from atlas images; (ii) the input and atlas images can be of different resolutions; (iii) input images can be slightly out of plane relative to the atlas. After extensive use of the tool, we find that users are likely the best judges of a match between input tissue and the atlas template. Automatic registration is a longer-term goal but one which we are not able to include in this version of the software.
More extensive comments should be made about Brainrender, which was published in eLife in March 2021. This tool is only mentioned and no extensive comparison with TRACER is made.
The new manuscript now describes Brainrender more fully in the Introduction (3rd paragraph) and in the Discussion (3rd paragraph), where we describe the main features which distinguish HERBS from Brainrender. This is part of a larger section in the Discussion, “Novelty and utility of HERBS in relation to other tool kits”, in which we discuss HERBS in relation to the other anatomical software released in recent years. As noted above, the primary difference between HERBS and Brainrender is that HERBS provides the core function of registering histological images back to a reference atlas, which gives reconstructions anatomical coordinates, in millimetres, relative to Bregma and the brain surface. Brainrender provides beautiful visualizations, but it cannot be used to register anatomical data, which is done in a separate step with separate software and plugins. This brings up another major difference, HERBS was designed to be self-sufficient—the GUI can be used to download and load its own source atlases, as well as register and visualize anatomical data without additional software programs.
Software issues:
In evaluating the package (on a machine with Linux Mint 20 Cinnamon, version 4.6.7. Linux Kernel, 5.4.0-89-generic), there were issues with getting the atlas to load. It was an issue with an xcf library, so perhaps this is very specific to this setup, but perhaps is worth noting that some Linux users may have a similar issue.
We thank the Reviewer for pointing out this difficulty in Linux. We have refined the packaging of the Atlas and have been able to load it on Linux systems (Kubuntu and Ubuntu 18.04) subsequently. We hope this resolves the issue.
More generally, there were issues with getting the latest atlas (v4) to work. An error was received that the process was "Killed" and then a message stating that the atlas v3 couldn't be found. Downloading atlas v3 resolved the issue.
We have revamped the atlas downloading procedure by having a copy of the Waxholm Space Atlas (v4) ready for download from the GitHub repository. Both it and the Allen Mouse Brain Atlas can be downloaded in a click-button process when HERBS is installed. Details on how to do this are provided in the user manual (“HERBS Cookbook” Chapter 6.1) and the “ReadMe” tab on the GitHub page (https://github.com/Whitlock-Group/HERBS/tree/main/Tutorial).
It would be useful to know if this software allow for localization of microelectrode arrays? The paper states that TRACER can place trajectory of 6 probes for prediction or reconstruction, so does this mean it can only be used for single point trajectories (such as those from single shank electrodes, fiber optic cannula, or a drug infusion cannula)? A statement should be included about the utility of TRACER for array probes. (If it is not capable of mapping arrays, perhaps this is a modification to consider for the future).
We are glad to report that HERBS, unlike TRACER, has no upper limit on the number of probes / trajectories it can reconstruct, so it is compatible with multi-electrode arrays and multi-tetrode drives. Each trajectory (electrode) still needs to be defined individually by clicking the start- and endpoints, but again there is no upper bound on how many times this can be done. We note this feature of HERBS in the Introduction (top paragraph on Page 2), and in the Results sections, “Generating pre-surgical coordinates” (page 4, paragraph 2), and “Reconstructing electrode tracks” (page 6, paragraph 1).
The text in Figure 5 as a bit small and maybe the axis labels could also be shortened and bounding boxes removed.
Figure 5 from the original draft has been removed from the current version of the paper.
Potential issue with tissue processing:
How was shrinkage dealt with in processing the brain tissue? Was any estimate done? This might matter for the specific experiment reported in the manuscript, which involved staining with several antibodies. This could also be a major issue for users, especially in cases where histochemical or immunohistochemical stains might be combined in a study.
This is an excellent question since tissue shrinkage is an inherent constraint when using any kind of tissue fixation, and it may be further compounded during immuno/histochemical staining protocols. While there is no way to regularize or remove shrinkage artifacts completely, our solution to deformation artifacts in HERBS is to include a “matching” step in which histological images are fit onto the reference atlas template. Specifically, HERBS uses triangulation-based piecewise affine transformation to locally warp the histological image to fit the template, based on key point the user defines with mouse-clicks. The warping and template matching methods are noted in the Introduction (2nd paragraph on page 2) and in Results section, “Reconstructing electrode tracks” (2nd paragraph on page 6). The stepwise process for matching is laid out in detail and with illustrations in the HERBS CookBook (Chapter 6.5).
Reviewer #2 (Recommendations for the authors):
Strengths
– The tool and user manual both appear excellent. The authors have put a lot of effort into making this tool.
– Prior tools were focused on mice, while this one is optimized for rat histology.
– The "surgery planning" aspects were interesting and very useful, particularly for deciding how many recording sites would end up in various brain regions with different insertion angles, etc.
We thank the Reviewer for their praise and are happy that the amount of effort that went into TRACER was apparent when it was reviewed. We are also glad to share that the new HERBS software now works for both rats and mice, and we note that the surgery planning functionalities are included in the present tool kit as well.
Weaknesses
– There were files from the Waxholm Space rat brain atlas that needed to be downloaded. I clicked on the provided link but it wasn't clear how to find the relevant files, they appear to come from multiple different releases. Unless it violates licensing, can these be automatically included in TRACER? Extra steps like this can confuse and trip up new users (like me!), and potentially create obsolete instructions if the external links change their organization or content.
We are sorry for the previous difficulty in locating and downloading the relevant files for the Waxholm Space rat brain atlas. We have revamped the atlas downloading procedure by including file links in HERBS so that either the Waxholm Space Rat Brain Atlas (v4) or the Allen Mouse Brain Atlas (Wang et al., Cell, 2020) can be downloaded in a click-button process after HERBS is installed. Details on how to do this are provided in the user manual (“HERBS Cookbook”, chapter 6.1) and the “Tutorial” tab on the GitHub page (https://github.com/Whitlock-Group/HERBS/tree/main/Tutorial).
– The authors correctly note that installing and running TRACER requires some knowledge of Python and the command line. I see this as the biggest weakness of the package. They say they are working on a stand-alone GUI to run it, but in the meantime I suggest they develop instructional videos to talk a new user through a standard installation and example case.
We have radically simplified the process of installing HERBS, in that it requires a single command (“pip install herbs”) in a Python terminal. However, this assumes the user is already running a current version of Python, and installation of Python can be challenging for someone who has never done so. To make the process easier, we include links to download the appropriate versions of Python (3.8.10 or 3.9.9) in Chapter 3 of the HERBS Cookbook, and in Chapter 4 we give instructions for installing HERBS from PyPI or GitHub. As for running HERBS, all functionalities are performed with mouse clicks and keystrokes and do not require extensive programming knowledge.
– Both myself and a grad student in our lab tried to install the tool but ultimately failed to do so. We are moderately experienced with Python and we worked through some errors and felt like we were getting closer, but after ~3 hours we finally gave up. While I'm sure the fault is on our end to some degree, we were motivated to test the tool out and we are experienced in Python but we could not get it installed on our system. I suggest the author's β test the tool with novice users with no instruction other than what is on the Github, and see if they can discover any pain points in the installation process. I believe this is addressable, but is a critical weakness of the tool as it currently stands.
We again apologize for the difficulty in installing and running TRACER and are very sorry for costing the Reviewer’s and trainee’s time. To avoid this happening with HERBS, we have had multiple β testers vet the downloading and installation process on their own per the written instructions provided in the Cookbook.
Suggestions for improving the user experience
– Strongly encourage the authors to upload the package to Pypi or conda package repository. This will make the installation of the dependencies and the package itself much easier.
This is an excellent suggestion, and we are happy to share that HERBS has been uploaded to PyPI: https://pypi.org/project/herbs/
– At the bare minimum, instructions should be expanded and clarified starting from the creation of the environment. If the terminal will be used anyway for installing the dependencies, it is much easier to create the environment using the Anaconda prompt from scratch.
We understand and apologize for the prior lack of clear instructions. We sought to address this issue with additional installation instructions in the HERBS Cookbook, Chapter 4. All useful links for the installation of anaconda and Conda environments have been included in this section. We believe we have solved the installation of dependencies in making HERBS a PyPI package.
– Downloading packages from Github can be confusing for people who are not experienced with this. Where the instructions say they need "TRACER package downloaded on your local computer…" I think the user manual should explicitly walk them through each step – What does a user do when they're looking at the Github page? Click download as Zip? Does it matter where this is saved? Should this be unzipped? Getting tripped up on these early steps can be deal breakers for new users.
We thank the reviewer for pointing out these pitfalls for new users. We have radically simplified the process of installing HERBS by uploading it to PyPI, and by including instructions on downloading HERBS from GitHub, both on the ReadMe page and in the HERBS cookbook. Specifically, Chapter 3 of the Cookbook includes links to download the appropriate versions of Python (3.8.10 or 3.9.9), and Chapter 4 includes basic installation instructions for HERBS (which are single commands) from PyPI and GitHub.
– In the user manual, some screenshots would be helpful to orient the user, instead of things like "open the terminal by clicking the arrow near the name of your environment".
We thank the Reviewer for this helpful suggestion and again apologize for the difficulties with the user manual for TRACER. Accordingly, the HERBS Cookbook contains numerous screenshots and directions for every step of the core functionalities of the software (the “HERBS recipes” in Chapter 6). We sincerely hope for a better user experience with the HERBS Cookbook.
– After downloading the zip file from Github and extracting the package, the name of the folder is TRACER_main (or TRACER_master) and not just TRACER. So when trying to run it on Spyder (or wherever), it doesn't find the module.
We are very sorry for the difficulties faced for the installation of the TRACER software.
We have sought to solve installation-related technical issues by making HERBS a PyPI package which can be installed in the terminal or a Python IDE with a simple line. Chapter 4 of the CookBook includes these instructions on the installation process.
– To run the package, the working directory has to be inside the first TRACER_main folder, since there is another TRACER_main folder inside the first. This tripped us up for a while.
The new installation process for HERBS solves this issue as well.
Reviewer #3 (Recommendations for the authors):
The authors propose here a new open-source, python-based toolkit to reconstruct the trajectories of recording electrodes in the rat brain. Other possible applications include to visualize virus spread or to provide candidates stereotaxic coordinates before starting a surgery. At first glance, the tool is promising and may effectively fill a gap as many existing tools have been designed for mice primarily although rats continue to be highly relevant for behavioral studies. Installing and using the tool is not trivial for users with no Python experience though and the added value by comparison with other tools recently developed is unclear as detailed below.
We thank the Reviewer for taking the time to evaluate and give feedback on the previous submission and TRACER tool kit. Based on the difficulties reported in downloading and operating TRACER in Python, we have re-vamped the tool to work as a click-button GUI, and only one command line in Python is required for the initial installation. Beyond that, the functionalities of HERBS are driven with a mouse and keyboard following detailed instructions, with illustrations, in the Cookbook. We also discuss in more detail how HERBS compares against and differs from other software released in recent years, and have included a new Supplementary Table comparing functionalities of the different tool kits.
Installing/running TRACER
The authors acknowledge in the short discussion that using TRACER may be challenging for users with no experience in Python-based environments. I can concur with that comment. I have asked a few trainees in the lab (with no coding experience) to try to install it and none of them was able to go through the entire process alone. So I think getting a GUI as stand-alone is really needed to impact on the field. Otherwise it is hard to appreciate why this could be more useful than any other tools. I would really encourage the authors to develop this GUI early on rather than only suggesting it's a possible future direction.
We apologize for difficulties the Reviewer and their trainees encountered in downloading and using TRACER previously, and we thank them for their time and effort. These and similar sentiments from the other Reviewers prompted us to produce the new HERBS GUI in the current paper, which we hope is far simpler to sue. We could not remove usage of Python from the process completely, but once the tool is installed and running it requires no further programming or command windows. We hope the tool in its current form gives a better experience and will reach a wider user base.
Added value versus other existing tools
Earlier this year, another paper was published at eLife documenting Brainrender, which is potentially suitable across species, including rats (Claudi et al., 2021). There are multiple other resources that are also available. I think a greater effort to explain how the present tool is positioned by respect with these other options is needed. This is very important for the field; while we can appreciate the value of having diverse tools to rely on, there is also some merit in adopting standards and splitting the community around multiple tools may not be beneficial in the long run. I think a much more thorough discussion is needed to present the PROs and CONs of TRACER versus Brainrender and other tools.
We fully agree that it is important for the paper to clearly state what functionalities HERBS and other software offers, and what differentiates HERBS from the tools already out there. This can be found in a new section in the Discussion entitled “Novelty and utility of HERBS in relation to other tool kits”. As noted at the beginning of the Rebuttal, we feel the key distinguishing points are (i) the diversity of functionalities it offers (pre- and post-surgical), (ii) the simplistic, click-button interface of the GUI, and (iii) that the relevant mouse or rat reference atlases can be downloaded from a drop-down menu in the GUI—so it does not require other software. Moreover, it works with nearly any type of slice histology or staining method. These and other details are listed in the new Supplementary Table in the revised manuscript. We hope the HERBS GUI will be of service to those with little to no coding experience.
To address my general comments, I think the authors should really answer the following question: Considering that Brainrender is available in multiple species, what is the added value of TRACER?
We can absolutely appreciate this question, not only with respect to Brainrender, but other tools released in the last year. As noted above in the Rebuttal, Brainrender is an outstanding visualization resource, but it cannot on its own perform anatomical registration to a reference atlas. This must be done with separate software and plugins, which requires knowledge of programming that a proportion of would-be users may lack. HERBS, on the other hand, was conceived as a registration software that comes with its primary reference atlases in tow, so it fulfills a complementary role to Brainrender’s visualization functions. We also included some 2D and 3D visualization functions in HERBS to reduce the need for added software and steps, but we do not include animations like Brainrender.
I do not intend at all to minimize the work produced by the authors, I just want to make my point clearer from the end-user viewpoint: as many potentially equivalent tools exist, why choosing a specific one over the others?
We thank the Reviewer for considering our effort and agree it is important to clarify which tools do what, and how the present tool kit is different. We hope the revised manuscript does this more effectively than before. After the original TRACER manuscript was reviewed and rejected, we took the Reviewer's input seriously and sought to generate a radically simpler tool that minimizes user effort. Our main objective with HERBS was to make a tool that we would want to use in our own lab to expedite the time-consuming process of anatomical registration, especially across subjects.
[Editors’ note: what follows is the authors’ response to the second round of review.]
The manuscript has been improved but there are some remaining issues that need to be addressed, as outlined below:
All reviewers recognized the value of HERB to process brain histology data and think it could be particularly useful for people working with rats, for which very little tools are currently available. The reviewers also identified a number of points that, if adequately addressed, may considerably improve the impact of HERB for the field. The authors are encouraged to implement these points or at least to provide a thorough discussion on their will and ability to carry further developments of the software in the future.
1) There is a need for clearer plans for long term sustainability of the software following future releases of Python. The authors should indicate with more details if they have the manpower necessary to ensure the maintenance of all packages in the long run, and possibly to implement further features (see other points below)
The creator of HERBS, Jingyi Guo Fuglstad, has and will continue to actively respond to technical queries posted on the HERBS GitHub page. The co-first author, Pearl Saldanha, will regularly check for updates on dependencies and new versions of Python. HERBS and the CookBook will be duly updated after major updates in Python are released.
So far, in response to GitHub requests and discussions, several new features have already been implemented, including compatibility with different kinds of linear silicon probes (the geometry and site layout of which the user can define), unmerging of object layers, as well as other functions described below.
2) Being able to incorporate other brain atlases and other packages (e.g. CellFinder) would enhance its value and the potential for HERB to be widely adopted.
We agree that compatibility with other brain atlases would enhance the utility of HERBS for a broader user base. As detailed below in response to Reviewer 3, HERBS is now compatible with any brain atlas, so long as the user can provide the appropriate volume files, segmentation files, and label information. HERBS can also use Mask files if they are included with a given atlas (e.g. the Waxholm Space Atlas). Illustrated instructions on how to upload and process other atlases can be found on the HERBS GitHub Tutorial sub-paged (https://github.com/Whitlock-Group/HERBS/blob/main/Tutorial/upload_and_process_user_defined_atlases.md). This link is noted and included in subsection 6.1.3 of the HERBS CookBook, and the added functionality is stated in the Abstract and on lines 79-82 of the General Outline section in the Results.
As further requested, we made it possible to load cell point data generated from CellFinder, and to visualize those data in 3D brain volumes according to whichever atlas the user has installed. Instructions on how to do this can be found on the HERBS GitHub sub-page (https://github.com/Whitlock-Group/HERBS/blob/main/Tutorial/External_Related/upload_external_cell_points.md), and can be found in the 6.8.3 sub-section of the CookBook. This is also noted in the manuscript on lines 161-165 of the “Reconstruction of viral expression” sub-section in the Results.
3) Viral reconstruction could benefit from a more quantitative assessment: since the user is provided with a list of brain structures affected by the viral spread, it would be incredibly helpful to provide the volume estimates (or %) affected for each of these brain regions.
We agree this would be highly beneficial for users wishing to have an unbiased estimate of viral spread in affected brain areas. Accordingly, we have updated the viral reconstruction functionality to include the volume (in voxels) of virus expressed in each brain region, as well as the estimated proportion of that brain region expressing the virus. We note that this applies the same for any kind of tissue labeling or lesions in a region of interest.
The newest version of HERBS generates these estimates automatically for viral expression analyses, and an example of the updated output is shown in the revised Figure 4D in the manuscript (new columns in the readout are for “Volume (stk voxel)” and “Proportion (%)” of each area containing viral expression or labeling).
4) Automatic registration of sections is not available, and therefore requires extensive manual work to use the software. Perhaps the authors have plans to improve on this front.
We acknowledge that it would great to add automated registration and that it would expedite the workflow in HERBS. However, adding automatic slice registration is a very large request, since doing so properly would require the development of sufficiently robust machine vision algorithms that can handle variable histological input. We respectfully suggest that developing such algorithms falls outside the scope of the current version of HERBS, which we feel nevertheless brings considerable added value to users wishing register histological slices in rodents or other species. Automated registration is part of our long-term strategy for HERBS, and this is noted in lines 218-220 of the revised manuscript.
Reviewer #2 (Recommendations for the authors):
We gave HERBS some testing in the team and we found that it could really be very helpful for many researchers.
One potential caveat will be to ensure that maintenance of the main packages is being covered as new versions of Python are being developed. Recommending older Python versions for HERB may not be a realistic option in the long run as this is currently suggested in the Cooking book (which currently do not point on the right page for Python 3.9.9 – p.10, section 3.4.2).
Please see our response to this same query in Point (1).
We do have a major suggestion for viral spread reconstruction as we think this particular option may be particularly useful. Since the user is provided with a list of brain structures affected by the viral spread, it would be incredibly helpful to provide the volume estimates (or %) affected for each of these brain regions. This would thus open the way for relatively unbiased quantitative analyses (specificity of viral spread, but also lesions, or any infusion). This is much needed in the field to encourage researchers to better report histology data and I strongly believe it will really make HERB reaching another level.
Please see our response to this same query in Point (3).
Reviewer #3 (Recommendations for the authors):
It would be useful to specify whether this toolkit covers the following features, and if so, how?
– Designing multi-area implants: does the first section (generating surgical coordinates) include the possibility to design multi-probe implants that could target different brain areas? this can be a great value to those who'd like prototype headstages for targeting multiple areas.
We have added this feature in the newest version of HERBS—to accommodate users wishing to target multiple brain areas with a custom-developed multi-probe implant. The user can specify the geometry of the probe following the steps in the illustrated tutorial provided on the GitHub sub-page ( https://github.com/Whitlock-Group/HERBS/blob/main/Tutorial/Probe_Related/5-Design_multi_shanks_Probes.md.)
In addition, the user can define the geometry and site layout on individual probes following a separate illustrated tutorial on the GitHub sub-page linked here. This functionality is noted in the manuscript on lines 113-116, and all probe-related instructions and links to tutorials can be found in the section 6.6 of the CookBook.
– Adaptable to other atlases: is it possible to upload brain atlas for similar animals (e.g. naked mole rats or tree shrews)? How about other available rat brain atlases?
We have added a new feature by which users can upload and use any volume atlas—as long the volume atlas data file (i.e. scanned or imaged brain volume data, such as MRI scans) and the attendant segmentation and label files are provided. Some atlases also include mask files (e.g. the Waxholm Space Atlas), which HERBS can also use.
This functionality is noted in the revised Abstract, and illustrated instructions on how upload and process other atlases can be found on the HERBS GitHub sub-paged linked here. The update and relevant tutorials are noted in subsection 6.1.3 in the Herbs CookBook.
– Integrating other available packages: it would be great if one could easily integrate e.g. CellFinder with HERBS.
We have now made it possible to load cell point data generated from CellFinder, and to visualize those data in 3D brain volumes according to whichever atlas the user has installed. Instructions on how to do this can be found on the HERBS GitHub sub-paged linked here. The link to this tutorial is available in sub-section 6.8.3 of the CookBook, and the added CellFinder functionality is noted in lines 161-165 of the “Reconstruction of viral expression” sub-section of the Results.
https://doi.org/10.7554/eLife.83496.sa2Article and author information
Author details
Jonathan R Whitlock
Funding
Norges Forskningsråd (300709)
- Jonathan R Whitlock
Norges Forskningsråd (223262)
- Jonathan R Whitlock
Norges Forskningsråd (197467)
- Jonathan R Whitlock
Kavli Foundation
- Jonathan R Whitlock
The funders had no role in study design, data collection and interpretation, or the decision to submit the work for publication.
Acknowledgements
The authors thank T B Leergaard, I E Bjerke, and H Kleven for graciously sharing and assisting with the Waxholm Space atlas version 4; T Tombaz, B Mimica, E H Holmberg, and I Rautio for sample tissue; M Andresen and GM Olsen for technical assistance; E H Holmberg, B Kanter, T Tomaz, I Rautio and A Vollan, J Rudolf, D Hayden for beta testing HERBS and/or TRACER functionalities; M P Witter, GM Olsen, and members of the Whitlock lab for helpful discussion; B Mimica and T Tombaz for motivating the need for such a tool kit. This work was supported by a Research Council of Norway FRIPRO Grant (no. 300709) to JRW, the Centre of Excellence Scheme of the Research Council of Norway (Centre for Neural Computation, Grant no. 223262), the National Infrastructure Scheme of the Research Council of Norway – NORBRAIN (Grant no. 197467), and The Kavli Foundation. The MRI core facility is funded by the Faculty of Medicine at NTNU and Central Norway Regional Health Authority.
Ethics
All experiments were performed in accordance with the Norwegian Animal Welfare Act and the European Convention for the Protection of Vertebrate Animals used for Experimental and Other Scientific Purposes. All procedures were approved by the Norwegian Food Safety Authority (Mattilsynet; protocol IDs 27175 and 25094). All tissue for in-house testing came from adult (>15wk) Long-Evans hooded rats. Detailed steps of the surgical preparation and post-operative care are described in Mimica et al. 2018 (doi:10.1126/science.aau2013).
Senior Editor
- Laura L Colgin, University of Texas at Austin, United States
Reviewing Editor
- Mathieu Wolff, CNRS, University of Bordeaux, France
Reviewer
- Mathieu Wolff, CNRS, University of Bordeaux, France
Version history
- Preprint posted: October 3, 2021 (view preprint)
- Received: September 16, 2022
- Accepted: January 12, 2023
- Accepted Manuscript published: January 13, 2023 (version 1)
- Version of Record published: February 7, 2023 (version 2)
Copyright
© 2023, Fuglstad, Saldanha et al.
This article is distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use and redistribution provided that the original author and source are credited.
Metrics
-
- 1,663
- Page views
-
- 161
- Downloads
-
- 3
- Citations
Article citation count generated by polling the highest count across the following sources: PubMed Central, Crossref, Scopus.
Download links
A two-part list of links to download the article, or parts of the article, in various formats.
Downloads (link to download the article as PDF)
Open citations (links to open the citations from this article in various online reference manager services)
Cite this article (links to download the citations from this article in formats compatible with various reference manager tools)
Histological E-data Registration in rodent Brain Spaces
eLife 12:e83496.
https://doi.org/10.7554/eLife.83496
Further reading
-
- Neuroscience
Several discrete groups of feeding-regulated neurons in the nucleus of the solitary tract (nucleus tractus solitarius; NTS) suppress food intake, including avoidance-promoting neurons that express Cck (NTSCck cells) and distinct Lepr- and Calcr-expressing neurons (NTSLepr and NTSCalcr cells, respectively) that suppress food intake without promoting avoidance. To test potential synergies among these cell groups we manipulated multiple NTS cell populations simultaneously. We found that activating multiple sets of NTS neurons (e.g., NTSLepr plus NTSCalcr (NTSLC), or NTSLC plus NTSCck (NTSLCK)) suppressed feeding more robustly than activating single populations. While activating groups of cells that include NTSCck neurons promoted conditioned taste avoidance (CTA), NTSLC activation produced no CTA despite abrogating feeding. Thus, the ability to promote CTA formation represents a dominant effect but activating multiple non-aversive populations augments the suppression of food intake without provoking avoidance. Furthermore, silencing multiple NTS neuron groups augmented food intake and body weight to a greater extent than silencing single populations, consistent with the notion that each of these NTS neuron populations plays crucial and cumulative roles in the control of energy balance. We found that silencing NTSLCK neurons failed to blunt the weight-loss response to vertical sleeve gastrectomy (VSG) and that feeding activated many non-NTSLCK neurons, however, suggesting that as-yet undefined NTS cell types must make additional contributions to the restraint of feeding.
-
- Genetics and Genomics
- Neuroscience
In the fruit fly Drosophila melanogaster, gustatory sensory neurons express taste receptors that are tuned to distinct groups of chemicals, thereby activating neural ensembles that elicit either feeding or avoidance behavior. Members of a family of ligand -gated receptor channels, the Gustatory receptors (Grs), play a central role in these behaviors. In general, closely related, evolutionarily conserved Gr proteins are co-expressed in the same type of taste neurons, tuned to chemically related compounds, and therefore triggering the same behavioral response. Here, we report that members of the Gr28 subfamily are expressed in largely non-overlapping sets of taste neurons in Drosophila larvae, detect chemicals of different valence, and trigger opposing feeding behaviors. We determined the intrinsic properties of Gr28 neurons by expressing the mammalian Vanilloid Receptor 1 (VR1), which is activated by capsaicin, a chemical to which wild-type Drosophila larvae do not respond. When VR1 is expressed in Gr28a neurons, larvae become attracted to capsaicin, consistent with reports showing that Gr28a itself encodes a receptor for nutritious RNA. In contrast, expression of VR1 in two pairs of Gr28b.c neurons triggers avoidance to capsaicin. Moreover, neuronal inactivation experiments show that the Gr28b.c neurons are necessary for avoidance of several bitter compounds. Lastly, behavioral experiments of Gr28 deficient larvae and live Ca2+ imaging studies of Gr28b.c neurons revealed that denatonium benzoate, a synthetic bitter compound that shares structural similarities with natural bitter chemicals, is a ligand for a receptor complex containing a Gr28b.c or Gr28b.a subunit. Thus, the Gr28 proteins, which have been evolutionarily conserved over 260 million years in insects, represent the first taste receptor subfamily in which specific members mediate behavior with opposite valence.
