Cable cell morphology¶
- arbor.mnpos: int¶
Value used to indicate “no parent” in
segment_tree
andmorphology
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
, wherepos
, in the range0 ≤ 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 μmpos=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 valuesprox
=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 theradius
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¶
-
- 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.
- 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
ismnpos
, 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
ismnpos
, 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
- split_at(id)¶
Split a segment_tree
T
into a pair of subtrees(L, R)
such thatR
is the subtree ofT
that starts at the given id and L isT
withoutR
. Splitting above the rootmnpos
returns(T, {})
.
- join_at(id, other)¶
Join two subtrees
L
andR
at a givenid
inL
, such thatjoin_at
is inverse tosplit_at
for a proper choice ofid
. The join pointid
must be inL
.
- tag_roots(tag)¶
Get IDs of roots of region with a particular
tag
in the segment tree, i.e. segments whose parent is eithermnpos
or a segment with a different tag.
- apply_isometry(iso)¶
Apply an
isometry
to the segment tree, returns the transformed tree as a copy. Isometries are rotations around an arbritary axis and/or translations; they can be instantiated usingtranslate
androtate
and combined using the*
operator.- Returns:
new tree
- Parameters:
iso – isometry
- equivalent(other)¶
Two trees are equivalent if
the root segments’
prox
anddist
points and theirtags
are identical.recursively: all sub-trees starting at the current segment are equivalent.
- 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
- 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 forplace_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.
- 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 forisometry
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 theaxis
tuple.
- __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.
Discretisation and CV policies¶
The set of boundary points used by the simulator is determined by a
CV policy. These are objects of type
cv_policy
, which has the following public methods:
- class arbor.cv_policy¶
- domain¶
A read only string expression describing the subset of a cell morphology (region) on which this policy has been declared.
CV policies can be composed with
+
and|
operators.# The plus operator applies policy = arbor.cv_policy_single('"soma"') + cv_policy('"dend"') # The | operator uses CVs of length 10 μm everywhere, except # on the soma, to which a single CV policy is applied. policy = arbor.cv_policy_max_extent(10) | cv_policy_single('"soma"')
Specific CV policy objects are created by functions described below.
These all take a region
parameter that restrict the
domain of applicability of that policy; this facility is useful for specifying
differing discretisations on different parts of a cell morphology. When a CV
policy is constrained in this manner, the boundary of the domain will always
constitute part of the CV boundary point set.
- arbor.cv_policy_single(domain='(all)')¶
Use one CV for the whole cell, or one for each connected component of the supplied domain.
# Use one CV for the entire cell (a single compartment model) single_comp = arbor.cv_policy_single() # Use a single CV for the soma. single_comp_soma = arbor.cv_policy_single('"soma"')
- Parameters:
domain (str) – The region on which the policy is applied.
- arbor.cv_policy_explicit(locset, domain='(all)')¶
Use the provided locset as control volume boundaries.
# Place CV boundaries midway every branch. midbranch_cvp = arbor.cv_policy_explicit('(on-branches 0.5)') # Place CV boundaries at 10 random positions on the soma. random_soma_cvp = arbor.cv_policy_explicit('(uniform (tag 3) 0 9 0)','"soma"')
- Parameters:
locset (str) – The locset on which CV boundaries are placed.
domain (str) – The region on which the policy is applied.
- arbor.cv_policy_every_segment(domain='(all)')¶
Use every sample point in the morphology definition as a CV boundary, optionally restricted to the supplied domain. Each fork point in the domain is represented by a trivial CV.
- Parameters:
domain (str) – The region on which the policy is applied.
- arbor.cv_policy_fixed_per_branch(cv_per_branch, domain='(all)')¶
For each branch in each connected component of the domain (or the whole cell, if no domain is given), evenly distribute boundary points along the branch so as to produce exactly
cv_per_branch
CVs.- Parameters:
cv_per_branch (int) – The number of CVs per branch.
domain (str) – The region on which the policy is applied.
- arbor.cv_policy_max_extent(max_extent, domain='(all)')¶
As for
cv_policy_fixed_per_branch()
, save that the number of CVs on any given branch will be chosen to be the smallest number that ensures no CV will have an extent on the branch longer thanmax_extent
micrometres.- Parameters:
max_etent (float) – The maximum length for generated CVs.
domain (str) – The region on which the policy is applied.
CV discretization as mcables¶
It is often useful for the user to have a detailed view of the CVs generated for a given morphology and cv-policy. For example, while debugging and fine-tuning model implementations, it can be helpful to know how many CVs a cable-cell is comprised of, or how many CVs lie on a certain region of the cell.
The following classes and functions allow the user to inspect the CVs of a cell or region.
- class arbor.cell_cv_data¶
Stores the discretisation data of a cable-cell in terms of CVs and the
cables
comprising each of these CVs.- children(idx) list[int] ¶
Returns a list of the indices of the CVs representing the children of the CV at index
idx
.
- parent(idx) int ¶
Returns the index of the CV representing the parent of the CV at index
idx
.
- int num_cv
Returns the total number of CVs on the cell.
- arbor.cv_data(cell) optional<cell_cv_data> ¶
Constructs a
cell_cv_data
object representing the CVs comprising the cable-cell according to thecv_policy
provided in thedecor
of the cell. ReturnsNone
if nocv_policy
was provided in the decor.- Parameters:
cell (cable_cell) – The cable-cell.
- Return type:
optional<
cell_cv_data
>
- arbor.intersect_region(reg, cv_data, integrate_along) list[idx, proportion] ¶
Returns a list of tuples
[idx, proportion]
identifying the indices (idx
) of the CVs from thecv_data
argument that lie in the provided regionreg
, and how much of each CV belongs to that region (proportion
). Theproportion
is either the area proportion or the length proportion, chosen according to theintegrate_along
argument.- Parameters:
reg (str) – The region on the cable-cell represented as s-expression or a label from the label-dictionary of the cell.
cv_data (cell_cv_data) – The cv_data of a cell.
integrate_along (string) – Either “area” or “length”. Decides whether the proportion of a CV is measured according to the area or length of the CV.
- Return type:
list[idx, proportion]
SWC¶
- arbor.load_swc_arbor(filename, raw=False)¶
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. SWC files with single point somas are common, for example SONATA model descriptions.
Such representations are challenging to consistently interpret in different simulation tools because they require heuristics and, often undocumented, rules for how to interpret the connectin of axons and dendrites to the soma.
The
load_swc_neuron()
function provides support for loading SWC files according to the interpretation used by NEURON.- Parameters:
filename (str) – the name of the SWC file.
raw (bool) – return segment_tree instead of morphology?
- Return type:
- arbor.load_swc_neuron(filename, raw=False)¶
Loads the
morphology
from an SWC file according to NEURON’sImport3D
interpretation of the SWC specification. See the SWC file documention for more details.- Parameters:
filename (str) – the name of the SWC file.
raw (bool) – return segment_tree instead of morphology?
- Return type:
NeuroML¶
- class arbor.neuroml_morph_data¶
A
neuroml_morphology_data
object contains a representation of a morphology defined in NeuroML.- cell_id: optional<str>¶
The id attribute of the cell that was used to find the morphology in the NeuroML document, if any.
- id: str¶
The id attribute of the morphology.
- group_segments: dict[str, list[long]]¶
A map from each segment group id to its corresponding collection of segments.
- morphology: morphology¶
The morphology associated with the
neuroml_morph_data
object.
- segments()¶
Returns a label dictionary with a region entry for each segment, keyed by the segment id (as a string).
- Return type:
- named_segments()¶
Returns a label dictionary with a region entry for each name attribute given to one or more segments. The region corresponds to the union of all segments sharing the same name attribute.
- Return type:
- groups()¶
Returns a label dictionary with a region entry for each defined segment group.
- Return type:
- class arbor.neuroml¶
A
neuroml
object represent NeuroML documents, and provides methods for the identification and translation of morphology data.An implementation limitation restricts valid segment id values to those which can be represented by an unsigned long long value.
The
allow_spherical_root
optional parameter below, if set to true, will instruct the parser to interpret a zero-length constant radius root segment as denoting a spherical segment, and this will in turn be represented in the resultant morphology by a cylinder of equivalent surface area.- neuroml(filename)¶
Build a NeuroML document representation from the supplied file contents.
- Parameters:
filename (str) – the name of the NeuroML file.
- cell_ids()¶
Return the id of each
<cell>
element defined in the NeuroML document.- Return type:
list[str]
- morphology_ids()¶
Return the id of each top-level
<morphology>
element defined in the NeuroML document.- Return type:
list[str]
- morphology(morph_id, allow_spherical_root=false)¶
Returns a representation of the top-level morphology with the supplied morph_id if it could be found. Parse errors or an inconsistent representation will raise an exception.
- Parameters:
morph_id (str) – ID of the top-level morphology.
allow_spherical_root (bool) – Treat zero length root segments especially.
- Return type:
optional(neuroml_morph_data)
- cell_morphology(cell_id, allow_spherical_root=false)¶
Returns a representation of the morphology associated with the cell with the supplied cell_id if it could be found. Parse errors or an inconsistent representation will raise an exception.
- Parameters:
morph_id (str) – ID of the cell.
allow_spherical_root (bool) – Treat zero length root segments especially.
- Return type:
optional(neuroml_morph_data)
Neurolucida¶
- class arbor.asc_morphology¶
The morphology and label dictionary meta-data loaded from a Neurolucida ASCII
.asc
file.- morphology¶
The cable cell morphology.
- segment_tree¶
The raw segment tree.
- labels¶
The labeled regions and locations extracted from the meta data. The four canonical regions are labeled
'soma'
,'axon'
,'dend'
and'apic'
.
- arbor.load_asc(filename)¶
Loads the
asc_morphology
from a Neurolucida ASCII file.import arbor # Load morphology and labels from file. asc = arbor.load_asc('granule.asc') # Construct a cable cell. cell = arbor.cable_cell(asc.morphology, arbor.decor(), asc.labels)
- Parameters:
filename (str) – the name of the input file.
- Return type: