ShuTu: Open-Source Software for Neuron Reconstruction
ShuTu ["dendrite" in Chinese] is a software platform for reconstructing dendritic tree of neurons. Combining automated reconstruction and manual editing, ShuTu enables the user to obtain the dendritic morphology accurately and efficiently. It is designed for neurons stained following patch-clamp recording and biocytin staining. It can also handle fluorescence images from confocal stacks. ShuTu was written by Dezhe Jin [Penn State University] and Ting Zhao [formerly at Janelia] in collaboration with Nelson Spruston [Janelia]. A detailed description of ShuTu can be found in our paper ShuTu: Open-Source Software for Efficient and Accurate Reconstruction of Dendritic Morphology. For support and discussions, reach Dezhe Jin through twitter @djintwt. Tutorial Video. InstallationAfter unzipping the file, the GUI can be found in the installation directory. The GUI is precompiled and ready for use. It is for loading a neuron reconstruction project, and editing the SWC structure of the neuron. For Mac and Linux, programs for image processing and automated reconstruction are also in the directory. These programs require further installations. To use the programs in Windows 10, the user needs to download and install Ubuntu App from App Store. For older Windows verisons, the user needs to install and run Linux virtual machine. Quick evaluationTo see what it looks like after everything is done, download images and other files for a granule cell from rat dentate gyrus. This neuron is relatively small and was imaged with 63X, hence the image file sizes are suitable for quick download and evaluations. To load the project, start ShuTu as follows: cd distro ./ShuTu & When first starting ShuTu, it will prompt about the working directory into which the log file is stored. Accept the default by pressing OK. To load the project, click on the first icon on the menu, navigate to the dirctory of the images, and double click on granule-.tiles.json file. The final reconstruction file granule-.swc is automatically loaded. Now there are three windows. While pressing Command [Mac; use Ctrl in Linux], press ~ key to switch between windows. In all windows, zoom in and out are controled with + and - key. In the stack window, a tiff stack is shown, and the SWC structure is overlayed on the image. To go up and down in z, use the left and right arrow keys. After zoom in, press and drag mouse to examine different parts of the images. The Tile Manager window displays the 2D projections of the tiles of tiff stacks, and the 2D projection of the SWC structure. Double clicking on one of them loads the corresponding tiff stack in the stack window. The 3D window, the SWC structure can be examined in 3D. Pressing and dragging the mouse rotates the structure; doing so while pressing Shift key shifts the structure. To better see the structure in 3D, the use can enlarge the scale in z relative to xy s in Z Scale under the Control and Settings panel in this window. To load the automatic reconstruction file granule-.auto.swc, first delete granule-.swc by pressing Command-a in the 3D window and press x; and then do File → Load SWC, select granule-.auto.swc. Another example suitable for evaluation is Installing programs
Image processing and automated reconstruction programs need to further installation steps.
To install on Mac and Linux, in a terminal and in the directory ShuTuMac or ShuTuUbuntu, type the command
On the most recent Windows 10, Ubuntu can be natively installed, as described in
this blog.
Or follow these steps:
For older versions of Windows, the user needs to install Linux virtual machine [see this bolg for guidance]. Note from Nate Glasgow on installing on Windows 10 (2/21/2020): "If any users tried ./build.sh before installing build-essential, they will have to 'rm -rf Downloads' before proceeding, because it gets stuck for some reason." The source code for GUI is at Github GUI source code. Image processing and automated reconstructionDownload the image files from Granule Cell 63X Start. Unzip in the home directory, which should create a directory granuleCell63XStart. The commands are typed in a terminal and in the directory of ShuTu. The programs utilizes multiple CPU cores to speed up computaion. We assume that there are at least 4 CPU cores and 16 GB memory. There are following steps : [1] Create tiff stacks:mpirun -n 4 ./createTiffStacksZeiss ~/granuleCell63XStart/ granule [here granule is filenameCommon given to the created tiff stacks] [2] Process images: mpirun -n 4 processImages ~/granuleCell63XStart/ [3] Stitch images: mpirun -n 4 ./stitchTiles ~/granuleCell63XStart/ [4] Auto reconstruction: mpirun -n 4 ./ShuTuAutoTrace ~/granuleCell63XStart/ ShuTu.Parameters.granule63XTest.dat These commands can be combined into a single script [see script process.sh]. If there are less CPU cores and memory, reduce the number after -n; if there are more, increase. The user needs to make sure that the total memory used is below 100%, otherwise the programs can crash. The use of memory during the run can be checked in a terminal with command top. A useful trick when typing file directories is to type first few letters and use the tab key to complete the path. Steps [1] & [3] assumes that the images are taken with a Zeiss AxioImager microscope with AxioCam and ZEN blue software. The meta data are stored in ~/granuleCell63XStart/*info.xml file. In step [1], this file is parsed to assemble tiff stacks from individual images at varying depths, placed under directory ~/granuleCell63XStart/slides. In step [3], the relative positions of tiff stacks are parsed for sticthing.
If tiff stacks are created in other ways, step [1] can be skipped.
To stich tiff stacks, the user can create a file tileSequences.txt
in the image directory, with the following format:
In step [2], if the images are dark background, add 1 at the end of the command. This will invert tiff stacks into bright-field images. Note on Windows 10 Ubuntu app: The image files can be stored outside of the Ubuntu system; to access them, use path /mnt/c/Users/username/imageDirectory/. Reconstruction from single tiff stackIf the neuron is contained in a single tiff stack, the steps are different. To test this, download fly motor neurons [imaged by Baek and Mann, J Neuroscie 2009, courtesy of John Tuthill], and unzip in the home directory. To load the stack, do File → Open and select ~/flyMotorNeurons/22-24-1-7.tif. To automatically reconstruct neuron, use a single command./ShuTuAutoTraceOneStack ~/flyMotorNeurons/22-24-1-7.tif ShuTu.Parameters.flyMotorNeuron.dat Load the reconstrocted SWC structure by File → Load SWC, select 22-24-1-7.tif.auto.swc. Since these are dark-background images, use Tools → Invert intensity to convert them to bright-field images to edit the SWC structure in GUI. More dataHere we provided the images and reconstructions of the neurons described in the paper. Due to large sizes of images files, the data for some neurons are split into multiple parts. After downloading and decompressing, the parts should be combined into one directory. Mouse CA3 neurons and the Purkinje cell were imaged by David Hunt; rat CA1 neuron and granule cell by Ching-Lung Hsu at Janelia while they were at Nelson Spruston's Lab. Details of viewing SWC structuresA reconstruction project can be opened by clicking on Open Project icon or File → Open Project. In the directory of the neuron, there should be a file filenameCommon.tiles.json, which is created after stitching the tiff stacks. Clicking on it opens Tile View, in which the 2D projections of the tiff stacks are shown. The 2D projection of the neuron should be visible. If there is a previous reconstruction of the neuron, which is stored a file filenameCommon.swc, it will be automatically loaded and overlaid onto the 2D projection. The SWC file generated by the automated algorithm, filenameCommon.auto.swc, can be loaded by selecting File → Load SWC. Double clicking on any tile in the Tile View loads the corresponding tiff stack in Stack View. The loaded SWC points are overlaid onto the tiff stack. To go up and down in the z-dimension, use the right and left arrow keys. Clicking on Make Projection button creates 2D projection of the tiff stack. The user can specify the number of subdivisions used in the projection. All of the projections of the subdivisions are contained in the Projection View, which can be browsed with the left and right arrow keys. The SWC structure is also displayed in 3D View. It can be rotated with the arrow keys, and shifted with the arrow keys while pressing the Shift key, In all views, zoom is controlled with + and - keys. After zooming in, different parts of the images can be navigated by pressing-dragging the mouse. The functions of the arrow keys can be also performed with mouse wheel or track pad when available. Editing SWC pointsThe SWC structure can be edited in Stack View, Projection View, and 3D View. All editing can be reversed by Ctrl-z [substitute Ctrl for Command in Mac]. Colors of SWC points indicate their topological roles in the structure: yellow and blue indicate the end points of branches; green at the branching points; and red the interior points. Lines between SWC points indicate their connectivity.In Stack View, an SWC point is plotted with a circle at its xyz position in the tiff stack. The radius of the circle is the same as that of the SWC point. As the focus plane shifts away from the z of the SWC point, the circle shrinks with its color fading. This helps the user to visually locate the z of the SWC points and inspect whether the positions and radii of the SWC points match the underlying signals of the neurites in the tiff stack. Extension is the most used editing function. In Stack View, it can be done in two ways. The first is manual extension. Click an SWC point to extend, and the cursor becomes a circle connected to the SWC point. Focus on the target neurite using the arrow keys, and match the radius of circle with that of the neurite using e and q. Ctrl-clicking on the target points creates a new SWC point connected to the starting SWC point. The second is smart extension. It is the same as manual extension, except that the user clicks without pressing Ctrl. This method allows clicking far from the starting SWC points; the algorithm fills in additional connected SWC points along the neurites with the radii and depths automatically calculated. Smart extension works well when the underlying signal is strong. To change the properties of a particular SWC point, select it by clicking on it and pressing Esc to come out of the extension mode. The radius can be changed with e and q. It can be moved with w, s, a, d for up, down, left, right. Pressing x deletes it. To connect two SWC points, click on the first point and Shift-click on the second point, then press c. Pressing Shift-c after selecting two points automatically fills additional SWC points, similarly as in the smart extension. To disconnect two SWC points, select them then press b. In Projection View, 2D projections of the subdivisions of the tiff stack are overlaid with the SWC points. In this view it is easier to spot missed branches and incorrect connections. There is also a mask-to-SWC method for tracing branches. To draw a mask along a branch, press r. The cursor becomes a red dot. Roughly match the radius of the dot with that of neurite with e and q. Click on the start point, then Shift-click on the target. A red mask will be drawn along the branch. Clicking on Mask → SWC icon converts the mask into SWC points, which can be examined in detail in the Stack View. The mask can also be drawn manually by press-dragging the mouse along the branch. To get of out the mask drawing mode, press Esc. Clicking on an SWC point selects it. Pressing z locates the selected point in the Stack View, and its z position and other properties can be further examined with the tiff stack. The user can directly modify the connections in the Projection View. The operations are the same as in Stack View. In 3D View, the user can examine and modify the connections between SWC points. Connecting or breaking connections between two SWC points is the same as in Stack View and Projection View. Selecting an SWC point and pressing z locates it in the Stack View for further examination and extension. This operation also loads a new tiff stack if the selected point is not in the current tiff stack. A useful way of locating broken points in the SWC structure is the operation that selects all connected SWC points to the selected SWC point. It is done by pressing h-3, or right-clicking the mouse and selecting Select → All connected nodes. After correctly connecting all SWC points belonging to the neuron, the user can delete all noise points simply by selecting all SWC points in the neuron, right-clicking the mouse, and performing delete unselected. Annotating, saving, and scaling the SWC structureAfter the reconstruction is done, the user needs to annotate the SWC points as soma, axon, apical dendrite, basal dendrite. This is best done in the 3D View. In the panel control and settings, change Color Mode to Branch Type to reveal the types of SWC points. To annotate the soma, the user can select one point in the soma, right-click the mouse, and select Change Property → Set as root. More SWC points belong to the soma can be selected by Shift-clicking. Then right-click to bring up the menu, then select Change type and set the value to 1. The SWC points in the soma are shown in blue. To annotate the axon, select the one SWC point closet to the soma, and press h-1. This selects all SWC points down stream of the selected point. Then change type to 2. Basal dendrites and apical dendrite can be similarly annotated, and their types are 3 and 4, respectively. In the panel control and settingings, setting Geometry to normal produces the volume representation of the SWC structure, with surface rendered between adjacent SWC points.To save the reconstruction, click on the objects in the panel Objects, which selects the corresponding SWC points. Then in the window of the SWC structure, left-click and do save as. It is best to use the default filename filenameCommon.swc.
The dimensions of the SWC points in filenameCommon.swc are pixel based.
To convert them into physical dimensions in micron, type in the terminal
This process uses xyDist and zDist in parameterFile.dat, which specify in micron the xy pixel distance and z distance between successive planes. The results are saved in filenameCommon.scaled.swc.
Right after finishing the reconstruction and with ShuTu closed,
the number of various editing operations can be analyzed using the command
Another useful Python script is scaleSWC.py.
This is used to scale pixel based swc file into micron based swc.
Use the command
To get basic statsitics of the neuron after scaling, use Python script
analyzeSWC.py.
The command is
|
psu.edu