From fdd30bdaa1c5856576f67939a9861d95397201f1 Mon Sep 17 00:00:00 2001
From: Nora Abi Akar <nora.abiakar@gmail.com>
Date: Fri, 18 Dec 2020 11:07:44 +0100
Subject: [PATCH] Docs: Add missing class descriptions (#1280)
Add API for `single_cell_model` and `label_dict`
---
doc/concepts/labels.rst | 2 +-
doc/python/index.rst | 1 +
doc/python/labels.rst | 30 +++++++++++-
doc/python/single_cell_model.rst | 76 ++++++++++++++++++++++++++++++
doc/tutorial/single_cell_model.rst | 13 +++--
5 files changed, 113 insertions(+), 9 deletions(-)
create mode 100644 doc/python/single_cell_model.rst
diff --git a/doc/concepts/labels.rst b/doc/concepts/labels.rst
index a9a2d458..97ba60a6 100644
--- a/doc/concepts/labels.rst
+++ b/doc/concepts/labels.rst
@@ -654,5 +654,5 @@ the regions or locsets defined in the label dictionary by referring to their lab
API
---
-* :ref:`Python <py_labels>`
+* :ref:`Python <pylabels>`
* *TODO*: C++ documentation.
diff --git a/doc/python/index.rst b/doc/python/index.rst
index f9cf4589..4aaca827 100644
--- a/doc/python/index.rst
+++ b/doc/python/index.rst
@@ -51,3 +51,4 @@ These details are described and examples are given in the next sections :ref:`py
morphology
labels
mechanisms
+ single_cell_model
diff --git a/doc/python/labels.rst b/doc/python/labels.rst
index 37492a2a..faef5675 100644
--- a/doc/python/labels.rst
+++ b/doc/python/labels.rst
@@ -1,8 +1,36 @@
-.. _py_labels:
+.. _pylabels:
Cell labels
===========
+.. currentmodule:: arbor
+
+.. py:class:: label_dict
+
+ Stores labels and their associated expressions as key-value pairs.
+
+ .. method:: label_dict()
+
+ Create an empty label dictionary
+
+ .. method:: label_dict(dictionary)
+
+ Initialize a label dictionary from a ``dictionary`` with string labels as keys,
+ and corresponding string definitions as values.
+
+ .. code-block:: python
+
+ labels = arbor.label_dict({'soma': '(tag 1)', # region
+ 'center': '(location 0 0.5)'}) # locset
+
+ .. attribute:: regions
+
+ The region definitons in the dictionary.
+
+ .. attribute:: locsets
+
+ The locset definitons in the dictionary.
+
The ``arbor.label_dict`` type is used for creating and manipulating label dictionaries,
which can be initialised with a dictionary that defines (label, expression)
pairs. For example, a dictionary that uses tags that correspond to SWC
diff --git a/doc/python/single_cell_model.rst b/doc/python/single_cell_model.rst
new file mode 100644
index 00000000..20be222e
--- /dev/null
+++ b/doc/python/single_cell_model.rst
@@ -0,0 +1,76 @@
+.. _pysinglecellmodel:
+
+Single cell model
+=================
+
+.. currentmodule:: arbor
+
+.. py:class:: single_cell_model
+
+ Wrapper for simplified description and execution of single cell models.
+ Only available in the python library.
+ Abstracts away the details of a :class:`recipe`, :class:`context` and
+ :class:`domain_decomposition` for simulations of single, stand-alone
+ cable cells.
+ The simulation can not be distributed over several machines.
+
+ .. method:: single_cell_model(cable_cell)
+
+ Construct a :class:`single_cell_model` from a :class:`cable_cell`
+
+ .. method:: run(tfinal, dt)
+
+ Run the model from time t= ``0`` to t= ``tflinal`` with a dt= ``dt``.
+
+ .. method:: probe(what, where, frequency)
+
+ Sample a variable on the cell:
+
+ :param what: Name of the variable to record (currently only 'voltage').
+ :param where: :class:`location` at which to sample the variable.
+ :param frequency: The frequency at which to sample [Hz].
+
+ .. method:: spikes()
+
+ Returns a list spike times [ms] after a call to :class:`single_cell_model.run`.
+
+ .. method:: traces()
+
+ Returns a list of :class:`trace` after a call to :class:`single_cell_model.run`.
+ Each element in the list holds the trace of one of the probes added via
+ :class:`single_cell_model.probe`.
+
+ .. attribute:: properties
+
+ The :class:`cable_global_properties` of the model.
+
+ .. attribute:: catalogue
+
+ The :class:`mechanism_catalogue` of the model.
+
+.. py:class:: trace
+
+ Stores a trace obtained from a probe after running a model.
+
+ .. attribute:: variable
+
+ Name of the variable being recorded. Currently only 'voltage'.
+
+ .. attribute:: loc
+
+ :class:`location` of the trace
+
+ .. attribute:: t
+
+ Sample times [ms]
+
+ .. attribute:: v
+
+ Sample values [units specific to sample variable]
+
+.. Note::
+
+ The :class:`single_cell_model` is used in our :ref:`tutorials <gs_other_examples>`.
+ The examples illustrate how to construct a :class:`cable_cell` and use it to form
+ a :class:`single_cell_model`; how to add probes; how to run the model; and how to
+ visualize the results.
\ No newline at end of file
diff --git a/doc/tutorial/single_cell_model.rst b/doc/tutorial/single_cell_model.rst
index 0167bba6..5e98fbd5 100644
--- a/doc/tutorial/single_cell_model.rst
+++ b/doc/tutorial/single_cell_model.rst
@@ -99,9 +99,8 @@ Single cell model
Once the cell description has been built, the next step is to build and run the simulation.
Arbor provides an interface for constructing single cell models with the
-:class:`arbor.single_cell_model<arbor.single_cell_model>`
-helper that creates a model from a cell description, with an interface for
-recording outputs and running the simulation.
+:class:`arbor.single_cell_model` helper that creates a model from a cell description, with
+an interface for recording outputs and running the simulation.
.. code-block:: python
@@ -114,10 +113,10 @@ recording outputs and running the simulation.
# (7) Run simulation for 30 ms of simulated activity.
m.run(tfinal=30)
-Step **(5)** instantiates the :class:`arbor.single_cell_model<arbor.single_cell_model>`
+Step **(5)** instantiates the :class:`arbor.single_cell_model`
with our single-compartment cell.
-Step **(6)** adds a :meth:`arbor.single_cell_model.probe()<arbor.single_cell_model.probe>`
+Step **(6)** adds a :meth:`arbor.single_cell_model.probe`
used to record variables from the model. Three pieces of information are
provided: the type of quantity we want probed (voltage), the location where we want to
probe ('"center"'), and the frequency at which we want to sample (10kHz).
@@ -146,12 +145,12 @@ the spike detector and a voltage probes from our model have produced.
df = pandas.DataFrame({'t/ms': m.traces[0].time, 'U/mV': m.traces[0].value})
seaborn.relplot(data=df, kind="line", x="t/ms", y="U/mV",ci=None).savefig('single_cell_model_result.svg')
-Step **(8)** accesses :meth:`arbor.single_cell_model.spikes<arbor.single_cell_model.spikes>`
+Step **(8)** accesses :meth:`arbor.single_cell_model.spikes`
to print the spike times. A single spike should be generated at around the same time the stimulus
we provided in step (3) gets activated (10ms).
Step **(9)** plots the measured potentials during the runtime of the simulation. The sampled quantities
-can be accessed through :meth:`arbor.single_cell_model.traces<arbor.single_cell_model.traces>`.
+can be accessed through :meth:`arbor.single_cell_model.traces`.
We should be seeing something like this:
.. figure:: single_cell_model_result.svg
--
GitLab