Section tree¶

class dendrotweaks.morphology.sec_trees.Section(idx: str, parent_idx: str, points: List[Node])[source]¶

Bases: Node

A class representing a section in a neuron morphology.

A section is continuous part of a neuron’s morphology between two branching points.

Parameters:

idx (str) – The index of the section.
parent_idx (str) – The index of the parent section.
points (List[Point]) – The points that define the section.

points¶

The points that define the section.

Type:: List[Point]

segments¶

The segments to which the section is divided.

Type:: List[Segment]

_ref¶

The reference to the NEURON section.

Type:: h.Section

domain¶

The domain to which the section belongs.

Type:: Domain

idx_within_domain¶

The index of the section within its domain.

Type:: int

property domain_name¶: The morphological or functional domain of the node.

property type_idx¶: The type index of the section based on its domain.

property domain_color¶: The color of the section based on its domain.

property df_points¶: A DataFrame of the points in the section.

property df¶: A DataFrame of the section.

property radii¶: Radii of the points in the section.

property diameters¶: Diameters of the points in the section.

property xs¶: X-coordinates of the points in the section.

property ys¶: Y-coordinates of the points in the section.

property zs¶: Z-coordinates of the points in the section.

get_location_coordinates(loc)[source]¶

Get point at a normalized location along the section.

Parameters:: loc (float) – The normalized location along the section (0 = start, 1 = end).
Returns:: The (x, y, z) coordinates of the point at the given location.
Return type:: tuple

property seg_centers¶: The list of segment centers in the section with normalized length.

property seg_borders¶: The list of segment borders in the section with normalized length.

property distances¶: The list of cumulative euclidean distances of the points in the section.

property center¶: The coordinates of the center of the section.

property length¶: The length of the section calculated as the sum of the distances between the points.

property area¶: The surface area of the section calculated as the sum of the areas of the frusta segments.

insert_mechanism(mech)[source]¶: Inserts a mechanism in the section if it is not already inserted.

uninsert_mechanism(mech)[source]¶: Uninserts a mechanism in the section if it was inserted.

get_param_value(param_name)[source]¶

Get the average parameter of the section’s segments.

Parameters:: param_name (str) – The name of the parameter to get.
Returns:: The average value of the parameter in the section’s segments.
Return type:: float

property path_distance_to_root: float¶

Calculate the total distance from the section start to the root.

Returns:: The distance from the section start to the root.
Return type:: float

property domain_root¶

Get the root section of the current domain.

The domain root is the shallowest (closest to tree root) section that still belongs to this domain.

Returns:: The root section of the current domain.
Return type:: Section
Raises:: ValueError – If the section has no parent (is the tree root).

path_distance(other=None, relative_position: float = None, relative_position_other: float = None) → float[source]¶

Calculate the path distance between positions on two sections.

Parameters:

other (Section, optional) – The other section. If None, calculates distance to root.
relative_position (float, optional) – Position along self (0 = start, 1 = end). Default None (context-dependent).
relative_position_other (float, optional) – Position along other (0 = start, 1 = end). Default None (context-dependent).

Returns:

The path distance between the two positions.

Return type:

float

disconnect_from_parent()[source]¶: Detach the section from its parent section.

connect_to_parent(parent)[source]¶

Attach the section to a parent section.

Parameters:: parent (Section) – The parent section to attach to.

plot(ax=None, plot_parent=True, section_color=None, parent_color='gray', show_labels=True, aspect_equal=True)[source]¶

Plot section morphology in 3D projections (XZ, YZ, XY) and radii distribution.

Parameters:

ax (list or array of matplotlib.axes.Axes, optional) – Four axes for plotting (XZ, YZ, XY, radii). If None, creates a new figure with axes.
plot_parent (bool, optional) – Whether to include parent section in the visualization.
section_color (str or None, optional) – Color for the current section. If None, assigns based on section domain.
parent_color (str, optional) – Color for the parent section.
show_labels (bool, optional) – Whether to show axis labels and titles.
aspect_equal (bool, optional) – Whether to set aspect ratio to ‘equal’ for the projections.

Returns:

ax – The axes containing the plots.

Return type:

list of matplotlib.axes.Axes

plot_radii(ax=None, include_parent=False, section_color=None, parent_color='gray')[source]¶

Plot just the radius distribution for the section.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates a new figure and axes.
include_parent (bool, optional) – Whether to include parent section in the plot.
section_color (str or None, optional) – Color for current section. If None, assigns based on section domain.
parent_color (str, optional) – Color for parent section if included.

Returns:

ax – The axes containing the plot.

Return type:

matplotlib.axes.Axes

property ancestors¶: Get all ancestors of this node up to the root.

property depth¶: Computes the depth of the node in the tree iteratively.

find_common_ancestor(other)¶: Find the common ancestor between this node and another node.

property is_root: bool¶

Check if the node is the root of the tree.

Returns:: True if the node is the root, False otherwise.
Return type:: bool

property nearest_neighbours¶

Gets the nearest neighbours of the node.

Returns:: A list of nodes that share the same parent or children as the node.
Return type:: list

property parent¶

path(other, include_self=True, include_other=True, include_ancestor=True)¶

Get the path between this node and another node.

Parameters:

other (Node) – The other node to get the path to.
include_self (bool) – Whether to include this node in the path.
include_other (bool) – Whether to include the other node in the path.
include_ancestor (bool) – Whether to include the lowest common ancestor (LCA) in the path. Only relevant when self and other are in parallel subtrees, ignored otherwise.

Returns:

A list of nodes representing the path from this node to the other node.

Return type:

list

