dendrotweaks 0.3.1__py3-none-any.whl

dendrotweaks/model_io.py

@@ -0,0 +1,75 @@
+import jinja2
+import os
+from collections import defaultdict
+
+DOMAINS_TO_NEURON = {
+    'soma': 'soma',
+    'perisomatic': 'dend_11',
+    'axon': 'axon',
+    'apic': 'apic',
+    'dend': 'dend',
+    'basal': 'dend_31',
+    'trunk': 'dend_41',
+    'tuft': 'dend_42',
+    'oblique': 'dend_43',
+    'custom': 'dend_5',
+    'reduced': 'dend_8',
+    'undefined': 'dend_0',
+}
+
+def get_neuron_domain(domain_name):
+    base_domain, _, idx = domain_name.partition('_')
+    if base_domain in ['reduced', 'custom'] and idx.isdigit():
+        return f'{DOMAINS_TO_NEURON[base_domain]}{idx}'
+    return DOMAINS_TO_NEURON.get(base_domain, 'dend_0')
+
+def render_template(path_to_template, context):
+    """
+    Render a Jinja2 template.
+
+    Parameters
+    ----------
+    path_to_template : str
+        The path to the Jinja2 template.
+    context : dict
+        The context to render the template with.
+    """
+    with open(path_to_template, 'r') as f:
+        template = jinja2.Template(f.read())
+    return template.render(context)
+
+
+def get_params_to_valid_domains(model):
+    
+    params_to_valid_domains = defaultdict(dict)
+
+    for param, mech in model.params_to_mechs.items():
+        for group_name, distribution in model.params[param].items():
+            group = model.groups[group_name]
+            valid_domains = [get_neuron_domain(domain) for domain in group.domains if mech == 'Independent' or mech in model.domains_to_mechs[domain]]
+            params_to_valid_domains[param][group_name] = valid_domains
+
+    return dict(params_to_valid_domains)
+
+
+def filter_params(model):
+    """
+    Filter out kinetic parameters from the model.
+
+    Parameters
+    ----------
+    model : Model
+        The model to filter.
+
+    Returns
+    -------
+    Model
+        The model with kinetic parameters filtered out.
+    """
+    filtered_params = {
+        param: {
+            group_name: distribution 
+            for group_name, distribution in distributions.items() 
+            if param in list(model.conductances.keys()) + ['cm', 'Ra', 'ena', 'ek', 'eca']} 
+            for param, distributions in model.params.items()}
+    return filtered_params

dendrotweaks/morphology/__init__.py

@@ -0,0 +1,5 @@
+from dendrotweaks.morphology.trees import Node, Tree
+from dendrotweaks.morphology.point_trees import Point, PointTree
+from dendrotweaks.morphology.sec_trees import Section, SectionTree, Domain
+from dendrotweaks.morphology.seg_trees import Segment, SegmentTree
+from dendrotweaks.morphology.io.validation import validate_tree

dendrotweaks/morphology/domains.py

@@ -0,0 +1,100 @@
+
+class Domain:
+    """
+    A class representing
+    a morphological or functional domain in a neuron.
+
+    Parameters
+    ----------
+    name : str
+        The name of the domain.
+    sections : List[Section], optional
+        A list of sections in the domain.
+
+    Attributes
+    ----------
+    name : str
+        The name of the domain.
+    """
+
+    def __init__(self, name: str, sections = None) -> None:
+        self.name = name
+        self._sections = sections if sections else []
+
+
+    def __repr__(self):
+        return f'<Domain({self.name}, {len(self.sections)} sections)>'
+
+
+    def __contains__(self, section):
+        return section in self.sections
+
+
+    @property
+    def sections(self):
+        """
+        A list of sections in the domain.
+        """
+        return self._sections
+
+
+    # def merge(self, other):
+    #     """
+    #     Merge the sections of the other domain into this domain.
+    #     """
+    #     self.inserted_mechanisms.update(other.inserted_mechanisms)
+    #     sections = self.sections + other.sections
+    #     self._sections = []
+    #     for sec in sections:
+    #         self.add_section(sec)
+
+
+    def add_section(self, sec: "Section"):
+        """
+        Add a section to the domain.
+
+        Changes the domain attribute of the section.
+
+        Parameters
+        ----------
+        sec : Section
+            The section to be added to the domain.
+        """
+        if sec in self._sections:
+            warnings.warn(f'Section {sec} already in domain {self.name}.')
+            return
+        sec.domain = self.name
+        sec.domain_idx = len(self._sections)
+        self._sections.append(sec)
+
+
+    def remove_section(self, sec):
+        """
+        Remove a section from the domain.
+
+        Sets the domain attribute of the section
+        to None.
+
+        Parameters
+        ----------
+        sec : Section
+            The section to be removed from the domain.
+        """
+        if sec not in self.sections:
+            warnings.warn(f'Section {sec} not in domain {self.name}.')
+            return
+        sec.domain = None
+        sec.domain_idx = None
+        self._sections.remove(sec)
+
+
+    def is_empty(self):
+        """
+        Check if the domain is empty.
+
+        Returns
+        -------
+        bool
+            True if the domain is empty, False otherwise.
+        """
+        return not bool(self._sections)

