webKnossos Tutorial: Neuron Reconstruction
In this blog post, I am going to show you how to reconstruct neurons in webKnossos. The software supports both creating sparse line-segment-based (skeleton) annotations and volume reconstructions. In this tutorial, we will focus on sparse annotation and explore webKnossos’s unique flight mode. I will also show you how to download the annotation and process it in Python.
Sparse neuron annotations are useful for a wide range of research questions:
- You can do statistical analysis on the annotations themselves: path length, the density of neighboring neurons, branching behavior, and others.
- We often use manual sparse annotations as ground-truth information when evaluating automatic volume (over-)segmentations created by machine-learning systems. (Which predicted segments/patches are picked along the skeleton?)
- You can use a sparse annotation as a guide-line for creating volume annotations later.
This blog post is aimed at new and intermediate webKnossos users. The presented techniques are explained by working on electron microscopy (EM) data but can be applied to other image modalities as well.
TL;DR Watch the tutorial on YouTube
Getting started
If you do not have an account on webknossos.org yet, sign up for free. Next, either upload your dataset from the dashboard — webKnossos supports a growing variety of data formats, e.g. Tiff files, image stacks, Knossos cubes, Neuroglancer formats, and others — or select a public dataset from the neuroscience community. For this tutorial, I will use the public data from “Dense connectomic reconstruction in layer 4 of the somatosensory cortex” (A Motta et. al., Science 2019) that you can find under “Featured Publications” in the webKnossos dashboard.
Open the webKnossos main annotation interface by selecting your dataset from the “My Datasets” tab in the dashboard and click “New Annotation” on the right-hand side. The dataset will be open in the main annotation interface of webKnossos. By default, webKnossos will present your data in 4 viewports: 3 reslices along the XY, XZ, and YZ axes and a 3D viewport. Additionally, you will find various settings and contrast adjustments in the panels on the left-hand side. The panels on the right-hand side mostly keep track of the various annotations that we will create.
Neurite tracing
Now, that we are more familiar with the interface, we can start with the real task at hand. Sparse neuron annotations are typically represented as line-segment annotations of interconnected nodes (called “skeletons” and sometimes “tree” in webKnossos lingo). In this tutorial, we will learn how to place nodes and line segments and how to work with them.
For neurite tracing, we typically start by identifying a nucleus or soma as the starting point for reconstructing individual axons and dendrites. Navigate in any of the three cross-sectional planes by dragging with the left mouse until you find a suitable starting point. From the toolbar at the top of the screen, switch to the “Skeleton tool” and place the first node of your annotation by left-clicking at your starting location. You will notice that a colored node with a circle around it will mark the spot where you clicked and that the “Trees” tab on the right-hand side will update. The circle indicates that the node is marked as being “active” or currently selected.
Continue by placing more nodes along the direction of an axon or dendrite. You will see the new nodes being connected automatically to the active node by a line to form a line-segment (skeleton) annotation. If your neurite/process goes off into the third dimension, use the mouse wheel to move between individual slices of the 3D dataset. (Alternatively use the keyboard shortcut SPACE and SHIFT+SPACE for movement along the third axis). Continue placing nodes and moving through the data until you reach the end of your neurite.
A few hints: I typically only work in the cross-section viewport with the highest imaging resolution, typically along the XY plane, and mostly use the other two viewports only for validation. In the case of neurites it also makes sense to work in the viewport which shows their biological features best, e.g. where the neurites appear the roundest.
Also, you don’t have to place nodes in every slice but it is often sufficient to place a node after moving a few slices to speed things up. For large dendrites placing a node every 5µm is typically sufficient.
If you ever make a mistake just use the handy undo/redo functionality from the top navigation bar (or use the keyboard shortcuts CTRL/CMD + Z and CTRL/CMD + Y).
You can exit webKnossos at any time and continue later. webKnossos automatically saves your progress every 30 seconds (or you click on the “SAVE” button in the upper left corner.) Continue any annotation from the “My Annotations” tab in your dashboard.
Working with skeleton annotations
Sometimes it is tricky to see the correct spot for placing a node, especially when dealing with very thin axons. Try zooming in/out with CTRL + mouse wheel to find the right node location (or use the keyboard shortcuts I and O for zooming in/out). webKnossos will automatically account for the zoom level in the annotated 3D positions.
Sometimes I make mistakes and want to move a node that I placed. Simply drag any node to its desired location with the left-mouse button dragging gesture.
When working with axons and dendrites, you will come across many locations in the data where they branch off in a different direction. webKnossos can record these branch points for you so that you can return to them later and continue tracing these offsprings. When at a junction, press the keyboard shortcut “B” to mark the active node as a branch point. You will see it changing its color slightly to make it easier to find again. Once you reach the end of a process, jump back to the latest branchpoint by pressing “J” and continue your annotation from there. webKnossos supports recording many branch points along the way and returning to them (first-in, last-out).
For locations of high interest (e.g. branch points or spine heads along a dendrite), I typically put down a comment to find these nodes again in a complex annotation. In the right-hand side sidebar is a tab called “Comments”. Enter a message into the text input to associate a comment with the active node. You can always come back to your node of interest by clicking the node ID number in the list of comments. They act as a “hyperlink” to quickly return to known positions in your annotation.
Sometimes it is helpful to delete nodes, e.g. when making a wrong branchpoint decision, or when splitting a long annotation into several parts. Use the right-click context menu to delete nodes (and split a single skeleton into two or more sub annotations). To reverse this, bring up the context menu on a target node and use the “Create Edge & Merge With this Tree” option (or use undo/redo).
Flight Mode
Creating sparse line-segment annotations by repeated left-clicking can be laborious and time-consuming. To help with this, webKnossos offers a unique “flight mode”. Imagine being the pilot in a flight simulator while flying through your data/along the path of a neurite. webKnossos will automatically “record your flight path” and place down nodes along the way. While this annotation strategy has a slight learning curve, it can be significantly quicker than manually placing nodes. Trained annotators can reach up to 1.5 to 2.1 mm/h in the mouse cortex (as quantified in Boergens et al. 2017).
Switch to flight mode by selecting it from the mode dropdown in the navigation bar at the top of the screen. Once in flight mode, start moving through the data by holding down “SPACE” and move the camera by left-clicking + dragging the mouse. Once you switch back to the orthogonal annotation mode, you will see that you annotated quite some distance in a short amount of time.
Read more about flight mode in our earlier blog post or the webKnossos publication.
Download and Computational Analysis
Once you are happy with your sparse annotation you can download it for further analysis in other tools. The download option is located in the dropdown menu next to the “Save” button in the webKnossos toolbar header at the top of the screen. The downloaded ZIP archive will contain any sparse and volume annotations that you created. We provide several Python and MatLab libraries for working with this data.
Sparse annotations are represented as human-readable NML files, a custom XML-style structure. Let’s analyze the path length of our annotation using the wKNML library for Python:
As you can imagine, you can also upload an NML back to webKnossos and continue your annotation there. We often do this with skeleton annotations that were created by our automated machine-learning analysis tool. But that is a story for a different time.
That is all for today’s tutorial. webKnossos is a very capable tool for quickly creating sparse line-segment annotations, tracing neurons, and computational analysis. You can try the whole tutorial yourself by signing up for free at https://webknossos.org.
If you want to speed up your annotations or don’t have the time to do it yourself, then have a look at the webKnossos annotation service, where we do the reconstruction for you. https://webknossos.org/services/annotations
