From 7c9a3193a73696ca31ac283b6b2d92bfd04b7e6f Mon Sep 17 00:00:00 2001
From: Ben Cumming <bcumming@cscs.ch>
Date: Mon, 7 Sep 2020 15:27:39 +0200
Subject: [PATCH] update flat_cell_builder docs and add deprecation warning
(#1130)
Update flat_cell_builder docs and add deprecation warning.
Addresses #1129.
---
doc/single_cell.rst | 84 +++++++++++++--------------------------------
1 file changed, 23 insertions(+), 61 deletions(-)
diff --git a/doc/single_cell.rst b/doc/single_cell.rst
index a92cab5b..f60f37f0 100644
--- a/doc/single_cell.rst
+++ b/doc/single_cell.rst
@@ -88,24 +88,29 @@ an interface for recording
m.run(tfinal=100)
Step (4) instantiates the single cell model using our single-compartment cell.
-To record variables from the model three pieces of information are prov
-*
-
-
-**Everything below here is to be discarded/moved**
+To record variables from the model three pieces of information are provided.
.. _single_morpho:
Morphology
----------
+.. warning::
+
+ The flat cell builder documented below is likely to change before
+ version 0.4 is released. It is a wrapper around a segment tree that
+ simplifies morphology construction when the spatial location of segments
+ is not important (for example, when we only need to describe the length,
+ radius and parent-child relationship of branches in the morphology).
+
The first step in building a cell model is to define the cell's *morphology*.
-Conceptually, Arbor treats morphologies as a tree of truncated frustums, with
-an optional spherical segment at the root of the tree.
+Conceptually, Arbor treats morphologies as a tree of truncated frustums.
These are represented as a tree of segments, where each segment is defined
by two end points with radius, and a tag, and a parent segment to which it is attached.
-Let's start with a simple "ball and stick" model cell.
+Let's start with a simple "ball and stick" model cell, with a spherical soma
+(the ball, treated as a cylinder with length=with) and a y-shaped dendritic
+tree (the sticks).
.. container:: example-code
@@ -114,9 +119,9 @@ Let's start with a simple "ball and stick" model cell.
import arbor
builder = arbor.flat_cell_builder()
- # Start with a spherical segment with radius 10 μm.
- # Label this segment 'soma'.
- p = builder.add_sphere(radius=10, name='soma')
+ # Start with the soma, which is a cylinder with the same area as
+ # a sphere of radius 5 μm. Label this segment 'soma'.
+ p = builder.add_cable(parent=arbor.mnpos, length=10, radius=5, name='soma')
# Attach a cable to the soma with length 100 μm and constant radius 4 μm.
q = builder.add_cable(parent=p, length=100, radius=4, name='dend')
@@ -125,55 +130,12 @@ Let's start with a simple "ball and stick" model cell.
p = builder.add_cable(parent=q, length=50, radius=(4,2), name='dend')
p = builder.add_cable(parent=q, length=50, radius=(4,2), name='dend')
+ # Generate the cable cell once all cables have been described.
+ cell = builder.build()
+
-Building the morphology there are two approaches: construct it manually using
-``segment_tree`` or ``flat_cell_builder``, or load from swc file.
-
-TODO: cover all methods here?
- - we could just ``flat_cell_builder`` because it is most comfortable for
- users coming over from NEURON.
- - have links to another page that goes into detail on all the different
- methods for morphology building. That page could take a moderately
- complicated, well-defined, morphology, and illustrate how to build
- it using all of the different methods.
-
-NEURON erratum
-------------------------------
-
-These should probably be combined into a single section that describes the differences
-between Arbor and NEURON, because the alternative is to keep stopping the
-narative to point out the difference with NEURON, instead of explaining what
-Arbor is from a fresh start.
-
-.. note::
- Most readers will be familiar with NEURON. Boxes like this
- will be used to highlight differences between NEURON and Arbor
- throughout the guide.
-
- NEURON users will recognise that Arbor uses many similar concepts, and
- an effort has been made to use the same nomenclature wherever possible.
-
- Arbor takes a more structured approach to model building,
- from morphology descriptions up to network connectivity, to allow model
- descriptions that are more scalable and portable.
-
-.. note::
- NEURON represents morphologies as a tree of cylindrical *segments*, whereas
- in Arbor the radius can vary linearly along segments.
-
- A cylinder with equal diameter and length is used to model spherical somata
- in NEURON, which coincidently has the same surface area as a sphere of the same diameter.
- Arbor allows the user to optionally use a spherical section at the root
- of the tree to represent spherical somata.
-
-.. note::
- In NEURON cell morphologies are constructed by creating individual sections,
- then connecting them together. In Arbor we start with an "empty"
- segment tree, to which segments are appended to build a connected morphology.
-
-1. Defining the `morphology <single_morpho_>`_ of the cell.
-2. Labeling regions and locations on the morphology.
-3. Defining the mechanisms that will be applied to the cell.
-4. Adding ion channels and synapses (mechanisms) to labeled regions and locations.
-5. Attaching stimuli, spike detectors, event generators and probes to locations (inputs & outputs).
+There are two approaches available for building a morphology: construct it manually using
+:ref:`segment tree<morph-segment_tree>` or ``flat_cell_builder``, or load from a file.
+The ``flat_cell_builder`` is a helper tool, that internally constructs a segment
+tree.
--
GitLab