From d7c7c28e54c12242f17fe08429be3976dd71ad35 Mon Sep 17 00:00:00 2001
From: Nora Abi Akar <nora.abiakar@gmail.com>
Date: Fri, 18 Dec 2020 11:02:25 +0100
Subject: [PATCH] Docs: Miscellaneous (#1281)
* `concepts/cable_cell`: number subcategories to better illustrate document structure.
* `concepts/labels`: concretize -> thingify; more on label dictionaries.
* `concepts/mechanisms`: Some info on modcc, link to nmodl files in repo.
* `concepts/morphology`: NeuroML section and some notes on branches/segments
---
doc/concepts/cable_cell.rst | 38 ++++++++---------
doc/concepts/labels.rst | 52 ++++++++++++++++--------
doc/concepts/mechanisms.rst | 42 ++++++++++++++-----
doc/concepts/morphology.rst | 81 +++++++++++++++++++++++++++++++------
doc/python/labels.rst | 2 +-
5 files changed, 155 insertions(+), 60 deletions(-)
diff --git a/doc/concepts/cable_cell.rst b/doc/concepts/cable_cell.rst
index b54d8ab9..7042c197 100644
--- a/doc/concepts/cable_cell.rst
+++ b/doc/concepts/cable_cell.rst
@@ -3,8 +3,8 @@
Cable cells
===========
-An Arbor *cable cell* is a full description of a cell with morphology and cell
-dynamics like ion species and their properties, ion
+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 sites, stimuli and spike detectors.
Cable cells are constructed from three components:
@@ -41,7 +41,7 @@ Once constructed, the cable cell can be queried for specific information about t
.. _cablecell-decoration:
Decoration
-----------------
+----------
The distribution and placement of dynamics on a cable cell is called the *decor* of a cell.
A decor is composed of individual *decorations*, which associate a property or dynamic process
@@ -114,8 +114,8 @@ will override any cell-local or global definition on that region.
.. _cablecell-properties:
-Cable properties
-~~~~~~~~~~~~~~~~
+1. Cable properties
+~~~~~~~~~~~~~~~~~~~
There are four cable properties that must be defined everywhere on a cell:
@@ -149,8 +149,8 @@ specialised on specific regions.
.. _cablecell-density-mechs:
-Density mechanisms
-~~~~~~~~~~~~~~~~~~~~~~
+3. Density mechanisms
+~~~~~~~~~~~~~~~~~~~~~
Regions can have density mechanisms defined over their extents.
Density mechanisms are :ref:`NMODL mechanisms <nmodl>`
@@ -203,8 +203,8 @@ Take for example a mechanism passive leaky dynamics:
.. _cablecell-ions:
-Ion species
-~~~~~~~~~~~
+4. Ion species
+~~~~~~~~~~~~~~
Arbor allows arbitrary ion species to be defined, to extend the default
calcium, potassium and sodium ion species.
@@ -303,32 +303,32 @@ and are assigned to specific locations.
.. _cablecell-synapses:
-Connection sites
-~~~~~~~~~~~~~~~~
+1. Connection sites
+~~~~~~~~~~~~~~~~~~~
Connections (synapses) are instances of NMODL POINT mechanisms. See also :ref:`modelconnections`.
.. _cablecell-gj-sites:
-Gap junction sites
-~~~~~~~~~~~~~~~~~~
+2. Gap junction sites
+~~~~~~~~~~~~~~~~~~~~~
See :ref:`modelgapjunctions`.
.. _cablecell-threshold-detectors:
-Threshold detectors (spike detectors).
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+3. Threshold detectors (spike detectors).
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _cablecell-stimuli:
-Stimuli
-~~~~~~~~
+4. Stimuli
+~~~~~~~~~~
.. _cablecell-probes:
-Probes
-~~~~~~
+5. Probes
+~~~~~~~~~
.. _cablecell-cv-policies:
diff --git a/doc/concepts/labels.rst b/doc/concepts/labels.rst
index 2487ebaa..a9a2d458 100644
--- a/doc/concepts/labels.rst
+++ b/doc/concepts/labels.rst
@@ -1,7 +1,7 @@
.. _labels:
-Cell labels
-===========
+Cable cell labels
+=================
Arbor provides a domain specific language (DSL) for describing regions and
locations on morphologies, and a dictionary for associating these descriptions
@@ -44,12 +44,12 @@ tapers from 4 μm to 0.4 μm attached to the proximal end of the soma; and the s
axon proper with constant radius 0.4 μm.
Label types
-------------
+-----------
.. _labels-locset:
Locsets
-~~~~~~~~~~~
+~~~~~~~
A *locset* is a set of locations on a morphology, specifically a *multiset*,
which may contain multiple instances of the same location, for example:
@@ -72,7 +72,7 @@ which may contain multiple instances of the same location, for example:
.. _labels-region:
Regions
-~~~~~~~~~~~~
+~~~~~~~
A *region* is a subset of a morphology's cable segments, for example:
@@ -157,7 +157,7 @@ describes the region of all parts of a cell with either tag 3 or tag 4 and radiu
.. _labels-expr-docs:
Expression syntax
-~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
The DSL uses `s-expressions <https://en.wikipedia.org/wiki/S-expression>`_, which are composed of the following basic types:
@@ -201,7 +201,7 @@ dendritic tree where the radius first is less than or equal to 0.2 μm.
Locset expressions
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
.. figure:: ../gen-images/label_branch.svg
:width: 800
@@ -348,7 +348,7 @@ Locset expressions
(join (location 1 0.5) (location 2 0.1) (location 1 0.2) (location 1 0.5) (location 4 0))
Region expressions
-~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
.. label:: (nil)
@@ -570,20 +570,21 @@ Region expressions
Two regions (left and middle) and their intersection (right).
-.. _labels-concretise:
+.. _labels-thingify:
-Concretisation
-----------------
+Thingification
+--------------
-When a region or locset expression is applied to a cell morphology it is
-*concretised*. Concretising a locset will return a set of *locations* on the
-morphology, and concretising a region will return a list of unbranched *cables*
-on the morphology.
+When a region or locset expression is applied to a cell morphology, it is represented
+as a list of unbranched *cables* or a set of *locations* on the morphology.
+This process is called ``thingify`` in arbor, because it turns the abstract description
+of a region or a loscet into an actual 'thing' when it is applied to a real morphology.
.. note::
Applying an expression to different morphologies may give different
- concretised results.
+ thingified results.
+.. _labels-locations:
Locations
~~~~~~~~~
@@ -599,8 +600,9 @@ Examples of locations, :ref:`expressed using the DSL <labels-location-def>`, inc
* The end of branch 5 ``(location 5 1)``.
* One quarter of the way along branch 5 ``(location 5 0.25)``.
+.. _labels-cables:
Cables
-~~~~~~~~~
+~~~~~~
An unbranched *cable* is a tuple of the form ``(branch, prox, dist)``,
where ``branch`` is the branch id, and ``0 ≤ prox ≤ dist ≤ 1`` define the relative position
@@ -631,6 +633,22 @@ also be valid expressions in the region DSL; creating a label ``"(tag 1)"`` will
lead to confusion.
Labels are stored with their associated expressions as key-value pairs in *label dictionaries*.
+Label dictionaries are then used to create a cable-cell along with the :ref:`morphology <co_morphology>`
+and a :ref:`decor <cablecell-decoration>`. The decorations can be painted or placed on
+the regions or locsets defined in the label dictionary by referring to their labels.
+
+.. code-block:: python
+ :caption: Example of a lable dictionary in python:
+
+ arbor.label_dict({
+ 'soma': '(tag 1)', # soma is every cable with tag 1 in the morphology.
+ 'axon': '(tag 2)', # axon is every cable with tag 2 in the morphology.
+ 'dend': '(tag 3)', # dend is every cable with tab 3 in the morphology
+ 'root': '(root)', # typically the start of the soma is at the root of the cell.
+ 'stim_site': '(location 0 0.5)', # site for the stimulus, in the middle of branch 0.
+ 'axon_end': '(restrict (terminal) (region "axon"))'} # end of the axon.
+ })
+
API
diff --git a/doc/concepts/mechanisms.rst b/doc/concepts/mechanisms.rst
index f8072c14..e5074430 100644
--- a/doc/concepts/mechanisms.rst
+++ b/doc/concepts/mechanisms.rst
@@ -1,7 +1,7 @@
.. _mechanisms:
-Cell mechanisms
-===============
+Cable cell mechanisms
+=====================
Mechanisms describe biophysical processes such as ion channels and synapses.
Mechanisms are assigned to regions and locations on a cell morphology
@@ -9,8 +9,15 @@ through the process of :ref:`decoration <cablecell-decoration>`.
Mechanisms are described using a dialect of the :ref:`NMODL <nmodl>` domain
specific language that is similarly used in `NEURON <https://neuron.yale.edu/neuron/>`_.
+Arbor supports mechanism descriptions using the NMODL language through our ``modcc``
+compiler. ``modcc`` supports many of NMODL's features but there are a few
+additional `guidelines <https://github.com/arbor-sim/arbor/wiki/Arbor's-NMODL-guidlines>`_
+for users who wish to compile their own mechanisms for Arbor. Unfortunately, out-of-tree
+mechanism building is not yet supported in Arbor. However, we have many built-in mechanisms
+that can be used, which are oragnized in *mechanism catalogues*.
+
Mechanism catalogues
-----------------------
+--------------------
A *mechanism catalogue* is a collection of mechanisms that maintains:
@@ -19,7 +26,14 @@ A *mechanism catalogue* is a collection of mechanisms that maintains:
global parameters, ion bindings, and implementations.
3. A map for looking up a concrete mechanism implementation on a target hardware back end.
-Derived mechanisms will always have a different name to the mechanism from which they are derived. This name is given explicitly when the derivation is constructed, or implicitly when a mechanism is :ref:`requested <mechanisms-name-note>` with a name of the form ``"mech/param=value,..."``. In this instance, if a mechanism of that name does not already exist in the catalogue, it will be implicitly derived from an existing mechanism ``"mech"`` with global parameters and ion bindings set according to the assignments following the slash. If the mechanism ``"mech"`` depends upon only a single ion, the name of that ion can be omitted in the assignments: ``"mech/oldion=newion"`` and ``"mech/newion"`` are equivalent derivations.
+Derived mechanisms will always have a different name to the mechanism from which they are derived.
+This name is given explicitly when the derivation is constructed, or implicitly when a mechanism
+is :ref:`requested <mechanisms-name-note>` with a name of the form ``"mech/param=value,..."``.
+In this instance, if a mechanism of that name does not already exist in the catalogue, it will be
+implicitly derived from an existing mechanism ``"mech"`` with global parameters and ion bindings
+set according to the assignments following the slash. If the mechanism ``"mech"`` depends upon
+only a single ion, the name of that ion can be omitted in the assignments:
+``"mech/oldion=newion"`` and ``"mech/newion"`` are equivalent derivations.
Catalogues provide an interface for querying mechanism metadata, which includes the following information:
@@ -27,10 +41,18 @@ Catalogues provide an interface for querying mechanism metadata, which includes
* Global parameter names, units, and default values.
* Range parameter names, units, and default values.
* State variable names, units and default values.
-* Ion dependencies: for each ion used by the mechanism, information on whether the mechanism writes to its internal or external concentration or to its reversal potential value, and whether it reads or asserts the ionic charge.
+* Ion dependencies: for each ion used by the mechanism, information on whether the mechanism writes
+ to its internal or external concentration or to its reversal potential value, and whether it reads
+ or asserts the ionic charge.
+
+Arbor provides a default catalogue of mechanisms as well as two other catalogues containing the sets of common mechanisms
+used by the `Allen Institute <https://alleninstitute.org/>`_ and the `Blue Brain Project <https://portal.bluebrain.epfl.ch/>`_.
+(Find the NMODL decsriptions of the `default mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/default>`_,
+the `Allen institute mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/allen>`_ and
+the `BBP mechanisms <https://github.com/arbor-sim/arbor/tree/master/mechanisms/bbp>`_ at the provided links.)
-Default mechanisms
-''''''''''''''''''
+Default catalogue
+'''''''''''''''''
Arbor provides a default catalogue with the following mechanisms:
@@ -103,9 +125,9 @@ computing ionic reversal potentials.
Density mechanisms
''''''''''''''''''''''
-Density mechanisms are :ref:`NMODL mechanisms <nmodl>`
-which describe biophysical processes that are distributed in space, but whose behaviour
-is defined purely by the state of the cell and the process at any given point.
+Density mechanisms describe biophysical processes that are distributed in space,
+but whose behaviour is defined purely by the state of the cell and the process
+at any given point.
Density mechanisms are commonly used to describe ion channel dynamics,
for example the ``hh`` and ``pas`` mechanisms provided by NEURON and Arbor,
diff --git a/doc/concepts/morphology.rst b/doc/concepts/morphology.rst
index 6d73c1d7..769c5c95 100644
--- a/doc/concepts/morphology.rst
+++ b/doc/concepts/morphology.rst
@@ -1,15 +1,16 @@
.. _morph:
-Cell morphology
-===============
+Cable cell morphology
+=====================
A cell's *morphology* describes both its geometry and branching structure.
Morphologies in Arbor are modelled as a set of one dimensional cables of variable radius,
-joined together to form a tree.
+joined together to form a tree. Only :ref:`cable cells <modelcablecell>` support custom
+morphologies in Arbor.
-The building blocks of morphology tree are points and segments.
-A *point* is a three-dimensional location and a radius, used to mark the centre and radius
-of the cable.
+The building blocks of a morphology tree are points and segments.
+A *point* is a three-dimensional location and a radius, used to mark the cross-sectional
+centre and radius of the cable.
.. csv-table::
:widths: 10, 10, 30
@@ -140,11 +141,11 @@ uses 4 segments to model the soma.
.. _morph-morphology:
-Geometry
---------
+Morphology
+----------
-A *morphology* describes the geometry of a cell as unbranched cables with variable radius
-, and their associated tree structure.
+A *morphology* describes the geometry of a cell as unbranched cables with variable radius,
+and their associated tree structure.
Every segment tree can be used to generate a unique morphology, which derives and enumerates
*branches* from the segments.
The branches of a morphology are unbranched cables, composed of one or more segments, where:
@@ -183,7 +184,7 @@ which is illustrated along with its branches below.
:align: center
The code used to generate this morphology is in the :class:`segment_tree<arbor.segment_tree>`
- documentation :ref:`below <morph-label-seg-code>`.
+ :ref:`python documentation <morph-label-seg-code>`.
The first branch contains the soma and the first two segments of the dendritic tree.
There are four more branches in the dendritic tree, and one representing the two
@@ -271,6 +272,18 @@ multiple soma and dendrite segments in branch 0.
ion channels, by using referring to all parts of the cell with
:ref:`tag 1 <labels-expressions>`.
+.. Note::
+ This representation of the cell morphology in terms of *branches* is what
+ Arbor uses to create a :ref:`cable cell <cablecell>`, and it is how Arbor
+ view's the cell's geometry and refers to it internally.
+ :ref:`Regions <labels-region>` and :ref:`locsets <labels-locset>` formed
+ on the cell, are eventually represented either as
+ :ref:`subsets of branches <labels-cables>` of the morphology, or exact
+ :ref:`locations on branches <labels-locations>` of the morphology.
+
+ Once the morphology is formed from a segment tree, the specific segments
+ are no longer of much use for the user and it is better to think of the
+ cell structure as Arbor does: in terms of branches.
Examples
~~~~~~~~~~~~~~~
@@ -492,8 +505,11 @@ SWC
Arbor supports reading morphologies described using the
`SWC <http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html>`_ file format.
-SWC files may contain comments, which are stored as metadata. A blank line anywhere in the file is
-interpreted as end of data. The description of the morphology is encoded as a list of samples with an id,
+
+SWC files may contain comments, which are stored as metadata. And a blank line anywhere in the file is
+interpreted as end of data.
+
+The description of the morphology is encoded as a list of samples with an id,
an `x,y,z` location in space, a radius, a tag and a parent id. Arbor parses these samples, performs some checks,
then generates a morphology according to one of three possible interpretations.
@@ -575,6 +591,45 @@ interpreter:
* To create a segment with a certain tag, that is to be attached to the soma, we need at least 2 samples with that
tag.
+NeuroML
+~~~~~~~
+
+Arbor offers limited support for models described in `NeuroML version 2 <https://neuroml.org/neuromlv2>`_.
+This is not built by default (see :ref:`NeuroML support <install-neuroml>` for instructions on how
+to build arbor with NeuroML).
+
+Once support is enabled, Arbor is able to parse and check the validity of morphologies described in NeuroML files,
+and present the encoded data to the user. This is more than a simple a `segment tree`.
+
+NeuroML can encode in the same file multiple top-level morphologies, as well as cells:
+
+.. code:: XML
+
+ <neuroml xmlns="http://www.neuroml.org/schema/neuroml2">
+ <morphology id="m1">
+ <segment id="seg-0">
+ <proximal x="1" y="1" z="1" diameter="1"/>
+ <distal x="2" y="2" z="2" diameter="2"/>
+ </segment>
+ <segmentGroup id="group-0">
+ <member segment="1"/>
+ </segmentGroup>
+ </morphology>
+ <morphology id="m2"/>
+ <cell id="c1" morphology="m1"/>
+ <cell id="c2">
+ <morphology id="m3"/>
+ </cell>
+ </neuroml>
+
+The above NeuroML description defines 2 top-level morphologies ``m1`` and ``m2`` (empty); a cell ``c1`` that uses
+morphology ``m1``; and a cell ``c2`` that uses an internally defined (empty) morphology ``m3``.
+
+Arbor can query the cells and morphologies using their ids and return all the associated morphological data for each.
+The morphological data includes the actual morphology as well as the named segments and groups of the morphology.
+For example, the above ``m1`` morphology has one named segment ``seg-0`` and one named group ``group-0`` that are
+both represented using Arbor's :ref:`region expressions <labels-expressions>`.
+
API
---
diff --git a/doc/python/labels.rst b/doc/python/labels.rst
index d4aa13c9..37492a2a 100644
--- a/doc/python/labels.rst
+++ b/doc/python/labels.rst
@@ -115,7 +115,7 @@ two labels refer to one another:
.. note::
In the example above there will be no error when the label dictionary is defined.
Instead, there will be an error later when the label dictionary is applied to
- a morphology, and the cyclic dependency is detected when concretising the locations
+ a morphology, and the cyclic dependency is detected when thingifying the locations
in the locsets and the cable segments in the regions.
--
GitLab