dendrotweaks/morphology/io/__init__.py

@@ -0,0 +1,5 @@
+from dendrotweaks.morphology.io.reader import SWCReader
+from dendrotweaks.morphology.io.validation import validate_tree
+from dendrotweaks.morphology.io.factories import create_point_tree
+from dendrotweaks.morphology.io.factories import create_section_tree
+from dendrotweaks.morphology.io.factories import create_segment_tree

dendrotweaks/morphology/io/factories.py

@@ -0,0 +1,212 @@
+from dendrotweaks.morphology.trees import Node, Tree
+from dendrotweaks.morphology.point_trees import Point, PointTree
+from dendrotweaks.morphology.sec_trees import Section, SectionTree
+from dendrotweaks.morphology.seg_trees import Segment, SegmentTree
+
+from dendrotweaks.morphology.io.reader import SWCReader
+
+from typing import List, Union
+import numpy as np
+from pandas import DataFrame
+
+from dendrotweaks.morphology.io.validation import validate_tree
+
+
+
+def create_point_tree(source: Union[str, DataFrame]) -> PointTree:
+    """
+    Create a point tree from either a file path or a DataFrame.
+    
+    Parameters
+    ----------
+    source : Union[str, DataFrame]
+        The source of the SWC data. Can be a file path or a DataFrame.
+
+    Returns
+    -------
+    PointTree
+        The point tree representing the reconstruction of the neuron morphology.
+    """
+    if isinstance(source, str):
+        reader = SWCReader()
+        df = reader.read_file(source)
+    elif isinstance(source, DataFrame):
+        df = source
+    else:
+        raise ValueError("Source must be a file path (str) or a DataFrame.")
+
+    nodes = [
+        Point(row['Index'], row['Type'], row['X'], row['Y'], row['Z'], row['R'], row['Parent'])
+        for _, row in df.iterrows()
+    ]
+    point_tree =  PointTree(nodes)
+    point_tree.remove_overlaps()
+
+    return point_tree
+
+
+def create_section_tree(point_tree: PointTree):
+    """
+    Create a section tree from a point tree.
+
+    Parameters
+    ----------
+    point_tree : PointTree
+        The point tree to create the section tree from by splitting it into sections.
+
+    Returns
+    -------
+    SectionTree
+        The section tree created representing the neuron morphology on a more abstract level.
+    """
+
+    point_tree.extend_sections()
+    point_tree.sort()
+
+    sections = _split_to_sections(point_tree)
+
+    sec_tree = SectionTree(sections)
+    sec_tree._point_tree = point_tree
+
+    return sec_tree
+
+
+def _split_to_sections(point_tree: PointTree) -> List[Section]:
+    """
+    Split the point tree into sections.
+    """
+    sections = []
+
+    bifurcation_children = [
+        child for b in point_tree.bifurcations for child in b.children]
+    bifurcation_children = [point_tree.root] + bifurcation_children
+    # Filter out the bifurcation children to enforce the original order
+    bifurcation_children = [node for node in point_tree._nodes 
+                            if node in bifurcation_children]
+
+    # Assign a section to each bifurcation child
+    for i, child in enumerate(bifurcation_children):
+        section = Section(idx=i, parent_idx=-1, points=[child])
+        sections.append(section)
+        child._section = section
+        # Propagate the section to the children until the next 
+        # bifurcation or termination point is reached
+        while child.children:
+            next_child = child.children[0]
+            if next_child in bifurcation_children:
+                break
+            next_child._section = section
+            section.points.append(next_child)
+            child = next_child
+
+        section.parent = section.points[0].parent._section if section.points[0].parent else None
+        section.parent_idx = section.parent.idx if section.parent else -1
+
+
+    if point_tree.soma_notation == '3PS':
+        sections = _merge_soma(sections, point_tree)
+
+    return sections
+
+
+def _merge_soma(sections: List[Section], point_tree: PointTree):
+    """
+    If soma has 3PS notation, merge it into one section.
+    """
+
+    true_soma = point_tree.root._section
+    true_soma.idx = 0
+    true_soma.parent_idx = -1
+
+    false_somas = [sec for sec in sections 
+        if sec.domain == 'soma' and sec is not true_soma]
+    if len(false_somas) != 2:
+        print(false_somas)
+        raise ValueError('Soma must have exactly 2 children of domain soma.')
+
+    for i, sec in enumerate(false_somas):
+        sections.remove(sec)
+        if len(sec.points) != 1:
+            raise ValueError('Soma children must have exactly 1 point.')
+        for pt in sec.points:
+            pt._section = true_soma
+
+    true_soma.points = [
+        false_somas[0].points[0], 
+        true_soma.points[0], 
+        false_somas[1].points[0]
+    ]
+
+    for sec in sections:
+        if sec is true_soma:
+            continue
+        sec.idx -= 2
+        sec.parent_idx = sec.points[0].parent._section.idx
+        
+
+    return sections
+
+
+def create_segment_tree(sec_tree):
+    """
+    Create a segment tree from a section tree.
+
+    Parameters
+    ----------
+    sec_tree : SectionTree
+        The section tree to create the segment tree from by splitting it into segments.
+
+    Returns
+    -------
+    SegmentTree
+        The segment tree representing spatial discretization of the neuron morphology for numerical simulations.
+    """
+
+    segments = _create_segments(sec_tree)
+
+    seg_tree = SegmentTree(segments)
+    sec_tree._seg_tree = seg_tree
+
+    return seg_tree
+
+
+def _create_segments(sec_tree) -> List[Segment]:
+    """
+    Create a list of Segment objects from a SectionTree object.
+    """
+
+    segments = []  
+    # TODO: Refactor this to use a stack instead of recursion
+    def add_segments(sec, parent_idx, idx_counter):
+        segs = {seg: idx + idx_counter for idx, seg in enumerate(sec._ref)}
+        sec.segments = []
+        for seg, idx in segs.items():
+            segment = Segment(
+                idx=idx, parent_idx=parent_idx, neuron_seg=seg, section=sec)
+            segments.append(segment)
+            sec.segments.append(segment)
+
+            parent_idx = idx
+        
+        idx_counter += len(segs)
+
+        
+        for child in sec.children:
+            # IMPORTANT: This is needed since 0 and 1 segments are not explicitly
+            # defined in the section segments list
+            if child._ref.parentseg().x == 1:
+                new_parent_idx = list(segs.values())[-1]
+            elif child._ref.parentseg().x == 0:
+                new_parent_idx = list(segs.values())[0]
+            else:
+                new_parent_idx = segs[child._ref.parentseg()]
+            # Recurse for the child section
+            idx_counter = add_segments(child, new_parent_idx, idx_counter)
+
+        return idx_counter
+
+    # Start with the root section of the sec_tree
+    add_segments(sec_tree.root, parent_idx=-1, idx_counter=0)
+
+    return segments
+        

