swcgeom 0.14.0__py3-none-any.whl → 0.16.0__py3-none-any.whl

swcgeom/analysis/sholl.py

@@ -23,10 +23,15 @@ YLABLE = "Count of Intersections"
 class Sholl:
     """Sholl analysis.
 
+    Implementation of original Sholl analysis as described in [1]_. The
+    Sholl analysis is a method to quantify the spatial distribution of
+    neuronal processes. It is based on the number of intersections of
+    concentric circles with the neuronal processes.
+
     References
     ----------
-    [1] Dendritic organization in the neurons of the visual and motor
-    cortices of the cat J. Anat., 87 (1953), pp. 387-406
+    .. [1] Dendritic organization in the neurons of the visual and
+       motor cortices of the cat J. Anat., 87 (1953), pp. 387-406
     """
 
     tree: Tree
@@ -156,6 +161,12 @@ class Sholl:
         return self.get_rs(self.rmax, steps)
 
     def get_count(self) -> npt.NDArray[np.int32]:
+        """Get the count of intersection.
+
+        .. deprecated:: 0.5.0
+            Use :meth:`Sholl.get` instead.
+        """
+
         warnings.warn(
             "`Sholl.get_count` has been renamed to `get` since v0.5.0, "
             "and will be removed in next version",
@@ -164,6 +175,12 @@ class Sholl:
         return self.get().astype(np.int32)
 
     def avg(self) -> float:
+        """Get the average of the count of intersection.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`Shool(x).get().mean()` instead.
+        """
+
         warnings.warn(
             "`Sholl.avg` has been deprecated since v0.6.0 and will be "
             "removed in next version, use `Shool(x).get().mean()` "
@@ -173,6 +190,12 @@ class Sholl:
         return self.get().mean()
 
     def std(self) -> float:
+        """Get the std of the count of intersection.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`Shool(x).get().std()` instead.
+        """
+
         warnings.warn(
             "`Sholl.std` has been deprecate since v0.6.0 and will be "
             "removed in next version, use `Shool(x).get().std()` "
@@ -182,6 +205,12 @@ class Sholl:
         return self.get().std()
 
     def sum(self) -> int:
+        """Get the sum of the count of intersection.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`Shool(x).get().sum()` instead.
+        """
+
         warnings.warn(
             "`Sholl.sum` has been deprecate since v0.6.0 and will be "
             "removed in next version, use `Shool(x).get().sum()` "

swcgeom/core/__init__.py

@@ -3,6 +3,10 @@
 from swcgeom.core import swc_utils
 from swcgeom.core.branch import *
 from swcgeom.core.branch_tree import *
+from swcgeom.core.compartment import (  # Segment and Segments don't expose
+    Compartment,
+    Compartments,
+)
 from swcgeom.core.node import *
 from swcgeom.core.path import *
 from swcgeom.core.population import *

swcgeom/core/branch.py

@@ -5,8 +5,8 @@ from typing import Generic, Iterable, List
 import numpy as np
 import numpy.typing as npt
 
+from swcgeom.core.compartment import Compartment, Compartments
 from swcgeom.core.path import Path
-from swcgeom.core.segment import Segment, Segments
 from swcgeom.core.swc import DictSWC, SWCTypeVar
 
 __all__ = ["Branch"]
@@ -24,9 +24,11 @@ class Branch(Path, Generic[SWCTypeVar]):
     attach: SWCTypeVar
     idx: npt.NDArray[np.int32]
 
-    class Segment(Segment["Branch"]):
+    class Compartment(Compartment["Branch"]):
         """Segment of branch."""
 
+    Segment = Compartment  # Alias
+
     def __repr__(self) -> str:
         return f"Neuron branch with {len(self)} nodes."
 
@@ -36,8 +38,11 @@ class Branch(Path, Generic[SWCTypeVar]):
     def get_ndata(self, key: str) -> npt.NDArray:
         return self.attach.get_ndata(key)[self.idx]
 
-    def get_segments(self) -> Segments[Segment]:
-        return Segments(self.Segment(self, n.pid, n.id) for n in self[1:])
+    def get_compartments(self) -> Compartments[Compartment]:
+        return Compartments(self.Compartment(self, n.pid, n.id) for n in self[1:])
+
+    def get_segments(self) -> Compartments[Compartment]:
+        return self.get_compartments()  # Alias
 
     def detach(self) -> "Branch[DictSWC]":
         """Detach from current attached object."""

swcgeom/core/branch_tree.py

@@ -5,7 +5,6 @@ from typing import Dict, List
 
 import numpy as np
 import pandas as pd
-from typing_extensions import Self
 
 from swcgeom.core.branch import Branch
 from swcgeom.core.swc_utils import to_sub_topology
@@ -31,7 +30,7 @@ class BranchTree(Tree):
         return self.branches[idx]
 
     @classmethod
-    def from_tree(cls, tree: Tree) -> Self:
+    def from_tree(cls, tree: Tree) -> "BranchTree":
         """Generating a branch tree from tree."""
 
         branches = tree.get_branches()
@@ -56,6 +55,6 @@ class BranchTree(Tree):
         return branch_tree
 
     @classmethod
-    def from_data_frame(cls, df: pd.DataFrame, *args, **kwargs) -> Self:
+    def from_data_frame(cls, df: pd.DataFrame, *args, **kwargs) -> "BranchTree":
         tree = super().from_data_frame(df, *args, **kwargs)
         return cls.from_tree(tree)

swcgeom/core/{segment.py → compartment.py}

@@ -9,11 +9,11 @@ from swcgeom.core.path import Path
 from swcgeom.core.swc import DictSWC, SWCTypeVar
 from swcgeom.core.swc_utils import SWCNames, get_names
 
-__all__ = ["Segment", "Segments"]
+__all__ = ["Compartment", "Compartments", "Segment", "Segments"]
 
 
-class Segment(Path, Generic[SWCTypeVar]):
-    r"""Segment attached to external object."""
+class Compartment(Path, Generic[SWCTypeVar]):
+    r"""Compartment attached to external object."""
 
     attach: SWCTypeVar
     idx: npt.NDArray[np.int32]
@@ -27,7 +27,7 @@ class Segment(Path, Generic[SWCTypeVar]):
     def get_ndata(self, key: str) -> npt.NDArray:
         return self.attach.get_ndata(key)[self.idx]
 
-    def detach(self) -> "Segment[DictSWC]":
+    def detach(self) -> "Compartment[DictSWC]":
         """Detach from current attached object."""
         # pylint: disable=consider-using-dict-items
         attact = DictSWC(
@@ -37,18 +37,18 @@ class Segment(Path, Generic[SWCTypeVar]):
         )
         attact.ndata[self.names.id] = self.id()
         attact.ndata[self.names.pid] = self.pid()
-        return Segment(attact, 0, 1)
+        return Compartment(attact, 0, 1)
 
 
-SegmentT = TypeVar("SegmentT", bound=Segment)
+T = TypeVar("T", bound=Compartment)
 
 
-class Segments(List[SegmentT]):
-    r"""Segments contains a set of segments."""
+class Compartments(List[T]):
+    r"""Comparments contains a set of comparment."""
 
     names: SWCNames
 
-    def __init__(self, segments: Iterable[SegmentT]) -> None:
+    def __init__(self, segments: Iterable[T]) -> None:
         super().__init__(segments)
         self.names = self[0].names if len(self) > 0 else get_names()
 
@@ -94,3 +94,8 @@ class Segments(List[SegmentT]):
         The order of axis 1 is (parent, current node).
         """
         return np.array([s.get_ndata(key) for s in self])
+
+
+# Aliases
+Segment = Compartment
+Segments = Compartments

swcgeom/core/node.py

@@ -95,14 +95,6 @@ class Node(Generic[SWCTypeVar]):
         items = [self.id, self.type, x, y, z, r, self.pid]
         return " ".join(map(str, items))
 
-    def child_ids(self) -> npt.NDArray[np.int32]:
-        warnings.warn(
-            "`Node.child_ids` has been deprecated since v0.3.1 and "
-            "will be removed in next version",
-            DeprecationWarning,
-        )
-        return self.attach.id()[self.attach.pid() == self.id]
-
     def is_bifurcation(self) -> bool:
         return np.count_nonzero(self.attach.pid() == self.id) > 1
 

swcgeom/core/path.py

@@ -1,5 +1,6 @@
-"""Nueron node."""
+"""Nueron path."""
 
+import warnings
 from typing import Generic, Iterable, Iterator, List, overload
 
 import numpy as np
@@ -12,7 +13,7 @@ __all__ = ["Path"]
 
 
 class Path(SWCLike, Generic[SWCTypeVar]):
-    """Neural path.
+    """Neuron path.
 
     A path is a linear set of points without bifurcations.
     """
@@ -31,7 +32,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
         self.source = self.attach.source
 
     def __iter__(self) -> Iterator[Node]:
-        return (self.get_node(i) for i in range(len(self)))
+        return (self.node(i) for i in range(len(self)))
 
     def __len__(self) -> int:
         return self.id().shape[0]
@@ -50,7 +51,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return [self.get_node(i) for i in range(*key.indices(len(self)))]
+            return [self.node(i) for i in range(*key.indices(len(self)))]
 
         if isinstance(key, (int, np.integer)):
             length = len(self)
@@ -60,7 +61,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
             if key < 0:  # Handle negative indices
                 key += length
 
-            return self.get_node(key)
+            return self.node(key)
 
         if isinstance(key, str):
             return self.get_ndata(key)
@@ -74,6 +75,20 @@ class Path(SWCLike, Generic[SWCTypeVar]):
         return self.attach.get_ndata(key)[self.idx]
 
     def get_node(self, idx: int | np.integer) -> Node:
+        """Get the count of intersection.
+
+        .. deprecated:: 0.16.0
+            Use :meth:`path.node` instead.
+        """
+
+        warnings.warn(
+            "`Path.get_node` has been deprecated since v0.16.0 and "
+            "will be removed in future version",
+            DeprecationWarning,
+        )
+        return self.node(idx)
+
+    def node(self, idx: int | np.integer) -> Node:
         return self.Node(self, idx)
 
     def detach(self) -> "Path[DictSWC]":
@@ -129,7 +144,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
         The end-to-end straight-line distance between start point and
         end point.
         """
-        return np.linalg.norm(self.get_node(-1).xyz() - self.get_node(0).xyz()).item()
+        return np.linalg.norm(self.node(-1).xyz() - self.node(0).xyz()).item()
 
     def tortuosity(self) -> float:
         """Tortuosity of path.

swcgeom/core/population.py

@@ -2,21 +2,25 @@
 
 import os
 import warnings
+from concurrent.futures import ProcessPoolExecutor
 from functools import reduce
 from typing import (
     Any,
+    Callable,
     Dict,
     Iterable,
     Iterator,
     List,
     Optional,
     Protocol,
+    TypeVar,
     cast,
     overload,
 )
 
 import numpy as np
 import numpy.typing as npt
+from tqdm.contrib.concurrent import process_map
 from typing_extensions import Self
 
 from swcgeom.core.swc import eswc_cols
@@ -25,6 +29,9 @@ from swcgeom.core.tree import Tree
 __all__ = ["LazyLoadingTrees", "ChainTrees", "Population", "Populations"]
 
 
+T = TypeVar("T")
+
+
 class Trees(Protocol):
     """Trees protocol support index and len."""
 
@@ -49,6 +56,7 @@ class LazyLoadingTrees:
         kwargs : Dict[str, Any]
             Forwarding to `Tree.from_swc`
         """
+
         super().__init__()
         self.swcs = list(swcs)
         self.trees = [None for _ in swcs]
@@ -62,6 +70,9 @@ class LazyLoadingTrees:
     def __len__(self) -> int:
         return len(self.swcs)
 
+    def __iter__(self) -> Iterator[Tree]:
+        return (self[i] for i in range(self.__len__()))
+
     def load(self, key: int) -> None:
         if self.trees[key] is None:
             self.trees[key] = Tree.from_swc(self.swcs[key], **self.kwargs)
@@ -93,6 +104,9 @@ class ChainTrees:
     def __len__(self) -> int:
         return self.cumsum[-1].item()
 
+    def __iter__(self) -> Iterator[Tree]:
+        return (self[i] for i in range(self.__len__()))
+
 
 class Population:
     """Neuron population."""
@@ -154,6 +168,31 @@ class Population:
     def __repr__(self) -> str:
         return f"Neuron population in '{self.root}'"
 
+    def map(
+        self,
+        fn: Callable[[Tree], T],
+        *,
+        max_worker: Optional[int] = None,
+        verbose: bool = False,
+    ) -> Iterator[T]:
+        """Map a function to all trees in the population.
+
+        This is a straightforward interface for parallelizing
+        computations. The parameters are intentionally kept simple and
+        user-friendly. For more advanced control, consider using
+        `concurrent.futures` directly.
+        """
+
+        trees = (t for t in self.trees)
+
+        if verbose:
+            results = process_map(fn, trees, max_workers=max_worker)
+        else:
+            with ProcessPoolExecutor(max_worker) as p:
+                results = p.map(fn, trees)
+
+        return results
+
     @classmethod
     def from_swc(cls, root: str, ext: str = ".swc", **kwargs) -> Self:
         if not os.path.exists(root):
@@ -162,7 +201,7 @@ class Population:
             )
 
         swcs = cls.find_swcs(root, ext)
-        return Population(LazyLoadingTrees(swcs, **kwargs), root=root)
+        return cls(LazyLoadingTrees(swcs, **kwargs), root=root)
 
     @classmethod
     def from_eswc(
@@ -236,7 +275,7 @@ class Populations:
         return Population(ChainTrees(p.trees for p in self.populations))
 
     @classmethod
-    def from_swc(  # pylint: disable=too-many-arguments
+    def from_swc(
         cls,
         roots: Iterable[str],
         ext: str = ".swc",
@@ -268,7 +307,7 @@ class Populations:
 
             fs = [inter for _ in roots]
         elif check_same:
-            assert reduce(lambda a, b: a == b, fs), "not the same among populations"
+            assert [fs[0] == a for a in fs[1:]], "not the same among populations"
 
         populations = [
             Population(

swcgeom/core/swc_utils/assembler.py

@@ -1,155 +1,37 @@
-"""Assemble lines to swc."""
+"""Assemble lines to swc.
 
-import warnings
-from copy import copy
-from typing import Iterable, List, Optional, Tuple
-
-import numpy as np
-import pandas as pd
-
-from swcgeom.core.swc_utils.base import SWCNames, get_names
-from swcgeom.core.swc_utils.normalizer import link_roots_to_nearest_, sort_nodes_
+Notes
+-----
+This module is deprecated, please use `~.transforms.LinesToTree`
+instead.
+"""
 
 __all__ = ["assemble_lines", "try_assemble_lines"]
 
 
-def assemble_lines(*args, **kwargs) -> pd.DataFrame:
-    """Assemble lines to a tree.
-
-    Assemble all the lines into a set of subtrees, and then connect
-    them.
+def assemble_lines(*args, **kwargs):
+    """Assemble lines to tree.
 
-    Parameters
-    ----------
-    lines : List of ~pd.DataFrame
-        An array of tables containing a line, columns should follwing
-        the swc.
-    **kwargs
-        Forwarding to `try_assemble_lines`
-
-    Returns
-    -------
-    tree : ~pd.DataFrame
-
-    See Also
-    --------
-    ~swcgeom.core.swc_utils.try_assemble_lines
+    .. deprecated:: 0.15.0
+        Use :meth:`~.transforms.LinesToTree` instead.
     """
-    warnings.warn(
+
+    raise DeprecationWarning(
         "`assemble_lines` has been replaced by "
         "`~.transforms.LinesToTree` because it can be easy assemble "
-        "with other tansformations, and this will be removed in next "
-        "version.",
-        DeprecationWarning,
+        "with other tansformations.",
     )
-    return assemble_lines_impl(*args, **kwargs)
 
 
-def try_assemble_lines(*args, **kwargs) -> Tuple[pd.DataFrame, List[pd.DataFrame]]:
-    """Trying assemble lines to a tree.
+def try_assemble_lines(*args, **kwargs):
+    """Try assemble lines to tree.
 
-    Treat the first line as a tree, find a line whose shortest distance
-    between the tree and the line is less than threshold, merge it into
-    the tree, repeat until there are no line to merge, return tree and
-    the remaining lines.
-
-    Parameters
-    ----------
-    lines : List of ~pd.DataFrame
-        An array of tables containing a line, columns should follwing
-        the swc.
-    undirected : bool, default `True`
-        Both ends of a line can be considered connection point. If
-        `False`, only the starting point.
-    thre : float, default `0.2`
-        Connection threshold.
-    id_offset : int, default `0`
-        The offset of the line node id.
-    sort_nodes : bool, default `True`
-        sort nodes of subtree
-    names : SWCNames, optional
-
-    Returns
-    -------
-    tree : ~pd.DataFrame
-    remaining_lines : List of ~pd.DataFrame
+    .. deprecated:: 0.15.0
+        Use :meth:`~.transforms.LinesToTree` instead.
     """
-    warnings.warn(
+
+    raise DeprecationWarning(
         "`try_assemble_lines` has been replaced by "
         "`~.transforms.LinesToTree` because it can be easy assemble "
-        "with other tansformations, and this will be removed in next "
-        "version.",
-        DeprecationWarning,
+        "with other tansformations.",
     )
-    return try_assemble_lines_impl(*args, **kwargs)
-
-
-# TODO: move the following codes to `transforms` module
-
-EPS = 1e-5
-
-
-def assemble_lines_impl(lines: Iterable[pd.DataFrame], **kwargs) -> pd.DataFrame:
-    tree, lines = try_assemble_lines_impl(lines, sort_nodes=False, **kwargs)
-    while len(lines) > 0:
-        t, lines = try_assemble_lines_impl(
-            lines, id_offset=len(tree), sort_nodes=False, **kwargs
-        )
-        tree = pd.concat([tree, t])
-
-    tree = tree.reset_index()
-    link_roots_to_nearest_(tree)
-    sort_nodes_(tree)
-    return tree
-
-
-def try_assemble_lines_impl(  # pylint: disable=too-many-arguments
-    lines: Iterable[pd.DataFrame],
-    undirected: bool = True,
-    thre: float = 0.2,
-    id_offset: int = 0,
-    sort_nodes: bool = True,
-    *,
-    names: Optional[SWCNames] = None,
-) -> Tuple[pd.DataFrame, List[pd.DataFrame]]:
-    names = get_names(names)
-    lines = copy(list(lines))
-
-    tree = lines[0]
-    tree[names.id] = id_offset + np.arange(len(tree))
-    tree[names.pid] = tree[names.id] - 1
-    tree.at[0, names.pid] = -1
-    del lines[0]
-
-    while True:
-        for i, line in enumerate(lines):
-            for p in [0, -1] if undirected else [0]:
-                xyz = [names.x, names.y, names.z]
-                vs = tree[xyz] - line.iloc[p][xyz]
-                dis = np.linalg.norm(vs, axis=1)
-                ind = np.argmin(dis)
-                if dis[ind] > thre:
-                    continue
-
-                if dis[ind] < EPS:
-                    line = line.drop((p + len(line)) % len(line)).reset_index(drop=True)
-
-                line[names.id] = id_offset + len(tree) + np.arange(len(line))
-                line[names.pid] = line[names.id] + (-1 if p == 0 else 1)
-                line.at[(p + len(line)) % len(line), names.pid] = tree.iloc[ind][
-                    names.id
-                ]
-                tree = pd.concat([tree, line])
-                del lines[i]
-                break
-            else:
-                continue
-
-            break
-        else:
-            break
-
-    if sort_nodes:
-        sort_nodes_(tree)
-
-    return tree, lines

swcgeom/core/swc_utils/base.py

@@ -1,7 +1,16 @@
 """Base SWC format utils."""
 
 from dataclasses import dataclass
-from typing import Callable, List, Literal, Optional, Tuple, TypeVar, overload
+from typing import (
+    Callable,
+    List,
+    Literal,
+    NamedTuple,
+    Optional,
+    Tuple,
+    TypeVar,
+    overload,
+)
 
 import numpy as np
 import numpy.typing as npt
@@ -23,8 +32,7 @@ T, K = TypeVar("T"), TypeVar("K")
 Topology = Tuple[npt.NDArray[np.int32], npt.NDArray[np.int32]]  # (id, pid)
 
 
-@dataclass
-class SWCNames:
+class SWCNames(NamedTuple):
     """SWC format column names."""
 
     id: str = "id"
@@ -46,8 +54,7 @@ def get_names(names: Optional[SWCNames] = None) -> SWCNames:
     return names or swc_names
 
 
-@dataclass
-class SWCTypes:
+class SWCTypes(NamedTuple):
     """SWC format types.
 
     See Also

swcgeom/core/swc_utils/checker.py

@@ -10,7 +10,6 @@ import pandas as pd
 from swcgeom.core.swc_utils.base import SWCNames, Topology, get_dsu, get_names, traverse
 from swcgeom.utils import DisjointSetUnion
 
-
 __all__ = [
     "is_single_root",
     "is_bifurcate",
@@ -83,6 +82,12 @@ def has_cyclic(topology: Topology) -> bool:
 
 
 def check_single_root(*args, **kwargs) -> bool:
+    """Check if the tree is single root.
+
+    .. deprecated:: 0.5.0
+        Use :meth:`is_single_root` instead.
+    """
+
     warnings.warn(
         "`check_single_root` has been renamed to `is_single_root` since"
         "v0.5.0, and will be removed in next version",
@@ -94,7 +99,12 @@ def check_single_root(*args, **kwargs) -> bool:
 def is_binary_tree(
     df: pd.DataFrame, exclude_root: bool = True, *, names: Optional[SWCNames] = None
 ) -> bool:
-    """Check is it a binary tree."""
+    """Check is it a binary tree.
+
+    .. deprecated:: 0.8.0
+        Use :meth:`is_bifurcate` instead.
+    """
+
     warnings.warn(
         "`is_binary_tree` has been replaced by to `is_bifurcate` since"
         "v0.8.0, and will be removed in next version",

swcgeom/core/swc_utils/subtree.py

@@ -27,8 +27,8 @@ def to_sub_topology(sub: Topology) -> Tuple[Topology, npt.NDArray[np.int32]]:
     Returns
     -------
     sub_topology : Topology
-    id_map : List of int
-        Map from new id to original id.
+    mapping : List of int
+        Map from new id to old id.
 
     See Also
     --------