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

swcgeom/__init__.py

@@ -1,6 +1,31 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 """A neuron geometry library for swc format."""
 
 from swcgeom import analysis, core, images, transforms
-from swcgeom._version import __version__, __version_tuple__
 from swcgeom.analysis import draw
 from swcgeom.core import BranchTree, Population, Populations, Tree
+
+__all__ = [
+    "analysis",
+    "core",
+    "images",
+    "transforms",
+    "draw",
+    "BranchTree",
+    "Population",
+    "Populations",
+    "Tree",
+]

swcgeom/analysis/__init__.py

@@ -1,10 +1,23 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """Analysis for neuron trees."""
 
-from swcgeom.analysis.branch_features import *
-from swcgeom.analysis.feature_extractor import *
-from swcgeom.analysis.node_features import *
-from swcgeom.analysis.path_features import *
-from swcgeom.analysis.sholl import *
-from swcgeom.analysis.trunk import *
-from swcgeom.analysis.visualization import *
-from swcgeom.analysis.volume import *
+from swcgeom.analysis.feature_extractor import *  # noqa: F403
+from swcgeom.analysis.features import *  # noqa: F403
+from swcgeom.analysis.sholl import *  # noqa: F403
+from swcgeom.analysis.trunk import *  # noqa: F403
+from swcgeom.analysis.visualization import *  # noqa: F403
+from swcgeom.analysis.volume import *  # noqa: F403

swcgeom/analysis/feature_extractor.py

@@ -1,3 +1,18 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """Easy way to compute and visualize common features for feature.
 
 Notes
@@ -7,23 +22,24 @@ naming specification.
 """
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 from functools import cached_property
 from itertools import chain
 from os.path import basename
-from typing import Any, Callable, Dict, List, Literal, Tuple, overload
+from typing import Any, Literal, overload
 
 import numpy as np
 import numpy.typing as npt
 import seaborn as sns
 from matplotlib.axes import Axes
 
