From 0998de7b53f22dac07a7451b4c84d7fd84beffb3 Mon Sep 17 00:00:00 2001
From: Brent Huisman <brenthuisman@users.noreply.github.com>
Date: Tue, 10 Aug 2021 14:55:48 +0200
Subject: [PATCH] Improved documentation about weights (#1620)
---
doc/python/interconnectivity.rst | 6 +++---
doc/python/recipe.rst | 4 +++-
doc/tutorial/network_ring.rst | 12 +++++++++---
python/example/network_ring.py | 4 ++--
4 files changed, 17 insertions(+), 9 deletions(-)
diff --git a/doc/python/interconnectivity.rst b/doc/python/interconnectivity.rst
index df1445d3..7bb2e8b1 100644
--- a/doc/python/interconnectivity.rst
+++ b/doc/python/interconnectivity.rst
@@ -32,9 +32,9 @@ Interconnectivity
.. attribute:: weight
- The weight delivered to the target synapse.
- The weight is dimensionless, and its interpretation is specific to the type of the synapse target.
- For example, the expsyn synapse interprets it as a conductance with units μS (micro-Siemens).
+ The weight delivered to the target synapse. It is up to the target mechanism to interpret this quantity.
+ For Arbor-supplied point processes, such as the ``expsyn`` synapse, a weight of ``1`` corresponds to an
+ increase in conductivity in the target mechanism of ``1`` μS (micro-Siemens).
.. attribute:: delay
diff --git a/doc/python/recipe.rst b/doc/python/recipe.rst
index 30a383b4..8e9419c8 100644
--- a/doc/python/recipe.rst
+++ b/doc/python/recipe.rst
@@ -118,7 +118,9 @@ Event generator and schedules
.. attribute:: weight
- The weight of events to deliver.
+ The weight delivered to the target synapse. It is up to the target mechanism to interpret this quantity.
+ For Arbor-supplied point processes, such as the ``expsyn`` synapse, a weight of ``1`` corresponds to an
+ increase in conductivity in the target mechanism of ``1`` μS (micro-Siemens).
.. class:: regular_schedule
diff --git a/doc/tutorial/network_ring.rst b/doc/tutorial/network_ring.rst
index ab4a341c..6c650ae1 100644
--- a/doc/tutorial/network_ring.rst
+++ b/doc/tutorial/network_ring.rst
@@ -44,7 +44,12 @@ These locations will form the endpoints of the connections between the cells.
After we've created a basic :py:class:`arbor.decor`, step **(3)** places a synapse with an exponential decay (``'expsyn'``) on the ``'synapse_site'``.
The synapse is given the label ``'syn'``, which is later used to form :py:class:`arbor.connection` objects terminating *at* the cell.
-Note that mechanisms can be initialized with their name; ``'expsyn'`` is short for ``arbor.mechanism('expsyn')``.
+
+.. Note::
+ Mechanisms can be initialized with their name; ``'expsyn'`` is short for ``arbor.mechanism('expsyn')``.
+ Mechanisms typically have some parameters, which can be queried (see :py:class:`arbor.mechanism_info`) and set
+ (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
:py:class:`arbor.connection` objects originating *from* the cell.
@@ -72,7 +77,8 @@ are connecting the cells **(8)**, returning a configurable number of cells **(6)
(``make_cable_cell()`` returns the cell above).
Step **(8)** creates an :py:class:`arbor.connection` between consecutive cells. If a cell has gid ``gid``, the
-previous cell has a gid ``(gid-1)%self.ncells``. The connection has a weight of 0.1 μS and a delay of 5 ms.
+previous cell has a gid ``(gid-1)%self.ncells``. The connection has a weight of 0.01 (inducing a conductance of 0.01 μS
+in the target mechanism ``expsyn``) and a delay of 5 ms.
The first two arguments to :py:class:`arbor.connection` are the **source** and **target** of the connection.
The **source** is a :py:class:`arbor.cell_global_label` object containing a cell index ``gid``, the source label
@@ -119,7 +125,7 @@ In addition to having the timestamps of spikes, we want to extract the voltage a
Step **(14)** sets the probes (step **10**) to measure at a certain schedule. This is sometimes described as
attaching a :term:`sampler` to a :term:`probe`. :py:func:`arbor.simulation.sample` expects a :term:`probe id` and the
-desired schedule (here: a recording frequency of 10 kHz). Note that the probe id is a separate index from those of
+desired schedule (here: a recording frequency of 10 kHz, or a ``dt`` of 0.1 ms). Note that the probe id is a separate index from those of
:term:`connection` endpoints; probe ids correspond to the index of the list produced by
:py:func:`arbor.recipe.probes` on cell ``gid``.
diff --git a/python/example/network_ring.py b/python/example/network_ring.py
index 2617a2de..c1c6a07b 100755
--- a/python/example/network_ring.py
+++ b/python/example/network_ring.py
@@ -87,7 +87,7 @@ class ring_recipe (arbor.recipe):
# (8) Make a ring network. For each gid, provide a list of incoming connections.
def connections_on(self, gid):
src = (gid-1)%self.ncells
- w = 0.01
+ w = 0.01 # 0.01 μS on expsyn
d = 5
return [arbor.connection((src,'detector'), 'syn', w, d)]
@@ -95,7 +95,7 @@ class ring_recipe (arbor.recipe):
def event_generators(self, gid):
if gid==0:
sched = arbor.explicit_schedule([1])
- weight = 0.1
+ weight = 0.1 # 0.1 μS on expsyn
return [arbor.event_generator('syn', weight, sched)]
return []
--
GitLab