Mar 13, 2025

Public workspaceReconstructing Complete Neurons in Whole Brains Using HortaCloud

DOI
dx.doi.org/10.17504/protocols.io.yxmvm38wnl3p/v1
  • 1HHMI Janelia Research Campus
Tiago A Ferreira
Icon indicating open access to content
QR code linking to this content
DOI: dx.doi.org/10.17504/protocols.io.yxmvm38wnl3p/v1
Protocol Citation: Mary L Lay, Emily Tenshaw, Alyssa K Stark, Monet Weldon, Cameron Arshadi, Ahmad Elsayed, Daniel Ramirez, Bruno Dos Santos, Amina Zafar, Mashtura Hasan, Regina Blake, Jayaram Chandrashekar, Tiago A Ferreira 2025. Reconstructing Complete Neurons in Whole Brains Using HortaCloud. protocols.io https://dx.doi.org/10.17504/protocols.io.yxmvm38wnl3p/v1
License: This is an open access protocol distributed under the terms of the Creative Commons Attribution License,  which permits unrestricted use, distribution, and reproduction in any medium, provided the original author and source are credited
Protocol status: Working
We use this protocol and it's working
Created: February 28, 2024
Last Modified: March 13, 2025
Protocol Integer ID: 95884
Keywords: Neuron, tracing, reconstruction, whole-brain, axon, dendrite, projectome
Funders Acknowledgements:
HHMI
Abstract
Complete and accurate reconstruction of axonal arbors is a challenging task because axons are very thin, with diameters of less than 100 nanometers, and traverse large distances (up to 60 centimeters in the mouse brain). This protocol documents the workflow used by the MouseLight Project Team to reconstruct complete axonal arbors in whole mouse brains. This protocol is centered around HortaCloud, a collaborative, open-source, cloud-based platform for 3D neuron tracing in large (TB-size) image volumes.
Before start

Protocl workflow. The first part describes the software and the preliminary work required to have images ready for tracing. The second part describes tracing of projection neurons in which axons are traced independently by two annotators until a consensus reconstruction is achieved.

Requirements:
  • HortaCloud account (obtain one at hortacloud.org)
  • Fast internet connection
  • Compatible browser (NB: HortaCloud may require certain website permissions (e.g., clipboard access, JavaScript execution) to be enabled. Also, it may be required to disable ad-blockers or third-party browser extensions on HortaCloud URLs)
  • Computer mouse (as opposed to trackpad)

Optional but recommended:
  • Large display
  • Accurate mouse with adjustable DPI settings
  • Basic understanding of digital images
  • Basic understanding of brain anatomy/neuronal morphology
HortaCloud Overview
HortaCloud Overview
This protocol is centered around the HortaCloud software, a collaborative, open-source, cloud-based platform for 3D neuron tracing in large (TB-sized) image volumes. The application is organized into several panes, including the Horta Control Center, Data Explorer and Inspector, and the Color Sliders.


HortaCloud overview, version 9.20.


HortaCloud starting view

When opened for the first time, several components are displayed:

  • Menu bar: The menu bar contains various menus for items such as layout options, keyboard shortcuts, and widgets like camera control, movie maker, and scene editor.
  • Data Explorer: The data explorer shows folders and files that are accessible in HortaCloud.
  • Home: An icon view of the folders and files that are accessible in HortaCloud.
  • Search: The search window allows to filter and search for a file of interest.
  • Background Tasks: The background tasks window shows the status of tasks running in HortaCloud, such as a neurite being exported.
  • Data Inspector: The data inspector shows different attributes of neurites and workspaces. It also displays permissions and annotations for a neurite or workspace.


The Horta Control Center

The Horta Control Center (HCC) is a panel that shows information about the workspace and all annotations within that workspace. To open the HCC, right-click on any sample or workspace in the Data Explorer, and select “Open in Horta.” The HCC has four sections: Workspace, Neurons, Views, and Annotations.

Horta Control Center


  • Workspace: The workspace section displays the workspace name, sample info, and settings for management of image data and the workspace itself.
  • Views: The views section displays the options for viewing the sample
  • Neurons: The neuron table area contains a table that lists the names, ownership, colors, and visibility of each neuron in the workspace. This list can be filtered using the options below the table. Neurons can be created and deleted using the “Add...” and “Remove” buttons.
  • Annotations table: The annotations table shows annotated nodes (---), branch nodes (--<), root nodes (o-- ), and end nodes (--o).

Samples are rendered in the Horta3D viewer and can be viewed by selecting the “3D” checkbox in the Workspace section. Intensity levels of sample images are adjusted using the Color sliders (Window → Horta → Color Sliders). This process is described in Enhancing Image Contrast (section 4).

Further settings can be accessed by exploring the different menus of the program and by accessing Tools → Options, in which it is possible to:

  • Enable/disable shared workspaces
  • List and customize mapping of keyboard shortcuts
  • Edit the overall appearance of the application
