snt: describe delineation analysis

_pages/plugins/snt/analysis.md

@@ -231,6 +231,15 @@ 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/).
 
+# Delineation Analysis
+
+Delineations allow measuring proportions of recontructions within other structures defined by ROIs or neuropil annotations (e.g., cortical layers, biomarkers, or counterstaining landmarks). Some of the questions that delineation analyses can answer include:
+
+- Do branching patterns of neurons change along strata (cell layers)?
+- Do branches near a lesion site differ from branches further away from it?
+- Are there morphological differences across subregions of a neuron's receptive field?
+
+Delineations are described in [Walkthroughs › Delineation Analysis](/plugins/snt/walkthroughs#delineation-analysis).
 
 # 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:

_pages/plugins/snt/key-shortcuts.md

@@ -112,7 +112,7 @@ See [sciview](/plugins/sciview)'s {% include bc path='Help| '%}menu for a full l
 
 ### Legacy 3D Viewer
 
-The most important shortcuts for the [Legacy 3D viewer](/plugins/snt/walkthroughs#legacy-3d-viewer) are:
+The most important shortcuts for the [Legacy 3D viewer](/plugins/snt/walkthroughs#tracing-in-the-legacy-3d-viewer) are:
 
 | {% include key key='H' %} | Selects the <u>H</u>and (pan) tool |
 | {% include key key='W' %} | Selects the <u>W</u>and (tracing) tool |

_pages/plugins/snt/manual.md

@@ -483,6 +483,7 @@ The Legacy 3D Viewer is a functional tracing canvas and allows images to be trac
 
 This tab hosts the Bookmark Manager, a utility that stores image locations to be (re)visited during tracing (e.g., a location of an ambiguous branching point or an ambiguous cross-over between two neurites). Bookmarked locations can also be used as [spine/varicosity markers](/plugins/snt/walkthroughs#spinevaricosity-analysis). The basic usage is as follows:
 
+<img align="right" width="300" src="/media/plugins/snt/snt-delineations-tab.png" title="Delineations tab" />
 <img align="right" width="300" src="/media/plugins/snt/snt-bookmarks-tab.png" title="Bookmarks tab" />
 
 - Right-click on the image and choose {% include bc path='Bookmark Cursor Position' %} from the image contextual menu (shortcut: {% include key key='Shift|B' %}). A new bookmark will be added logging the cursor's X, Y, Z, C, T coordinates
@@ -496,6 +497,13 @@ This tab hosts the Bookmark Manager, a utility that stores image locations to be
 
 - Use {% include bc path='Export...' %} to save the current list to either: 1) a CSV file, 2) ImageJ's ROI Manager or 3) the overlay of the active image. Note that when images are saved as TIFF, ROIs are saved in the file's header, and automatically loaded by ImageJ when the image is open.
 
+
+<span id="delineations"></span>
+<span id="delineations-manager"></span>
+
+## Delineations Tab
+This tab hosts the Delineations Manager, a utility that allows measuring proportions of paths within other structures defined by ROIs or neuropil annotations (e.g., cortical layers, biomarkers, or counterstaining landmarks). Delineation analyses are described in detail in [Walkthroughs › Delineation Analysis](/plugins/snt/walkthroughs#delineation-analysis).
+
 ## Status Bar
 The status bar at the bottom of the Main Dialog displays brief messages about ongoing operations. By default, the status bar reports the image title and the CT position being traced.
 

_pages/plugins/snt/metrics.md

@@ -81,11 +81,17 @@ The extent to which the [convex hull](#convex-hull) approaches a rectangle (if 2
 ###### Convex hull: Centroid-root distance
 The distance between the root of a neuronal arbor and the centroid of its [convex hull](#convex-hull)
 
+###### Convex hull: Compactness
+The ratio between $$area^3/volume^2$$ of the 3D [convex hull](#convex-hull), normalized so that a sphere has a compactness value of 1. Defined in [Bribiesca E, 2008](https://doi.org/10.1016/j.patcog.2007.06.029). Not applicable to 2D convex hulls. Range of values: 0--1 (unitless)
+
+###### Convex hull: Eccentricity
+Defined as $$\sqrt{1 - \left(\frac{b}{a}\right)^2}$$, where $$a$$ and $$b$$ are the semi-major and semi-minor axes of the 2D [convex hull](#convex-hull). Not applicable to 3D Convex hulls. An eccentricity of 0 corresponds to a perfect circle. An eccentricity close to 1 indicates a highly elongated ellipse. Unitless
+
 ###### Convex hull: Elongation
-The [caliper (also known as Feret) diameter](https://en.wikipedia.org/wiki/Feret_diameter) of the [convex hull](#convex-hull)
+The [caliper (Feret) diameter](https://en.wikipedia.org/wiki/Feret_diameter) of the [convex hull](#convex-hull)
 
 ###### Convex hull: Roundness
-The extent to which the [convex hull](#convex-hull) approaches a circle (2D) or a sphere (3D). Range of values: 0--1 (unitless)
+The extent to which the [convex hull](#convex-hull) approaches a circle (i.e., circularity in 2D) or a sphere (i.e., sphericity in 3D). Range of values: 0--1 (unitless)
 
 ###### Convex hull: Size
 Either the area of the 2D polygon, or the volume of the 3D polyhedron defining the [convex hull](#convex-hull)

_pages/plugins/snt/walkthroughs.md

@@ -143,6 +143,7 @@ Accurate node placement requires <em>XY</em>, <em>ZY</em> and <em>XZ</em> views
   </tbody>
 </table>
 
+<span id="legacy-3d-viewer"></span>
 ## Tracing in the Legacy 3D Viewer
 
 The legacy 3D Viewer allows for tracing in an interactive 3D scene.
@@ -291,7 +292,7 @@ NB:
 
 # Time-lapse analysis
 {% capture timelapse-demo%}
-There are two demo datasets ({% include bc path='File|Load Demo Dataset...' %}) you can use to follow these instructions:
+You can use one of two demo datasets ({% include bc path='File|Load Demo Dataset...' %}) to follow these instructions:
 - _Hippocampal neuron (DIC timelapse)_ dataset: A timelapse video of a cultured neuron in which neurites have been pre-traced across time
 - _Segmented video (2D timelapse)_ dataset: A small, thresholded video of a cultured neuron processed by a script that automates tracing at each frame
 {% endcapture %}
@@ -445,6 +446,76 @@ Currently, only the output images/CSV summary of fills can be exported. TRACES f
 {% endcapture %}
 {% include notice icon="info" content=text %}
 
+# Delineation Analysis
+Delineations aggregate sections of reconstructions into groups to allow measuring proportions of paths within other structures defined by ROIs or neuropil annotations (e.g., cortical layers, biomarkers, or counterstaining landmarks). Delineation analyses can be applied to disconnected paths, a single cell, or multiple cells. Some of the questions that delineation analyses can answer include:
+
+- Do branching patterns of neurons change along strata (cell layers)?
+- What is the total dendritic/axonal length contained within a cortical layer?
+- Do branches near a lesion site differ from branches further away from it?
+- Are there morphological differences across subregions of a neuron's receptive field?
+
+{% capture ml-demo %}
+You can use the _MouseLight dendrites_ demo dataset to follow the delineation tutorials. While this dataset does not include counterstaining images, it can still be used for both ROI-based and Atlas-based delineations:
+
+1. Open {% include bc path='File|Load Demo Dataset...' %} and choose _MouseLight dendrites (Reconstructions only)_
+2. Right-click on the _Display Canvas_ and choose _Pause SNT_ from the contextual menu
+3. Follow the instructions below
+{% endcapture %}
+{% include notice icon="info" content=ml-demo %}
+
+<div align="center">
+  <img  src="/media/plugins/snt/snt-delineation-analysis.png" title="Delineation Analysis: MouseLight dendrites demo dataset delineated by cortical layers " width="650" />
+</div>
+
+## Creating Delineations from ROIs
+The most common way to generate delineations is by means of ROIs:
+
+1. Activate the _Delineations_ tab in the [main dialog](/plugins/snt/manual#delineations-tab)
+
+2. Pause SNT by right-clicking on the image and choose "Pause SNT" from the contextual menu
+
+3. Create an area ROI. _Any_ area ROI is supported (freehand, polygon, wand-defined, rectangular, oval, etc.)
+
+4. Press the _Assign_ button. Sections of paths with XY coordinates contained by the ROI are colored by the delineation label. Note that assignments propagate to all Z-coordinates within the ROI
+
+5. Optional: If you prefer, press the <i class="fas fa-pen"></i> icon and type a new label in the _name_ field You can also change the delineation color by clicking its color tag
+
+6. Repeat this process as needed until all paths of interest have been tiled by a delineation. If needed, visibility of previously assigned ROIs can be toggled using the <i class="fas fa-eye"></i> button
+
+7. Proceed to [Measuring Delineations](#measuring-delineations)
+
+ROIs generated programmatically or in bulk outside SNT can be applied in a single step using _Import Assignments from ROI Manager_ from the Options (gear) menu. This command will parse each area ROI in the ROI Manager as an assignment ROI. The delineation name and color will be retrieved directly from ROIs that have been renamed or colored (either stroke or fill color).
+
+
+## Creating Delineations from Atlas Annotations
+Delineations can also be created from [neuropil annotations](/plugins/snt/analysis#atlas-based-analysis) using the _Import Assignments from Atlas Annotation_ option from the Options (gear) menu. In this case delineations are created from selected brain compartments associated with the cell(s) being analyzed. Note that this requires cells to be tagged by atlas annotations. Currently only cells downloaded directly from the MouseLight database fullfill this criterion.
+
+
+## Editing Delineations
+To re-define a delineation it is sufficient to re-define or re-adjust an existing ROI and press the _Assign_ button. The Options (gear) menu lists commands for rebuilding, restoring, and deleting delineations. Most of the editing operations can be performed through the toolbar at the bottom of the delineations list, including:
+- <i class="fas fa-plus"></i> Adds more entries to the delineations list
+- <i class="fas fa-object-group"></i> Merges two or more delineations into one
+- <i class="fas fa-swatchbook"></i> Applies one of the default color schemes to the delineations list
+- <i class="fas fa-pen"></i> Enables/Disables direct editing of delineation names
+- _Outside color_ widget: Defines the color for non-delineated sections, i.e., those sections that remain _outside_ delineated areas
+
+
+## Measuring Delineations
+
+Measurements are retrieved using the <i class="fas fa-chart-bar"></i> _Plot_ and <i class="fas fa-table"></i> _Measure_ buttons:
+
+- <i class="fas fa-chart-bar"></i> _Plot_: Plots distributions of selected metrics. Plotting styles include: Box plots (one delineation per category), multi-series histograms (one delineation per series), or a montage of single-series histograms (one panel per delineation)
+- <i class="fas fa-table"></i> _Measure_: Reports common metrics to a dedicated table (Total length, No. of nodes, No. of junctions, etc.) across delineations
+
+In addition to defined delineations, plots and tables may include two other categories:
+
+- _Non-delineated_: This category corresponds to all the path sections that remained in-between or outside delineations. _Non-delineated_ sections are labeled by [outside color](#editing-delineations)
+
+- _Unaffected paths_: This category corresponds to full paths that have no XY coordinates inside any delineation. _Unaffected paths_  retain their rendered colors 
+
+{% include notice icon="info" content="Topological constraints may not allow certain metrics to be computed for a particular delineation. E.g., a metric that requires a [graph-theoretic tree](./analysis#graph-based-analysis) may not be computed for a delineation defined by a non-contiguous ROI." %}
+
+
 # Generating *Filtered Images* in Bulk
 
 This section describes how to generate [Filtered Images](/plugins/snt/manual#tracing-on-secondary-image-layer) outside SNT in bulk. Note that there are [many tutorials](/scripting/batch) on this topic. Arguably, the easiest way to process multiple images is to 1) record a macro that processes a single image, then 2) wrap it in a loop to iterate over all files in a directory. For example, using IJ1 macro language: