From 86ad95d7055c277cb9e5cb10490dfdcb6eabc408 Mon Sep 17 00:00:00 2001
From: Thorsten Hater <24411438+thorstenhater@users.noreply.github.com>
Date: Thu, 25 Aug 2022 21:10:41 +0200
Subject: [PATCH] add spike source docs. (#1939)
Document use and care of spike detectors.
---
doc/concepts/decor.rst | 23 +++++++++++++++++++++++
doc/concepts/interconnectivity.rst | 13 +++++++++++++
doc/concepts/labels.rst | 2 +-
doc/concepts/mechanisms.rst | 2 +-
doc/concepts/probe_sample.rst | 6 ++++++
doc/concepts/simulation.rst | 9 +++++++++
doc/python/simulation.rst | 3 ++-
7 files changed, 55 insertions(+), 3 deletions(-)
diff --git a/doc/concepts/decor.rst b/doc/concepts/decor.rst
index 630af679..db6264c7 100644
--- a/doc/concepts/decor.rst
+++ b/doc/concepts/decor.rst
@@ -356,6 +356,28 @@ A point mechanism (synapse) can form the target of a :term:`connection` on a cel
2. Threshold detectors (spike detectors).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Spike 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.
+ decor = arbor.decor()
+ decor.place('"root"', arbor.spike_detector(-10), "my_spike_detector")
+
+ # At this point, "my_spike_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.
+ sim = arbor.simulation(...)
+ sim.record(arbor.spike_recording.all)
+ sim.run(...)
+ print("spikes:")
+ for sp in sim.spikes():
+ print(" ", sp)
+
+See also :term:`spike detector`.
+
.. _cablecell-gj-mechs:
3. Gap junction connection sites
@@ -424,6 +446,7 @@ constant stimuli and constant amplitude stimuli restricted to a fixed time inter
5. Probes
~~~~~~~~~
+See :ref:`probesample`.
API
---
diff --git a/doc/concepts/interconnectivity.rst b/doc/concepts/interconnectivity.rst
index 5ff303a2..4fee5f69 100644
--- a/doc/concepts/interconnectivity.rst
+++ b/doc/concepts/interconnectivity.rst
@@ -39,6 +39,19 @@ A recipe lets you define which sites are connected to which.
action potential
Spikes travel over :term:`connections <connection>`. In a synapse, they generate an event.
+ spike 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
+ <cablecell-threshold-detectors>` for more information.
+
+ spike source cell
+ Artificial cell to generate spikes on a given schedule, see :ref:`spike cell <spikecell>`.
+
+ recording
+ By default, spikes are used for communication, but not stored for analysis,
+ however, :ref:`simulation <modelsimulation>` objects can be instructed to record spikes.
+
event
In a synapse :term:`spikes <spike>` generate events, which constitute stimulation of the synapse
mechanism and the transmission of a signal. A synapse may receive events directly from an
diff --git a/doc/concepts/labels.rst b/doc/concepts/labels.rst
index a103e0e5..70272753 100644
--- a/doc/concepts/labels.rst
+++ b/doc/concepts/labels.rst
@@ -866,4 +866,4 @@ API
---
* :ref:`Python <pylabels>`
-* *TODO*: C++ documentation.
+* :ref:`C++ <cpplabels>`
diff --git a/doc/concepts/mechanisms.rst b/doc/concepts/mechanisms.rst
index 36d17164..3146af8d 100644
--- a/doc/concepts/mechanisms.rst
+++ b/doc/concepts/mechanisms.rst
@@ -267,4 +267,4 @@ API
---
* :ref:`Python <py_mechanisms>`
-* *TODO* C++ documentation.
+* :ref:`C++ <cpp_mechanisms>`
diff --git a/doc/concepts/probe_sample.rst b/doc/concepts/probe_sample.rst
index 6ea48b0d..cdd480c4 100644
--- a/doc/concepts/probe_sample.rst
+++ b/doc/concepts/probe_sample.rst
@@ -58,6 +58,12 @@ Definitions
An object representing a series of monotonically increasing points in time, used for determining
sample times (see :ref:`pyrecipe`).
+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`.
+
API
---
diff --git a/doc/concepts/simulation.rst b/doc/concepts/simulation.rst
index 6dc7c055..c0ab208e 100644
--- a/doc/concepts/simulation.rst
+++ b/doc/concepts/simulation.rst
@@ -20,6 +20,15 @@ To build a simulation the following is needed:
not given, the default context will be used, which allocates one thread, one
process (MPI task), and no GPU.
+Configuring data extraction
+---------------------------
+
+Two kinds of data extraction can be set up:
+1. certain state variables can be :ref:`sampled <probesample>` by attaching a
+ sampler to a probe.
+2. spikes can be recorded by either a callback (C++) or a preset recording model
+ (Python), see the API docs linked below.
+
Simulation execution and interaction
------------------------------------
diff --git a/doc/python/simulation.rst b/doc/python/simulation.rst
index 943291e3..533041d7 100644
--- a/doc/python/simulation.rst
+++ b/doc/python/simulation.rst
@@ -214,7 +214,8 @@ over the local and distributed hardware resources (see :ref:`pydomdec`). Then, t
Recording spikes
----------------
-By default, spikes are not recorded. Recording is enabled with the
+Spikes are generated by various sources, including detectors and spike source
+cells, but by default, spikes are not recorded. Recording is enabled with the
:py:func:`simulation.record` method, which takes a single argument instructing
the simulation object to record no spikes, all locally generated spikes, or all
spikes generated by any MPI rank.
--
GitLab