How to install and use the Filament Editor and ZIB extension

How to install and use the Filament Editor and
ZIB extension
Document version: September 5, 2014. This document describes how to obtain, install and use the software and a supplementary data package to try functionality and reproduce results described in the paper: [1] Vincent J. Dercksen, Hans­Christian Hege, Marcel Oberlaender (2014): The Filament Editor: An Interactive Software Environment for Visualization, Proof­Editing and Analysis of 3D Neuron Morphology. Neuroinformatics 12(2), pp 325­339. 1. Download and installation of software and data
The use of the ZIB extension package for neuron reconstruction requires Amira 5.5 including a valid license. For users without Amira 5.5, a trial version of Amira 5.5 together with a time­limited license can be applied for from FEI­VSG (http://www.vsg3d.com). For system requirements see http://www.vsg3d.com/amira­system­requirements. The ZIB extension package is provided for the Linux 64­bit and Windows 64­bit platforms. Installation instructions: 1. Obtain and install Amira 5.5, including a valid license. 2. Start Amira, when the license dialog appears, copy the license string into the appropriate box and restart. 3. Quit Amira. 4. Download the ZIB extension package for your platform from http://www.zib.de/de/visual/software/neuronreconstruction.html. 5. Unpack the ZIB extension package in the Amira installation directory. Windows note: if you installed Amira as Administrator and extraction of the files in the Amira directory fails due to permission restrictions, extract the files in a different directory, and copy the contents into the Amira directory. 6. Download the data package from https://amira.zib.de/zibexts/filamenteditor/datapackage/FilamentEditorPaperSupplem
entaryData.zip 7. Unpack the data package in a directory of your choosing. 1 2. Data description
The supplementary data package consists of a README file containing information on which publications to cite when using the data for your own work, and these 3 directories: ● ThalamoCorticalAxon: contains the data sets used in the results section of [1]. ○ MaximumProjectionImages: MIP images of 8 sections ○ AutomaticTracingResults: 1 SpatialGraph for each of the 8 sections as produced by the automatic tracing algorithm (to be proofedited) ○ User1...User5: For each user the proof­editing results for each section, all sections combined, aligned, smoothed and scaled in z. ● MorphometricAnalysis: 2 SpatialGraphs, a layer 5 excitatory pyramid in rat somatosensory cortex and an excitatory VPM neuron in rat thalamus, used to illustrate the morphometric analysis functionality. ● LandmarkContours: MIP image of a brain section showing barrels to illustrate the interactive contour tracing. 3. Amira Help
The Amira Help contains documentation of data types, modules, file formats, etc. The Help window is opened by either: ● Main menu: Help → User’s Guide ● Pressing F1 The “Search Help” box lets the user search the documentation. This is an effective means to find the relevant information. 1. Enter the search term in the “Search Help” text box, and press <Enter>. 2. Select the desired help page in the search result list. In the sections below search terms are included to find relevant and detailed information for each feature. 2 4. General introduction to Amira and the Filament Editor
For a general introduction to the use of Amira, please refer to the “Tutorials” and the “Getting started” sections, accessible through the main page of the Amira Help (F1). For a general introduction to the Filament Editor, please refer to the Filament Editor tutorial (accessible by searching for “introduction to the filament editor” in the Help Search) and/or the help pages: 1. Open Help (F1), 2. In the top menu bar of the Help window click “Editors”, 3. At the bottom, under “ Microscopy Option”, click “Filament Editor”. The annotated screenshot below shows some important GUI elements that are used in the howto’s below. 3 5. Features described in the paper
5.1. Proof-editing
To proof­edit an automatically created tracing do the following: 1. Open the MIP image file: ThalamoCorticalAxon/MaximumProjectionImages/ S01_max_z_projection.tif 2. In the “Image Read Parameters” dialog that opens, set: “Min coords” to 0, 0, 50 “Voxel size” to: 0.184, 0.184, 0.5. 3. Open the tracing file: ThalamoCorticalAxon/AutomaticTracingResults/S01_final.am. 4. Activate the Filament Editor. 5. Hide the 2D viewer (left) by clicking the “1 viewer” button twice. 6. Click the button marked “Show image in 3D viewer” in the image above (Tooltip: 3D thick slice). 7. Click the camera button to switch to orthographic. 8. In the “View” toolbox, set “Node scaling factor” to 0.5, and “Segment coloring” to edge labels. 9. Use the camera tools to zoom in on a region. 10. Use the selection and edit tools to select and edit structures to remove, connect, etc. Help Search terms: “the tool box”, “overview of the filament editor”, “edit tools reference”, “selection tools reference”. 5.2. Section alignment
To automatically align a stack of sections, do the following: 1. Main menu: Create → SpatialGraph → CreateSpatialGraphStack 2. Select the CreateSpatialGraphStack module. 3. In the properties area, under “File names” click “Browse”. 4. In the “Files List” dialog click “Add…”. 5. Navigate to the ThalamoCorticalAxon/User1/ directory 6. Click S01_User1.am. 7. Holding shift, click S08_User1.am, then click “Load”, then “OK”. 8. In the properties area, click “Apply”. 9. Activate the Filament Editor. 10. In the “View” toolbox set “Node coloring” and “Segment coloring” to “TransformInfo”. 11. In the “Align” toolbox, set “Align sections” to “All”. 12. Click “Auto­align”. Help Search terms: CreateSpatialGraphStack, “align toolbox” 4 5.3. Quantify inter-user differences in alignment
To quantify inter­user differences in alignment, do the following: 1. Main menu: Create → SpatialGraph → SpatialGraphAlignmentErrors 2. Select the SpatialGraphAlignmentErrors module. 3. In the properties area, under “File names” click “Browse”. 4. In the “Files List” dialog click “Add…”, and add the following files: ThalamoCorticalAxon/User1/S01­08_User1_aligned.am ThalamoCorticalAxon/User1/S01­08_User1_aligned.am ThalamoCorticalAxon/User1/S01­08_User1_aligned.am ThalamoCorticalAxon/User1/S01­08_User1_aligned.am ThalamoCorticalAxon/User1/S01­08_User1_aligned.am 5. In the properties area, click “Apply”. 6. The new “AlignmentTransformationComparison” spreadsheet contains tables for the relative (i.e. with respect to the previous section) translation and rotation, which were used for Table 3 in [1]. 7. For derived quantities, open the spreadsheet in Excel or similar application: File → Save Data as... Under “File type”, select “CSV (.csv)”, save, and open in the spreadsheet application. Use the appropriate functions to compute the (max­min) range and the standard deviation. Help Search terms: SpatialGraphAlignmentErrors 5.4. Interactive manual tracing
To interactively trace the landmark contours shown in Figure 3a of [1], perform the following steps: 1. Load the file LandmarkContours/Barrels_max_z_projection.am 2. Start the Filament Editor 3. Create a new SpatialGraph by clicking the “New” button under “Graph Data” 4. Adjust image contrast setting the “Window Level” range to 58­101 5. Activate the “View” toolbox by clicking “View” 6. In the “2D Settings box” set Node size to 10, “Line width” to 4. 7. Activate the “Trace” toolbox by clicking “Trace” 8. In the “Interactive Tracing” box, set “Tracing method” to “Linear”. 9. In the tool bar, activate the “Trace filament” tool. 10. Click on the image to place nodes along the barrel boundary. A new node is automatically connected to the previously created and automatically selected node. 11. To close the contour, click on the first node (an N appears at the mouse cursor when hovering over an existing node). 12. Adding a new node starts a new contour. To start a new contour without closing the first one, clear the selection first (shortcut: c). 5 5.5. Morphometric analysis: length density and profile
To visualize the length density and 1D profile along the z­axis (Figure 3c in [1]), do the following: 1. Activate the Object Pool, when not already visible. 2. Load the file MorphometricAnalysis/ExcitatoryNeuron_VentralPosteriorMedialN
ucleus_InRatThalamus.am. 3. Show the tracing: Right­click on the data object → SpatialGraphView. 4. Compute density: Right­click on the data object → Compute → SpatialGraphDensity. 5. Visualize density: Right­click on the data object → Display → Volren. 6. Select the Volren module (left­click). 7. In the Properties area, right­click on the color bar, select “physics.icol”. 8. Under “Color”, set the range from 0 to 100. 9. Set “AlphaScale” to 0.6. 10. Select the new SpatialGraphDensity Module. 11. In the Properties area, set “Bin size” to 50, 50, 50. 12. Click “Apply”. 13. Compute 1D profile: Right click on the new data → Compute → ProfileAlongAxis. 14. Select the the new module, under “Output” select “Scalar field”. 15. Click “Apply”. 16. Visualize the profile: Right click on profile data object → Display → Plot1DProfile. 17. Adjust camera: set camera to Orthographic, click the “View XZ” button. 18. Fine­tune axis display: select the Plot1DProfile, adjust the settings in the Properties area. Help Search terms: SpatialGraph, SpatialGraphView, SpatialGraphDensity, Volren, Plot1DProfile, “viewer window”, ProfileAlongAxis 6 5.6. Morphometric analysis: axon length within barrels
To create surfaces representing cortical barrel volumes, delineated by 2D contours, do the following: 1. Load the file MorphometricAnalysis/ExcitatoryPyramid_Layer5_InRatSomatosens
oryCortex.am 2. Activate the Filament Editor. 3. Activate the “Analysis” toolbox. 4. Select all barrel contours: In the Label viewer, click “Barrel”. 5. Create barrel surfaces: in the Analysis toolbox, in the “Column/Barrel Geometry” box, under “Surface”, click “Create” (surface creation takes some time). 6. Make the surfaces transparent: activate the Object pool, select the yellow SurfaceView module connected to the “Barrels.surf”. Set “Draw Style” to transparent. Adjust “Base trans”. To axon fragments contained in barrel columns, defined by extruding barrel contours along the z­axis (Figure 3b in [1]), do the following: 1. Load the file MorphometricAnalysis/ExcitatoryPyramid_Layer5_InRatSomatosens
oryCortex.am 2. Activate the Filament Editor. 3. Activate the “Analysis” toolbox. 4. Select “Axon” in the Label viewer. 5. Select one or more barrel contours: activate the “Single node, edge or point” selection tool. Click one or more barrel contours while holding Ctrl. 6. In the Analysis toolbox, in the “Column/Barrel Point Containment” box, under “Label edge points”, select “Above/below selected contour” and hit “Compute”. 7. In the View toolbox, set “Segment coloring” to “ColumnContainment”. 8. To obtain a spreadsheet with node/branch containment statistics, repeat steps 4 and 5, the in the “Column/Barrel Analysis box”, under “Branch/Node statistics”, select “Above/below selected contour”, and hit “Compute”. The spreadsheet appears in the Object pool. Help Search terms: “Analysis toolbox”, SurfaceView 7 5.7. Inter-user comparison of tracings
To reproduce the inter­user comparison results for the entire 8­section stack ([1], Table 2, S01­08, R=5 μm, D=2.5 μm), perform the following steps: 1. Main menu: Create → SpatialGraph → CompareSpatialGraphsByPointDistance 2. Select the new module. 3. In the properties area, select “N­Way” under “Comparison”. 4. Under “File names” click “Browse”. 5. In the appearing dialog, click “Add...” and add the following files from the ThalamoCorticalAxon directory: User1/S01­08_User1_smoothZ9_Zscale1_255887.am User2/S01­08_User2_smoothZ9_Zscale1_2539185.am User3/S01­08_User3_smoothZ9_Zscale1_255887.am User4/S01­08_User4_smoothZ9_Zscale1_2539185.am User5/S01­08_User5_smoothZ9_Zscale1_255887.am 6. Set “Maximum sampling distance” to 2.5. 7. Set “Maximum correspondence distance” to 5. 8. Click “Apply”. The tracings are displayed colored by the number of users that agreed on each point (Figure 8e in [1]). The “MatchStatistics” data object is a spreadsheet quantifying the agreement. To reproduce the numbers in the last row of Table 2: 1. Select the “MatchStatistics” spreadsheet. 2. Main menu: File → Save Data as... Under “File type”, select “CSV (.csv)”, and save. 3. Open the file in a spreadsheet application 4. For each user 1...5, add the cells “Length matched with 3, 4, and 5 other graphs”, divide by the “Total length” value, and multiply by 100%. The panels a, b, c, and f of Figure 8 and the other rows in Table 2 can be reproduced analogously by ● using the ThalamoCorticalAxon/UserX/S01_UserX.am data sets, ● setting the appropriate values of “Maximum sampling distance” and “Maximum correspondence distance”, ● removing the appropriate SpatialGraphView objects, and/or ● changing the camera direction to XY. Help Search terms: CompareSpatialGraphsByPointDistance 8 5.8. Tube rendering
There are two modules that can display SpatialGraphs with varying radius: LineRaycast and SpatialGraphView. To illustrate these, data from the Amira tutorial package is used, as the tracings in the data package described above do not contain radius information. Render tubes using the LineRaycast module: 1. Open <AmiraDir>/data/tutorials/neuron/Neuron­SpatialGraph.am 2. Right­click on data object → Display → LineRaycast. 3. Select LineRaycast module by left­clicking it. 4. In Properties area, set “Edge radius” to “point:thickness”. Render tubes using the SpatialGraphView module: 1. Open <AmiraDir>/data/tutorials/neuron/Neuron­SpatialGraph.am 2. Right­click on data object → Display → SpatialGraphView. 3. Select SpatialGraphView module by left­clicking it. 4. In Properties area, activate the “Tubes” checkbox under “Segment scale”. 5. Set “Tube scale” to “thickness”. Help search terms: SpatialGraph, SpatialGraphView, LineRaycast 5.9. NeuroML export
SpatialGraphs are exported to NeuroML as follows: 1. Open the file: MorphometricAnalysis/ExcitatoryPyramid_Layer5_InRatSomatosens
oryCortex.am 2. Main menu: File → Save data as … 3. In the “File type” menu select “NeuroML (.xml)”. 4. Click “Save”. Help search term: NeuroML 9