dendrotweaks/morphology/io/reader.py

@@ -0,0 +1,66 @@
+import pandas as pd
+
+class SWCReader():
+    """
+    Reads an SWC file and returns a DataFrame.
+    """
+
+    def __init__(self):
+        pass
+
+    @staticmethod
+    def read_file(path_to_swc_file: str) -> pd.DataFrame:
+        """
+        Read the SWC file and return a DataFrame.
+
+        Parameters
+        ----------
+        path_to_swc_file : str
+            The full path to the SWC file.
+
+        Returns
+        -------
+        pd.DataFrame
+            The DataFrame containing the SWC data
+        """
+        with open(path_to_swc_file, 'r') as f:
+            lines = f.readlines()
+        lines = [' '.join(line.split()) for line in lines if line.strip()]
+        with open(path_to_swc_file, 'w') as f:
+            f.write('\n'.join(lines))
+
+        df = pd.read_csv(
+            path_to_swc_file, 
+            sep=' ', 
+            header=None, 
+            comment='#', 
+            names=['Index', 'Type', 'X', 'Y', 'Z', 'R', 'Parent'],
+            index_col=False
+        )
+
+        if (df['R'] == 0).all():
+            df['R'] = 1.0
+
+        if df['Index'].duplicated().any():
+            raise ValueError("The SWC file contains duplicate node ids.")
+        return df
+
+    @staticmethod
+    def plot_raw_data(df, ax):
+        """
+        Plot the raw data from the SWC file using the DataFrame.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            The DataFrame containing the SWC data (generated by read_file).
+        ax : matplotlib.pyplot.Axes
+            The axes to plot on.
+        """
+        types_to_colors = {1: 'C1', 2: 'C3', 3: 'C2', 4: 'C0', 31: 'green', 41: 'blue', 42: 'magenta', 43: 'brown'}
+        for t in df['Type'].unique():
+            color = types_to_colors.get(t, 'k')
+            mask = df['Type'] == t
+            ax.scatter(df[mask]['X'], df[mask]['Y'], df[mask]['Z'], 
+                       c=color, s=1, label=f'Type {t}')
+        ax.legend()