path_to_ancestor(ancestor=None, include_self=True, include_ancestor=True)¶

Get the path from this node to a given ancestor node.

Parameters:

ancestor (Node, optional) – The ancestor node to get the path to. If None, the path to the root is returned.
include_self (bool, optional) – Whether to include this node in the path. Defaults to True.
include_ancestor (bool, optional) – Whether to include the ancestor node in the path. Defaults to True.

Returns:

A list of nodes representing the path from this node to the ancestor node.

Return type:

list

property siblings¶

Gets the siblings of the node.

Returns:: A list of nodes that share the same parent as the node.
Return type:: list

property subtree: list¶

Gets the subtree of the node (including the node itself) using an iterative depth-first traversal.

Returns:: A list of nodes in the subtree.
Return type:: list

property subtree_size¶

Gets the size of the subtree of the node.

Returns:: The size of the subtree of the node.
Return type:: int

property topological_type: str¶

The topological type of the node based on the number of children.

Returns:: The topological type of the node: ‘continuation’, ‘bifurcation’, or ‘termination’.
Return type:: str

class dendrotweaks.morphology.sec_trees.SectionTree(sections: list[Section])[source]¶

Bases: Tree

A class representing a tree graph of sections in a neuron morphology.

Parameters:: sections (List[Section]) – A list of sections in the tree.

domains¶

A dictionary of domains in the tree.

Type:: Dict[str, Domain]

property sections¶: A list of sections in the tree. Alias for self._nodes.

property soma¶: The soma section of the tree. Alias for self.root.

property sections_by_depth¶: A dictionary of sections grouped by depth in the tree (depth is the number of edges from the root).

property df¶: A DataFrame of the sections in the tree.

sort(**kwargs)[source]¶

Sort the sections in the tree using a depth-first traversal.

Parameters:

sort_children (bool, optional) – Whether to sort the children of each node based on the number of bifurcations in their subtrees. Defaults to True.
force (bool, optional) – Whether to force the sorting of the tree even if it is already sorted. Defaults to False.

remove_subtree(section)[source]¶

Remove a section and its subtree from the tree.

Parameters:: section (Section) – The section to remove.

reposition_subtree(section, new_parent_section, origin=None)[source]¶

Reposition a subtree in the tree.

Parameters:

node (Node) – The root node of the subtree to reposition.
new_parent_node (Node) – The new parent node of the subtree.
origin (Node, optional) – The origin node to use as the reference point for the repositioning. Defaults to None.

Note

Treats differently the children of the root node.

remove_zero_length_sections()[source]¶: Remove sections with zero length.

downsample(factor: float)[source]¶

Downsample the SWC tree by reducing the number of points in each section based on the given factor, while preserving the first and last points.

Parameters:: factor – The proportion of points to keep (e.g., 0.5 keeps 50% of points) If factor is 0, keep only the first and last points.

plot(ax=None, show_points=False, show_lines=True, show_domains=True, annotate=False, projection='XY', highlight_sections=None, focus_sections=None)[source]¶

Plot the sections in the tree in a 2D projection.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates a new figure and axes.
show_points (bool, optional) – Whether to show the points in the sections.
show_lines (bool, optional) – Whether to show the lines connecting the points.
show_domains (bool, optional) – Whether to color sections based on their domain.
annotate (bool, optional) – Whether to annotate the sections with their index.
projection (str or tuple, optional) – The projection to use for the plot. Can be ‘XY’, ‘XZ’, ‘YZ’, or a tuple of two axes.
highlight_sections (list of Section, optional) – Sections to highlight in the plot.
focus_sections (list of Section, optional) – Sections to focus on in the plot.

add_subtree(node, parent)¶

Add a subtree to the tree.

Parameters:

node (Node) – The root node of the subtree to add.
parent (Node) – The parent node to attach the subtree to.

property bifurcations¶

The bifurcation nodes in the tree.

Returns:: A list of bifurcation nodes in the tree.
Return type:: list

property edges: list¶

Returns a list of edges in the tree.

Returns:: A list of edges in the tree.
Return type:: list[tuple[Node, Node]]

insert_node_after(new_node, existing_node)¶

Insert a node after a given node in the tree.

Parameters:

new_node (Node) – The new node to insert.
existing_node (Node) – The existing node after which to insert the new node.

insert_node_before(new_node, existing_node)¶

Insert a node before a given node in the tree.

Parameters:

new_node (Node) – The new node to insert.
existing_node (Node) – The existing node before which to insert the new node.

property is_connected¶

Whether the tree is connected i.e. each node can be reached from the root.

Returns:

bool – True if the root node’s subtree contains exactly the same nodes
as the entire tree. False otherwise.

property is_sorted¶

Whether the nodes in the tree are sorted by index.

Returns:: True if the nodes are sorted by index. False otherwise.
Return type:: bool

plot_radii_distribution(ax=None, highlight=None, domains=True, show_soma=False)[source]¶

Plot the radius distribution of the sections in the tree.

Parameters:

ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, creates a new figure and axes.
highlight (list of int, optional) – Indices of sections to highlight in the plot.
domains (bool, optional) – Whether to color sections based on their domain.
show_soma (bool, optional) – Whether to show the soma section in the plot.

remove_node(node)¶

Remove a node from the tree.

Parameters:: node (Node) – The node to remove.
Raises:: ValueError – If the tree is not sorted.

property terminations¶

topology()¶: Print the topology of the tree with a visual tree structure.

traverse(root=None)¶

Iterate over the nodes in the tree using a stack-based depth-first traversal.

Parameters:: root (Node, optional) – The root node to start the traversal from. Defaults to None.