API reference

Modules for processing tree-like morphology reconstructions.

Module tree

class treem.Tree

Recursive tree data structure.

add(tree)

Appends tree as continuation.

ascendorder()

Iterates tree nodes in ascending order until root is reached.

Yields:sequence of tree nodes (generator object).

breadth()

Returns tree breadth.

degree()

Returns node degree.

depth()

Returns node depth.

forks(iterator=<function Tree.preorder>)

Iterates tree branching points.

Parameters:iterator – iterator type (defaults to Tree.preorder) Returns:sequence of tree nodes (generator object).

height()

Returns tree height.

is_fork()

Returns True for a branching point (except root).

is_leaf()

Returns True for a terminal node.

is_root()

Returns True if tree has no parent.

leaves()

Iterates tree terminals.

Returns:sequence of tree nodes (generator object).

level()

Returns node depth.

levelorder()

Traverses tree in level-order (breadth first).

Yields:sequence of tree nodes (generator object).

postorder()

Traverses tree in post-order (depth first).

Yields:sequence of tree nodes (generator object).

preorder()

Traverses tree in pre-order (depth first).

Yields:sequence of tree nodes (generator object).

size()

Returns tree size.

width()

Returns tree width.

Module morph

class treem.Node(value=None)

Morphology data storage.

area()

Returns segment area at the node (float).

coord()

Returns coordinates of the node (x,y,z) (NumPy ndarray[3]).

diam()

Returns diameter of the node (float).

dist(origin=[0.0, 0.0, 0.0])

Returns Euclidean distance of the node to origin (float).

ident()

Returns node ID (int).

is_stem()

Returns True if node is a stem node.

length()

Returns segment length at the node (float).

order()

Returns branch order (int). A primary neurite has order 1.

parent_ident()

Returns node’s parent ID (int).

point()

Returns point data of the node (x,y,z,r) (NumPy ndarray[4]).

radius()

Returns radius of the node (float).

section(reverse=False)

Iterates through the nodes of the section.

Iteration starts with the current node and procedes until the end of the section.

Parameters:reverse (bool) – ascending order if True (defaults to False). Yields:sequence of nodes (generator object).

sections()

Iterates through the sections in descending order.

Iterations traverse entire branch starting with the current node.

Yields:sequence of sections (generator object).

type()

Returns point type of the node (int).

volume()

Returns segment volume at the node (float).

walk(reverse=False)

Iterates through the tree nodes starting from the current node.

Iteration is terminated when root is reached if reverse is True. If False, full tree is traversed downstream in pre-order.

Parameters:reverse (bool) – walk the tree in ascending order if True. Returns:sequence of tree nodes (generator object).

class treem.Morph(source=None, data=None)

Neuron morphology representation.

area(sec)

Returns section area (float).

coords(sec)

Returns reference to section coordinates.

copy(node=None)

Copies branch at the node (defaults to root).

delete(node)

Delete node.

graft(tree, node=None)

Grafts tree at the given node (defaults to root).

insert(new_node, node)

Inserts new node before the given node.

length(sec)

Returns section length (float).

load(source=None, data=None)

Fill-in Morph from source file or data.

Parameters:

• source (str) – source file (swc).
• data (NumPy ndarray) – morphology data (N, 7).

move(shift, node)

Shifts node coordinates by 3D vector (float[3]).

node(ident)

Returns node by it’s ID.

points(sec)

Returns reference to section data.

prune(node)

Prunes branch at the given node.

radii(sec)

Returns reference to section radii.

rotate(axis, angle, node=None)

Rotates branch at the node.

Branch is traversed downstream from the given node.

Parameters:

• axis (float[3]) – rotation axis.
• angle (float) – rotation angle in degrees.
• node (treem.Node) – starting node (defaults to root).

save(target)

Writes morphology to file (str).

stems()

Iterates through stem nodes.

Returns:sequence of stem nodes (generator object).

translate(shift, node=None)

Shifts coordinates of the branch at the given node.

Branch is traversed downstream from the given node.

Parameters:

• shift (float[3]) – translation vector.
• node (treem.Node) – starting node (defaults to root).

volume(sec)

Returns section volume (float).

Module io

SWC data format defintion and services.

class treem.io.SWC

Definitions of the data format.

class treem.io.TreemEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Extended JSONEncoder to serialize treem objects.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

treem.io.load_swc(source)

Reads data from SWC file.

treem.io.save_swc(target, data)

Writes data to SWC file.

Module utils

Miscellaneous functions.

Module utils.geom

Utilities for manipulating geometry of morphology reconstructions.

treem.utils.geom.angle_between(u, v)

Returns angle in radians between two 3D vectors (float[3]).

treem.utils.geom.fibonacci_sphere(npoints=100)

Samples equally spaced points on a unit sphere.

Parameters:npoints (int) – sample size [100]. Returns:array of 3D points (NumPy ndarray[3]).

treem.utils.geom.norm(vec)

Returns magnitude of a 3D vector.

treem.utils.geom.repair_branch(cmorph, cut, rmorph, rep, force=False, keep_radii=False)

Attempts to extend cut neurite using intact branch.

Parameters:

• cmorph (treem.Morph) – cut morphology.
• cut (treem.Node) – cut node, from cmorph.
• rmorph (treem.Morph) – repair morphology.
• rep (treem.Node) – undamaged branch start node, from rmorph.
• force (bool) – force repair if branch is too short.
• keep_radii (bool) – do not scale radii of repaired branch.

Returns:

True if repaired.

treem.utils.geom.rotation(u, v)

Computes rotation axis and angle for two 3D vectors (float[3]).

Returns:axis (NumPy ndarray[3]), angle (float)

rotation axis, rotation angle in radians.

treem.utils.geom.rotation_matrix(axis, angle)

Computes rotation matrix for 3D manipulations.

Parameters:

• axis (float[3]) – rotation axis.
• angle (float) – rotation angle in radians.

Returns:

rotation matrix (NumPy ndarray).

treem.utils.geom.sample(points, num)

Samples points with fixed resolution using linear interpolation.

Parameters:

• points (NumPy ndarray[4]) – array of 4D data points (x,y,z,r).
• num (int) – sample size.

Returns:

array of 4D points (NumPy ndarray[4]).

Module utils.plot

Plotting utilities.

treem.utils.plot.plot_neuron(ax, morph, types=range(1, 5), colors=None, linewidth=1)

Plots neuron morphology.

Parameters:

• ax – matplotlib axes object.
• morph (treem.Morph) – neuron morphology.
• types (int iterable) – point types to be displayed.
• colors (dict) – colors for point types ({pt: colspec}).
• linewidth (int) – line width.

treem.utils.plot.plot_points(ax, morph, ids, types=range(1, 5), show_id=False, markersize=6)

Plots marker points.

Parameters:

• ax – matplotlib axes object.
• morph (treem.Morph) – neuron morphology.
• ids (int iterable) – list of node IDs.
• types (int iterable) – point types to display.

treem.utils.plot.plot_section(ax, tree, data, **kwargs)

Plots single section.

Parameters:

• ax – matplotlib axes object.
• tree (treem.Node) – branch start node.
• data (NumPy ndarray) – raw data of morphology Morph.
• kwargs – arguments for matplotlib plot().

treem.utils.plot.plot_tree(ax, tree, data, **kwargs)

Plots entire branch.

Parameters:

• ax – matplotlib axes object.
• tree (treem.Node) – branch start node.
• data (NumPy ndarray) – raw data of morphology Morph.
• kwargs – arguments for matplotlib plot().

Module cli

Command-line interface to package treem.

treem.cli.cli()

Command-line interface definition.