-from swcgeom.analysis.branch_features import BranchFeatures
-from swcgeom.analysis.node_features import (
-    BifurcationFeatures,
+from swcgeom.analysis.features import (
+    BranchFeatures,
+    FurcationFeatures,
     NodeFeatures,
+    PathFeatures,
     TipFeatures,
 )
-from swcgeom.analysis.path_features import PathFeatures
 from swcgeom.analysis.sholl import Sholl
 from swcgeom.analysis.volume import get_volume
 from swcgeom.core import Population, Populations, Tree
@@ -39,6 +55,9 @@ Feature = Literal[
     "node_count",
     "node_radial_distance",
     "node_branch_order",
+    # furcation nodes
+    "furcation_count",
+    "furcation_radial_distance",
     # bifurcation nodes
     "bifurcation_count",
     "bifurcation_radial_distance",
@@ -54,9 +73,9 @@ Feature = Literal[
 ]
 
 NDArrayf32 = npt.NDArray[np.float32]
-FeatAndKwargs = Feature | Tuple[Feature, Dict[str, Any]]
+FeatAndKwargs = Feature | tuple[Feature, dict[str, Any]]
 
-Feature1D = set(["length", "volume", "node_count", "bifurcation_count", "tip_count"])
+Feature1D = set(["length", "volume", "node_count", "furcation_count", "tip_count"])
 
 
 class Features:
@@ -69,7 +88,7 @@ class Features:
     @cached_property
     def node_features(self) -> NodeFeatures: return NodeFeatures(self.tree)
     @cached_property
-    def bifurcation_features(self) -> BifurcationFeatures: return BifurcationFeatures(self.node_features)
+    def furcation_features(self) -> FurcationFeatures: return FurcationFeatures(self.node_features)
     @cached_property
     def tip_features(self) -> TipFeatures: return TipFeatures(self.node_features)
     @cached_property
@@ -121,9 +140,9 @@ class FeatureExtractor(ABC):
     @overload
     def get(self, feature: Feature, **kwargs) -> NDArrayf32: ...
     @overload
-    def get(self, feature: List[FeatAndKwargs]) -> List[NDArrayf32]: ...
+    def get(self, feature: list[FeatAndKwargs]) -> list[NDArrayf32]: ...
     @overload
-    def get(self, feature: Dict[Feature, Dict[str, Any]]) -> Dict[str, NDArrayf32]: ...
+    def get(self, feature: dict[Feature, dict[str, Any]]) -> dict[str, NDArrayf32]: ...
     # fmt:on
     def get(self, feature, **kwargs):
         """Get feature.
@@ -168,7 +187,7 @@ class FeatureExtractor(ABC):
 
     # Custom Plots
 
-    def plot_node_branch_order(self, feature_kwargs: Dict[str, Any], **kwargs) -> Axes:
+    def plot_node_branch_order(self, feature_kwargs: dict[str, Any], **kwargs) -> Axes:
         vals = self._get("node_branch_order", **feature_kwargs)
         bin_edges = np.arange(int(np.ceil(vals.max() + 1))) + 0.5
         return self._plot_histogram_impl(vals, bin_edges, **kwargs)
@@ -213,6 +232,12 @@ class FeatureExtractor(ABC):
     ) -> Axes:
         raise NotImplementedError()
 
+    def get_bifurcation_count(self, **kwargs):
+        raise DeprecationWarning("Use `furcation_count` instead.")
+
+    def get_bifurcation_radial_distance(self, **kwargs):
+        raise DeprecationWarning("Use `furcation_radial_distance` instead.")
+
 
 class TreeFeatureExtractor(FeatureExtractor):
     """Extract feature from tree."""
@@ -234,7 +259,7 @@ class TreeFeatureExtractor(FeatureExtractor):
 
     def plot_sholl(
         self,
-        feature_kwargs: Dict[str, Any],  # pylint: disable=unused-argument
+        feature_kwargs: dict[str, Any],  # pylint: disable=unused-argument
         **kwargs,
     ) -> Axes:
         _, ax = self._features.sholl.plot(**kwargs)
@@ -264,7 +289,7 @@ class PopulationFeatureExtractor(FeatureExtractor):
     """Extract features from population."""
 
     _population: Population
-    _features: List[Features]
+    _features: list[Features]
 
     def __init__(self, population: Population) -> None:
         super().__init__()
@@ -279,7 +304,7 @@ class PopulationFeatureExtractor(FeatureExtractor):
 
     # Custom Plots
 
-    def plot_sholl(self, feature_kwargs: Dict[str, Any], **kwargs) -> Axes:
+    def plot_sholl(self, feature_kwargs: dict[str, Any], **kwargs) -> Axes:
         vals, rs = self._get_sholl_impl(**feature_kwargs)
         ax = self._lineplot(xs=rs, ys=vals.flatten(), **kwargs)
         ax.set_ylabel("Count of Intersections")
@@ -295,7 +320,7 @@ class PopulationFeatureExtractor(FeatureExtractor):
 
     def _get_sholl_impl(
         self, steps: int = 20, **kwargs
-    ) -> Tuple[NDArrayf32, NDArrayf32]:
+    ) -> tuple[NDArrayf32, NDArrayf32]:
         rmax = max(t.sholl.rmax for t in self._features)
         rs = Sholl.get_rs(rmax=rmax, steps=steps)
         vals = self._get_impl("sholl", steps=rs, **kwargs)
@@ -333,7 +358,7 @@ class PopulationsFeatureExtractor(FeatureExtractor):
     """Extract feature from population."""
 
     _populations: Populations
-    _features: List[List[Features]]
+    _features: list[list[Features]]
 
     def __init__(self, populations: Populations) -> None:
         super().__init__()
@@ -348,7 +373,7 @@ class PopulationsFeatureExtractor(FeatureExtractor):
 
     # Custom Plots
 
-    def plot_sholl(self, feature_kwargs: Dict[str, Any], **kwargs) -> Axes:
+    def plot_sholl(self, feature_kwargs: dict[str, Any], **kwargs) -> Axes:
         vals, rs = self._get_sholl_impl(**feature_kwargs)
         ax = self._lineplot(xs=rs, ys=vals, **kwargs)
         ax.set_ylabel("Count of Intersections")
@@ -369,7 +394,7 @@ class PopulationsFeatureExtractor(FeatureExtractor):
 
     def _get_sholl_impl(
         self, steps: int = 20, **kwargs
-    ) -> Tuple[NDArrayf32, NDArrayf32]:
+    ) -> tuple[NDArrayf32, NDArrayf32]:
         rmaxs = chain.from_iterable((t.sholl.rmax for t in p) for p in self._features)
         rmax = max(rmaxs)
         rs = Sholl.get_rs(rmax=rmax, steps=steps)

swcgeom/analysis/features.py

@@ -0,0 +1,250 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+"""Feature anlysis of tree."""
+
+from abc import ABC, abstractmethod
+from functools import cached_property
+from typing import TypeVar
+
+import numpy as np
+import numpy.typing as npt
+from typing_extensions import Self, deprecated
+
+from swcgeom.core import Branch, BranchTree, Tree
+
+__all__ = [
+    "NodeFeatures",
+    "BifurcationFeatures",
+    "TipFeatures",
+    "PathFeatures",
+    "BranchFeatures",
+]
+
+T = TypeVar("T", bound=Branch)
+
+# Node Level
+
+
+class NodeFeatures:
+    """Evaluate node feature of tree."""
+
+    tree: Tree
+
+    @cached_property
+    def _branch_tree(self) -> BranchTree:
+        return BranchTree.from_tree(self.tree)
+
+    def __init__(self, tree: Tree) -> None:
+        self.tree = tree
+
+    def get_count(self) -> npt.NDArray[np.float32]:
+        """Get number of nodes.
+
+        Returns
+        -------
+        count : array of shape (1,)
+        """
+
+        return np.array([self.tree.number_of_nodes()], dtype=np.float32)
+
+    def get_radial_distance(self) -> npt.NDArray[np.float32]:
+        """Get the end-to-end straight-line distance to soma.
+
+        Returns
+        -------
+        radial_distance : npt.NDArray[np.float32]
+            Array of shape (N,).
+        """
+
+        xyz = self.tree.xyz() - self.tree.soma().xyz()
+        radial_distance = np.linalg.norm(xyz, axis=1)
+        return radial_distance
+
+    def get_branch_order(self) -> npt.NDArray[np.int32]:
+        """Get branch order of criticle nodes of tree.
+
+        Branch order is the number of bifurcations between current
+        position and the root.
+
+        Criticle node means that soma, bifucation nodes, tips.
+
+        Returns
+        -------
+        order : npt.NDArray[np.int32]
+            Array of shape (N,), which k is the number of branchs.
+        """
+
+        order = np.zeros_like(self._branch_tree.id(), dtype=np.int32)
+
+        def assign_depth(n: Tree.Node, pre_depth: int | None) -> int:
+            cur_order = pre_depth + 1 if pre_depth is not None else 0
+            order[n.id] = cur_order
+            return cur_order
+
+        self._branch_tree.traverse(enter=assign_depth)
+        return order
+
+
+class _SubsetNodesFeatures(ABC):
+    _features: NodeFeatures
+
+    @property
+    @abstractmethod
+    def nodes(self) -> npt.NDArray[np.bool_]:
+        raise NotImplementedError()
+
+    def __init__(self, features: NodeFeatures) -> None:
+        self._features = features
+
+    def get_count(self) -> npt.NDArray[np.float32]:
+        """Get number of nodes.
+
+        Returns
+        -------
+        count : npt.NDArray[np.float32]
+            Array of shape (1,).
+        """
+
+        return np.array([np.count_nonzero(self.nodes)], dtype=np.float32)
+
+    def get_radial_distance(self) -> npt.NDArray[np.float32]:
+        """Get the end-to-end straight-line distance to soma.
+
+        Returns
+        -------
+        radial_distance : npt.NDArray[np.float32]
+            Array of shape (N,).
+        """
+
+        return self._features.get_radial_distance()[self.nodes]
+
+    @classmethod
+    def from_tree(cls, tree: Tree) -> Self:
+        return cls(NodeFeatures(tree))
+
+
+class FurcationFeatures(_SubsetNodesFeatures):
+    """Evaluate furcation node feature of tree."""
+
+    @cached_property
+    def nodes(self) -> npt.NDArray[np.bool_]:
+        return np.array([n.is_furcation() for n in self._features.tree])
+
+
+@deprecated("Use FurcationFeatures instead")
+class BifurcationFeatures(FurcationFeatures):
+    """Evaluate bifurcation node feature of tree.
+
+    Notes
+    -----
+    Deprecated due to the wrong spelling of furcation. For now, it
+    is just an alias of `FurcationFeatures` and raise a warning. It
+    will be change to raise an error in the future.
+    """
+
+
+class TipFeatures(_SubsetNodesFeatures):
+    """Evaluate tip node feature of tree."""
+
+    @cached_property
+    def nodes(self) -> npt.NDArray[np.bool_]:
+        return np.array([n.is_tip() for n in self._features.tree])
+
+
+# Path Level
+
+
+class PathFeatures:
+    """Path analysis of tree."""
+
+    tree: Tree
+
+    def __init__(self, tree: Tree) -> None:
+        self.tree = tree
+
+    def get_count(self) -> int:
+        return len(self._paths)
+
+    def get_length(self) -> npt.NDArray[np.float32]:
+        """Get length of paths."""
+
+        length = [path.length() for path in self._paths]
+        return np.array(length, dtype=np.float32)
+
+    def get_tortuosity(self) -> npt.NDArray[np.float32]:
+        """Get tortuosity of path."""
+
+        return np.array([path.tortuosity() for path in self._paths], dtype=np.float32)
+
+    @cached_property
+    def _paths(self) -> list[Tree.Path]:
+        return self.tree.get_paths()
+
+
+class BranchFeatures:
+    """Analysis bransh of tree."""
+
+    tree: Tree
+
+    def __init__(self, tree: Tree) -> None:
+        self.tree = tree
+
+    def get_count(self) -> int:
+        return len(self._branches)
+
+    def get_length(self) -> npt.NDArray[np.float32]:
+        """Get length of branches."""
+
+        length = [br.length() for br in self._branches]
+        return np.array(length, dtype=np.float32)
+
+    def get_tortuosity(self) -> npt.NDArray[np.float32]:
+        """Get tortuosity of path."""
+
+        return np.array([br.tortuosity() for br in self._branches], dtype=np.float32)
+
+    def get_angle(self, eps: float = 1e-7) -> npt.NDArray[np.float32]:
+        """Get agnle between branches.
+
+        Returns
+        -------
+        angle : npt.NDArray[np.float32]
+            An array of shape (N, N), which N is length of branches.
+        """
+
+        return self.calc_angle(self._branches, eps=eps)
+
+    @staticmethod
+    def calc_angle(branches: list[T], eps: float = 1e-7) -> npt.NDArray[np.float32]:
+        """Calc agnle between branches.
+
+        Returns
+        -------
+        angle : npt.NDArray[np.float32]
+            An array of shape (N, N), which N is length of branches.
+        """
+
+        vector = np.array([br[-1].xyz() - br[0].xyz() for br in branches])
+        vector_dot = np.matmul(vector, vector.T)
+        vector_norm = np.linalg.norm(vector, ord=2, axis=1, keepdims=True)
+        vector_norm_dot = np.matmul(vector_norm, vector_norm.T) + eps
+        arccos = np.clip(vector_dot / vector_norm_dot, -1, 1)
+        angle = np.arccos(arccos)
+        return angle
+
+    @cached_property
+    def _branches(self) -> list[Tree.Branch]:
+        return self.tree.get_branches()

swcgeom/analysis/lmeasure.py

@@ -1,13 +1,26 @@
+# Copyright 2022-2025 Zexin Yuan
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
 """L-Measure analysis."""
 
 import math
-from typing import Literal, Tuple
+from typing import Literal
 
 import numpy as np
 import numpy.typing as npt
-
 from swcgeom.core import Branch, Compartment, Node, Tree
-from swcgeom.utils import angle
 
 __all__ = ["LMeasure"]
 
@@ -69,7 +82,7 @@ class LMeasure:
         --------
         L-Measure: http://cng.gmu.edu:8080/Lm/help/N_bifs.htm
         """
-        return len(tree.get_bifurcations())
+        return len(tree.get_furcations())
 
     def n_branch(self, tree: Tree) -> int:
         """Number of branches.
@@ -163,12 +176,15 @@ class LMeasure:
         --------
         L-Measure: http://cng.gmu.edu:8080/Lm/help/Partition_asymmetry.htm
         """
+
         children = n.children()
         assert (
             len(children) == 2
         ), "Partition asymmetry is only defined for bifurcations"
         n1 = len(children[0].subtree().get_tips())
         n2 = len(children[1].subtree().get_tips())
+        if n1 == n2:
+            return 0
         return abs(n1 - n2) / (n1 + n2 - 2)
 
     def fractal_dim(self):
@@ -274,7 +290,7 @@ class LMeasure:
         rall_power, _, _, _ = self._rall_power(bif)
         return rall_power
 
-    def _rall_power_d(self, bif: Tree.Node) -> Tuple[float, float, float]:
+    def _rall_power_d(self, bif: Tree.Node) -> tuple[float, float, float]:
         children = bif.children()
         assert len(children) == 2, "Rall Power is only defined for bifurcations"
         parent = bif.parent()
@@ -284,7 +300,7 @@ class LMeasure:
         da, db = 2 * children[0].r, 2 * children[1].r
         return dp, da, db
 
-    def _rall_power(self, bif: Tree.Node) -> Tuple[float, float, float, float]:
+    def _rall_power(self, bif: Tree.Node) -> tuple[float, float, float, float]:
         dp, da, db = self._rall_power_d(bif)
         start, stop, step = 0, 5, 5 / 1000
         xs = np.arange(start, stop, step)
@@ -336,7 +352,7 @@ class LMeasure:
         return (da**rall_power + db**rall_power) / dp**rall_power
 
     def bif_ampl_local(self, bif: Tree.Node) -> float:
-        """Bifuraction angle.
+        """Bifurcation angle.
 
         Given a bifurcation, this function returns the angle between
         the first two compartments (in degree).
@@ -350,7 +366,7 @@ class LMeasure:
         return np.degrees(angle(v1, v2))
 
     def bif_ampl_remote(self, bif: Tree.Node) -> float:
-        """Bifuraction angle.
+        """Bifurcation angle.
 
         This function returns the angle between two bifurcation points
         or between bifurcation point and terminal point or between two
@@ -361,7 +377,7 @@ class LMeasure:
         L-Measure: http://cng.gmu.edu:8080/Lm/help/Bif_ampl_remote.htm
         """
 
-        v1, v2 = self._bif_vector_local(bif)
+        v1, v2 = self._bif_vector_remote(bif)
         return np.degrees(angle(v1, v2))
 
     def bif_tilt_local(self, bif: Tree.Node) -> float:
@@ -501,7 +517,7 @@ class LMeasure:
 
     def _bif_vector_local(
         self, bif: Tree.Node
-    ) -> Tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
+    ) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
         children = bif.children()
         assert len(children) == 2, "Only defined for bifurcations"
 
@@ -511,7 +527,7 @@ class LMeasure:
 
     def _bif_vector_remote(
         self, bif: Tree.Node
-    ) -> Tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
+    ) -> tuple[npt.NDArray[np.float32], npt.NDArray[np.float32]]:
         children = bif.children()
         assert len(children) == 2, "Only defined for bifurcations"
 
@@ -665,7 +681,7 @@ class LMeasure:
         n = node
         order = 0
         while n is not None:
-            if n.is_bifurcation():
+            if n.is_furcation():
                 order += 1
             n = n.parent()
         return order
@@ -819,3 +835,23 @@ def pill_surface_area(ra: float, rb: float, h: float) -> float:
     bottom_hemisphere_area = 2 * math.pi * rb**2
     total_area = lateral_area + top_hemisphere_area + bottom_hemisphere_area
     return total_area
+
+
+# TODO: move to `utils`
+def angle(a: npt.ArrayLike, b: npt.ArrayLike) -> float:
+    """Get the angle of vectors.
+
+    Returns
+    -------
+    angle : float
+        Angle [0, PI) in radians.
+    """
+
+    a, b = np.array(a), np.array(b)
+    if np.linalg.norm(a) == 0 or np.linalg.norm(b) == 0:
+        raise ValueError("Input vectors must not be zero vectors.")
+
+    costheta = np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
+    costheta = np.clip(costheta, -1, 1)  # avoid numerical errors
+    theta = np.arccos(costheta)
+    return theta