SNT: Manual

5,289 bytes added, 07:49, 15 August 2019
Tiago moved page SNT: Overview to SNT: Manual: Improve naming consistency
(Return to the main {{SNTNavBar}}[[Category:SNT]] page)[[Category:Neuroanatomy]]<div class="toclimit-32">
=Startup Prompt=
TBD[[Image:SNT-Startup-Prompt.png|right|thumb]]SNT is initialized by running {{bc|Plugins|NeuroAnatomy|SNT...}}. All the options in the startup prompt can be set once SNT is opened, but the startup prompt provides the convenience of setting the most important parameters at once.* '''Image'''/'''Image File''' The image to be traced/analyzed. The drop-down menu will list all images currently open in ImageJ. Alternatively, an image path may be specified by clicking ''Browse'' and choosing an image file. If no image is chosen, SNT will create an empty display canvas from the computed bounding box of the reconstruction file (if provided).* '''Reconstruction file''' The path of the reconstruction file to be imported. SNT will automatically try to guess if there is a reconstruction file associated with the chosen image by looking at all the reconstruction files (<tt>.traces</tt>, <tt>.(e)swc</tt>, or <tt>.json</tt>) in the image directory, and choosing one that more [ closely matches] the image filename.* '''User interface''' Specifies which views to display for 3D images. The default setting provides the XY, ZY, and XZ views and allows for more [[SNT:_Step-By-Step_Instructions#Accurate_Point_Placement|accurate node placement]] but requires more RAM.* '''Tracing Channel''' Specifies the image channel to trace on (this option is ignored with single-channel images). 
=Main Dialog=
==Menu Commands==
Lists commands for I/O operations. Most are self-explanatory. Noteworthy:
[[Image:SNT-From-Open-Image-Prompt.png|right|thumb|200px|]]* {{bc|Choose Tracing Image|&nbsp;}} TBDSpecifies the image to trace on without having to restart SNT. To trace on an image currently open in ImageJ, use ''From Open Image...''. A prompt with the currently open images will appear, allowing selection of one. To browse for an image file, use ''From File...''. You should toggle the ''validate spatial calibration'' checkbox to ensure the image to be imported is compatible with the existing one. * {{bc|Import| Labels (AmiraMesh)...}} TBDThis option assumes you are tracing on the same spatial coordinates of an annotated neuropil, for which compartments have been segmented (''labeled'') and stored in an [ Amira] labels file. Once loaded, SNT will report the name of the compartments in the ImageJ status bar when hovering over the image. [[Image:SNT-MouseLight-Remote-Loader-Prompt.png|right|thumb|200px|]]* {{bc|Import| Remote Databases|&nbsp;}} TBDAllows import of neuronal reconstructions from the [ FlyCircuit], [ MouseLight] and [ NeuroMorpho] remote databases.  * {{bc|Export (All Paths)|&nbsp;}} TBDAllows export of all traced paths in the [[SNT:_FAQ#swc|SWC]] file format, the most common format for representing neuronal reconstructions. Note that you can also export subsets of paths using the [[#Path Manager|Path Manager]]. Additionally, useful numeric properties of paths can be stored in a CSV file by choosing the ''CSV Properties...'' export option.<div align="left"><ul> <li style="display:inline-block;"> [[Image:SNT-Path-CSV-Properties-Example-Spreadsheet.png|none|thumb|600px|OP_1 CSV Properties snapshot in LibreOffice]] </li></ul></div>{{clear}} 
* {{bc|Choose Tracing ImageQuick Measurements|}} Shows a table with summary statistics for all existing paths. To measure only selected paths, use {{bc|Analyze|Measure}} TBDin the Path Manager. * {{bc|ImportSholl Analysis...}} Shows a help menu which describes how to conduct [[Simple_Neurite_Tracer:_Sholl_analysis| Labels (AmiraMesh)Sholl Analysis]] from within SNT on existing paths.<div align="left"><ul> <li style="display:inline-block;"> [[Image:SNT-Sholl-Analysis-How-to-Menu.png|none|thumb|200px]] </li></ul></div>* {{bc|Strahler Analysis}} TBDConducts Strahler Analysis on existing paths, producing a table of analysis results and a Strahler plot.<div align="left"><ul> <li style="display:inline-block;"> [[Image:SNT-Strahler-Analysis-Table.png|none|thumb|200px|Strahler Analysis table for OP_1]] </li><li style="display:inline-block;"> [[Image:SNT-Strahler-Analysis-Plot.png|none|thumb|200px|Strahler Analysis plot for OP_1]] </li></ul></div>* {{bc|ImportReconstruction Plotter...}} Plots a dynamic 2D projection of all existing paths. A control panel is included which allows adjustment of the spatial orientation of the tracing. If paths are assigned color tags, use {{bc| Remote DatabasesActions|Render final (colorized) plot}} TBDfrom the control panel to render the (static) plot with color-mapped paths, with the final orientation matching that of the dynamic plot.<div align="left"><ul> <li style="display:inline-block;"> [[Image:SNT-Reconstruction-Plotter-Example.png|none|thumb|200px]] </li><li style="display:inline-block;"> [[Image:SNT-Reconstruction-Plotter-Controls.png|none|thumb|200px]] </li><li style="display:inline-block;"> [[Image:SNT-Reconstruction-Plotter-Colored.png|none|thumb|200px]] </li></ul></div>* {{bc|Export (All Paths)Compare Reconstructions...}} Given two input reconstruction files, runs ''Quick Measurements'' on both and generates a plot with summary statistics, allowing for quick morphometric comparisons.<div align="left"><ul> <li style="display:inline-block;"> [[Image:SNT-Compare-Reconstructions-Table.png|none|thumb|600px|Comparison of OP_1 and OP_2]] </li></ul></div>{{clear}} TBD 
Contains commands for organizing tracing views on screen, plus commands for displaying cached data used for auto-tracing.
* '''Arrange Views''' Resets the view pane on-screen positions to their default.
* '''Hide Tracing Canvas''' Allows toggling of the visibility of the three view panes as well as the Legacy 3D View window.
* '''Show Cached ''Filtered Image''''' Displays the cached filtered image in a separate window. Note a filtered image must be loaded in order to use this feature. The process of loading a filtered image is detailed in [[SNT:_Step-By-Step_Instructions#Generating_Filtered_Images|Generating Filtered Images]].
* '''Show Cached ''Hessian Tubeness Image''''' Displays the cached ''Hessian (Tubeness) image'' in a separate window. Note there are two ways to enable this feature. Either 1) enable ''Hessian-based analysis'' then run the ''Cache All Hessian Computations'' command from the "Auto-tracing" gear drop-down menu or 2) use the ''Load Precomputed "Tubeness" Image'' option in the same gear menu. These features are detailed in the "Auto-tracing" section of the [[SNT:_Overview#Main_Dialog|Main Dialog]] overview guide.
==Main Tab==
Other options are also available in the ''gear'' drop-down menu:
* '''Cache All Hessian Cached Computations(Main/Secondary Image)''' By default SNT computes the Hessian matrix on a "compute-as-you-go" basis, which saves memory but increases the pathfinding time. If you have enough RAM, you can use this option set of options to compute once the matrix and once for the full image and cache the result, which in certain cases, can lead to almost-instantaneous searches. Note that this computation adopts the current values of sigma and max. reported in the widget, so you should adjust those before running this command. 
* '''Flush Cached Data''' Removes cached data from memory
* '''Load Precomputed "Tubeness Image"''' This (advanced) option prompts you to load a file of a ''Tubeness image'' generated elsewhere. This is useful if e.g., you want o experiment algorithms from other software packages, or your own. Note that loaded image is assumed to have compatible dimensions with the image currently being traced.
* '''Show Cached "Tubeness Image"''' Displays the ''Tubeness'' data currently cached. Useful for debugging purposes. Also mirrored in {{bc | View | Show Cached/Loaded Hessian (Tubeness) Image}}.
[[File:original-hessian-side-by-side.png|center|thumb|600px400px|Original (left) and Hessian (right) TBD: Replace with MIPsOP_1 "Tubeness" image overlay at 80% opacity]]
===Tracing on Filtered Secondary Image===This is one of SNT's most advanced features. [[#Auto-tracing|Hessian-based analysis]] provides a convenient and easy way to perform auto-tracing on pre-process processed data in which voxels defining the traced structure are scored by their likelihood of ''belonging'' to a tube-like structure. However, it is just one approach for "tubeness" classification. What if your data requires different filtering?, or you want to experiment with other approaches?, or the perfect pre-processing algorithm for your images is not yet available in ImageJ? ''Tracing on Filtered Secondary Image'' is the answer to these questions: It allows you to feed SNT with pre-processed data on which the A*star search will operate. Here are two specific usages for this option:
*'''Frangi ''Vesselness'' filtering''' For certain datasets Frangi filtering ([ Frangi et al. 1998]) is more effective than [[Tubeness]] at enhancing tube-like structures in the image. However, it is more computation intensive, and thus, less suitable to be adopted by the "compute-as-needed" approach used in Hessian-based analysis. Thus, one can import a pre-computed Frangi-filtered image using this option.
*'''Hessian-analysis at multiple scales''' Let's consider a structure formed simultaneously by very thick and very thin processes(e.g. axons and dendrites). To trace it one would need to adjust continuously the sigma parameter while tracing. Instead, to trace structures of variable diameters more effectively, one could load a copy of the Hessian current image associated with the second sigma could be loaded as ''Filtered Imagesecondary image'', and assign different hessian parameters to both images.
*'''Adopting probability maps''' Pre-classified images (using e.g., machine learning) could also be loaded here.
Importantly, this option can be toggled at will, during tracing. Indeed, one can ping-pong between ''filtered secondary image'' and tracing main image simply, by pressing {{key|I}}, the shortcut for the ''Trace on filtered Secondary '''I'''mage'' checkbox.
'''Filtered Secondary Image options''' can be specified in the ''gear'' drop-down menu, including commands for Loading/displaying the image file and the powerful ''Generate Filtered Secondary Image'' command:
TBD[[Image:SNT-Tracing-On-Filtered-Image-Gear-Options.png|right|thumb|200px]][[Image:SNT-Generate-Filtered-Image-Prompt.png|right|thumb|200px]]* '''Load Specified File''' Loads the filtered image specified in the ''File'' textbox. * '''Generate Secondary Image''' Enables processing of the currently open image directly from SNT. Three routines are currently supported: ''Frangi'', ''Frangi (without Gaussian)'' and ''Tubeness''. Supports saving and display of the resulting image. To use the currently open image as the secondary image, choose ''None. Duplicate Primary Image''. Noteworthy: It is assumed that the current sigma value in the Auto-tracing widget reflects the size of structures to be filtered. If that is not the case, the sigma should be adjusted before running this command.* '''Adjust Min-Max''' Sets the range of pixel intensities used by A* search. * '''Show Cached image''' Displays the currently loaded filtered image in a separate window.* '''Show Path in File Explorer''' Opens the directory containing the filtered image specified in the ''File'' textbox in the File Explorer GUI.
See the [[SNT:_Step-By-Step_Instructions#Generating_Filtered_Images|Generating Filtered Images]] walk-through for more details.
===Filters for Visibility of Paths===
By default, all the entire nodes of a path is are projected onto the current Z-slice. This is useful to see how much has been completed and gives a sense of the overall structure of the reconstruction. However, SNT provides 3 three additional visibility options for paths:
[[File:Path-visibility-filters.png|right|thumb|"Filters for visibility of paths" widget]]
# '''Only selected paths (hide deselected)''' Only show paths that have been manually selected in the Path Manager or with the {{Key|G}} key ({{Key|Shift}}+{{Key|G}} to select multiple paths).
# '''Only nodes within X nearby Z-slices''' Only highlight nodes within X number of Z-slices on either side of the current slice. The projected skeletons of all paths remain visible.
# '''Only paths from active channel/frame''' If tracing on a multichannel image or an image with a time axis, only show paths from the active channel or frame.
Any combination of these options may be toggled simultaneously. Note that these options do not apply to [[SNT:_Reconstruction_Viewer|Rec. Viewer]] and [[SciView]].
===Default Path Colors===
By default, finished paths are colored by their selection status (only selected paths can be edited, or extended). The default colors are <font color="#00FF00">Green</font> (selected paths) and <font color="#FF00FF">Magenta</font> (deselected). Default colors can be customized by pressing the respective button in the widget and using the [ CMYK color chooser]. For customizing unconfirmed and temporary paths, see the ''Colors'' option in the [[#UI_Interaction|UI Interaction]] widget.
'''Enforce default colors (ignore color tags)''' If active, SNT will force all paths to conform to the default "Selected" and "Deselected" color buttons. Any custom color tags will be ignored until the option is toggled off. Note that this options does not apply to [[SNT:_Reconstruction_Viewer|Rec. Viewer]] and [[SciView]].
{{Tip| id = coloring-paths|tip = The [[#Path Manager|Path Manager]] offers several ways to colorize Paths: 1) Using {{bc | Tag | Color}} swatches (custom colors can be temporarily assigned to empty swatches, by right-clinking on them) or 2) Using {{bc|Analyze|Color Coding}}, providing morphometric-based [[SNT:_Overview#Analyze|color mapping]]. Note that Path Manager commands are applied to all paths if no no path(s) are selected.
SNT can use the fluorescent signal around traced paths to optimize curvatures and estimate the thickness of traced structuresto sub-voxel accuracy. The optimization algorithm uses pixel intensities to fit circular cross-sections around each node. Once computed, fitted cross-sections can be used to: 1) Infer the radius of nodes, and/or 2) refine node positioning, by snapping their coordinates to the cross-section centroid. The {{bc|Refine/Fit|&nbsp;}} menu contains three entries:
[[File:Explore-fit-preview.png|right|thumb|250px|Slice in "Explore/Preview Fit" image stack]]
* '''Fit Paths/Un-fit paths/Apply Existing Fit''' This option will change depending on which paths are currently selected. You can use it to 1) Fit selected paths, 2) un-fit paths that have already been fitted, or 3) apply a generated preview of the fit.
==Filter Toolbar==
[[File:SNT-Path-Manager-Text-Filter.png|right|thumb|Text Filter]]The text filter toolbar allows paths to be searched by any characters in the path name string and by colorfiltered quickly using tags (colors, annotations, SWC-type, etc.) or morphometric properties. The name string includes all tagstext field is used for text-based searches (recent searches can be recovered through its drop-down menu).* '''Up Arrow Button''' The [[File:SNT-Text-Filter-Up-Arrow-Button.png]] Finds next occurrence of the entered phrase.* '''Down Arrow Button''' and [[File:SNT-Text-Filter-Down-Arrow-Button.png]] Finds buttons find the next/previous occurrence of the entered phrase.* '''Balloon Button''' (shortcuts: {{key|up}} {{key|down}}), while the [[File:SNT-Text-Filter-Balloon-Button.png]] Highlights button highlights all occurrences of the entered phrase.{{clear}} [[File:SNTSettings for advance text-Path-Manager-Filtering-Menu.png|right|thumb|"Advanced Filtering Menu"]]The Advanced Filtering Menu based filtering can be accessed through the [[File:SNT-Text-Filter-Advanced-Button.png]] provides more sophisticated means of filtering paths, including wildcard support for wildcards (?*), color case sensitive matching, and morphology tag matchingreplace-by-pattern.[[File:SNT-In addition, the ''Advanced-Text-Filtering-Text-Filtering-Menu.png|right|thumb|"Text Filtering" menu]]'' [[File:SNT-Path-Manager-Text-Filter-ReplaceAdvanced-PromptButton.png|right|thumb|"Replace" prompt]]* '''Text Filtering''' Contains options for advanced text provides other sophisticated means of filtering** ''Case Sensitive Matching'' treats uppercase and lowercase characters as distinct.** ''Enable Wildcards'' Allows the use of the question mark (?) and asterisk (*) wildcards.*** ''"?"'' Matches exactly one character. For example, the pattern 123? will match 123 and 1234, but not 12345. *** ''"*"'' Matches zero or more characters. For example, doc* matches doc and document but not dodo.** ''Loop After First/Last Hit'' Cycles back to the first/last matched phrase upon pressing the Up/Down Arrow Button at the end of the list of matches.** ''Display No. of Matches'' Displays the number of phrase matches in the bottom left corner of the Path Manager dialog.** ''Replace'' Replaces all occurrences of the matched phrase in the path name string for currently selected paths. ** ''Clear History'' Erases the previously searched phrases in the text filter drop-down menu.** ''Tips & Shortcuts''*** Case-insensitive by default. Wildcards ? (any character), and * (any string) can also be used.*** Press the ''Highlight All'' button or Ctrl+A to select all the paths filtered by the search string.*** Press and hold Ctrl while pressing the up/down keys to select multiple filtered paths.*** Press the up/down keys to find the next/previous occurrence of the filtering string.*** Uncheck ''Display No. of Matches'' to improve search performance.:
[[File:SNT-Path-Manager-Text-Filter-Color-Filters.png|right|thumb|"Color Filters" menu]]
* '''Color Filters''' Allows filtering of paths by color codetags. Custom colors may be selected by right-clicking an empty swatch, which will bring up the CMYK palette. The chosen color is temporarily saved in that swatch.{{clear}}[[File:SNT-Path-Manager-Morphology-Filters.png|right|thumb|"Morphology Filters" menu]]* '''Morphology Filters''' Allows filtering of paths by select selected morphological properties. Note that these filters do not require paths to be labeled using {{bc|Tag|Morphology|&nbsp;}}.** ''Branch Order'' Filters for paths of [[Strahler Analysis|branch order ]] in the inputted range. Note that the paths of interest must have ''Branch Order'' tags. To tag paths with their centrifugal branch orders, use {{bc|Tag|Morphology|Branch Order}}. See [[SNTExample queries: <tt>1-2</tt>: selects all primary and secondary branches; <tt>max-max</tt>:_Overview#Tag|Tag]] for more informationselects all terminal branches. ** ''Length'' Filters for paths of length within the inputted range. Note that the paths of interest must have ''Length'' tags. To tag Example queries: <tt>10-20</tt>: selects all paths with their length, use {{bc|Tag|Morphology|Length}}. See [[SNTlengths between 10 and 20μm; <tt>max-max</tt>:_Overview#Tag|Tag]] for more informationselects the longest path(s). ** ''Mean Radius'' Filters for paths of mean radius within the inputted range. Note that the paths of interest must have ''Mean Radius'' tags. To tag paths with their mean radius, use {{bc|Tag|Morphology|Mean Radius}}. See [[SNT:_Overview#Tag|Tag]] for more information.
** ''No. of Nodes'' Filters for paths with node count within the inputted range.
** ''SWC Type'' Filters for paths with the selected SWC type tags. Note that the paths of interest must have ''Type'' tags. To tag paths with SWC types, use {{bc|Tag|Type}}. See been [[SNT:_Overview#Tag|Tagtagged]] for more informationusing the{{bc|Tag|Type|&nbsp;}} menu.
<div align="center">
=Fill Manager=
Provides controls for all filling operations. It is described in more detail in the [[SNT:_Step-By-Step_Instructions#Filling|Filling: Step-By-Step Instructions]].