Importing a Sample
Importing a Sample
If a dataset is not yet in HortaCloud, it needs to be imported into the application. A detailed guide to importing samples can be found in the HortaCloud manual. To begin, navigate to File → New → Horta Sample. The following options will appear in the dialog prompt:

  • Sample Name: The sample name will appear in the File Explorer.
  • Path to Render Folder: This is the path to the sample data. HortaCloud is currently hosted by Amazon S3, so this path must point to an S3 bucket using Linux-style file paths, e.g. /s3data/path/to/sample or S3 paths: s3://bucket/path/to/sample
  • Path to KTX folder (optional): This is the path to the KTX directory within the sample data. This should also point to an S3 bucket using Linux-style file paths, e.g. /s3data/path/to/sample/ktx.

Adding a new sample

After the sample is created, use the refresh button to refresh the Data Explorer. The new sample will appear in the Data Explorer and can be searched for in the search window.

Permissions

Permissions for team members should be added before any annotations are created. To edit permissions, select the sample in Data Explorer. The sample should now appear in the Data Inspector window. In the Data Inspector > Permissions tab, select Grant permission. If other team members will be working in the same workspace, they will need read and write permissions. Team members may be added individually or as a group.
Data Inspector, Permissions tab

Creating a Workspace
Creating a Workspace
Workspaces store the annotations associated with a sample. Multiple workspaces may be created from a single sample (e.g., one workspace per annotator or per research group), or all annotators may work in the same workspace. A detailed guide for workspace creation can be found in the HortaCloud manual. In short:

  1. Right-click on a sample in the Data Explorer and select “Open in Horta.”
  2. Click the "New workspace..." button in the Horta Control Center.
  3. The sample date and neuron code will together form the name of the workspace. The field "Neuron Code" may be any designation to distinguish this workspace from other workspaces based on the same sample (e.g., a team or project name).


Creating a new workspace
For example, a sample with the following information:

Sample Date: 2021-03-17
Neuron Code: test
User Initials: AB
Suffix (optional): cortex

will form the following workspace name: 2021-03-17_test_AB_cortex
Enhancing Image Contrast
Enhancing Image Contrast
Adjusting the brightness and contrast of neurites is key for optimal tracing. This is performed using the Colors Sliders widget (Window→ Horta → Color Sliders). These sliders allow for:

  1. Linear adjustments of fluorescence levels
  2. Spectral unmixing (discussed below)
  3. Non-linear adjustments of contrast (gamma correction)

The latter is not addressed in this protocol, but is detailed in the HortaCloud manual.

Default color sliders

Detailed refinement possible by using the '#' buttons

If a sample contains two or more channels (i.e., two or more imaged wavelengths), it is possible to unmix overlapping fluorescence between channels. This spectral unmixing technique is useful to enhance the signal to noise ratio (SNr) by mitigating bleed-through between fluorophores, and to remove background auto-fluorescence. Note that the rendering color of a channel is arbitrary. In this protocol, channel 1 is the channel containing GFP-labeled neurons and is displayed in green, while channel 2 (displayed magenta) is a label-free recording of auto-fluorescence. Features common to both channels are expected to be non-specific to the neuronal labeling, and can be subtracted or “unmixed.” The un-mixing result will be displayed on the third channel (here displayed in cyan).

To start, open the Color Sliders widget (Window→ Horta → Color Sliders):

  • Display only channel 1 by hiding channels 2 and 3. Toggle visibility of channels using the open/closed eye buttons on the left side of the widget.
  • For each slider, the left tick mark adjusts the clipping of background fluorescence (displayed minimum); the right one adjusts the clipping of signal fluorescence (displayed maximum).
  • Adjust sliders to suitable levels: the signal outside the brain should be reduced to black without causing the interior of the brain to be black.


Channel 1 (GFP) and Channel 2 (auto-fluorescence) adjusted for color subtraction
Note that the adjustments to Channel 1 and Channel 2 do not have to be identical.

  • Once the first two channels have been adjusted, right-click on the image and select “Tracing Channel” → “Unmix Channel Using Current Brightness.” This will perform the spectral unmixing operation described above, displaying an enhanced rendering with reduced autofluorescence
  • From this point onwards, levels of the ‘unmixing’ channel 3 can be adjusted as any of the original channels. Note that readjustments to original channels are only applied to the unmixing channel after an unmoving option, such as “Unmix Channel 1 Using Current Brightness,” is selected.

Channel 3, following a successful unmixing of Channels 1 and 2

These adjustments can be saved as “color models” and loaded between tracing sessions so that the steps in this section do not need to be repeated. To save a color model, select the gear icon and click "Export Color Model." To load a previously-saved model, select the gear icon and click "Import color Model." (See HortaCloud manual for details.)
Importing and exporting color models

