swcgeom 0.17.1__py3-none-any.whl → 0.18.1__py3-none-any.whl

swcgeom/__init__.py

@@ -1,3 +1,17 @@
+# 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

swcgeom/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.17.1'
-__version_tuple__ = version_tuple = (0, 17, 1)
+__version__ = version = '0.18.1'
+__version_tuple__ = version_tuple = (0, 18, 1)

swcgeom/analysis/__init__.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.
+
+
 """Analysis for neuron trees."""
 
 from swcgeom.analysis.feature_extractor import *

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
@@ -19,8 +34,8 @@ import seaborn as sns
 from matplotlib.axes import Axes
 
 from swcgeom.analysis.features import (
-    BifurcationFeatures,
     BranchFeatures,
+    FurcationFeatures,
     NodeFeatures,
     PathFeatures,
     TipFeatures,
@@ -40,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",
@@ -57,7 +75,7 @@ Feature = Literal[
 NDArrayf32 = npt.NDArray[np.float32]
 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:
@@ -70,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
@@ -214,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."""

swcgeom/analysis/features.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.
+
+
 """Feature anlysis of tree."""
 
 from abc import ABC, abstractmethod
@@ -6,7 +21,7 @@ from typing import TypeVar
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 from swcgeom.core import Branch, BranchTree, Tree
 
@@ -121,12 +136,24 @@ class _SubsetNodesFeatures(ABC):
         return cls(NodeFeatures(tree))
 
 
-class BifurcationFeatures(_SubsetNodesFeatures):
-    """Evaluate bifurcation node feature of tree."""
+class FurcationFeatures(_SubsetNodesFeatures):
+    """Evaluate furcation node feature of tree."""
 
     @cached_property
     def nodes(self) -> npt.NDArray[np.bool_]:
-        return np.array([n.is_bifurcation() for n in self._features.tree])
+        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):

swcgeom/analysis/lmeasure.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.
+
+
 """L-Measure analysis."""
 
 import math
@@ -5,9 +20,7 @@ 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):
@@ -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:
@@ -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

swcgeom/analysis/sholl.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.
+
+
 """Sholl analysis."""
 
 import warnings
@@ -8,6 +23,7 @@ import numpy.typing as npt
 import seaborn as sns
 from matplotlib.axes import Axes
 from matplotlib.figure import Figure
+from typing_extensions import deprecated
 
 from swcgeom.analysis.visualization import draw
 from swcgeom.core import Tree
@@ -160,20 +176,17 @@ class Sholl:
 
         return self.get_rs(self.rmax, steps)
 
+    @deprecated("Use `Sholl.get(x)` instead")
     def get_count(self) -> npt.NDArray[np.int32]:
         """Get the count of intersection.
 
         .. deprecated:: 0.5.0
-            Use :meth:`Sholl.get` instead.
+            Use :meth:`Sholl(x).get()` instead.
         """
 
-        warnings.warn(
-            "`Sholl.get_count` has been renamed to `get` since v0.5.0, "
-            "and will be removed in next version",
-            DeprecationWarning,
-        )
         return self.get().astype(np.int32)
 
+    @deprecated("Use `Shool(x).get().mean()` instead")
     def avg(self) -> float:
         """Get the average of the count of intersection.
 
@@ -181,14 +194,9 @@ class Sholl:
             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()` "
-            "instead",
-            DeprecationWarning,
-        )
         return self.get().mean()
 
+    @deprecated("Use `Shool(x).get().std()` instead")
     def std(self) -> float:
         """Get the std of the count of intersection.
 
@@ -196,14 +204,9 @@ class Sholl:
             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()` "
-            "instead",
-            DeprecationWarning,
-        )
         return self.get().std()
 
+    @deprecated("Use `Shool(x).get().sum()` instead")
     def sum(self) -> int:
         """Get the sum of the count of intersection.
 
@@ -211,10 +214,4 @@ class Sholl:
             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()` "
-            "instead",
-            DeprecationWarning,
-        )
         return self.get().sum()

swcgeom/analysis/trunk.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.
+
+
 """Plot trunk and florets."""
 
 # pylint: disable=invalid-name

swcgeom/analysis/visualization.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.
+
+
 """Painter utils."""
 
 import os

swcgeom/analysis/visualization3d.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.
+
+
 """Painter utils.
 
 Notes

swcgeom/analysis/volume.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.
+
+
 """Analysis of volume of a SWC tree."""
 
 from typing import Literal

swcgeom/core/__init__.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.
+
+
 """Neuron trees."""
 
 from swcgeom.core import swc_utils

swcgeom/core/branch.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.
+
+
 """Branch is a set of node points."""
 
 from collections.abc import Iterable

swcgeom/core/branch_tree.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.
+
+
 """Branch tree is a simplified neuron tree."""
 
 import itertools

swcgeom/core/compartment.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.
+
+
 """The segment is a branch with two nodes."""
 
 from collections.abc import Iterable

swcgeom/core/node.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.
+
+
 """Nueron node."""
 
 from collections.abc import Iterable
@@ -5,6 +20,7 @@ from typing import Any, Generic
 
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import deprecated
 
 from swcgeom.core.swc import DictSWC, SWCTypeVar
 from swcgeom.core.swc_utils import SWCNames
@@ -95,9 +111,22 @@ class Node(Generic[SWCTypeVar]):
         items = [self.id, self.type, x, y, z, r, self.pid]
         return " ".join(map(str, items))
 
-    def is_bifurcation(self) -> bool:
+    def is_furcation(self) -> bool:
+        """Is furcation node."""
         return np.count_nonzero(self.attach.pid() == self.id) > 1
 
+    @deprecated("Use is_furcation instead")
+    def is_bifurcation(self) -> bool:
+        """Is furcation node.
+
+        Notes
+        -----
+        Deprecated due to the wrong spelling of furcation. For now, it
+        is just an alias of `is_furcation` and raise a warning. It will
+        be change to raise an error in the future.
+        """
+        return self.is_furcation()
+
     def is_tip(self) -> bool:
         return self.id not in self.attach.pid()
 

swcgeom/core/path.py

@@ -1,11 +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.
+
+
 """Nueron path."""
 
-import warnings
 from collections.abc import Iterable, Iterator
 from typing import Generic, overload
 
 import numpy as np
 import numpy.typing as npt
+from typing_extensions import deprecated
 
 from swcgeom.core.node import Node
 from swcgeom.core.swc import DictSWC, SWCLike, SWCTypeVar
@@ -16,7 +31,7 @@ __all__ = ["Path"]
 class Path(SWCLike, Generic[SWCTypeVar]):
     """Neuron path.
 
-    A path is a linear set of points without bifurcations.
+    A path is a linear set of points without furcations.
     """
 
     attach: SWCTypeVar
@@ -75,6 +90,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
     def get_ndata(self, key: str) -> npt.NDArray:
         return self.attach.get_ndata(key)[self.idx]
 
+    @deprecated("Use `path.node` instead.")
     def get_node(self, idx: int | np.integer) -> Node:
         """Get the count of intersection.
 
@@ -82,11 +98,6 @@ class Path(SWCLike, Generic[SWCTypeVar]):
             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: