bsb.morphologies package

Subpackages

Module contents

Morphology module

class bsb.morphologies.Branch(points, radii, labels=None, properties=None, children=None)[source]

Bases: object

A vector based representation of a series of point in space. Can be a root or connected to a parent branch. Can be a terminal branch or have multiple children.

Parameters:

  • points (list | numpy.ndarray) – Array of 3D coordinates defining the point of the branch

  • radii (list | numpy.ndarray) – Array of radii associated to each point

  • labels (List[str] | set | numpy.ndarray) – Array of labels to associate to each point

  • properties (dict) – dictionary of per-point data to store in the branch

  • children (List[bsb.morphologies.Branch]) – list of child branches to attach to the branch

Raises:

bsb.exceptions.MorphologyError – if a property of the branch does not have the same size as its points

as_arc()[source]

Return the branch as a vector of arclengths in the closed interval [0, 1]. An arclength is the distance each point to the start of the branch along the branch axis, normalized by total branch length. A point at the start will have an arclength close to 0, and a point near the end an arclength close to 1

Returns:

Vector of branch points as arclengths.

Return type:

numpy.ndarray

attach_child(branch)[source]

Attach a branch as a child to this branch.

Parameters:

branch (Branch) – Child branch

cached_voxelize(N)[source]

Turn the morphology or subtree into an approximating set of axis-aligned cuboids and cache the result.

Return type:

bsb.voxels.VoxelSet

ceil_arc_point(arc)[source]

Get the index of the nearest distal arc point.

center()

Center the morphology on the origin

property children

Collection of the child branches of this branch.

Returns:

list of Branches

Return type:

list

close_gaps()

Close any head-to-tail gaps between parent and child branches.

collapse(on=None)

Collapse all the roots of the morphology or subtree onto a single point.

Parameters:

on (int) – Index of the root to collapse on. Collapses onto the origin by default.

contains_labels(labels)[source]

Check if this branch contains any points labelled with any of the given labels.

Parameters:

labels (List[str]) – The labels to check for.

Return type:

bool

copy(branch_class=None)[source]

Return a parentless and childless copy of the branch.

Parameters:

branch_class (type) – Custom branch creation class

Returns:

A branch, or branch_class if given, without parents or children.

Return type:

bsb.morphologies.Branch

delete_point(index)[source]

Remove a point from the branch

Parameters:

index (int) – index position of the point to remove

Returns:

the branch where the point has been removed

Return type:

bsb.morphologies.Branch

detach()[source]

Detach the branch from its parent, if one exists.

detach_child(branch)[source]

Remove a branch as a child from this branch.

Parameters:

branch (Branch) – Child branch

property end

Return the spatial coordinates of the terminal point of this branch.

property euclidean_dist

Return the Euclidean distance from the start to the terminal point of this branch.

find_closest_point(coord)[source]

Return the index of the closest on this branch to a desired coordinate.

Parameters:

coord – The coordinate to find the nearest point to

Type:

numpy.ndarray

flatten()

Return the flattened points of the morphology or subtree.

Return type:

numpy.ndarray

flatten_labels()

Return the flattened labels of the morphology or subtree.

Return type:

numpy.ndarray

flatten_properties()

Return the flattened properties of the morphology or subtree.

Return type:

numpy.ndarray

flatten_radii()

Return the flattened radii of the morphology or subtree.

Return type:

numpy.ndarray

floor_arc_point(arc)[source]

Get the index of the nearest proximal arc point.

property fractal_dim

Return the fractal dimension of this branch, computed as the coefficient of the line fitting the log-log plot of path vs euclidean distances of its points.

get_arc_point(arc, eps=1e-10)[source]

Strict search for an arc point within an epsilon.

Parameters:

  • arc (float) – Arclength position to look for.

  • eps (float) – Maximum distance/tolerance to accept an arc point as a match.

Returns:

The matched arc point index, or None if no match is found

Return type:

