Merge pull request #366 from imagej/snt-fixes

snt: add snippet for external data analysis

Author: tferr

_pages/plugins/snt/analysis.md

@@ -27,16 +27,19 @@ If this becomes an issue, consider fitting paths in situ using the Replace exist
 # Statistics
 SNT assembles comparison reports and simple statistical reports (two-sample t-test/one-way ANOVA) for up to six groups of cells. This is described in [Comparing Reconstructions](#comparing-reconstructions). In addition, descriptive statistics are commonly reported in histograms from *Frequency/Distribution Analysis* commands.
 
-{% include img align="center" src="/media/plugins/snt/snt-combined-histograms.png"
-caption="
-**Cell-based Distributions...**
-<p>
-SNT charts are zoomable, scalable, and rendered using scientific plotting styles to be as publication-ready as possible.
-Righ-click on a plot canvas to export it as vector graphics (PDF or SVG), acess customization controls, a light/dark theme toggle, and options to aggregate charts in multi-panel figures. 
-With histograms, normal distribution curves and quartile marks can be overlaid on frequencies. With simple charts, it is typically enough to double-click on plotted components to edit them. 
-</p>
-"%}
+{% include img align="right" src="/media/plugins/snt/snt-combined-histograms.png" caption="Distributions or morphometric traits..."%}
 
+Notes on SNT charts and plots:
+
+- SNT charts are zoomable, scalable, and rendered using scientific plotting styles to be as publication-ready as possible. Righ-click on a plot canvas to export it as vector graphics (PDF or SVG), acess customization controls, a light/dark theme toggle, and options to aggregate charts in multi-panel figures
+
+- With simple charts, it is possible double-click on plotted components to edit them and export data as CSV
+
+- Histogram distributions can be fitted to a [normal distribution](https://en.wikipedia.org/wiki/Normal_distribution) (Gaussian) or a [Gaussian mixture model](https://en.wikipedia.org/wiki/Mixture_model) (see _Components & Curve Fitting_ in the histogram right-click menu). In both cases, curves are scaled so that the [area under the curve](https://en.wikipedia.org/wiki/Integral) of the fitted curve matches that of the histogram. [Quartile](https://en.wikipedia.org/wiki/Quartile) marks can also be overlaid. By default, the [Freedman-Diaconis](https://en.wikipedia.org/wiki/Freedman%E2%80%93Diaconis_rule) rule is used to compute the no. of histogram bins.
+
+- Unless specified, all radial plots display angles in [0°-360°[ degrees
+
+- While SNT is not a statistical analysis software, it does offer some basic convenience methods to parse third-party data. See e.g., [this example](./scripting#analysis-of-external-data) for fitting a Gaussian mixture model to CSV data
 
 # Comparing Reconstructions
 

_pages/plugins/snt/faq.md

@@ -32,11 +32,11 @@ In addition, you should also cite any additional modules that you may use:
 
 ### What is the difference between SNT and Simple Neurite Tracer?
 
-Simple Neurite Tracer was the first Fiji plugin dedicated to visualization and reconstruction of neurons, developed by [Mark Longair](/people/mhl) and [published in 2011](https://doi.org/10.1093/bioinformatics/btr390), to become the single most cited open-source software for semi-automated 3D reconstructions. In the wake of ImageJ2 development, a new team of developers lead by [Tiago Ferreira](/people/tferr) took on the effort of modernizing its code base. The project quickly snowballed beyond the re-write of the software, and focused on establishing a complete framework for reconstruction, visualization, quantification and modelling of neuronal morphology. Several name changes were proposed for this "next-gen" Simple Neurite Tracer (*Not so Simple Neurite Tracer*, *Smart Neurite Tracer*, *Super Neurite Tracer* to name a few), but in the end it was decided to adopt the acronym of the original software, as an homage to Mark's outstanding work. You can follow the entire history of the plugin on GitHub: Simple Neurite Tracer's {% include github org='fiji ' repo='Simple_Neurite_Tracer' label='historic ' %} and SNT's {% include github org='morphonets ' repo='SNT ' label='current ' %} repositories.
+Simple Neurite Tracer was the first Fiji plugin dedicated to visualization and reconstruction of neurons, developed by [Mark Longair](/people/mhl) and [published in 2011](https://doi.org/10.1093/bioinformatics/btr390), to become the single most cited open-source software for semi-automated 3D reconstructions. In the wake of ImageJ2 development, a new team of developers lead by [Tiago Ferreira](/people/tferr) took on the effort of modernizing its code base. The project quickly snowballed beyond the re-write of the software, and focused on establishing a complete framework for reconstruction, visualization, quantification and modelling of neuronal morphology. Several name changes were proposed for this "next-gen" Simple Neurite Tracer (*Not so Simple Neurite Tracer*, *Smart Neurite Tracer*, *Super Neurite Tracer* to name a few), but in the end it was decided to adopt the acronym of the original software, as an homage to Mark's outstanding work. You can follow the entire history of the plugin on GitHub: Simple Neurite Tracer's {% include github org='fiji' repo='Simple_Neurite_Tracer' label='historic' %} and SNT's {% include github org='morphonets' repo='SNT' label='current' %} repositories.
 
 ### How accurate is SNT?
 
-When SNT is compiled, a [suite of tests](https://github.com/morphonets/SNT/tree/-/src/test/java/sc/fiji/snt) is run to detect deficiencies in the code base. Morphometry results are benchmarked against values obtained in [L-Measure](http://cng.gmu.edu:8080/Lm/) and [NeuroM](https://github.com/BlueBrain/NeuroM). However, no test suite is ever perfect. If you detect inaccuracies, please {% include github org='morphonets ' repo='SNT ' label='report ' %} them\!
+When SNT is compiled, a [suite of tests](https://github.com/morphonets/SNT/tree/-/src/test/java/sc/fiji/snt) is run to detect deficiencies in the code base. Morphometry results are benchmarked against values obtained in [L-Measure](http://cng.gmu.edu:8080/Lm/) and [NeuroM](https://github.com/BlueBrain/NeuroM). However, no test suite is ever perfect. If you detect inaccuracies, please {% include github org='morphonets' repo='SNT' label='report' %} them\!
 
 ### What is a SWC file?
 <span id="swc"></span>

_pages/plugins/snt/scripting.md

@@ -76,6 +76,38 @@ The REPL has access to _all_ of SNT's API. The prompt does not feature auto-comp
   demoTreesSWC()                   -> List
 {% endhighlight %}
 
+# Analysis of External Data
+While SNT is not a statistical analysis software, it does offer some convenience methods to parse third-party data. E.g., to take a quick peek at a distribution of tabular values, one could use the following snippet to plot a histogram while fitting a Gaussian mixture model to the data. While it is written in Groovy, it would run almost verbatim in any other scripting language because it relies only on the SNT API.
+
+{% highlight groovy %}
+import sc.fiji.snt.analysis.*
+
+path = "https://raw.githubusercontent.com/morphonets/misc/master/dataset-demos/csv/demo-trees-coord.csv" // url or path to local file
+table = SNTTable.fromFile(path) // read data into a table
+headers = ["y", "z"] // headers of columns to be plotted
+histogram = SNTChart.getHistogram(table, headers, false) // table, col. headers, radial plot?
+histogram.setGMMFitVisible(true) // fit Gaussian mixed model to data
+histogram.show() // display histogram
+{% endhighlight %}
+
+Alternatively, the same data could be plotted in a two-dimensional histogram:
+
+{% highlight groovy %}
+import sc.fiji.snt.analysis.*
+import sc.fiji.snt.util.*
+
+path = "https://raw.githubusercontent.com/morphonets/misc/master/dataset-demos/csv/demo-trees-coord.csv" // url or path to local file
+table = SNTTable.fromFile(path) // read data into a table
+SNTChart.showHistogram3D(table.get("y"), table.get("z"), ColorMaps.get("viridis")) // show 3D histogram of the same columns using viridis LUT
+{% endhighlight %}
+
+Note that this approach would work for both local and remote files. The result of both snippets side-by-side:
+
+<div align="center">
+  <img src="/media/plugins/snt/snt-analysis-external-data.png" title="Analysis of tabular data in SNT" width="700px" />
+</div>
+
+
 # Python Notebooks
 
 Direct access to the SNT API from the [Python](https://www.python.org/) programming language is made possible through the [PyImageJ](/scripting/pyimagej) module. This enables full integration between SNT and any library in the Python ecosystem (numpy, scipy, etc.). The [Notebooks](https://github.com/morphonets/SNT/tree/-/notebooks) directory in the SNT repository contains several examples at different complexity levels.