Evaluating the Sample
Evaluating the Sample
Not every cell in a sample can be traced to completion. There are many factors that impact the traceability of a cell, including:

  • Quality of neuronal labeling: Are axonal arbors completely labeled from soma to arbor?
  • Density of neuronal labeling: Are cells aggregated in clusters, or sparsely distributed?
  • Signal-to-Noise Ratio (SNR): Are neurites bright enough?
  • Signal consistency: Is the fluorescent signal contiguous across tile boundaries or interrupted by artifacts? Are there fluctuations in background signal?

While ultimately the quality of neuronal labeling can only be confirmed through tracing, most of these issues can be detected by perusing the sample in 3D. Some examples are provided in the figures below:

a. Dense cluster of cells.
b. Dense cluster of axons.
c. Low SNR
d. Neuron (A) in proximity to auto-fluorescent vasculature (B). In this particular example the vasculature is enhanced by the spectral unmixing routine, either due to erroneous settings, or localized changes in background fluorescence


Examples of stitching artifacts between neighboring 3D tiles (fields of view).
a. Overlap region between adjacent tiles with pronounced doublets and triplets of "ghosted" neurites. These artifacts occur when the stitching algorithm is unable to generate a smooth transition between overlapping volumes.
b. Translation offset between adjacent tiles
c. Gap between adjacent tiles
Locating and Evaluating Somas and Axons
Locating and Evaluating Somas and Axons
To ensure no somas in the sample are overlooked, navigate through the sample in coronal view in 2D:

  • Open the Camera Control pane (Window → Horta → Camera Control).
  • Select a very thin display 'slab’ by clicking on the "|" icon.


Thin slab selection


3D depth: Full-depth of brain (left) and thin slab (right)


Once a soma is identified, create a neuron object to mark the soma: Select the "Add..." button in the Neurons section of the Horta Control Center, and place a node by shift-clicking at the soma’s approximate centroid. (See First Tracing (section 11) for details.) After locating all somas, the camera control settings can be reset by clicking on the ‘||’ icon.


Evaluating Somas

  • The soma of a fully-labeled cell is expected to be bright
  • Neurites branching from the soma should be obvious and bright at deeper zoom levels
  • A soma should be far enough from surrounding neurons that the axon can be distinguished from other axons and dendrites
Evaluating axons

  • The axon should be distinguishable from dendrites
  • The axon should maintain or increase in brightness at least 10 cm away from the soma

The best way to assess if an axonal arbor can be traced to completion is to inspect its primary branches and confirm no obvious impediments to its reconstruction. If the soma and first 10 cm of the axon are bright and traceable, then it is likely that the rest of the axon is traceable.

Axon vs. Dendrites
Axon vs. Dendrites
The axons of a neuron are traced twice to ensure that the most accurate tracing is represented. The dendrites are only traced once because they are much smaller and easier to trace than axons. The tracing of a dendrite can be completed at any time after the first tracing is complete. It is preferable not to trace the dendrite until the axon is traced completely. This ensures time is not "wasted" tracing a dendritic arbor from a cell that may have an incomplete or untraceable axon.

Assuming that axons are labeled with the same fluorophore as dendrites and are not molecularly tagged, axons of most neuronal types in the mouse brain can be identified by morphological criteria:
  • A sensible expectation is that the axon remains the thinnest and longest projection emerging from the soma. When dendrites are polarized, the main axon typically opposes the dendritic arbor. For example, most pyramidal neurons in the isocortex have the axon emerging at the base of the soma, opposite to the apex in which apical dendrite(s) emerge.
  • With stellate cells and other interneurons, identification of the axons can be less immediate. However, it is expected that the main axon will branch out at greater distances than most primary dendrites. Note that in certain cell types axons can originate from dendrites instead of from the soma.
  • In some neuronal populations, axons remain anatomically indistinguishable from dendrites at the anatomical level and display comparable lengths, radii, and ramification patterns. In such cases, axonal identification is only possible through molecular counterstainings. These cells are not covered by this protocol.
  • Studying existing reconstructions in the MouseLight database and other databases can provide insights and inform expectations of arborization patterns for cells of similar properties.
Axonal Tracing Overview
Axonal Tracing Overview
Axonal arbors are reconstructed in 3 steps:

  1. First Tracing
  2. Second Tracing
  3. Consensus

Once these three steps are completed, there will be 7 resulting files for each individual neuron:

  • First Tracing: The axonal tracing completed by the first annotator, also called the first pass.
  • Second Tracing: The axonal tracing completed by the second annotator, also called the second pass.
  • First Unique: Tracings of neurites for each of the unique branches of the first tracing.
  • Second Unique: Tracings of neurites for each of the unique branches of the second tracing.
  • Base: The union between the first and second tracings, everything that the first and second tracings have in common.
  • Consensus: The final tracing of a neuron including the base tracing as well as any branches that are deemed correct from the first and second unique files.
  • Dendrite: A tracing of the neuron's dendrites.
