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:

Segments of the morphology are coloured according to tags: soma (tag 1, red), axon (tag 2, grey), dendrites (tag 3, blue) (left). The 6 branches of the morphology with their branch ids (right).

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.

Examples of locsets on the example morphology. The terminal points (left). Fifty random locations on the dendritic tree (right). The root of the morphology is shown with a red circle for reference.

region

A region is a subset of a morphology’s cable segments.

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.

Examples of regions on the example morphology. Left: The dendritic tree. Right: All cables with a radius less than 0.5 μm.

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.

The input morphology with branch numbers for reference in the examples below.

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.

The result of (location 1 0.5), which corresponds to the mid point of branch 1.

(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.

The terminal points, generated with (terminal).

(uniform reg:region first:int last:int seed:int)

Ten random locations on the dendrites drawn using different random seeds. On the left with a seed of 0: (uniform (tag 3) 0 9 0), and on the right with a seed of 1: (uniform (tag 3) 0 9 1).

(on-branches pos:double)

The set of locations {(location b pos) | 0 ≤ b < nbranch-1}.

The set of locations at the midpoint of every branch, expressed as (on-branches 0.5).

(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.

On the left is the region with a radius between 0.3 μm and 0.5 μm. The right shows the distal set of this 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.

On the left is the region with a radius between 0.3 μm and 0.5 μm. The right shows the proximal set of this 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.

The proximal translation of the terminal locations (left) a distance of 10 μm using the expression (proximal-translate (terminal) 10).

(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.

Two distal translations of the midpoint of branch 0 (left). The first translation of 5 μm, (distal-translate (location 0 0.5) 5), generates a single location on the same branch (center). The second translation of 15 μm (distal-translate (location 0 0.5) 15) extends beyond the end of branch 0, generating an additional location at each fork point (right).

(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.

The result of restricting the terminal locations (left) onto the dendritic tree (middle) is the tips of the dendritic tree (right).

(restrict-to (terminal) (tag 3))

(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.

The trivial region definitions (region-nil) (left) and (all) (right).

(tag tag_id:integer)

All of the segments with tag tag_id.

The soma, axon and dendritic tree, selected using (tag 1), (tag 2), and (tag 3) respectively.

(branch branch_id:integer)

Refer to a branch by its id.

Branches 0 and 3, selected using (branch 0) and (branch 3) respectively.

(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.

Segments 0 and 3, selected using (segment 0) and (segment 3) respectively.

(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.

Selecting parts of branch 1, from left to right: (cable 1 0 1) to select the whole branch, (cable 1 0.3 1) and (cable 0 0.3 0.7) to select part of the branch.

(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.

On the left is a locset of 3 locations: 1 on the axon and 2 in the dendritic tree. The right shows the locset’s distal interval with extent 5 μm, formed with the following expression:

(distal-interval (sum (location 1 0.5) (location 2 0.7) (location 5 0.1)) 5)

(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.

On the left is a locset of 3 locations: 1 on the axon and 2 in the dendritic tree. The right shows the locset’s distal interval formed with the following expression:

(distal-interval (sum (location 1 0.5) (location 2 0.7) (location 5 0.1)))

(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.

On the left is a locset with two locations on separate sub-trees of the dendritic tree. On the right is their proximal interval with an extent of 5 μm, formed as follows:

(proximal-interval (sum (location 1 0.8) (location 2 0.3)) 5)

(proximal-interval start:locset)

When no extent distance is provided, the proximal intervals are extended to the root location.

On the left is a locset with two locations on separate sub-trees of the dendritic tree. On the right is their proximal interval formed as follows:

(proximal-interval (sum (location 1 0.8) (location 2 0.3)))

(radius-lt reg:region radius:real)

All parts of cable segments in the region reg with radius less than radius.

All cable segments with radius less than 0.5 μm, found by applying radius-lt to all of the cables in the morphology. Note that branch 2, which has a constant radius of 0.5 μm, is not in the result because its radius is not strictly less than 0.5 μm.

(radius-lt (all) 0.5)

(radius-le reg:region radius:real)

All parts of cable segments in the region reg with radius less than or equal to radius.

All cable segments with radius less than or equal to 0.5 μm, found by applying radius-le to all of the cables in the morphology. Note that branch 2, which has a constant radius of 0.5 μm, is in the result.

(radius-le (all) 0.5)

(radius-gt reg:region radius:real)

All parts of cable segments in the region reg with radius greater than radius.

All cable segments with radius greater than 0.5 μm, found by applying radius-ge to all of the cables in the morphology. Note that branch 2, which has a constant radius of 0.5 μm, is not in the result because its radius is not strictly greater than 0.5 μm.

(radius-gt (all) 0.5)

(radius-ge reg:region radius:real)

All parts of cable segments in the region reg with radius greater than or equal to radius.

All cable segments with radius greater than or equal to 0.5 μm, found by applying radius-le to all of the cables in the morphology. Note that branch 2, which has a constant radius of 0.5 μm, is in the result.

(radius-ge (all) 0.5)

(join lhs:region rhs:region [...region])

The union of two or more regions.

Two regions (left and middle) and their union (right).

(intersect lhs:region rhs:region [...region])

The intersection of two or more regions.

Two regions (left and middle) and their intersection (right).

(difference lhs:region rhs:region)

The intersection of two regions.

Two regions (left and middle) and their difference (right).

(complement reg:region)

The complement of a region.

A region (left) and its complement (right).

(complete reg:region)

Complete a region, i.e., add all covers of all included forks.

A region (left) and its completion (right).

(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 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 parameter scale has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.

The distance between any two points (the evaluation location and a location within the locset), is calculated along the entire tree, even across the root. Therefore, a distance expression is defined on the entire cell and only zero if evaluated at a location within the locset (or the scale parameter is set to zero).

(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 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 parameter scale has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.

Example of a proximal-distance expression with a single input location. Left: Input location. Right: Area where the expression evaluates to non-zero values.

(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 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 parameter scale has unit \({\mu m}^{-1}\) and is multiplied by the distance, such that the result is unitless.

Example of a distal-distance expression with a single input location. Left: Input location. Right: Area, where the expression evaluates to non-zero values.

(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 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 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.

Example of an interpolation expression. Red: The root of the morphology. Blue: The proximal locset consisting of a single location. Green: The distal locset, consisting of four locations. Given these locsets, an interpolation expression only evaluates to non-zero in the highlighted area. For locations 3 and 4 of the distal locset, there is no location within the proximal locset, that is between them and the root (in proximal direction), and therefore an interpolation expression cannot be evaluated and defaults to zero. Contrary, for locations 1 and 2 of the distal locset, there is a location within the proximal locset in the proximal direction.

(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 region dist_reg in the 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 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.

Example of a label 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-to (terminal) (region "axon"))',  # end of the axon.
   'rad_expr': '(radius 0.5)'  # iexpr evaluating the radius scaled by 0.5
 })

API

• Python

• C++