revised metrics/plotting neurocog docs

Author: Alexander Ororbia

docs/tutorials/neurocog/metrics.md

@@ -1,26 +1,11 @@
 # Metrics and Measurement Functions
 
-Inside of `ngclearn.utils.metric_utils`, ngc-learn offers metrics and measurement
-utility functions that can be quite useful when building neurocognitive models using
-ngc-learn's node-and-cables system for specific tasks. While this utilities
-sub-module will not always contain every possible function you might need,
-given that measurements are often dependent on the task the experimenter wants
-to conduct, there are several commonly-used ones drawn from machine intelligence
-and computational neuroscience that are (jit-i-fied) in-built to ngc-learn you
-can readily use.
-In this small lesson, we will briefly examine two examples of importing such
-functions and examine what they do.
+Inside of `ngclearn.utils.metric_utils`, ngc-learn offers metrics and measurement utility functions that can be quite useful when building neurocognitive models using ngc-learn's node-and-cables system for specific tasks. While this utilities sub-module will not always contain every possible function you might need, given that measurements are often dependent on the task the experimenter wants to conduct, there are several commonly-used ones drawn from machine intelligence and computational neuroscience that are (jit-i-fied) in-built to ngc-learn you can readily use. 
+In this small lesson, we will briefly examine two examples of importing such functions and examine what they do.
 
 ## Measuring Task-Level Quantities
 
-For many tasks that you might be interested in, a useful measurement
-is the performance of the model in some supervised learning context. For example,
-you might want to measure a model's accuracy on a classification task. To do so,
-assuming we have some model outputs extracted from a model that you have constructed
-elsewhere -- say a matrix of scores `Y_scores` -- and a target set of predictions
-that you are testing against -- such as `Y_labels` (in one-hot binary encoded form )
--- then you can write some code to compute the accuracy, mean squared error (MSE),
-and categorical log likelihood (Cat-NLL), like so:
+For many tasks that you might be interested in, a useful measurement is the performance of the model in some supervised learning context. For example, you might want to measure a model's accuracy on a classification task. To do so, assuming we have some model outputs extracted from a model that you have constructed elsewhere -- say a matrix of scores `Y_scores` -- and a target set of predictions that you are testing against -- such as `Y_labels` (in one-hot binary encoded form ) -- then you can write some code to compute the accuracy, mean squared error (MSE), and categorical log likelihood (Cat-NLL), like so:
 
 ```python
 from jax import numpy as jnp
@@ -55,24 +40,18 @@ and you should obtain the following in I/O like so:
  >  Cat-NLL = 4.003
 ```
 
-Notice that we imported the utility function `softmax` from
-`ngclearn.utils.model_utils` to convert our raw theoretical model scores to
-probability values so that using `measure_CatNLL()` makes sense (as this
-assumes the model scores are normalized probability values).
+Notice that we imported the utility function `softmax` from `ngclearn.utils.model_utils` to convert our raw theoretical model scores to
+probability values so that using `measure_CatNLL()` makes sense (as this assumes the model scores are normalized probability values).
 
 ## Measuring Some Model Statistics
 
-In some cases, you might be interested in measuring certain statistics
-related to aspects of a model that you construct. For example, you might have
-collected a (binary) spike train produced by one of the internal neuronal layers
-of your ngc-learn-simulated spiking neural network and want to compute the
-firing rates and Fano factors associated with each neuron. Doing so with
-ngc-learn utility functions would entail writing something like:
+In some cases, you might be interested in measuring certain statistics related to properties of a model that you construct. For example, you might have collected a (binary) spike train produced by one of the internal neuronal layers of your ngc-learn-simulated spiking neural network and want to compute the firing rates and Fano factors associated with each neuron. Doing so with ngc-learn utility functions would entail writing something like: 
 
 ```python
 from jax import numpy as jnp
 from ngclearn.utils.metric_utils import measure_fanoFactor, measure_firingRate
 
+## let's create a fake synthetic spike train for 3 neurons (one per column)
 spikes = jnp.asarray([[0., 0., 0.],
                       [0., 0., 1.],
                       [0., 1., 0.],
@@ -92,6 +71,7 @@ spikes = jnp.asarray([[0., 0., 0.],
                       [0., 1., 0.],
                       [0., 0., 1.]], dtype=jnp.float32)
 
+## measure the firing rates and Fano factors of the 3 neurons
 fr = measure_firingRate(spikes, preserve_batch=True)
 fano = measure_fanoFactor(spikes, preserve_batch=True)
 
@@ -106,8 +86,4 @@ which should result in the following to be printed to I/O:
 > Fano Factor  = [[0.8888888  0.77777773 0.55555546]]
 ```
 