In this protocol, axonal and dendritic arbors are traced separately. Regarding unique tracings, HortaCloud will allow a neuron to have multiple root nodes. The unique tracing files will have one root node per unique branch. Each root node marks a disputed point on the tracing and does not reflect an accurate reconstruction of the neuron. Although other branching patterns exist, this protocol assumes only bifurcating branches.


In this protocol, each neuron file is named as follows:

  • First and Second Tracings: Each contain 3 components: the sample date, neuron name, and annotator initials. Ex: "2021-03-17_G-001_ET"
  • First and Second Unique: Similar pattern as the first and second tracings, but also contains "Uni" at the end of the name. Ex: "2021-03-17_G-001_ET_Uni"
  • Base, Consensus and Dendrite: Similar pattern to the first and second tracings, but annotator initials are replaced with either Base or Consensus. Ex: "2021-03-17_G-001_Consensus"

Having a standardized naming scheme allows for easier tracking of completed tracings and makes it easier for neuron analysis.
First Tracing
First Tracing

To create a new neuron, click the 'Add...' button in the Horta Control Center (HCC):


Adding a new neuron


Naming a new neuron

After giving the neuron a name, it will appear in the "Neurons" list in the HCC. A new neuron will not have any nodes. To place the first node, shift-click (hold down shift and left click) the location in the 3D view where the node should be placed. The first node that is placed is the root node, and should be located at the soma of a neuron. After placing the root node, it will appear in the "Annotations" list as (o--).

Placing first node

After the soma node is placed, use shift-click to place additional nodes along the neurite. As nodes are placed, they are 'snapped' to the signal of the neurite to ensure more accurate tracings.


Adding additional nodes


To create a branch on a neurite, start with the main axon and place a node at the branch point, followed by a node along the branch. After placing the first branched node, return to the branch point by clicking on it in 3D. Place a new node on the main neurite by shift-clicking on the main neurite. There are now two child nodes to the branch point node, one on the branch and one on the main neurite. The annotation list will now show a branched point annotation (--<) where the branch begins, and two new end nodes (--o).



Creating a branch


The main neurite is typically traced first, and branches are traced after. After creating the new branch, return to the main axon and continue tracing. Once the main axon is complete, return to any secondary branches.

Continue tracing until the neuron is traced to entirety. Use 't' as a shortcut to label end points as traced ends. Other notes serving as reminders to review a difficult area may be placed by right-clicking on a node and selecting "Add/Edit Note On Anchor." A pre-written note may be applied by using the appropriate button or hotkey, or a custom note can be typed into the "Enter note test" box. These notes will appear in the "Annotations" pane of the HCC for a selected neuron.

Adding a note


Notes appear in the Annotations pane of the Horta Control Center

Once the neuron is complete, export the neuron: right-click on the neuron in the Neurons list and select "Export SWC file...". Select the location to save the file and hit "Save."


Exporting and saving a neuron

Second Tracing
Second Tracing
It is expected that the first tracing of a neuron will not be completely accurate. A second tracing is performed by a second tracer to ensure the most accuracy possible while taking into consideration the time it takes to trace a neuron.

The protocol for the second tracing is the same procedure as the first tracing; however, the primary tracing may be used as an overlay in order to expedite the tracing process. This process makes use of neuron tags and neuron groups by tagging the first tracing and applying the "Crosscheck" property.

To apply the crosscheck property to the neuron, right click on a node in Horta 3D and select "Edit Neuron Tags." If a second tracing tag is not available, create a new tag by entering the tag name in the text box (e.g.,"second_pass") and then clicking the "New tag" button. If a second tracing tag is available, simply click on it to apply it to the neuron. Once a tag is applied to a neuron in the workspace it will appear in the "Applied" column.


Applying a tag to a neuron


After a neuron tag has been applied, a selection of neuronal properties may be applied to all tagged neurons using the "Edit Neuron Groups" window. To access this window, right click on the neuron and select "Edit Neuron Groups."



Editing Neuron Groups
Select a property from the drop-down menu and select a hot-key to toggle this property on and off.

Properties to Toggle:

  • Radius: Changes the radius of tagged neuron from 1.0μm to .5μm- tagged. The neuron is still interactable.
  • Visibility: Changes the neuron to hidden. The neuron radius does not change.
  • Background: The neuron becomes non-interactable. Neuron does not change size or visibility.
  • Crosscheck: Neuron radius decreases in size to 0.5μm and cannot be interacted with.

For second-tracings, the Crosscheck property is applied to the first tracing, and the second tracing is performed while the first tracing is visible but not interactable. When the second tracing is finished, export and save both the first and second tracings.

Consensus
Consensus
Consensus Overview


Overview of the Consensus Process

The consensus process compares the two separate annotator tracings to create the most accurate complete tracing.

The consensus process can be broken down into 3 steps:

  1. Splitting: The process of cutting unique branches off each tracing.
  2. Evaluating: The process of evaluating every unique branch for each annotator.
  3. Reattaching: The process of connecting the correct branches back to the base neuron.

To begin the consensus process, make sure that the completed first and second tracings are both present in the workspace, and they are set to different colors. Hide all other neurons in the workspace. Then, create two new neurons that will serve as the 'unique' files for each tracing, and name them accordingly ("Neuron_1_Uni_Tracer1" and "Neuron_1_Uni_Tracer2," for example).
Splitting

Zoom out to view the full tracings and look for any differences between the neurons. Find a branch from the first tracing that is not present in the second tracing and split one node into the branch from the vertex.

To split a neuron, select the node where the neuron should be split. Right-click on the selected node and click "Split Neurite at Vertex." The split branch will be cut and made into a new neuron. Right-click on any node of the new neuron and select "Transfer Neurite," then select the appropriate unique file. This will allow the transfer of each cut branch to the associated unique file for each tracing. Repeat the splitting steps for every unique branch in the first and second tracing. It is recommended to split every unique branch of the first tracing and then the second tracing so branches are not mixed up.


Splitting a unique branch (Green: annotator 1, Red: annotator 2)

Transferring a unique branch

At the end of the splitting process the first and second tracings will look identical. There will be a unique file for each tracing filled with multiple root nodes. Each root node indicates a unique neurite in the selected unique file.

The neuron before (left) and after (right) trimming unique branches (magenta: annotator 1, Green: annotator 2). The cable length of this axon is 184.32 mm (after consensus).


The final step in the splitting process is to create a 'base' neuron. The base neuron is created by selecting whichever tracing has more nodes from the now identical first and second tracings and changing its name to include the suffix "_base". To find the node count, select the wheel icon in the "Neurons" list of the Horta Control Center and then select "View Neuron Table." Identify which tracing has more nodes and rename this tracing to become the base neuron. Export and save the base neuron.


Select the 'base' neuron by choosing the tracing with the most points.


Evaluating

The second step in the consensus process is evaluation. During the evaluation process, a tracer looks at each neurite in the unique files created in the splitting step to determine if it belongs to the axon of interest. During this part of the process, it is helpful for other neurons to be visible in the workspace in order to ensure that a ‘unique’ neurite has not already been traced as part of a neighboring neuron. Once it is decided if a neurite is part of the neuron or not, a note should be placed on the root of that neurite. The MouseLight annotators will use notes such as "yes" or "no" to indicate if the neurite belongs to the axon or not. Export and save the two unique files with the notes so they can be used for future reference.
Reattaching

After all of the unique neurites have been evaluated, the final step of the consensus process begins. The reattaching process connects each correct neurite to the base neuron. To merge a neurite to the base, select the node on the base where the neurite should be attached. Shift-click on the root node of the neurite to merge it into the base neuron.

Note
Warning! Selecting the wrong neuron during this process can result in all uniques being transferred to the incorrect neuron. To undo this, use CTRL-Z.

Once all of the correct neurites from both unique files are connected, the resulting tracing is considered to be the most accurate skeleton representation of the neuron. The final step in the reattaching process is to rename this neuron to consensus, then export the consensus.
Considerations

While tracing and performing a consensus, it is important to check the accuracy of the neuronal tracing. There are a few things to consider when validating a tracing's accuracy including:

  • Signal quality
  • Neuron Forks
  • Neurons intertwining
  • Dim neurite terminus

If the tracing enters a dark or dim area, where the signal quality is low:
  • Adjust the color sliders to obtain better contrast of signal. Zooming out to view the entire neuron may reveal an obvious continuation in the surrounding area. The direction of possible continuations should be checked to ensure that the morphology of the continuation matches the morphology of the reconstruction as a whole.

If the neuron forks, but the fork is uncertain:
  • Inspect both sides of the neuron to ensure that the fork is not a crossover from another neuron. Zooming out to view the entire neuron is helpful for viewing the morphology of the reconstruction. Generally, neurons fork away from the soma and not towards it, although a possible branch should not be ruled out on forking direction alone. Uncertain branches should be traced carefully to ensure that the branch does not return to the soma of a different neuron.

If two neurons cross or intertwine:
  • The brightness of each possible continuation should be considered, and an attempt should be made to match neurites of similar brightness and/or thickness. All possible continuations should be traced carefully to ensure that no branch returns to the soma of a different neuron.

If a terminus on the neurite is dim:
  • Care should be taken to ensure that the neurite actually ends where indicated and was not mistraced or does not continue further. Axons have been found to end with well-defined features, and bouton-like structures (Winnubst et al 2019).


Axonal endings: Bright (left) vs dim (right) ending. Both images are 11µm in width.

