Cell morphology¶

arbor.mnpos: int¶

Value used to indicate “no parent” in segment_tree and morphology trees of segments and branches respectively.

import arbor

tree = arbor.segment_tree()

# mnpos can be used to explicitly specify that a segment
# is at the root of the tree. More than one segment can
# be at the root, and they will all be joined electrically
# at their proximal ends.
tree.append(parent=arbor.mnpos, # attach segment to root.
            prox=arbor.mpoint(0, 0,-5, 5),
            dist=arbor.mpoint(0, 0, 5, 5),
            tag=1)
tree.append(parent=0,
            prox=arbor.mpoint(0, 0, 5, 0.5),
            dist=arbor.mpoint(0, 0,50, 0.2),
            tag=3)

# mnpos can also be used when querying a segment_tree or morphology,
# for example the following snippet that finds all branches in the
# morphology that are attached to the root of the morphology.
m = arbor.morphology(tree)
base_branches = [i for i in range(m.num_branches)
                    if m.branch_parent(i) == arbor.mnpos]

print(base_branches)

class arbor.location¶

A location on branch, where pos, in the range 0 ≤ pos ≤ 1, gives the relative position between the proximal and distal ends of the branch. The position is in terms of branch path length, so for example, on a branch of path length 100 μm pos=0.2 corresponds to 20 μm and 80 μm from the proximal and distal ends of the branch respectively.

location(branch, pos)¶: Constructor.

branch: int¶: The branch id of the location.

pos: float¶: The relative position of the location on the branch.

class arbor.cable¶

An unbranched cable that is a subset of a branch. The values of 0 ≤ prox ≤ dist ≤ 1 are the relative position of the cable’s end points on the branch, in terms of branch path length. For example, on a branch of path length 100 μm, the values prox =0.2, dist =0.8 describe a cable that starts and ends 20 μm and 80 μm along the branch respectively.

cable(branch, prox, dist)¶: Constructor.

branch: int¶: The branch id of the cable.

prox: float¶: The relative position of the proximal end of the cable on the branch.

dist: float¶: The relative position of the distal end of the cable on the branch.

class arbor.mpoint¶

A location of a cell morphology at a fixed location in space. Describes the location of the as three-dimensional coordinates (x, y, z) and the radius of the cable.

x: real¶: X coordinate (μm)

y: real¶: Y coordinate (μm)

z: real¶: x coordinate (μm)

radius: real¶: Radius of the cable (μm)

class arbor.segment¶

prox: mpoint¶: The location and radius at the proximal end of the segment.

dist: mpoint¶: The location and radius at the distal end of the segment.

tag: int¶: Integer tag meta-data associated with the segment. Typically the tag would correspond to the SWC structure identifier: soma=1, axon=2, dendrite=3, apical dendrite=4, however arbitrary tags, including zero and negative values, can be used.

class arbor.segment_tree¶

A segment tree is a description of a the segments and their connections Segment trees comprise a sequence of segments starting from at lease one root segment, together with a parent-child adjacency relationship where a child segment is distal to its parent. Branches in the tree occur where a segment has more than one child. Furthermore, a segment can not have more than one parent. In this manner, neuron morphologies are modeled as a tree, where cables that represent dendrites and axons can branch, but branches can not rejoin. A segment tree is a segment-based description of a cell’s morphology.

segment_tree()¶: Construct an empty segment tree.

The tree is constructed by appending segments to the tree. Segments are numbered starting at 0 in the order that they are added, with the first segment getting id 0, the second segment id 1, and so forth.

A segment can not be added before its parent, hence the first segment is always at the root. In this manner, a segment tree is always guaranteed to be in a correct state, with consistent parent-child indexing, and with n segments numbered from 0 to n-1.

To illustrate how a segment tree is constructed by appending segments, take the segment tree used in the documentation above.

Which is constructed as follows.

import arbor
from arbor import mpoint
from arbor import mpos

