Merge pull request #363 from imagej/snt-root-angles

snt: document  root angle analysis

Author: tferr

_pages/plugins/snt/analysis.md

@@ -37,6 +37,25 @@ With histograms, normal distribution curves and quartile marks can be overlaid o
 </p>
 "%}
 
+
+# Comparing Reconstructions
+
+<img align="right" width="300px" src="/media/plugins/snt/snt-compare-groups-prompt.png" title=" " />
+SNT can compare up to six groups of cells. The entry point for this type of comparison is twofold:
+- **{% include bc path='Utilities|Compare Reconstructions/Cell Groups...'%}** in the main SNT dialog. This includes a convenience option to compare single reconstruction files.
+- **{% include bc path='Neuronal arbors|Load & Compare Groups...'%}** in Reconstruction Viewer, allowing groups to be tagged, and imported into a common scene while being compared.
+
+The dialog  prompt for this feature allows selection of up to six directories containing reconstruction files (SWC, TRACES, JSON, NDF). The metric to compare against is chosen from the *Metric* drop-down menu. Optionally, it is possible to  restrict the analysis to specific neurite compartments. After making your selections, press *OK* to run the analysis. The result typically includes:
+
+- A simple statistical report, including descriptive statistics and a two-sample t-test (when comparing two groups) or one-way ANOVA (when comparing three or more groups)
+- Comparison plots for the chosen metric: Grouped histogram and boxplot
+- _Montages_ of groups. These are multi-panel vignettes of up to 10 group exemplars. These can all be exported as PDF, PNG, or SVG
+
+{% include img align="center" src="/media/plugins/snt/snt-compare-reconstructions-overview.png" caption="Comparing _No. of branches_ between two cell groups: Overview of outputs."%}
+
+{% include notice icon="info" content="SNT performs statistical tests without verifying if samples fulfill basic test-criteria (e.g., normality, variance homogeneity, sample size, etc.)" %}
+
+
 # Convex Hull Analysis
 _Convex hull_ commands (in SNT  main dialog, [Rec. viewer](/plugins/snt/reconstruction-viewer) and [Rec. plotter](/plugins/snt/manual#plotter)) compute the 2D or 3D convex hull of a reconstruction (i.e., the smallest convex polygon/polyhedron that contains the nodes of its paths). Convex hull measurements are defined in [Metrics](/plugins/snt/metrics#convex-hull-boundary-size).
 
@@ -209,22 +228,23 @@ In addition, SNT also implements descriptors based on persistence landscapes, as
 
 Currently, _basic_ persistence homology descriptors can be computed using UI commands {% include bc path='Analysis|Persistence Homology...'%} (main interface), or {% include bc path='Analyze & Measure|Persistence Homology...'%} in [Rec. viewer](/plugins/snt/reconstruction-viewer). Complete extraction of descriptors can be obtained with [scripting](/plugins/snt/scripting).  See e.g.,  the *Persistence Landscape* [notebook](https://github.com/morphonets/SNT/blob/main/notebooks/).
 
-# Comparing Reconstructions
 
-<img align="right" width="300px" src="/media/plugins/snt/snt-compare-groups-prompt.png" title=" " />
-SNT can compare up to six groups of cells. The entry point for this type of comparison is twofold:
-- **{% include bc path='Utilities|Compare Reconstructions/Cell Groups...'%}** in the main SNT dialog. This includes a convenience option to compare single reconstruction files.
-- **{% include bc path='Neuronal arbors|Load & Compare Groups...'%}** in Reconstruction Viewer, allowing groups to be tagged, and imported into a common scene while being compared.
+# Root Angle Analysis
+Root angle analysis measures the angular distribution of how far neurites deviate from a direct path to the soma (or rootof the neuronal arbor), a functional property that is captured by [Sholl profiles](#sholl-analysis). It quantifies properties such as [balancing factor](./metrics#root-angles-balancing-factor), [centripetal bias](./metrics#root-angles-centripetal-bias), and [mean direction](./metrics#root-angles-mean-direction). It is described in:
 
-The dialog  prompt for this feature allows selection of up to six directories containing reconstruction files (SWC, TRACES, JSON, NDF). The metric to compare against is chosen from the *Metric* drop-down menu. Optionally, it is possible to  restrict the analysis to specific neurite compartments. After making your selections, press *OK* to run the analysis. The result typically includes:
+{% include citation doi='10.1016/j.celrep.2019.04.097' %}
 
-- A simple statistical report, including descriptive statistics and a two-sample t-test (when comparing two groups) or one-way ANOVA (when comparing three or more groups)
-- Comparison plots for the chosen metric: Grouped histogram and boxplot
-- _Montages_ of groups. These are multi-panel vignettes of up to 10 group exemplars. These can all be exported as PDF, PNG, or SVG
+A root angle is defined as the angle between a neurite segment (defined centripetally from the termination point to the soma) and the direct path to the soma or root (see [Bird and Cuntz 2019](https://pubmed.ncbi.nlm.nih.gov/31167149/)). The analysis proceeds as follows:
 
-{% include img align="center" src="/media/plugins/snt/snt-compare-reconstructions-overview.png" caption="Comparing _No. of branches_ between two cell groups: Overview of outputs."%}
+- Root angles are computed centripetally for every node in the arbor in centripetal sequence (from tips to root)
 
-{% include notice icon="info" content="SNT performs statistical tests without verifying if samples fulfill basic test-criteria (e.g., normality, variance homogeneity, sample size, etc.)" %}
+- The distribution of root angles is fitted to a [von Mises distribution](https://en.wikipedia.org/wiki/Von_Mises_distribution), a specialized probability distribution that models angles/directions. von Mises can be considered a 'wrapped normal', or a circular analogue of the normal distribution, as it addresses the issue of "wrapping" that occurs when dealing with angles revolving around a circle where 0° and 360° (2π) are the same. 
+
+- [Centripetal bias](./metrics#root-angles-centripetal-bias), [Balancing factor](./metrics#root-angles-balancing-factor), and [Mean direction](./metrics#root-angles-mean-direction) are then computed from the von Mises fit
+
+The analysis can be performed from the [Analysis menu](/plugins/snt/manual#root-angle-analysis) in the main dialog, Reconstruction Viewer's [Analyze & Measure](/plugins/snt/reconstruction-viewer#analyze--measure) menu, or [template scripts](/plugins/snt/scripting#bundled-templates). The screenshot below depicts the output of the *Analysis › Root Angle Analysis* template script:
+
+{% include img align="fit" src="/media/plugins/snt/snt-root-angle-analysis.png" %}
 
 # Other Specialized Analyses
 See [SNT Scripting](/plugins/snt/scripting), as well as script templates demonstrating a range of analysis possibilities.

_pages/plugins/snt/comp-tools.md

@@ -0,0 +1,28 @@
+---
+title: SNT › Complementary Tools
+nav-links: true
+nav-title: Comp. Tools
+artifact: org.morphonets:SNT
+icon: /media/icons/snt.png
+forum-tag: snt
+update-site: Neuroanatomy
+---
+
+### ImageJ Ecosystem
+
+| Tool | Description | Comments |
+|------|-------------|----------|
+| [Spot Spine](/plugins/spot-spine) | Detection and count dendritic spines, segmentation of spine heads, and quantitative morphological measurements of spines | Under active development |
+| [BigTrace](/plugins/bigtrace) | Semi-automated tracing in 3D using BigVolumeViewer | Under active development |
+| [NeuronJ](/plugins/neuronj) | Semi-automated tracing in 2D only | No longer maintained. SNT reads NDF files |
+
+
+### Other
+
+| Tool | Description |
+|------|-------------|
+| [BICCN Tools](https://biccn.org/tools) | List of tools supporting NIH's Brain Research through Advancing Innovative Neurotechnologies (BRAIN) Initiative - Cell Census Network (BICCN) |
+| [Blue Brain's Morphology Suite](https://github.com/BlueBrain/morphology-suite) | Blue brain's collection of tools (mostly Python) to build, analyze and visualize morphologies. Currently supported by the [Open Brain Institute](https://www.openbraininstitute.org/) |
+| [HBP Morphology Viewer](https://neuroinformatics.nl/HBP/morphology-viewer/)| WebGL-based viewer with Allen Cell Types and Neuromorpho.org integration |
+| [L-measure](http://cng.gmu.edu:8080/Lm/) | Classic toolkit for quantitative analyzes of neuronal reconstructions of neurons (cf. [metrics](metrics)) |
+| [natverse](https://natverse.org/) | Complete neuroanatomical data analysis in R |

_pages/plugins/snt/faq.md

@@ -16,11 +16,11 @@ See [Installation details](/plugins/snt/index#installation).
 
 ### How do I cite SNT?
 
-**The proper citation for SNT is**:
+**Note that neither the main [Fiji article](/software/fiji#publication), nor the first [Simple Neurite Tracer](#what-is-the-difference-between-snt-and-simple-neurite-tracer) publication are appropriate citations for SNT. The proper citation for SNT is**:
 
 - {% include citation id='plugins/snt' %}
 
-**Note that neither the main [Fiji article](/software/fiji#publication), nor the first [Simple Neurite Tracer](#what-is-the-difference-between-snt-and-simple-neurite-tracer) publication are appropriate citations for SNT**. To reference additional modules that enhance SNT:
+In addition, you should also cite any additional modules that you may use:
 
 - **[Sholl Analysis](/plugins/snt/sholl)**
   {% include citation id="plugins/sholl-analysis" %}

_pages/plugins/snt/key-shortcuts.md

@@ -8,22 +8,17 @@ forum-tag: snt
 update-site: Neuroanatomy
 ---
 
+
 {% capture text%}
 Most SNT features are triggered by keyboard shortcuts. Shortcuts are typically single keystrokes and most do not require other modifier keys to be pressed. Most are highlighted in the user interface. E.g., to toggle the *Trace/Fill on Secondary <u>L</u>ayer* checkbox, one only needs to press its highlighted letter, i.e., {% include key key='L' %}.
-<br><br>
+
+{% include img src="/media/plugins/snt/command-palette.png" align="right" width="450px" %}
 _Typically_, when {% include key keys='ctlcmd' %} is pressed, hotkeys are not intercepted by SNT. E.g., During a tracing session pressing {% include key key='N' %} triggers <u>N</u>o* in the interactive prompt while {% include key keys='ctlcmd|N' %} will trigger IJ's built-in command {% include bc path='File|New|image...'%}.
+<br><br>
+If you are not familiar with SNT commands the [Command Palette](manual#command-palette) ({% include key keys='ctlcmd|Shift|P' %}) is the fastest way to access actions and discover their respective shortcuts!
 {% endcapture %}
 {% include notice icon="info" content=text %}
 
-{% capture cmdpalette%}
-{% include img src="/media/plugins/snt/command-palette.png" align="right" width="450px" %}
-The Command Palette is the fastest way to access actions and discover their respective shortcuts:
-1. Press {% include key keys='ctlcmd|Shift|P' %} in either SNT or Reconstruction Viewer
-2. Start typing to filter actions, scripts and available commands
-3. Press {% include key keys='up' %} or {% include key keys='down' %} to select a command (or use the  {% include key keys='mouse wheel' %})
-4. Press {% include key keys='Enter' %} to run it
-{% endcapture %}
-{% include notice  icon="info" content=cmdpalette %}
 
 ### Interactive Prompt
 

_pages/plugins/snt/manual.md

@@ -89,7 +89,7 @@ This option assumes you are tracing on the same spatial coordinates of an annota
 
 #### Load Demo Dataset...
 
-Loads a demo dataset (a tracing image, a reconstruction, or both). Use this to familiarize yourself with the software, explore [Walk‑throughs](/plugins/snt/walkthroughs), and to create [Minimal reproducible example](https://en.wikipedia.org/wiki/Minimal_reproducible_example) when reporting problems. The bottom part of the dialog describes each dataset including source, citation, and DOI (when available). Note that while some of the data is bundled with SNT, the majority of the datasets is downloaded from remote servers (internet connection required).
+Loads a demo dataset (a tracing image, a reconstruction, or both). Use this to familiarize yourself with the software, explore [Walk‑throughs](/plugins/snt/walkthroughs), and to create [Minimal reproducible examples](https://en.wikipedia.org/wiki/Minimal_reproducible_example) when reporting problems. The bottom part of the dialog describes each dataset including source, citation, and DOI (when available). Note that while some of the data is bundled with SNT, the majority of the datasets is downloaded from remote servers (internet connection required).
 
 #### Save Tracings ›
 
@@ -117,17 +117,19 @@ Resets all preferences and restarts SNT using default options. It is recommended
 ### Analysis ›
 
 #### Atlas-based ›
-See [Atlas-based Analysis](/plugins/snt/analysis#atlas-based-analysis).
+See [Analysis › Atlas-based Analysis](/plugins/snt/analysis#atlas-based-analysis).
 
 #### Path-based ›
-See [Path-based Analysis](/plugins/snt/analysis#path-based-analysis).
+See [Analysis › Path-based Analysis](/plugins/snt/analysis#path-based-analysis).
 
 #### Convex Hull
-See [Convex hull Analysis](/plugins/snt/analysis#convex-hull-analysis).
+See [Analysis › Convex hull Analysis](/plugins/snt/analysis#convex-hull-analysis).
 
 #### Persistence Homology
-See [Persistence Homology Analysis](/plugins/snt/analysis#persistence-homology).
+See [Analysis › Persistence Homology Analysis](/plugins/snt/analysis#persistence-homology).
 
+#### Root Angle Analysis
+See [Analysis › Root Angle Analysis](/plugins/snt/analysis#root-angle-analysis).
 
 #### Sholl Analysis.../Sholl Analysis (by Focal Point)...
 
@@ -154,9 +156,11 @@ The Command Palette is the fastest way to access actions and discover their resp
 
 1. Press {% include key keys='ctlcmd|Shift|P' %} in either SNT or [Reconstruction Viewer](/plugins/snt/reconstruction-viewer)
 2. Start typing to filter actions, scripts and available commands
-3. Press {% include key keys='up' %} or {% include key keys='down' %} to select a command (or use the  {% include key keys='mouse wheel' %})
+3. Press {% include key keys='up' %} or {% include key keys='down' %} (or use the  {% include key keys='mouse wheel' %}) to select a command 
 4. Press {% include key keys='Enter' %} to run it. If the record button is toggled, executed commands are recorded by the [Script Recorder](/plugins/snt/scripting#script-recorder).
 
+By default, commands and actions are filtered using approximate string matching. Exact matching can be enabled by toggling the _Match Case/Whitespace_ buttons. Press the &nbsp;<i style="color:gray;" class="fas fa-map-pin"></i>&nbsp; button to display the Command Palette above all windows. Press the &nbsp;<i style="color:gray;" class="fas fa-lock"></i>&nbsp; button to keep the Palette open after running a command.
+
 
 #### Compare Reconstructions/Cell Groups...
 Allows morphometric comparisons of two single reconstruction files or multiple groups of reconstruction files (including statistical reports and two-sample t-test/one-way ANOVA analysis). Color-coded montages of analyzed groups can also be generated. See [Comparing Reconstructions](/plugins/snt/analysis#comparing-reconstructions) for details.