Automated Tracing
Automated Tracing
Reconstruction can be sped up by means of automated tracing. In HortaCloud this occurs in several steps:

  1. Image is segmented by means of an image processing pipeline
  2. Neurites are segmented and organized into topological skeletons
  3. Skeletons are then imported in bulk into a HortaCloud workspace
  4. Tracing proceeds as above described but focused on correcting the imported reconstructions rather than de novo tracing

Given the complexity of axonal arbors, it is typically more convenient to 'nick' skeletons into manageable portions (fragments) using algorithms that break skeletons at locations expected to be particularly ambiguous, such as cross-overs or junction points (Winnubst et al 2019). For this reason, we typically refer to this type of tracing as fragment-assisted-tracing, or assisted tracing.

NB:
  • Image segmentation routines occur outside HortaCloud and cannot be described in detail in this protocol. See HortaCloud documentation for details on known pipelines feeding segmentation results into the software
  • Fragmentation of skeletons is not always required. It occurs only to speed up the curation of misconnected structures. Consider the crossover location depicted in the figure below: e.g., it is faster to connect two of the disconnected neurites than to split the structure and reconnect split neurites. Merging of segments in HortaCloud cloud requires a single interaction (one-click merge feature)


Overview of automated segmentation at two cross-over locations: a cross-over between two neurites from neighboring cells.
Imagery (raw) is segmented and skeletons assembled from connected components of foreground signal (segmentation). In MouseLight worflows, skeletons are then fragmented (fragments) at problematic locations (typically junction points), to be more easily resolved by an annotator.


Fragment-based-tracing is enabled by importing the automated reconstructions in bulk into a workspace. To do so, select Import SWC Folder... from the gear menu of the Workspace section of Control Center. In the prompt that is displayed, specify the path of the directory containing the reconstructions and the name of the (new) workspace that will be hosting the imported fragments. Importantly, select the Mark all neurons as fragments checkbox so that the software is aware that the annotations being imported originate from automated segmentation.

Bulk (asynchronous) import of "fragments".

Note
Fragments can only be marked at import. Failure to do so will disable all fragment-related functionality. Annotations imported as "fragments" are tagged with a computer icon in the Neuron List and are managed by a different permission scheme.

While HortaCloud can handle hundreds of thousands of fragments, it is advised to adjust the number of annotations that are displayed at any given time in the viewer to keep the software responsive. This can be set by adjusting the "sspatial filter" options (seeoptions (see the HortaCloud manual for details). NoteHortaCloud manual for details). Note that the "spatial filter" option (that ge"spatial filter" option (that gets highlighted belowts hiNeuron List),st), is only available when fragments exist in the worksp

Fragments being displayed around the cursor. Note that the entire field of view is associated with thousands of other fragments, but those remain hidden under "spatial filter" options to keep the software more responsive.

Expectations
Expectations
Speed:
Based on our experience, an annotator manually tracing a neuron using this protocol should take an average of 18 mm/hr to complete a projection axon. Factors influencing the speed of tracing include cell type, annotator experience, neurite signal quality, neuronal arbor density. We've experienced manual tracing speeds as slow as 5mm/hr and as fast as 35mm/hr. With automated tracing (fragments), these speeds become at least 2x faster.

A difference in cable length ≥5mm between the first and second tracings was frequently associated with major topological defects. As such, we use this criterion to determine if the first or second tracings should be reexamined prior to consensus.
Frequent Errors:
Roughly speaking the most frequent reconstruction errors can be aggregated into four categories:

  • Missed branch: When a branch (and its children) are omitted from the reconstruction
  • Premature termination: When the path associated with a branch terminates abruptly
  • Incorrect crossover: When neighboring neurites (either from the same cell or neighboring cells) interact with each other (intertwining, juxtaposition, or intersection), and the path of the neurite being traced is not properly resolved
  • Local curvature: Errors that do not alter the neuron's topology but reflect local incorrections in traced paths

These type of errors have been detailed and quantified in Ferreira et al, 2024.

Exemplars of most frequent errors. (A) Missed branch. (B) Premature termination. (C) Incorrect crossover. (D) Local curvature.

Terminology
Terminology
Glossary

Annotation
  • See node

Arbor
  • A set of annotations with only one root and potentially many branches, named for resembling the canopy of woody plants.

Background
  • Unwanted images or noise detected by the microscope. Can be dimmed to become less visible using color sliders. See Enhancing Image Contrast section.

Base
  • An incomplete tracing showing only the parts of the neuron upon which both the first and second tracings agree. See unique

Branch
  • One of the multiple segments proceeding from a fork.

Color model
  • A set of view parameters (including colors, channel visibility, etc.) that are manipulated by the color sliders and can be saved and loaded together.

Consensus
  • The final form of the neuron, the agreed-upon tracing based on the first and second tracings, after all differences between those tracings have been resolved.

First tracing
  • The initial form of the neuron, i.e., the first completed tracing of the neuron. See second tracing