tree = arbor.segment_tree()
# Start with a cylinder segment for the soma (with tag 1)
tree.append(mnpos, mpoint(0,   0.0, 0, 2.0), mpoint( 4,  0.0, 0, 2.0), tag=1)
# Construct the first section of the dendritic tree,
# comprised of segments 1 and 2, attached to soma segment 0.
tree.append(0,     mpoint(4,   0.0, 0, 0.8), mpoint( 8,  0.0, 0, 0.8), tag=3)
tree.append(1,     mpoint(8,   0.0, 0, 0.8), mpoint(12, -0.5, 0, 0.8), tag=3)
# Construct the rest of the dendritic tree.
tree.append(2,     mpoint(12, -0.5, 0, 0.8), mpoint(20,  4.0, 0, 0.4), tag=3)
tree.append(3,     mpoint(20,  4.0, 0, 0.4), mpoint(26,  6.0, 0, 0.2), tag=3)
tree.append(2,     mpoint(12, -0.5, 0, 0.5), mpoint(19, -3.0, 0, 0.5), tag=3)
tree.append(5,     mpoint(19, -3.0, 0, 0.5), mpoint(24, -7.0, 0, 0.2), tag=3)
tree.append(5,     mpoint(19, -3.0, 0, 0.5), mpoint(23, -1.0, 0, 0.2), tag=3)
tree.append(7,     mpoint(23, -1.0, 0, 0.2), mpoint(26, -2.0, 0, 0.2), tag=3)
# Two segments that define the axon, with the first at the root, where its proximal
# end will be connected with the proximal end of the soma segment.
tree.append(mnpos, mpoint(0,   0.0, 0, 2.0), mpoint(-7,  0.0, 0, 0.4), tag=2)
tree.append(9,     mpoint(-7,  0.0, 0, 0.4), mpoint(-10, 0.0, 0, 0.4), tag=2)

append(parent, prox, dist, tag)¶

Append a segment to the tree.

Returns

index of the new segment

Parameters

parent (int) – index of segment
prox (mpoint) – proximal end of the segment
dist (mpoint) – distal end of the segment
tag (int) – tag meta data of segment

append(parent, dist, tag)

Append a segment to the tree whose proximal end has the location and radius of the distal end of the parent segment.

This version of append can’t be used for a segment at the root of the tree, that is, when parent is mnpos, in which case both proximal and distal ends of the segment must be specified.

Returns

index of the new segment

Parameters

parent (int) – index of segment
dist (mpoint) – distal end of the segment
tag (int) – tag meta data of segment

append(parent, x, y, z, radius, tag)

Append a segment to the tree whose proximal end has the location and radius of the distal end of the parent segment.

This version of append can’t be used for a segment at the root of the tree, that is, when parent is mnpos, in which case both proximal and distal ends of the segment must be specified.

Returns

index of the new segment

Parameters

parent (int) – index of segment
x (float) – distal x coordinate (μm)
y (float) – distal y coordinate (μm)
z (float) – distal z coordinate (μm)
radius (float) – distal radius (μm)
tag (int) – tag meta data of segment

empty: bool¶: If the tree is empty (i.e. whether it has size 0)

size: int¶: The number of segments.

parents: list¶: A list of parent indexes of the segments.

segments: list¶: A list of the segments.

class arbor.morphology¶

A morphology describes the geometry of a cell as unbranched cables with variable radius and their associated tree structure.

Note

A morphology takes a segment tree and construct the cable branches. Meta data about branches and their properties that may be expensive to calculate is stored for fast look up during later stages of model building, and querying by users.

For this reason, morphologies are read only. To change a morphology, a new morphology should be created using a new segment tree.

There is one constructor for a morphology:

morphology(segment_tree)¶: Construct from a segment tree.

The morphology provides an interface for querying morphology properties:

empty: bool¶: Indicates if the morphology is empty.

num_branches: int¶: The number of branches in the morphology.

branch_parent(i)¶

The parent branch of a branch.

Parameters: i (int) – branch index
Return type: int

branch_children(i)¶

The child branches of a branch.

Parameters: i (int) – branch index
Return type: list

branch_segments(i)¶

A list of the segments in a branch, ordered from proximal to distal.

Parameters: i (int) – branch index
Return type: list

arbor.load_swc_arbor(filename)¶

Loads the morphology from an SWC file according to arbor’s SWC specifications. (See the morphology concepts page for more details).

The samples in the SWC files are treated as the end points of segments, where a sample and its parent form a segment. The tag of each segment is the structure identifier of the distal sample. The structure identifier of the first (root) sample is ignored, as it can only be the proximal end of any segment.

Note

This method does not interpret the first sample, typically associated with the soma, as a sphere. SWCs with single point somas are, unfortunately, reasonably common, for example SONATA model descriptions.

Such representations are unfortunate because simulation tools like Arbor and NEURON require the use of cylinders or fustrums to describe morphologies, and it is not possible to infer how branches attached to the soma should be connected.

