ShuTu: an Open-Source Software for Neuron Reconstruction


ShuTu (Chinese for "dendrite") is a software platform for semi-automated reconstruction of neuronal morphology. It is designed for neurons stained following patch-clamp recording and biocytin filling/staining. With an additional preprocessing step, it can also handle fluorescence images from confocal stacks.

Even when there is only a single neuron in the imaged volume, automated reconstruction is tricky, because of background. Thus, ShuTu was developed to facilitate a two-step process: automated reconstruction, followed by manual correction. The software uses sophisticated algorithms to perform the automated reconstruction, as well as a convenient user interface to facilitate efficient completion of the reconstruction via manual annotation.

ShuTu was written by Dezhe Jin (Penn State University) and Ting Zhao (Janelia) in collaboration with Nelson Spruston (Janelia).

A more detailed description of ShuTu can be found in our paper

ShuTu: Open-Source Software for Efficient and Accurate Reconstruction of Dendritic Morphology (preprint by Jin, Zhao, Hunt, Pearcy, Hsu, and Spruston).

Tutorial

Video tutorial (10 minutes, created by Ting Zhao).

Installation

  • Download Mac installer ShuTuMac.
  • Download Linux installer ShuTuUbuntu.
  • Download Windows 10 version ShuTuWin64 (GUI for viewing, editing, and semi-automatic tracing.)
  • To install on Mac and Linux, download the zip file, and in a terminal and in the directory ShuTuMac or ShuTuUbuntu, type the command

  • sudo sh build.sh
  • bash
  • During the process, enter "yes" or "y" or "Y" when prompted.

    On Windows 10, unzip ShuTuWin64.zip to get the GUI software. To install programs for image processing and automatic tracing, install Ubuntu app in the App Store. Here are the steps:

  • Update Windows 10 to the current version. Ubuntu app requires Windows 10 version 16215 and up.
  • From App Store install Ubuntu app.
  • Use "Turn Windows features on or off", click on "Windows Subsystem for Linux", click OK, reboot.
  • Start Ubuntu app.
  • sudo apt-get install unzip
  • wget http://personal.psu.edu/dzj2/ShuTu/ShuTuUbuntu.zip
  • unzip ShuTuUbuntu.zip
  • cd ShuTuUbuntu
  • sudo sh build.sh
  • bash
  • View source code and collaborate on Github.

    Images for practice

    Here we provide images of a rat dente gyrus granule cell (filled and imaged by Ching-Lung Hsu, the Spruston Lab, Janelia) for evaluting the software and practing reconstruction. Two resolutions are provided, 63X and 100X. For quick evaluation, use 63X. For more accurate reconstruction, use 100X.

    To see what it looks like after everything is done, download images and other files Granule Cell Complete 63X (1.2 GB), or Granule Cell Complete 100X (11 GB).

    To load the project, start ShuTu as follows:

  • Linux: ./ShuTu & (in the terminal in the directory of the installation)
  • Mac & 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 files and automatically saved SWC files for recovery are 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. To load the automatic reconstruction file granule-.auto.swc, first delete granule-.swc by pressing "Ctr-a" ("command-a" for mac) in the stack window and press "x"; and then do "File -> Expand Current -> SWC", select granule-.auto.swc.

    For praticing from the beginining to the end, inlcuding creating tiff, processing images, stitching, auto reconstruction, and editing, download images for practicing reconstruction Granule Cell Start 63X (1.3 GB), or Granule Cell Start 100X (12 GB).

    We assume that the images are under the home directory. The commands are typed in a terminal in the directory of ShuTu. We assume that the computer has at least 4 processors and 8 GB of memory. If not, reduce the number of processors used in ShuTu.py (edit the file with a text editor and modify the line nProc = 3). If the computer has more memory and more processors, increase the number of processors used to reduce the time. There are following steps :

  • Create tiff stacks: python createTiffStacksZeiss.py ~/granuleCellStart63X/ granule (here granule is the filenameCommon)
  • Process images: python processImages.py ~/granuleCellStart63X/
  • Stitch images: python stitchTilesZeissXML.py ~/granuleCellStart63X/
  • Auto reconstruction: mpirun -n 4 ./ShuTuAutoTrace ~/granuleCellStart63X/ ShuTu.Parameters.63X.dat (here 4 is the number of processors used)
  • Edit the SWC using the gui ShuTu
  • These commands can be combined into a single script (see script trace , which can be used on Mac).

    For 100X, replace granuleCellStart63X with granuleCellStart, and ShuTu.Parameters.63X.dat with ShuTu.Parameters.dat. Also, edit ShuTu.py and change "mag = 63" to "mag = 100".

    The 100X images are also provided in a compressed form (jpeng2000) to reduce the download size Granule Cell Start 100X Compressed (1.1G). Currently this is set up only for Ubuntu. Due to agressive compression, the sharpness of the images is somewhat reduced. To decompress, first install OpenJPEG then decompress the images using the following commands

  • sudo sh installOpenJpegForCompression.sh
  • python decompressToTiff.py ~/granuleCellCompress
  • 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/".

    More data

    Here we provided the images and reconstructions of the neurons described in the paper. Due to large sizes of the 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 pyramidal neuron I, 100X (filled and imaged by David Hunt, the Spruston Lab, Janelia). 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 (David Hunt). 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).
  • Mouse Purkinje cell, confocal images, 63X (David Hunt). Download Purkinje Cell (0.5 GB).
  • Rat CA1 pyramidal neuron, 63X (Ching-Lung Hsu). 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).
  • Loading a project (more details)

    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 -> Expand current -> 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" (or "Command-z"). 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 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. (In Mac, use "Command" instead of "Ctrl".) 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 the "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 the "Stack View" and the "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 "s-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 "s-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

  • python scaleSWC.py dataDirectory
  • This process uses "xyDist" and "zDist" in the file ShuTu.py, 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.



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

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