Merge pull request #189 from jpgill86/firing-rates

Add computation of smoothed firing rates for spike trains

docs/api.rst

@@ -36,3 +36,9 @@ as ``neurotic.MetadataSelector``.
   api/epochencoder
   api/notebook
   api/standalone
+
+.. toctree::
+  :maxdepth: 1
+  :caption: Other
+
+  api/_elephant_tools

docs/api/_elephant_tools.rst

@@ -0,0 +1,6 @@
+.. _api-_elephant_tools:
+
+``neurotic._elephant_tools``
+============================
+
+.. automodule:: neurotic._elephant_tools

docs/conf.py

@@ -20,7 +20,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'neurotic'
-copyright = '2019, Jeffrey Gill'
+copyright = '2020, Jeffrey Gill'
 author = 'Jeffrey Gill'
 
 import neurotic
@@ -212,6 +212,7 @@
 intersphinx_mapping = {
     'python':       ('https://docs.python.org/3', None),
     'neo':          ('https://neo.readthedocs.io/en/latest', None),
+    'elephant':     ('https://elephant.readthedocs.io/en/latest', None),
     'ephyviewer':   ('https://ephyviewer.readthedocs.io/en/latest', None),
     'tridesclous':  ('https://tridesclous.readthedocs.io/en/latest', None),
 }

docs/metadata.rst

@@ -556,6 +556,55 @@ In this example, note again the punctuation:
 Now clusters 0 and 1 are combined into a single unit, and only that unit and
 cluster 3 are plotted; cluster 2 has been discarded.
 
+.. _config-metadata-firing-rates:
+
+Firing Rates
+------------
+
+If spike trains were generated using
+:ref:`config-metadata-amplitude-discriminators`, imported from
+:ref:`config-metadata-tridesclous`, or included in the ``data_file``, their
+smoothed firing rates can be computed. Note that firing rates are computed only
+if fast loading is off (``lazy=False``).
+
+Firing rates are plotted as continuous signals. Colors are inherited from
+``amplitude_discriminators``, if they are provided there.
+
+Firing rates are computed using a kernel that is convolved with the spike
+train. The metadata is specified like this:
+
+.. code-block:: yaml
+
+    my favorite dataset:
+        data_file: data.axgx
+        # etc
+
+        amplitude_discriminators:  # used only if fast loading is off (lazy=False)
+
+            - name: Unit 1
+              channel: Extracellular
+              units: uV
+              amplitude: [50, 150]
+
+        firing_rates:  # used only if fast loading is off (lazy=False)
+
+            - name: Unit 1
+              kernel: GaussianKernel
+              sigma: 1.5 # sec
+
+The elephant_ package's :func:`instantaneous_rate
+<elephant.statistics.instantaneous_rate>` function is used for calculating
+firing rates. See :mod:`elephant.kernels` for the names of kernel classes that
+may be used with the ``kernel`` parameter. **neurotic** provides an additional
+kernel, :class:`CausalAlphaKernel
+<neurotic._elephant_tools.CausalAlphaKernel>`, which may also be used. The
+``sigma`` parameter is passed as an argument to the kernel class and should be
+given in seconds.
+
+The rate calculation function and kernel classes are sourced from
+:mod:`neurotic._elephant_tools`, rather than the elephant_ package itself, to
+avoid requiring elephant_ as a package dependency.
+
 .. _config-metadata-burst-detectors:
 
 Firing Frequency Burst Detectors
@@ -564,9 +613,9 @@ Firing Frequency Burst Detectors
 If spike trains were generated using
 :ref:`config-metadata-amplitude-discriminators`, imported from
 :ref:`config-metadata-tridesclous`, or included in the ``data_file``, a simple
-burst detection algorithm that relies on firing rate thresholds can be run to
-detect periods of intense activity. Note that burst detectors are only applied
-if fast loading is off (``lazy=False``).
+burst detection algorithm that relies on instantaneous firing rate thresholds
+can be run to detect periods of intense activity. Note that burst detectors are
+only applied if fast loading is off (``lazy=False``).
 
 Detected bursts are plotted as epochs. Colors are inherited from
 ``amplitude_discriminators``, if they are provided there.
@@ -594,11 +643,14 @@ Burst detectors are specified in metadata like this:
 
 The algorithm works by scanning through the spike train with a name matching
 ``spiketrain`` (in this example, the spike train generated by the "Unit 1"
-amplitude discriminator). When the instantaneous firing frequency (IFF) exceeds
-the first threshold given (e.g., 10 Hz), a burst of activity is determined to
-start. After this, at the first moment when the IFF drops below the second
-threshold (e.g., 8 Hz), the burst is determined to end. After scanning through
-the entire spike train, many bursts that meet these criteria may be identified.
+amplitude discriminator). When the instantaneous firing frequency (IFF; note
+this is *NOT* the same as the :ref:`smoothed firing rate
+<config-metadata-firing-rates>`, but rather the inverse of the inter-spike
+interval) exceeds the first threshold given (e.g., 10 Hz), a burst of activity
+is determined to start. After this, at the first moment when the IFF drops
+below the second threshold (e.g., 8 Hz), the burst is determined to end. After
+scanning through the entire spike train, many bursts that meet these criteria
+may be identified.
 
 Note that in general the end threshold should not exceed the start threshold;
 this would essentially be the same as setting the start and end thresholds both
@@ -640,6 +692,7 @@ without arguments:
    :language: yaml
 
 
+.. _elephant:             https://elephant.readthedocs.io/en/latest
 .. _GIN:                  https://gin.g-node.org
 .. _Neo:                  https://github.com/NeuralEnsemble/python-neo
 .. _tridesclous:          https://github.com/tridesclous/tridesclous