Fork
  • (n.) The location where one segment splits or branches into two segments.
  • (v.) The act of splitting or branching into two segments.

Interactable neuron
  • A neuron whose nodes can be edited (added, moved, or deleted).

JSON file
  • A common structured text file format used to import/export text annotations. This type of file is also used by the MouseLight neuron browser.

KTX tiles
  • Files holding the 3D data for fast loading into a graphics card (GPU).

Loop
  • A tracing that connects back to itself.

Manual tracing
  • An annotated reconstruction created by a tracer in the absence of major computational aids by clicking along neurites. See semi-automated tracing

Neurite
  • A neuronal projection of either a dendrite or an axon.

Neuron
  • The traced tree of a cell, including axon and dendrites.

Node
  • A single annotation point or vertex.

Octree
  • The files holding the multiresolution imagery. It is referenced as an "octree" because each level in the image hierarchy has eight higher-resolution images for each lower-resolution image in the previous level.

Owner
  • A username or group that owns the neuron. If a neuron is owned by a user, only they may change it; if a neuron is owned by a group, any member of the group may take sole ownership of the neuron and then change it.

Primary tracing
  • See first tracing

Reconstruction
  • The traced neuron or neurite.

Root
  • An annotation node with no parent. The root of a finished neuron will be at the soma, and a completed tracing should have only one root.

Sample
  • The imaged data of a mouse brain.

Second tracing
  • A subsequent tracing of a neuron by a second annotator; also called a "second pass."

Segment
  • A linear series of annotations (nodes) with no forks.

Semi-automated tracing
  • Cooperative tracing between a tracer and a computational routine that detects fluorescence signal along neurites. Typically occurs in two modalities:

  1. A computer program pre-traces the signal in a dataset. These automatically-traced fragments are imported into HortaCloud so that a tracer connects and/or extends fragments as needed to produce the curated tracing.
  2. HortaCloud computes an optimal path along the neurite between two nodes defined by a tracer (A* search).

Signal
  • Imaged neurons and their neurites detected by the microscope. The signal-to-background contrast is adjusted using the color sliders.
Skeleton
  • Centerline representation of a tree. By default, trees in HortaCloud are skeletons since nodal radius is constant.

Spectral unmixing
  • Mathematical unmixing of signal crossover between imaged channels caused by spectral overlap between fluorophores .

Soma
  • 1-node representation of the neuronal soma, and typically the starting node and root of a tracing. When tracing whole neurons, the root node should be located in the middle of the soma.

SWC file
  • A common multi-column text file format for storing neuron skeletons. SWC files do not contain tags but can be opened by any text editor.

Tag
  • A word or phrase attached to a neuron. It may be used in filtering the neuron list or in controlling neuron appearance.

Tracer
  • The person tracing the neuron, also called an "annotator."

Tree
  • A set of annotations with parent-child relationships, in which each annotation has at most one parent and zero or more children. In a tree, all nodes trace back to a single root. Typically, the term is used to refer to neuronal arbors from a graph-theory point of view (i.e., as undirected graphs).

Tiles
  • The individual fields of view that stitched together form the large monolithic volume being traced. Tiles can be visualized individually or in neighborhoods depending on the active tile loading strategy. See octree

Tracing
  • The process of creating a reconstruction of a neuron by placing annotation nodes along the fluorescent signal of its neurites.

Unique
  • A traced section of a neuron by one annotator that either differs or has not been traced by the other annotator. Unique fragments reflect differences between first and second tracings.

Vertex
  • A single node connected to three or more other nodes; a branch point

Workspace
  • The object in HortCloud that collects user annotations (neurons and text annotations). It is associated with a sample, is owned by a user or group, and may also contain additional settings such as lookup tables.
Quick Reference Guide
Quick Reference Guide

Navigating along an anatomical axis
  • Orient the sample in the desired plane (e.g., coronal), then use Shift-Z and Shift+A to navigate forward/backward along the axis.

Placing a node
  • Shift-click on a location on the 3D image.

Moving a node
  • Left-click on a node. Hold down left-click while dragging the node to the desired location.

Delete a node
  • Right-click on a node. Select "Delete Vertex" from the drop-down menu.

Change neuron color
  • Click on the colored rectangle in the "C" column of the neuron list. A list of color options will appear. Select the desired color and press "OK" to change the neuron’s color.

Splitting a neurite
  • Right-click on a node and select "Split Neurite at Vertex." The original neuron name will remain with the neurite containing the original parent node (upstream of the split). A generic name "Neuron XX," where XX is a number, will be automatically assigned to the new, non-conjoined neurite.

Merging neurites
  • Left-click on the node of the neuron that will be attached to the other neurite. This will be the parent node. While holding the shift key, click the node where the first neurite will attach to the second neurite. Releasing the shift key merges the two neurites. The neurite will be connected to the neuron at the designated parent node. Note that the neuron will keep its name, while the neurite name will disappear from the Neurons list.

