Rename spike detector -> threshold detector (#1976)

- BREAKING: Rename spike detector -> threshold detector in Python
- `spike_detector` is still around, will throw a deprecation error; will be removed 0.9
- this brings Python closer to the C++ API and removes lots of ambiguities in the docs.

doc/concepts/cable_cell.rst

@@ -5,7 +5,7 @@ Cable cells
 
 An Arbor *cable cell* is a full :ref:`description <modelcelldesc>` of a cell
 with morphology and cell dynamics like ion species and their properties, ion
-channels, synapses, gap junction mechanisms, stimuli and spike detectors.
+channels, synapses, gap junction mechanisms, stimuli and threshold detectors.
 
 Cable cells are constructed from three components:
 

doc/concepts/cell.rst

@@ -26,7 +26,7 @@ Cells interact with each other via spike exchange and gap junctions.
 Cell interactions via :ref:`connections <modelconnections>` and :ref:`gap junctions <modelgapjunctions>` occur
 between **source**, **target** and **gap junction site** locations on a cell. Connections are formed from sources
 to targets. Gap junctions are formed between two gap junction sites. An example of a source on a
-:ref:`cable cell<modelcablecell>` is a :ref:`threshold detector <cablecell-threshold-detectors>` (spike detector);
+:ref:`cable cell<modelcablecell>` is a :ref:`threshold detector <cablecell-threshold-detectors>`;
 an example of a target on a cable cell is a :ref:`synapse <cablecell-synapses>`.
 
 **Sources**, **targets** and **gap junction sites** are placed on sets of one or more locations on a cell.

doc/concepts/decor.rst

@@ -22,7 +22,7 @@ The choice of region or locset is reflected in the two broad classes of dynamics
 
   * :ref:`Synapse mechanisms <cablecell-synapses>`.
   * :ref:`Gap junction mechanisms <cablecell-gj-mechs>`.
-  * :ref:`Threshold detectors <cablecell-threshold-detectors>` (spike detectors).
+  * :ref:`Threshold detectors <cablecell-threshold-detectors>`
   * :ref:`Stimuli <cablecell-stimuli>`.
   * :ref:`Probes <cablecell-probes>`.
 
@@ -353,19 +353,19 @@ A point mechanism (synapse) can form the target of a :term:`connection` on a cel
 
 .. _cablecell-threshold-detectors:
 
-2. Threshold detectors (spike detectors).
+2. Threshold detectors.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Spike detectors have a dual use: they can be used to record spike times, but are also used in propagating signals
+Threshold detectors have a dual use: they can be used to record spike times, but are also used in propagating signals
 between cells. An example where we're interested in when a threshold of ``-10 mV`` is reached:
 
 .. code-block:: Python
 
-    # Placing a spike detector might look like this.
+    # Placing a threshold detector might look like this.
     decor = arbor.decor()
-    decor.place('"root"', arbor.spike_detector(-10), "my_spike_detector")
+    decor.place('"root"', arbor.threshold_detector(-10), "detector")
 
-    # At this point, "my_spike_detector" could be connected to another cell,
+    # At this point, "detector" could be connected to another cell,
     # and it would transmit events upon the voltage crossing the threshold.
 
     # Just printing those spike times goes as follows.
@@ -376,7 +376,7 @@ between cells. An example where we're interested in when a threshold of ``-10 mV
     for sp in sim.spikes():
         print(" ", sp)
 
-See also :term:`spike detector`.
+See also :term:`threshold detector`.
 
 .. _cablecell-gj-mechs:
 

doc/concepts/domdec.rst

@@ -37,8 +37,8 @@ We define some terms as used in the context of connectivity
    connection
       Tuple of ``(source, target, weight, delay)`` describing an
       axon/synapse connection as travelling time (`delay`) and attenuation
-      (`weight`) between two sites `source = (gid, spike_detector)` and `target
-      = (gid, synapse)` where `spike_detector` and `synapse` are string labels.
+      (`weight`) between two sites `source = (gid, threshold_detector)` and `target
+      = (gid, synapse)` where `threshold_detector` and `synapse` are string labels.
 
    cell_group
       List of same-kinded cells that share some information. Must not be split

doc/concepts/interconnectivity.rst

@@ -105,7 +105,7 @@ full recipe.
    action potential
       Spikes travel over :term:`connections <connection>`. In a synapse, they generate an event.
 
-   spike detector
+   threshold detector
       :ref:`Placed <cablecell-place>` on a cell. Possible source of a connection.
       Detects crossing of a fixed threshold and generates corresponding events.
       Also used to :ref:`record spikes <>` for analysis. See :ref:`here

doc/concepts/probe_sample.rst

@@ -61,8 +61,8 @@ Definitions
 Spiking
 *******
 
-Spike detectors have a dual use: they can be used to record spike times, but are also used in propagating signals
-between cells. See also :term:`spike detector` and :ref:`cablecell-threshold-detectors`.
+Threshold detectors have a dual use: they can be used to record spike times, but are also used in propagating signals
+between cells. See also :term:`threshold detector` and :ref:`cablecell-threshold-detectors`.
 
 
 API

doc/concepts/recipe.rst

@@ -23,11 +23,11 @@ An example model
 To better illustrate the content of a recipe, let's consider the following network of
 three cells:
 
-- ``Cell 0``: Is a single soma, with ``hh`` (Hodgkin-huxley) dynamics. A spike detector
+- ``Cell 0``: Is a single soma, with ``hh`` (Hodgkin-huxley) dynamics. A threshold detector
   labelled "detector_0" is attached to the middle of the soma. The detector will generate a
   spike event when the voltage goes above 10 mV. At the same spot on the soma, a current clamp
   is also attached, with the intention of triggering some spikes. All of the preceding info —
-  the morphology, dynamics, spike detector and current clamp — constitute what is termed the
+  the morphology, dynamics, threshold detector and current clamp — constitute what is termed the
   **description** of the cell.
   ``Cell 0`` should be modelled as a :ref:`cable cell<modelcablecell>`,
   (because cable cells allow complex dynamics such as ``hh``). This is referred to as

doc/dev/communication.rst

@@ -11,7 +11,7 @@ reduced to a simple time value. The connection is abstracted into a weight and a
 delay; modelling all axonal processes. While this may seem crude, it is a well
 supported model and commonly used in neuronal simulations.
 
-Connections are formed between sources (cable cell: spike detectors) and targets
+Connections are formed between sources (cable cell: threshold detectors) and targets
 (cable cell: synapses). During runtime, events from all sources are concatenated
 on all MPI ranks using ``Allgatherv`` and targets are responsible for selecting
 events they have subscribed to. This is optimised for by sorting events locally

doc/dev/mechanism_abi.rst

@@ -177,7 +177,7 @@ fully formed to the interface. At this point:
 
   .. c:member:: arb_index_type n_detectors
 
-    Number of spike detectors
+    Number of threshold detectors
 
   .. c:member:: arb_index_type* vec_ci
 

doc/python/decor.rst

@@ -152,7 +152,7 @@ Cable cell decoration
     .. method:: place(locations, d, label)
         :noindex:
 
-        Add a voltage spike detector at each location in ``locations`` and label the group of detectors with ``label``.
+        Add a voltage threshold detector at each location in ``locations`` and label the group of detectors with ``label``.
         The label can be used to form connections from one of the detectors in the :py:class:`arbor.recipe` by creating
         a :py:class:`arbor.connection`.
 

doc/python/interconnectivity.rst

@@ -54,10 +54,10 @@ Interconnectivity
             labels['synapse_site'] = '(location 1 0.5)'
             labels['root'] = '(root)'
 
-            # Place 'expsyn' mechanism on "synapse_site", and a spike detector at "root"
+            # Place 'expsyn' mechanism on "synapse_site", and a threshold detector at "root"
             decor = arbor.decor()
             decor.place('"synapse_site"', 'expsyn', 'syn')
-            decor.place('"root"', arbor.spike_detector(-10), 'detector')
+            decor.place('"root"', arbor.threshold_detector(-10), 'detector')
 
             # Implement the connections_on() function on a recipe as follows:
             def connections_on(gid):
@@ -104,12 +104,11 @@ Interconnectivity
 
         The unit-less weight of the gap junction connection.
 
-.. class:: spike_detector
+.. class:: threshold_detector
 
-    A spike detector, generates a spike when voltage crosses a threshold. Can be used as source endpoint for an
+    A threshold detector, generates a spike when voltage crosses a threshold. Can be used as source endpoint for an
     :class:`arbor.connection`.
 
     .. attribute:: threshold
 
-        Voltage threshold of spike detector [mV]
-
+        Voltage threshold of threshold detector [mV]

doc/python/simulation.rst

@@ -232,7 +232,7 @@ spikes generated by any MPI rank.
 
 Spikes recorded during a simulation are returned as a NumPy structured datatype with two fields,
 ``source`` and ``time``. The ``source`` field itself is a structured datatype with two fields,
-``gid`` and ``index``, identifying the spike detector that generated the spike.
+``gid`` and ``index``, identifying the threshold detector that generated the spike.
 
 .. Note::
 

doc/tutorial/network_ring.rst

@@ -51,7 +51,7 @@ The synapse is given the label ``'syn'``, which is later used to form :py:class:
    (see :py:class:`arbor.mechanism`). In particular, the ``e`` parameter of ``expsyn`` defaults to ``0``, which makes it,
    given the typical resting potential of cell membranes of ``-70 mV``, an excitatory synapse.
 
-Step **(4)** places a spike detector at the ``'root'``. The detector is given the label ``'detector'``, which is later used to form
+Step **(4)** places a threshold detector at the ``'root'``. The detector is given the label ``'detector'``, which is later used to form
 :py:class:`arbor.connection` objects originating *from* the cell.
 
 .. Note::

doc/tutorial/single_cell_allen.rst

@@ -107,7 +107,7 @@ Step **(8)** assigns the regional mechanisms.
 Now that the electro-physiology is all set up, let's move on to the experimental setup.
 
 Step **(9)** configures the :class:`stimulus <arbor.iclamp>` of 150 nA for a duration of 1 s, starting after 200 ms
-of the start of the simulation. We'll also install a :class:`arbor.spike_detector` that triggers at -40 mV. (The
+of the start of the simulation. We'll also install a :class:`arbor.threshold_detector` that triggers at -40 mV. (The
 location is usually the soma, as is confirmed by coordinates found in the experimental dataset at
 ``488683423.nwb/general/intracellular_ephys/Electrode 1/location``)
 
@@ -147,7 +147,7 @@ Then, we extract Arbor's output, accessible after the simulation ran at
     :width: 400
     :align: center
 
-    Plot of experiment 35 of the Allen model, compared to the reference generated by the AllenSDK. In green: the spike detector output; in shaded grey: the stimulus.
+    Plot of experiment 35 of the Allen model, compared to the reference generated by the AllenSDK. In green: the threshold detector output; in shaded grey: the stimulus.
 
 .. note::
 

doc/tutorial/single_cell_detailed.rst

@@ -281,9 +281,9 @@ mechanism has a custom 'gbar' parameter.
    :language: python
    :lines: 8,56-59
 
-The decor object is also used to *place* stimuli and spike detectors on the cell using :meth:`arbor.decor.place`.
+The decor object is also used to *place* stimuli and threshold detectors on the cell using :meth:`arbor.decor.place`.
 We place 3 current clamps of 2 nA on the "root" locset defined earlier, starting at time = 10, 30, 50 ms and
-lasting 1ms each. As well as spike detectors on the "axon_terminal" locset for voltages above -10 mV.
+lasting 1ms each. As well as threshold detectors on the "axon_terminal" locset for voltages above -10 mV.
 Every placement gets a label. The labels of detectors and synapses are used to form connection from and to them
 in the recipe.
 
@@ -385,7 +385,7 @@ The probes
 ^^^^^^^^^^
 
 The model is almost ready for simulation. Except that the only output we would be able to
-measure at this point is the spikes from the spike detectors placed in the decor.
+measure at this point is the spikes from the threshold detectors placed in the decor.
 
 The :class:`arbor.single_cell_model` can also measure the voltage on specific locations of the cell.
 We can indicate the location we would like to probe using labels from the :class:`label_dict`:
@@ -406,9 +406,9 @@ The cell and model descriptions are now complete and we can run the simulation:
 The results
 ^^^^^^^^^^^
 
-Finally we move on to the data collection segment of the example. We have added a spike detector
+Finally we move on to the data collection segment of the example. We have added a threshold detector
 on the "axon_terminal" locset. The :class:`arbor.single_cell_model` automatically registers all
-spikes on the cell from all spike detectors on the cell and saves the times at which they occurred.
+spikes on the cell from all threshold detectors on the cell and saves the times at which they occurred.
 
 .. literalinclude:: ../../python/example/single_cell_detailed.py
    :language: python

doc/tutorial/single_cell_model.rst

@@ -32,7 +32,7 @@ and a current clamp stimulus, then run the model for 30 ms.
 The first step is to construct the cell. In Arbor, the abstract representation used to
 define a cell with branching cable morphology is a ``cable_cell``, which holds a
 description of the cell's morphology, named regions and locations on the morphology, and
-descriptions of ion channels, synapses, spike detectors and electrical properties.
+descriptions of ion channels, synapses, threshold detectors and electrical properties.
 
 Our *single-segment HH cell* has a simple morphology and dynamics, constructed as follows:
 
@@ -73,9 +73,9 @@ following way:
   HH dynamics on the region we previously named ``"soma"`` in our label dictionary.
 * :meth:`arbor.decor.place` is used to add objects on a precise
   :class:`arbor.location` on a cell. Examples of objects that are *placed* are synapses,
-  spike detectors, current stimuli, and probes. In the above example we place a current stimulus
+  threshold detectors, current stimuli, and probes. In the above example we place a current stimulus
   :class:`arbor.iclamp` with a duration of 2 ms and a current of 0.8 nA, starting at 10 ms
-  on the location we previously labelled ``"midpoint"``. We also place a :class:`arbor.spike_detector`
+  on the location we previously labelled ``"midpoint"``. We also place a :class:`arbor.threshold_detector`
   with a threshold of -10 mV on the same location.
 
 Step **(4)** constructs the :class:`arbor.cable_cell` from the segment tree and dictionary of labelled regions and locations.
@@ -93,7 +93,7 @@ The single cell model has 4 main functions:
 1. It holds the **global properties** of the model
 2. It registers **probes** on specific locations on the cell to measure the voltage.
 3. It **runs** the simulation.
-4. It collects **spikes** from spike detectors and voltage **traces** from registered probes.
+4. It collects **spikes** from threshold detectors and voltage **traces** from registered probes.
 
 Right now, we'll only set a probe and run the simulation.
 
@@ -115,7 +115,7 @@ The results
 -----------
 
 Our cell and model have been defined and we have run our simulation. Now we can look at what
-the spike detector and a voltage probes from our model have produced.
+the threshold detector and a voltage probes from our model have produced.
 
 .. literalinclude:: ../../python/example/single_cell_model.py
    :language: python

python/cells.cpp

@@ -577,8 +577,15 @@ void register_cells(pybind11::module& m) {
             return util::pprintf("<arbor.iclamp: frequency {} Hz>", c.frequency);});
 
     // arb::threshold_detector
-
-    pybind11::class_<arb::threshold_detector> detector(m, "spike_detector",
+    struct spike_detector {};
+    pybind11::class_<spike_detector> sd(m, "spike_detector", "Deprecated, please use 'threshold_detector'");
+    sd.def(pybind11::init(
+               [](pybind11::object) -> spike_detector {
+                   throw arb::arbor_exception{"Deprecated, please use 'threshold_detector' instead."};
+                   return {}; // unreachable
+               }));
+
+    pybind11::class_<arb::threshold_detector> detector(m, "threshold_detector",
             "A spike detector, generates a spike when voltage crosses a threshold. Can be used as source endpoint for an arbor.connection.");
     detector
         .def(pybind11::init(

python/example/gap_junctions.py

@@ -51,8 +51,8 @@ def make_cable_cell(gid):
         # Attach one synapse and gap junction each on their labeled sites
         .place('"synapse_site"', arbor.synapse("expsyn"), "syn")
         .place('"gj_site"', arbor.junction("gj"), "gj")
-        # Attach spike detector to cell root
-        .place('"root"', arbor.spike_detector(-10), "detector")
+        # Attach detector to cell root
+        .place('"root"', arbor.threshold_detector(-10), "detector")
     )
 
     return arbor.cable_cell(tree, labels, decor)

python/example/network_ring.py

@@ -64,8 +64,8 @@ def make_cable_cell(gid):
         .paint('"soma"', arbor.density("hh")).paint('"dend"', arbor.density("pas"))
         # (4) Attach a single synapse.
         .place('"synapse_site"', arbor.synapse("expsyn"), "syn")
-        # Attach a spike detector with threshold of -10 mV.
-        .place('"root"', arbor.spike_detector(-10), "detector")
+        # Attach a detector with threshold of -10 mV.
+        .place('"root"', arbor.threshold_detector(-10), "detector")
     )
 
     return arbor.cable_cell(tree, labels, decor)

python/example/network_ring_gpu.py

@@ -66,8 +66,8 @@ def make_cable_cell(gid):
     # (4) Attach a single synapse.
     decor.place('"synapse_site"', arbor.synapse("expsyn"), "syn")
 
-    # Attach a spike detector with threshold of -10 mV.
-    decor.place('"root"', arbor.spike_detector(-10), "detector")
+    # Attach a detector with threshold of -10 mV.
+    decor.place('"root"', arbor.threshold_detector(-10), "detector")
 
     cell = arbor.cable_cell(tree, labels, decor)