Cable cell labels¶
Arbor provides a domain specific language (DSL) for describing regions and locations on morphologies, and a dictionary for associating these expressions with a string label.
The labels are used to refer to regions and locations when setting cell properties and attributes. For example, the membrane capacitance on a region of the cell membrane, or the location of synapse instances.
Example cell¶
The following morphology is used on this page to illustrate region and location descriptions. It has a soma, a dendritic tree, and an axon with a hillock:
Branch 0 contains the soma, which is modelled as a cylinder of length and diameter 4 μm, and the proximal unbranched section of the dendritic tree which has a radius of 0.75 μm, attached to the distal end of the soma.
The other branches in the dendritic tree have the following properties:
branch 1 tapers from 0.4 to 0.2 μm;
branch 2 has a constant radius of 0.5 μm;
branch 3 tapers from 0.5 to 0.2 μm;
branch 4 tapers from 0.5 to 0.2 μm.
Branch 5 is the axon, composed of two cable segments: an axon hillock with a radius that tapers from 4 μm to 0.4 μm attached to the proximal end of the soma, and the start of the axon proper with a constant radius of 0.4 μm.
Label types¶
- locset¶
A locset is a set of locations on a morphology, specifically a multiset, which may contain multiple instances of the same location.
Possible locsets might refer to:
The centre of the soma.
The locations of inhibitory synapses.
The tips of the dendritic tree.
Some common regions:
The soma.
The dendritic tree.
An explicit reference to a specific unbranched cable, e.g., “branch 3” or “the distal half of branch 1”.
The axon hillock.
The dendrites with a radius less than 1 μm.
It is possible for a region to be empty, for example, a region that defines the axon will be empty on a morphology that has no axon.
Regions do not need to be complete sub-trees of a morphology, for example, the region of cables that have a radius less than 0.5 μm below is composed of three disjoint sub-trees.
- iexpr¶
An iexpr is an inhomogeneous expression that can be evaluated at any point on a cell.
Expressions¶
Regions and locsets are described using expressions written with the DSL.
Examples of expressions that define regions include:
(all)
: the complete cell morphology.(tag 1)
: all segments with tag 1.(branch 2)
: branch 2.(region "soma")
: the region with the label “soma”.
Examples of expressions that define locsets include:
(root)
: the location of the root points.(terminal)
: the locations of the terminal points.(location 3 0.5)
: the mid point of branch 3.(locset "synapse-sites")
: the locset labelled “synapse-sites”.
Detailed descriptions for all of the region and locset expression types are given below.
Note
The example expressions above will look familiar to readers who have use the Lisp programming language. This is because both the DSL and Lisp use s-expressions, which are a simple way to represent a nested list of data.
However, the DSL is not a dialect of Lisp and has very simple semantics that are only limited to describing morphology features.
Expressions are composable, so that expressions can be constructed from simple expressions. For example, the expression:
(radius-lt (join (tag 3) (tag 4)) 0.5)
describes the region of all parts of a cell with either tag 3 or tag 4 and a radius less than 0.5 μm.
Expression syntax¶
The DSL uses s-expressions, which are composed of the following basic types:
- string¶
A string literal enclosed in quotes, e.g.
"dendrites"
.
- integer¶
An integer. e.g:
42
,-2
,0
.
- real¶
A floating point value. e.g:
2
,4.3
,.3
,-2.1e3
.
- region¶
An expression that evaluates to a region. e.g.
(all)
,(tag 3)
,(intersect (tag 3) (tag 4))
.
- locset¶
An expression that evaluates to a locset. e.g.
(root)
,(location 3 0.2)
,(proximal (tag 2))
.
Expressions can be written over multiple lines, and comments are marked with semi-colon. This can be used to make more complex expressions easier to read, for example, the following region that finds all the sub-trees that start at the locations on the dendritic tree where the radius first is less than or equal to 0.2 μm.
(distal-interval ; take subtrees that start at
(proximal ; locations closest to the soma
(radius-le ; with radius <= 0.2 um
(join (tag 3) (tag 4)) ; on basal and apical dendrites
0.2)))
Note
If the expression above at first seems a little complex, consider how the same thing could be achieved using hoc in NEURON, and whether it would be free of bugs and applicable to arbitrary morphologies.
Locset expressions¶
- (locset-nil)¶
The empty locset.
- (root)¶
The location of the root.
Equivalent to
(location 0 0)
.
- (location branch:integer pos:real)¶
A location on
branch
, where0 ≤ pos ≤ 1
gives the relative position between the proximal and distal ends of the branch. The position is in terms of branch length, so for example, on a branch of length 100 μmpos=0.2
corresponds to 20 μm from the proximal end, or 80 μm from the distal end.
- (terminal)¶
The location of terminal points, which are the most distal locations on the morphology. These will typically correspond to the tips, or end points, of dendrites and axons.
- (uniform reg:region first:int last:int seed:int)¶
- (on-branches pos:double)¶
The set of locations
{(location b pos) | 0 ≤ b < nbranch-1}
.
- (on-components pos:double)¶
Points on each component of the region proportional to
pos
.This shows the component centers of the dendrite, i.e.,
(on-components 0.5 (region "dend"))
.
- (distal reg:region)¶
The set of the most distal locations of a region. These are defined as the locations for which there are no other locations more distal in the region.
- (proximal reg:region)¶
The set of the most proximal locations of a region. These are defined as the locations for which there are no other locations more proximal in the region.
- (boundary reg:region), (cboundary reg:region), and (segment-boundaries)¶
Boundary of (completed) region and those of all segments. The examples show
(boundary (segment 2))
,(cboundary (segment 2))
, and(segment-boundaries)
.
- (proximal-translate ls:locset distance:real)¶
The set of locations that correspond to moving each location in the
ls
in the proximal directiondistance
μm. The locations in the output have a one-to-one correspondence with those inls
.
- (distal-translate ls:locset distance:real)¶
The set of locations that correspond to translating each location in
ls
in the distal directiondistance
μm or to a terminal location, whichever is closest.An input location will generate multiple output locations when it is translated past a fork point, with a new location for each child branch (see the example below). For this reason, there is not a one-to-one correspondence between locations in the input and output sets, so the results are sorted and duplicates are removed.
- (locset name:string)¶
Refer to a locset by its label. For example,
(locset "synapse-sites")
could be used in an expression to refer to a locset with the name"synapse-sites"
.
- (restrict-to locations:locset reg:region)¶
The set of locations in the locset
loc
that are in the regionreg
.
- (join lhs:locset rhs:locset [...locset])¶
Set intersection for two locsets, with duplicates removed and results sorted. For example, the following:
(join (join (location 1 0.5) (location 2 0.1) (location 1 0.2)) (join (location 1 0.5) (location 4 0)))
Gives the following:
(join (location 1 0.2) (location 1 0.5) (location 2 0.1) (location 4 0))
Note that
(location 1 0.5)
occurs in both the sets, and occurs only once in the result.
- (sum lhs:locset rhs:locset [...locset])¶
Multiset summation of two locsets, such that
(sum lhs rhs) = A + B
, where A and B are multisets of locations. This is equivalent to concatenating the two lists, and the length of the result is the sum of the lengths of the inputs. For example:(sum (join (location 1 0.5) (location 2 0.1) (location 1 0.2)) (join (location 1 0.5) (location 4 0)))
Gives the following:
(join (location 1 0.5) (location 2 0.1) (location 1 0.2) (location 1 0.5) (location 4 0))
- (support ls:locset)¶
Support of the multiset
ls
, i.e., set of all points in the locset such that each appears once.
Region expressions¶
- (region-nil)¶
An empty region.
- (all)¶
All branches in the morphology.
- (branch branch_id:integer)¶
Refer to a branch by its id.
- (segment segment_id:integer)¶
Refer to a segment by its id. Note that segment ids depend on the construction order of the morphology. Arbor’s morphology loaders are stable in this regard.
- (cable branch_id:integer prox:real dist:real)¶
An unbranched cable that is a subset of
branch
. The values of0 ≤ prox ≤ dist ≤ 1
are the relative position of the ends of the branch. The positions are in terms of branch length, so for example, on a branch of length 100 μmprox=0.2, dist=0.8
would give a cable that starts and ends 20 μm and 80 μm along the branch respectively.
- (region name:string)¶
Refer to a region by its label. For example,
(region "axon")
would refer to a region with the label"axon"
.
- (distal-interval start:locset extent:real)¶
The distal interval of a location is the region that contains all points that are distal to the location, and up to
extent
μm from the location, measured as the distance traversed along cables between two locations. The distal interval of the locsetstart
is the union of the distal interval of each location instart
.
- (distal-interval start:locset)¶
When no
extent
distance is provided, the distal intervals are extended to all terminal locations that are distal to each location instart
.
- (proximal-interval start:locset extent:real)¶
The proximal interval of a location is the region that contains all points that are proximal to the location, and up to
extent
μm from the location, measured as the distance traversed along cables between two locations. The proximal interval of the locsetstart
is the union of the proximal interval of each location instart
.
- (proximal-interval start:locset)¶
When no
extent
distance is provided, the proximal intervals are extended to the root location.
- (radius-lt reg:region radius:real)¶
All parts of cable segments in the region
reg
with radius less thanradius
.
- (radius-le reg:region radius:real)¶
All parts of cable segments in the region
reg
with radius less than or equal toradius
.
- (radius-gt reg:region radius:real)¶
All parts of cable segments in the region
reg
with radius greater thanradius
.
- (radius-ge reg:region radius:real)¶
All parts of cable segments in the region
reg
with radius greater than or equal toradius
.
- (join lhs:region rhs:region [...region])¶
The union of two or more regions.
- (intersect lhs:region rhs:region [...region])¶
The intersection of two or more regions.
- (difference lhs:region rhs:region)¶
The intersection of two regions.
- (complement reg:region)¶
The complement of a region.
- (complete reg:region)¶
Complete a region, i.e., add all covers of all included forks.
- (z-dist-from-root-lt dist:real), (z-dist-from-root-le dist:real), (z-dist-from-root-gt dist:real) and (z-dist-from-root-ge dist:real)¶
All points
p
of the morphology such thatp
’s z-coordinate is less than, less than or equal, greater than, or greater than or equal todist
.
Inhomogeneous Expressions¶
- (scalar value:real)¶
A scalar of a given value.
- (pi)¶
A scalar expression representing the pi constant.
- (distance scale:real loc:locset)¶
The minimum distance to points within the locset
loc
. The scaling parameterscale
has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.
- (distance loc:locset)¶
A distance expression with a default scaling factor of 1.0.
- (distance scale:real reg:region)¶
The minimum distance to the region
reg
. Evaluates to zero within the region. The scaling parameterscale
has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.
- (distance reg:region)¶
A distance expression with a default scaling factor of 1.0.
- (proximal-distance scale:real loc:locset)¶
The minimum distance in proximal direction from the points within the locset
loc
. The scaling parameterscale
has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.
- (proximal-distance loc:locset)¶
A proximal-distance expression with a default scaling factor of 1.0.
- (proximal-distance scale:real reg:region)¶
The minimum distance in proximal direction from the region
reg
. The scaling parameterscale
has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.
- (proximal-distance reg:region)¶
A proximal-distance expression with a default scaling factor of 1.0.
- (distal-distance scale:real loc:locset)¶
The minimum distance in the distal direction from the points within the locset
loc
. The scaling parameterscale
has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.
- (distal-distance loc:locset)¶
A distal-distance expression with a default scaling factor of 1.0.
- (distal-distance scale:real reg:region)¶
The minimum distance in distal direction from the region
reg
. The scaling parameterscale
has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.
- (distal-distance reg:region)¶
A distal-distance expression with a default scaling factor of 1.0.
- (interpolation prox_value:real prox_loc:locset dist_value:real dist_loc:locset)¶
Interpolates between the closest point in the proximal direction in locset
prox_loc
and the closest point in distal directiondist_loc
with the assosiated unitless valuesprox_value
anddist_value
. Evaluates to zero if no point is located in each required direction.Note: At any fork, an interpolation expression may be discontinuous, if the distance to the closest location within the distal locset differs along each attached branch.
- (interpolation prox_value:real prox_reg:region dist_value:real dist_reg:region)¶
Interpolates between the region
prox_reg
in the proximal direction and the regiondist_reg
in the distal direction with the associated unitless valuesprox_value
anddist_value
. If evaluated inside either region, returns the corresponding value. Evaluates to zero, if no region is located in each required direction.
- (radius scale:real)¶
The radius of the cell at a given point multiplied with the
scale
parameter with unit \({\mu m}^{-1}\).
- (radius)¶
A radius expression with a default scaling factor of 1.0.
- (diameter scale:real)¶
The diameter of the cell at a given point multiplied with the
scale
parameter with unit \({\mu m}^{-1}\).
- (diameter)¶
A diameter expression with a default scaling factor of 1.0.
- (add (iexpr | real) (iexpr | real) [... (iexpr | real)])¶
Addition of at least two inhomogeneous expressions or real numbers.
- (sub (iexpr | real) (iexpr | real) [... (iexpr | real)])¶
Subtraction of at least two inhomogeneous expressions or real numbers. The expression is evaluated from left to right, subtracting each element from the first one in turn.
- (mul (iexpr | real) (iexpr | real) [... (iexpr | real)])¶
Multiplication of at least two inhomogeneous expressions or real numbers.
- (div (iexpr | real) (iexpr | real) [... (iexpr | real)])¶
Division of at least two inhomogeneous expressions or real numbers. The expression is evaluated from left to right, dividing the first element by each divisor in turn.
- (exp value:(iexpr | real))¶
The exponential function of the inhomogeneous expression or real
value
.
- (step_right value:(iexpr | real))¶
The Heaviside step function of the inhomogeneous expression or real
value
, with (step 0.0) evaluating to 1.
- (step_left value:(iexpr | real))¶
The Heaviside step function of the inhomogeneous expression or real
value
, with (step 0.0) evaluating to 0.
- (step value:(iexpr | real))¶
The Heaviside step function of the inhomogeneous expression or real
value
, with (step 0.0) evaluating to 0.5.
- (log value:(iexpr | real))¶
The logarithm of the inhomogeneous expression or real
value
.
Thingification¶
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 locset into an actual ‘thing’ when it is applied to a real morphology.
Note
Applying an expression to different morphologies may give different thingified results.
Locations¶
A location on a cell is described using a tuple (branch, pos)
, where
branch
is a branch id, and 0 ≤ pos ≤ 1
is the relative distance along
the branch, given that 0 and 1 are the proximal and distal ends of the branch
respectively.
Examples of locations, expressed using the DSL, include:
The root
(location 0 0)
.The start of branch 5
(location 5 0)
.The end of branch 5
(location 5 1)
.One quarter of the way along branch 5
(location 5 0.25)
.
In general, a location on a component can be specific with on-components
, e.g.:
One quarter of the way along segment 3
(on-components 0.25 (segment 3))
.One tenth of the way along branch 4
(on-components 0.1 (branch 4))
(identical to(location 4 0.1)
).
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
of the end points of the section on the branch.
Examples of cables, expressed using the DSL, include:
All of branch 2
(cable 2 0 1)
.The middle third of branch 2
(cable 2 0.333 0.667)
.A zero-length cable in the middle of branch 2
(cable 2 0.5 0.5)
.
Note
Zero-length cables are permitted. They are not useful for defining membrane properties, which are applied to the surface of a region. However, they can occur as the result of sub-expressions in larger expressions that define non-trivial regions and locsets.
Label Dictionaries¶
- label¶
A label is a string assigned to an expression, and used to refer to the expression or the concrete region or locset or iexpr generated when the expression is applied to a morphology.
Although any string is a valid label, it is a good idea to avoid labels that would
also be valid expressions in the region DSL; creating a label "(tag 1)"
will only
lead to confusion.
- label dictionary¶
An Arbor structure in which labels are stored with their associated expressions as key-value pairs.
Label dictionaries are used to create a cable-cell along with the morphology and a decor. The decorations can be painted or placed on the regions, locsets, or iexpr defined in the label dictionary by referring to their labels.
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-to (terminal) (region "axon"))', # end of the axon.
'rad_expr': '(radius 0.5)' # iexpr evaluating the radius scaled by 0.5
})
API¶
C++