# 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, 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 constant radius 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 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 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 is 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 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 expression 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`

, where`0 ≤ 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 μm`pos=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 direction`distance`

μm. The locations in the output have a one to one correspondence with those in`ls`

.

- (distal-translate ls:locset distance:real)#
The set of locations that correspond to translating each location in

`ls`

in the distal direction`distance`

μ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 region`reg`

.

- (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 of`0 ≤ 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 μm`prox=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 locset`start`

is the union of the distal interval of each location in`start`

.

- (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 in`start`

.

- (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 locset`start`

is the union of the proximal interval of each location in`start`

.

- (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 than`radius`

.

- (radius-le reg:region radius:real)#
All parts of cable segments in the region

`reg`

with radius less than or equal to`radius`

.

- (radius-gt reg:region radius:real)#
All parts of cable segments in the region

`reg`

with radius greater than`radius`

.

- (radius-ge reg:region radius:real)#
All parts of cable segments in the region

`reg`

with radius greater than or equal to`radius`

.

- (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 that`p`

’s z-coordinate is less than, less than or equal, greater than, or greater than or equal to`dist`

.

### Inhomogeneous Expressions#

- (scalar value:real)#
A scalar of 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 parameter`scale`

has unit \({\mu m}^{-1}\) and is multiplied with 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 parameter`scale`

has unit \({\mu m}^{-1}\) and is multiplied with 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 parameter`scale`

has unit \({\mu m}^{-1}\) and is multiplied with 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 parameter`scale`

has unit \({\mu m}^{-1}\) and is multiplied with 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 distal direction from the points within the locset

`loc`

. The scaling parameter`scale`

has unit \({\mu m}^{-1}\) and is multiplied with 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 parameter`scale`

has unit \({\mu m}^{-1}\) and is multiplied with 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 proximal direction in locset

`prox_loc`

and the closest point in distal direction`dist_loc`

with the assosiated unitless values`prox_value`

and`dist_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 proximal diretion and the region`dist_reg`

in distal direction with the associated unitless values`prox_value`

and`dist_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 the 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 the 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++