The load_swc_allen() and load_swc_neuron() functions provide support for interpreting such SWC files.

Parameters: filename (str) – the name of the SWC file.
Return type: morphology

arbor.load_swc_neuron(filename)¶

Loads the morphology from an SWC file according to NEURON’s SWC specifications. Specifically:

The first sample must be a soma sample.

The soma is represented by a series of n≥1 unbranched, serially listed samples.

The soma is constructed as a single cylinder with diameter equal to the piecewise average diameter of all the segments forming the soma.

A single-sample soma at is constructed as a cylinder with length=diameter.

If a non-soma sample is to have a soma sample as its parent, it must have the most distal sample of the soma as the parent.

Every non-soma sample that has a soma sample as its parent, attaches to the created soma cylinder at its midpoint.

If a non-soma sample has a soma sample as its parent, no segment is created between the sample and its parent, instead that sample is the proximal point of a new segment, and there is a gap in the morphology (represented electrically as a zero-resistance wire)

To create a segment with a certain tag, that is to be attached to the soma, we need at least 2 samples with that tag.

Parameters: filename (str) – the name of the SWC file.
Return type: morphology

arbor.load_swc_allen(filename, no_gaps=False)¶

Loads the morphology from an SWC file according to the AllenDB and Sonata’s SWC specifications. Specifically:

The first sample (the root) is treated as the center of the soma.

The morphology is translated such that the soma is centered at (0,0,0).

The first sample has tag 1 (soma).

All other samples have tags 2, 3 or 4 (axon, apic and dend respectively)

SONATA prescribes that there should be no gaps, however some models in AllenDB have gaps between the start of sections and the soma. The no_gaps flag can be used to enforce this requirement.

Arbor does not support modelling the soma as a sphere, so a cylinder with length equal to the soma diameter is used. The cylinder is centered on the origin, and aligned along the z axis. Axons and apical dendrites are attached to the proximal end of the cylinder, and dendrites to the distal end, with a gap between the start of each branch and the end of the soma cylinder to which it is attached.

Parameters

filename (str) – the name of the SWC file.
no_gaps (bool) – enforce that distance between soma center and branches attached to soma is the soma radius.

Return type

morphology

class arbor.place_pwlin¶

A place_pwlin object allows the querying of the 3-d location of locations and cables in a morphology. Refer to the C++ documentation for place_pwlin for more details.

place_pwlin(morphology, isometry)¶

place_pwlin(morphology): Construct a piecewise linear placement of the morphology in space, optionally applying the given isometry.

at(loc: location) → location ¶: Return any single point corresponding to the location loc in the placement.

all_at(loc: location) → list[location]¶: Return all points corresponding to the given location loc the placement.

segments(cables: list[cable]) → list[segment]¶: Return any minimal collection of segments and partial segments whose union is coterminous with the sub-region of the morphology covered by the given cables in the placement.

all_segments(cables: list[cable]) → list[segment]¶: Return the maximal set of segments and partial segments whose union is coterminous with the sub-region of the morphology covered by the given cables in the placement.

class arbor.isometry¶

Isometries represent rotations and translations in space, and can be used with place_pwlin to position a morphology in an arbitrary spatial location and orientation. Refer to the C++ documentation for isometry for more details.

static translate(x: float, y: float, z: float) → isometry ¶: Construct a translation (x, y, z) with respect to the extrinsic coordinate system.

static translate(displacement: Tuple[float, float, float]) → isometry: Construct a translation from the elements of the given tuple.

static translate(displacement: mpoint) → isometry: Construct a translation from the (x, y, z) components of the given mpoint.

static rotate(theta: float, x: float, y: float, z: float) → isometry ¶: Construct a rotation of theta radians about the axis (x, y, z) with respect to the intrinsic coordinate system.

static rotate(theta: float, axiss: Tuple[float, float, float]) → isometry: Construct a rotation of theta radians about the axis given by the axis tuple.

__call__(point: mpoint) → mpoint ¶: Apply the isometry to given point.

__call__(point: Tuple[float, float, float, …]) → Tuple[float, float, float, …]: Apply the isometry to the first three components of the given tuple, interpreted as a point.

__mul__(a: isometry, b: isometry) → isometry ¶: Compose the two isometries to form a new isometry that applies b and then applies a. Note that rotations are composed as being with respect to the intrinsic coordinate system, while translations are always taken to be with respect to the extrinsic absolute coordinate system.