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:

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

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

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

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

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

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

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

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

Region expressions

(nil)

An empty region.

(all)

All branches in the morphology.

The trivial region definitions (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).

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 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 or locsets 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 (terminal) (region "axon"))'} # end of the axon.
 })

API

• Python

• TODO: C++ documentation.