dendrotweaks/morphology/io/validation.py

@@ -0,0 +1,212 @@
+from dendrotweaks.morphology.trees import Tree
+from dendrotweaks.morphology.point_trees import PointTree
+from dendrotweaks.morphology.sec_trees import SectionTree
+
+import numpy as np
+import warnings
+
+# def custom_warning_formatter(message, category, filename, lineno, file=None, line=None):
+#     return f"WARNING: {message}\n({os.path.basename(filename)}, line {lineno})\n"
+
+# warnings.formatwarning = custom_warning_formatter
+
+
+def validate_tree(tree):
+    """
+    Validate the toplogical structure of a tree graph.
+
+    Parameters
+    ----------
+    tree : Tree
+        The tree to validate.
+    """
+    # Check for unique node ids
+    check_unique_ids(tree)
+    check_unique_root(tree)
+    check_unique_children(tree)
+    
+
+    # Check for connectivity
+    check_connections(tree)
+    check_loops(tree)
+    check_bifurcations(tree)
+    # validate_order(self.tree)
+
+    if isinstance(tree, PointTree):
+        validate_point_tree(tree)
+
+    if isinstance(tree, SectionTree):
+        validate_section_tree(tree)
+
+    # Check if the tree is sorted
+    print("Checking if the tree is sorted...")
+    if not tree.is_sorted:
+        warnings.warn("Tree is not sorted")
+    
+    print("***Validation complete.***")
+
+
+# -----------------------------------------------------------------------------
+# Indicies
+# -----------------------------------------------------------------------------
+
+def check_unique_ids(tree):
+    print("Checking for unique node ids...")
+    node_ids = {node.idx for node in tree._nodes}
+    if len(node_ids) != len(tree._nodes):
+        warnings.warn(f"Tree contains {len(tree._nodes) - len(node_ids)} duplicate node ids.")
+
+
+def check_unique_children(tree):
+    print("Checking for duplicate children...")
+    for node in tree._nodes:
+        children = node.children
+        if len(children) != len(set(children)):
+            warnings.warn(f"Node {node} contains duplicate children.")
+
+
+def check_unique_root(tree):
+    print("Checking for unique root node...")
+    root_nodes = {node for node in tree._nodes
+        if node.parent is None or node.parent_idx in {None, -1, '-1'}
+    }
+    if len(root_nodes) > 1:
+        warnings.warn(f"Found {len(root_nodes)} root nodes.")
+    elif len(root_nodes) == 0:
+        warnings.warn("Tree does not contain a root node.")
+
+
+# -----------------------------------------------------------------------------
+# Connectivity
+# -----------------------------------------------------------------------------
+
+def check_connections(tree):
+    """
+    Validate the parent-child relationships in the tree.
+
+    1. Ensure that every node is listed as a child of its parent.
+    2. Ensure that the parent of each child matches the node.
+    """
+    print("Checking tree connectivity...")
+    if not tree.is_connected:
+        not_connected = set(tree._nodes) - set(tree.root.subtree)
+        warnings.warn(f"The following nodes are not connected to the root node: {not_connected}")
+
+    for node in tree._nodes:
+        parent = node.parent
+        
+        # Validate that the node is in its parent's children list.
+        if parent is not None:
+            if node not in parent.children:
+                warnings.warn(
+                    f"Validation Warning: Node {node} is not listed in the children of its parent {parent}. "
+                    f"Expected parent.children to include {node}, but it does not."
+                )
+
+        # Validate that the parent of each child is the current node.
+        for child in node.children:
+            if child.parent is not node:
+                warnings.warn(
+                    f"Validation Warning: Node {child} has an incorrect parent. "
+                    f"Expected parent {node}, but found {child.parent}."
+                )
+
+
+def check_loops(tree):
+    print("Checking for loops...")
+    for node in tree._nodes:
+        for descendant in node.subtree:
+            if node in descendant.children:
+                warnings.warn(f"Node {node} is a descendant of itself. Loop detected at node {descendant}.")
+
+def check_bifurcations(tree):
+    print("Checking for bifurcations with more than 2 children...")
+    bifurcation_issues = {node: len(node.children) for node in tree.bifurcations if len(node.children) > 2 and node is not tree.root}
+    if bifurcation_issues:
+        issues_str = "\n".join([f"Node {node.idx:<6} has {count} children" for node, count in bifurcation_issues.items()])
+        warnings.warn(f"Tree contains bifurcations with more than 2 children:\n{issues_str}")
+    
+
+# =============================================================================
+# Point-specific validation
+# =============================================================================
+
+def validate_point_tree(point_tree):
+    """
+    Validate the geometry of a point tree.
+
+    Parameters
+    ----------
+    point_tree : PointTree
+        The point tree to validate.
+    """
+
+    # Check for NaN values in the DataFrame
+    print("Checking for NaN values...")
+    nan_counts = point_tree.df.isnull().sum()
+    if nan_counts.sum() > 0:
+        warnings.warn(f"Found {nan_counts} NaN values in the DataFrame")
+
+    # Check for bifurcations in the soma
+    print("Checking for bifurcations in the soma...")
+    bifurcations_without_root = [pt for pt in point_tree.bifurcations 
+        if pt is not point_tree.root]
+    bifurcations_within_soma = [pt for pt in bifurcations_without_root
+        if pt.type_idx == 1]
+    if bifurcations_within_soma:
+        warnings.warn(f"Soma must be non-branching. Found bifurcations: {bifurcations_within_soma}")
+
+
+    if point_tree._is_extended:
+        print("Checking the extended tree for geometric continuity...")
+        non_overlapping_children = [
+            (pt, child) for pt in bifurcations_without_root for child in pt.children
+            if not child.overlaps_with(pt)
+        ]
+        if non_overlapping_children:
+            issues_str = "\n".join([f"Child {child} does not overlap with parent {pt}" for pt, child in non_overlapping_children])
+            warnings.warn(f"Found non-overlapping children:\n{issues_str} for bifurcations")
+        
+
+# =============================================================================
+# Section-specific validation
+# =============================================================================
+
+def validate_section_tree(section_tree):
+    """
+    Validate a section tree.
+
+    Parameters
+    ----------
+    section_tree : SectionTree
+        The section tree to validate.
+    """
+
+    print("Checking that all points in a section belong to the same domain...")
+    for sec in section_tree:
+        if not all(pt.domain == sec.domain for pt in sec.points):
+            warnings.warn('All points in a section must belong to the same domain.')
+
+    print("Checking that all sections have a non-zero length...")
+    if any(sec.length == 0 for sec in section_tree):
+        warnings.warn('Found sections with zero length.')
+
+    print("Checking that all sections (except soma) have 0 or 2 children...")
+    if any(len(sec.children) not in {0, 2} and sec is not section_tree.root for sec in section_tree):
+        warnings.warn('Found sections with an incorrect number of children.')
+
+    print("Checking that the root section has domain soma...")
+    if not section_tree.root.domain == 'soma':
+        warnings.warn('Root section must have domain soma.')
+
+
+# =============================================================================
+# Validation utilities
+# =============================================================================
+
+def shuffle_indices_for_testing(df):
+    idx_range = int(df['Index'].max() - df['Index'].min()) + 1
+    random_mapping = {k:v for k, v in zip(df['Index'], np.random.permutation(idx_range))}
+    df['Index'] = df['Index'].map(random_mapping)
+    df.loc[df['Parent'] != -1, 'Parent'] = df['Parent'].map(random_mapping)
+    return df