Union[int, None]

get_axial_distances(idx_start=0, idx_end=-1, return_max=False)[source]

Return the displacements or its max value of a subset of branch points from its axis vector. :param idx_start = 0: index of the first point of the subset. :param idx_end = -1: index of the last point of the subset. :param return_max = False: if True the function only returns the max value of displacements, otherwise the entire array.

get_branches(labels=None)

Return a depth-first flattened array of all or the selected branches.

Parameters:

labels (list) – Names of the labels to select.

Returns:

List of all branches, or the ones fully labelled with any of the given labels.

Return type:

list

get_label_mask(labels)[source]

Return a mask for the specified labels

Parameters:

labels (List[str] | numpy.ndarray[str]) – The labels to check for.

Returns:

A boolean mask that selects out the points that match the label.

Return type:

List[numpy.ndarray]

get_points_labelled(labels)[source]

Filter out all points with certain labels

Parameters:

labels (List[str] | numpy.ndarray[str]) – The labels to check for.

Returns:

All points with the labels.

Return type:

List[numpy.ndarray]

insert_branch(branch, index)[source]

Split this branch and insert the given branch at the specified index.

Parameters:

  • branch (Branch) – Branch to be attached

  • index – Index or coordinates of the cutpoint; if coordinates are given, the closest point to the coordinates is used.

Type:

Union[numpy.ndarray, int]

introduce_arc_point(arc_val)[source]

Introduce a new point at the given arc length.

Parameters:

arc_val (float) – Arc length between 0 and 1 to introduce new point at.

Returns:

The index of the new point.

Return type:

int

introduce_point(index, position, radius=None, labels=None, properties=None)[source]

Insert a new point at index, before the existing point at index. Radius, labels and extra properties can be set or will be copied from the existing point at index.

Parameters:

  • index (int) – Index of the new point.

  • position (List[float]) – Coordinates of the new point

  • radius (float) – The radius to assign to the point.

  • labels (list) – The labels to assign to the point.

  • properties (dict) – The properties to assign to the point.

property is_root

Returns whether this branch is root or if it has a parent.

Returns:

True if this branch has no parent, False otherwise.

Return type:

bool

property is_terminal

Returns whether this branch is terminal or if it has children.

Returns:

True if this branch has no children, False otherwise.

Return type:

bool

label(labels, points=None)[source]

Add labels to the branch.

Parameters:

  • labels (List[str]) – Label(s) for the branch

  • points – An integer or boolean mask to select the points to label.

property labels

Return the labels of the points on this branch. Labels are represented as a number that is associated to a set of labels. See Labels for more info.

property labelsets

Return the sets of labels associated to each numerical label.

list_labels()[source]

Return a list of labels present on the branch.

property max_displacement

Return the max displacement of the branch points from its axis vector.

property parent
property path_length

Return the sum of the euclidean distances between the points on the branch.

property point_vectors

Return the individual vectors between consecutive points on this branch.

property points

Return the spatial coordinates of the points on this branch.

property radii

Return the radii of the points on this branch.

root_rotate(rot, downstream_of=0)

Rotate the subtree emanating from each root around the start of that root If downstream_of is provided, will rotate points starting from the index provided (only for subtrees with a single root).

Parameters:

  • rot (scipy.spatial.transform.Rotation) – Scipy rotation to apply to the subtree.

  • downstream_of – index of the point in the subtree from which the rotation should be applied. This feature works only when the subtree has only one root branch.

Returns:

rotated Morphology

Return type:

bsb.morphologies.SubTree

rotate(rotation, center=None)

Rotate the entire Subtree with respect to the center. The rotation angles are assumed to be in degrees. If the center is not provided, the Subtree will rotate from [0, 0, 0].

Parameters:
property segments

Return the start and end points of vectors between consecutive points on this branch.

set_properties(**kwargs)[source]
simplify(epsilon, idx_start=0, idx_end=-1)[source]

