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 [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

.

Installation

  • Download Mac installer ShuTuMac.

  • Download Linux installer ShuTuUbuntu.

  • Download Windows 10 version ShuTuWin64.
  • After 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 evaluation

    To 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.

  • Rat granule cell, biocytin filled bright-field images, 63X. Download granule cell complete 63X (1.2 GB).
  • To load the project, start ShuTu as follows:

  • Linux: In a terminal and in the directory of the installation, use two commands

    cd distro
    ./ShuTu &

  • Mac: In the directory of the installation, control-click on ShuTu icon. Select Open, then on the question Are you sure you want to open it? slect Open.

  • Windows: In the directory of the installation double click on ShuTu icon.
  • 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

  • Mouse Purkinje cell, confocal images, 63X. Download Purkinje Cell (0.16 GB).
  • 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

    ./build.sh

    On the most recent Windows 10, Ubuntu can be natively installed, as described in this blog. Or follow these steps:

    [1] Update Windows 10 to the current version. Ubuntu app requires Windows 10 version 16215 and up.

    [1] From App Store install Ubuntu app.

    [2] Use Turn Windows features on or off, click on Windows Subsystem for Linux, click OK, reboot.

    [3] Start Ubuntu app.

    [4] sudo apt-get install unzip

    [5] sudo apt-get install build-essential

    [6] Download Linux installer ShuTuUbuntu

    [7] unzip ShuTuUbuntu.zip

    [8] cd ShuTuUbuntu

    [9] ./build.sh

    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 reconstruction

    Download 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:

    80
    1, 2
    1, 4
    4, 3

    In this example there are 4 tiff stack tiles. The first line specifies shifts of nearby tiles in percentage. Here the tiles overlap by 20 percent, so the shifts are 80 percent. The second line lists the tiles in the first row from left to right. The third line specifies two tiles that link the first row to the second row. In this case tile 4 is directly below tile 1. The fourth line specifies tiles in the second row from left to right. If there are more rows, this alternation of row, link, row continues. The stitching command parses this file for relative positions of the tiff stacks.

    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 stack

    If 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 data

    Here 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.

  • Mouse CA3 pyramidal neuron I, 100X. This is the neuron discussed as the main example in the paper. Download CA3 I Part 1 (8.7 GB), CA3 I Part 2 (8.8 GB), CA3 I Part 3 (8.3 GB), CA3 I Part 4 (8.7 GB).

  • Mouse CA3 pyramidal neuron II, 100X. Download CA3 II Part 1 (7.8 GB), CA3 II Part 2 (8.3 GB), CA3 II Part 3 (8.4 GB), CA3 II Part 4 (8.6 GB).

  • Rat CA1 pyramidal neuron, 63X. Download CA1 Part 1 (9.8 GB), CA1 Part 2 (9.5 GB), CA1 Part 3 (9.4 GB), CA1 Part 4 (9.5 GB), CA1 Part 5 (9.5 GB), CA1 Part 6 (9.7 GB), CA1 Part 7 (9.5 GB), CA1 Part 8 (9.5 GB), CA1 Part 9 (9.5 GB), CA1 Part 10 (9.6 GB), CA1 Part 11 (9.4 GB), CA1 Part 12 (9.6 GB).

  • Rat granule cell imaged at 100X. Download Granule Cell Complete 100X (11 GB).
  • Details of viewing SWC structures

    A 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 points

    The 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 structure

    After 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

    ./scaleSWC dataDirectory parameterFile.dat

    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

    python analyzeNEO.py

    The script analyzeNEO.py parses the log file generated by ShuTu. The log file can contain several neuron reconstruction sessions, but the script only parses the most recent one. When estimating the total time of manual editing, idle times of the user are excluded if they are detected in the log file. The script is tested with Python 2.7. It should be modified if Python 3 is used.

    Another useful Python script is scaleSWC.py. This is used to scale pixel based swc file into micron based swc. Use the command

    python scaleSWC.py swcFilename xyDist zDist

    Here xyDist, zDist are pixel distance in micron in each plane, and the distance between planes in micron.

    To get basic statsitics of the neuron after scaling, use Python script analyzeSWC.py. The command is

    python analyzeSWC scaledSwcFilename



    Dezhe Jin
    Associate Professor of Physics
    contact: dzj2 psu.edu

    Department of Physics
    Penn State
    104 Davey Lab
    University Park, PA 16802-6300