-The Fano factor is a useful secondary statistic for characterizing the
-variable of a neuronal spike train -- as we see in the measurement above,
-the first and second neurons have a higher Fano factor (given they are
-more irregular in their spiking patterns) whereas the third neuron is far more
-regular in its spiking pattern and thus has a lower Fano factor.
+The Fano factor is a useful secondary statistic for characterizing the variability of a neuronal spike train -- as we see in the measurement above, the first and second neurons have a higher Fano factor (given they are more irregular in their spiking patterns) whereas the third neuron is far more regular in its spiking pattern and thus has a lower Fano factor.

docs/tutorials/neurocog/plotting.md

@@ -1,32 +1,20 @@
 # Plotting and Visualization
 
-While writing one's own custom task-specific matplotlib visualization code
-might be needed for specific experimental setups, there are several useful tools
-already in-built to ngc-learn, organized under the package sub-directory
-`ngclearn.utils.viz`, including utilities for generating raster plots and
-synaptic receptive field views (useful for biophysical models such as spiking
-neural networks) as well as t-SNE plots of model latent codes. While the other
-lesson/tutorials demonstrate some of these useful routines (e.g., raster plots
-for spiking neuronal cells), in this small lesson, we will demonstrate how to
-produce a t-SNE plot using ngc-learn's in-built tool.
+While writing one's own custom task-specific matplotlib visualization code might be needed for specific experimental setups, there are several useful tools already in-built to ngc-learn, organized under the package sub-directory `ngclearn.utils.viz`, including utilities for generating raster plots and synaptic receptive field views (useful for biophysical models such as spiking neural networks) as well as t-SNE plots of model latent codes. While the other lesson/tutorials demonstrate some of these useful routines (e.g., raster plots for spiking neuronal cells), in this small lesson, we will demonstrate how to produce a t-SNE plot using ngc-learn's in-built tool.
 
 ## Generating a t-SNE Plot
 
-Let's say you have a labeled five-dimensional (5D) dataset -- which we will
-synthesize artificially in this lesson from an "unobserved" trio of multivariate
-Gaussians -- and wanted to visualize these "model outputs" and their
-corresponding labels in 2D via ngc-learn's in-built t-SNE.
+Let's say you have a labeled five-dimensional (5D) dataset -- which we will artificially synthesize in this lesson from an "unobserved" trio of multivariate Gaussians -- and that you wanted to visualize these "model outputs" and their corresponding labels in 2D via ngc-learn's in-built t-SNE.
 
-The following bit of Python code will do this for you (including the artificial
-data generator):
+The following bit of Python code will do this for you (including setting up the data generator):
 
 ```python
 from jax import numpy as jnp, random
 from ngclearn.utils.viz.dim_reduce import extract_tsne_latents, plot_latents
 
 dkey = random.PRNGKey(1234)
 
-def gen_data(dkey, N): ## artificial data generator (or proxy model)
+def gen_data(dkey, N): ## data generator (or proxy stochastic data generating process)
     mu1 = jnp.asarray([[2.1, 3.2, 0.6, -4., -2.]])
     cov1 = jnp.eye(5) * 0.78
     mu2 = jnp.asarray([[-1.8, 0.2, -0.1, 1.99, 1.56]])
@@ -59,6 +47,4 @@ which should produce a plot, i.e., `codes.jpg`, similar to the one below:
 
 <img src="../../images/tutorials/neurocog/simple_codes.jpg" width="400" />
 
-In this example scenario, we see that we can successfully map the 5D model output
-data to a plottable 2D space, facilitating some level of downstream qualitative
-interpretation of the model.
+In this example scenario, we see that we can successfully map the 5D model output data to a plottable 2D space, facilitating some level of downstream qualitative interpretation of the model.