Apply Ramer–Douglas–Peucker algorithm to all points or a subset of points of the branch. :param epsilon: Epsilon to be used in the algorithm. :param idx_start = 0: Index of the first element of the subset of points to be reduced. :param epsilon = -1: Index of the last element of the subset of points to be reduced.

simplify_branches(epsilon)

Apply Ramer–Douglas–Peucker algorithm to all points of all branches of the SubTree. :param epsilon: Epsilon to be used in the algorithm.

property size

Returns the amount of points on this branch

Returns:

Number of points on the branch.

Return type:

int

property start

Return the spatial coordinates of the starting point of this branch.

subtree(labels=None)
translate(point)

Translate the subtree by a 3D vector.

Parameters:

point (numpy.ndarray) – 3D vector to translate the subtree.

Returns:

the translated subtree

Return type:

bsb.morphologies.SubTree

property vector

Return the vector of the axis connecting the start and terminal points.

property versor

Return the normalized vector of the axis connecting the start and terminal points.

voxelize(N)

Turn the morphology or subtree into an approximating set of axis-aligned cuboids.

Return type:

bsb.voxels.VoxelSet

walk()[source]

Iterate over the points in the branch.

class bsb.morphologies.Morphology(roots, meta=None, shared_buffers=None, sanitize=False)[source]

Bases: SubTree

A multicompartmental spatial representation of a cell based on a directed acyclic graph of branches whom consist of data vectors, each element of a vector being a coordinate or other associated data of a point on the branch.

property adjacency_dictionary

Return a dictonary associating to each key (branch index) a list of adjacent branch indices

as_filtered(labels=None)[source]

Return a filtered copy of the morphology that includes only points that match the current label filter, or the specified labels.

copy()[source]

Copy the morphology.

classmethod empty()[source]
get_label_mask(labels)[source]

Get a mask corresponding to all the points labelled with 1 or more of the given labels

property is_optimized
property labelsets

Return the sets of labels associated to each numerical label.

list_labels()[source]

Return a list of labels present on the morphology.

property meta
optimize(force=False)[source]
set_label_filter(labels)[source]

Set a label filter, so that as_filtered returns copies filtered by these labels.

simplify(*args, optimize=True, **kwargs)[source]
swap_axes(axis1: int, axis2: int)[source]

Interchange two axes of a morphology points.

Parameters:

  • axis1 (int) – index of the first axis to exchange

  • axis2 (int) – index of the second axis to exchange

Returns:

the modified morphology

Return type:

bsb.morphologies.Morphology

to_graph_array()[source]

Create a SWC-like numpy array from a Morphology.

Warning

Custom SWC tags (above 3) won’t work and throw an error

Returns:

a numpy array with columns storing the standard SWC attributes

Return type:

numpy.ndarray

to_swc(file)[source]

Create a SWC file from a Morphology. :param file: path to write to

class bsb.morphologies.MorphologySet(loaders, m_indices=None, /, labels=None)[source]

Bases: object

Associates a set of StoredMorphologies to cells

Parameters:
Type:

List[int]

clear_soft_cache()[source]
count_morphologies()[source]
count_unique()[source]
classmethod empty()[source]
get(index, cache=True, hard_cache=False)[source]
get_indices(copy=True)[source]
iter_meta(unique=False)[source]
iter_morphologies(cache=True, unique=False, hard_cache=False)[source]

Iterate over the morphologies in a MorphologySet with full control over caching.

Parameters:

  • cache (bool) – Use Soft caching (1 copy stored in mem per cache miss, 1 copy created from that per cache hit).

  • hard_cache – Use Soft caching (1 copy stored on the loader, always same copy returned from that loader forever).

merge(other)[source]
property names
set_label_filter(labels)[source]
class bsb.morphologies.RotationSet(data)[source]

Bases: object

Set of rotations. Returned rotations are of scipy.spatial.transform.Rotation

iter(cache=False)[source]
class bsb.morphologies.SubTree(branches, sanitize=True)[source]