Helpful hint: Do not make a merge where more than two branches will stem from one parent node. If there are more than two branches coming from one parent, later analysis of the neuron may be disrupted.

Transferring neurites between cells
  • Right-click on any node of the neurite to be transferred. Select "Transfer Neurite" from the drop-down menu. All neurons currently listed in the Neuron box will appear as options. Note that transferring the neurite to another neuron in this manner will not physically connect them; instead, the neurite is simply assigned to that neuron. To physically merge a neurite into another neuron, see Merging neurites.

Helpful hint: Before transferring a neurite, filter the Neurons table to only list neurons affected by the transfer. This will minimize ambiguities as there will be fewer neurons to choose from when transferring.

Adding a node to a neurite
  • Right-click on the node downstream of the location to add a node (further away from the soma). Select ‘Split Neuron Edge Between Vertices.' This will add a node upstream (toward the soma) of the node selected.

Viewing neurite information
  • Select the gear icon below the Neurons list, and click “Show neuron table.”

Adding a Neuron Tag
  • Right-click on a node of the neuron in Horta 3D. Click Edit Neuron Tags. Type a neuron descriptor, initials, or other signifier in the text entry box, then press New tag. Close the Edit Tags window.
  • Right-click on a node. Click the Edit Neuron Groups option. Click the empty box in the Toggle Hot-key column. Press any key on the keyboard to use as the hotkey. [Hint: avoid any pre-existing hotkeys]. Click the empty box in the Property To Toggle column. Select which property will be affected. For a full description of properties, see Adding a Neuron Tag section in the Second Tracing section.

Exporting a neurite
  • Right-click on the neuron in the Neurons table to export. Select “Export SWC file.” This will export the neuron as a .swc format. A JSON file with the same name will be simultaneously generated and saved to the same location; this file contains all notes listed in the Annotations box.

Bulk hide/unhide neurons
  • In the Text filter of the Horta Control Center, type the names of the neurons to be shown or hidden. Then click on the associated gear icon and select the appropriate command (Show neurons, Hide neurons, or Hide other neurons).
Troubleshooting Guide
Troubleshooting Guide
Sample does not open
  • Check sample paths
If not open already, open Data Inspector and Data Explorer: Horta > Core > Data Inspector, Data Explorer. In Data Explorer, click on the sample. Data Inspector will show the sample path. The sample path should point to an existing sample on an s3 bucket. See HortaCloud manual for details.

Workspace does not open / 3D image does not appear
  • Check sample paths
If not open already, open Data Inspector and Data Explorer: Horta > Core > Data Inspector, Data Explorer. In Data Explorer, click on the sample. Data Inspector will show the sample path. The sample path should point to an existing sample on an s3 bucket. See HortaCloud manual for details.

  • Compare GUIDs (Globally Unique IDentifier)
Click on the workspace in the Data Explorer. Note the Sample GUID in the Data Inspector. Confirm that this Sample GUID matches the GUID of the desired sample. (For example, Workspace 1 shows a Sample GUID that is expected to belong to Sample 1; however, this GUID actually belongs to Sample 2.)

Neurons do not appear inside the sample image
  • Zoom out to confirm that the sample image is visible
If sample image is visible, but neurons are outside of the sample space, contact customer support, or reload neurons from exported files.

Viewer not responsive
  • Clear cache
Tools > Options > Core > Under "Memory Management" click "Clear cache"

  • Verify browser compatibility
Some browsers may not support web applications. Ensure no add-on (e.g, ad- or JavaScript- blocker) is interfering with HortaCloud.

Tracings not snapping to signal
  • Check that correct channel has been unmixed
If "Unmix channel 1..." has been selected, then new nodes will snap to signal in Channel 1. If "Unmix channel 2..." has been selected, then new nodes will snap to signal in Channel 2.

  • Adjust the 'Snap to Signal Radius'
Right click anywhere in 3D > "Snap to Signal Radius"

Sample will not fully rotate in 3D
  • Window > Horta > Camera Control > uncheck "Dorsal is up"

Sample appears 'squished' in 3D
  • Right click anywhere in 3D > View > uncheck "Compress Voxels in Z"


Protocol references
https://doi.org/10.1016/j.cell.2019.07.042

Winnubst J, et al. (2019) Reconstruction of 1,000 Projection Neurons Reveals New Cell Types and Organization of Long-Range Connectivity in the Mouse Brain. Cell 179(1). https://doi.org/10.1016/j.cell.2019.07.042.

Economo MN et al. (2016) A platform for brain-wide imaging and reconstruction of individual neurons. eLife 5:e10566. https://doi.org/10.7554/elife.10566

Ferreira AT et al. (2024) Discovery of neuronal cell types by pairing whole cell reconstructions with RNA expression profiles. bioRxiv 2024.12.30.630829, https://doi.org/10.1101/2024.12.30.630829