Bases: object

Collection of branches, not necessarily all connected.

property bounds
property branch_adjacency

Return a dictionary containing mapping the id of the branch to its children.

property branches

Return a depth-first flattened array of all branches.

cached_voxelize(N)[source]

Turn the morphology or subtree into an approximating set of axis-aligned cuboids and cache the result.

Return type:

bsb.voxels.VoxelSet

center()[source]

Center the morphology on the origin

close_gaps()[source]

Close any head-to-tail gaps between parent and child branches.

collapse(on=None)[source]

Collapse all the roots of the morphology or subtree onto a single point.

Parameters:

on (int) – Index of the root to collapse on. Collapses onto the origin by default.

flatten()[source]

Return the flattened points of the morphology or subtree.

Return type:

numpy.ndarray

flatten_labels()[source]

Return the flattened labels of the morphology or subtree.

Return type:

numpy.ndarray

flatten_properties()[source]

Return the flattened properties of the morphology or subtree.

Return type:

numpy.ndarray

flatten_radii()[source]

Return the flattened radii of the morphology or subtree.

Return type:

numpy.ndarray

get_branches(labels=None)[source]

Return a depth-first flattened array of all or the selected branches.

Parameters:

labels (list) – Names of the labels to select.

Returns:

List of all branches, or the ones fully labelled with any of the given labels.

Return type:

list

label(labels, points=None)[source]

Add labels to the morphology or subtree.

Parameters:

  • labels (list[str]) – Labels to add to the subtree.

  • points (numpy.ndarray) – Optional boolean or integer mask for the points to be labelled.

property labels
property origin
property path_length

Return the total path length as the sum of the euclidian distances between consecutive points.

property points
property properties
property radii
root_rotate(rot, downstream_of=0)[source]

Rotate the subtree emanating from each root around the start of that root If downstream_of is provided, will rotate points starting from the index provided (only for subtrees with a single root).

Parameters:

  • rot (scipy.spatial.transform.Rotation) – Scipy rotation to apply to the subtree.

  • downstream_of – index of the point in the subtree from which the rotation should be applied. This feature works only when the subtree has only one root branch.

Returns:

rotated Morphology

Return type:

bsb.morphologies.SubTree

rotate(rotation, center=None)[source]

Rotate the entire Subtree with respect to the center. The rotation angles are assumed to be in degrees. If the center is not provided, the Subtree will rotate from [0, 0, 0].

Parameters:
simplify_branches(epsilon)[source]

Apply Ramer–Douglas–Peucker algorithm to all points of all branches of the SubTree. :param epsilon: Epsilon to be used in the algorithm.

property size
subtree(labels=None)[source]
translate(point)[source]

Translate the subtree by a 3D vector.

Parameters:

point (numpy.ndarray) – 3D vector to translate the subtree.

Returns:

the translated subtree

Return type:

bsb.morphologies.SubTree

voxelize(N)[source]

Turn the morphology or subtree into an approximating set of axis-aligned cuboids.

Return type:

bsb.voxels.VoxelSet

bsb.morphologies.branch_iter(branch)[source]

Iterate over a branch and all of its children depth first.

class bsb.morphologies.selector.MorphologySelector(*args, _parent=None, _key=None, **kwargs)[source]

Bases: ABC

get_node_name()
abstract pick(morphology)[source]
scaffold: Scaffold
select

Base implementation of all the different configuration attributes. Call the factory function attr() instead.

abstract validate(all_morphos)[source]
class bsb.morphologies.selector.NameSelector(*args, _parent=None, _key=None, **kwargs)[source]

Bases: MorphologySelector

get_node_name()
names: cfglist[str]
pick(morphology)[source]
validate(all_morphos)[source]
class bsb.morphologies.selector.NeuroMorphoSelector(*args, _parent=None, _key=None, **kwargs)[source]

Bases: NameSelector

get_node_name()