swcgeom 0.16.0__tar.gz → 0.18.3__tar.gz

{swcgeom-0.16.0 → swcgeom-0.18.3}/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [2024] [Zexin Yuan]
+   Copyright [yyyy] [name of copyright owner]
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

{swcgeom-0.16.0/swcgeom.egg-info → swcgeom-0.18.3}/PKG-INFO

@@ -1,8 +1,8 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: swcgeom
-Version: 0.16.0
+Version: 0.18.3
 Summary: Neuron geometry library for swc format
-Author-email: yzx9 <yuan.zx@outlook.com>
+Author-email: yzx9 <pypi@yzx9.xyz>
 License: Apache-2.0
 Project-URL: repository, https://github.com/yzx9/swcgeom
 Keywords: neuronscience,neuron,neuroanatomy,neuron-morphology
@@ -13,14 +13,14 @@ Requires-Dist: imagecodecs>=2023.3.16
 Requires-Dist: matplotlib>=3.5.2
 Requires-Dist: numpy>=1.22.3
 Requires-Dist: pandas>=1.4.2
-Requires-Dist: pynrrd>=1.0.0
+Requires-Dist: pynrrd>=1.1.0
 Requires-Dist: scipy>=1.9.1
 Requires-Dist: sdflit>=0.2.1
 Requires-Dist: seaborn>=0.12.0
 Requires-Dist: tifffile>=2022.8.12
 Requires-Dist: typing_extensions>=4.4.0
 Requires-Dist: tqdm>=4.46.1
-Requires-Dist: v3d-py-helper>=0.1.0
+Requires-Dist: v3d-py-helper>=0.4.1
 Provides-Extra: all
 Requires-Dist: beautifulsoup4>=4.11.1; extra == "all"
 Requires-Dist: certifi>=2023.5.7; extra == "all"
@@ -56,16 +56,20 @@ pip install build
 pip install --editable .
 ```
 
-Static analysis don't support import hook used in editable install for [PEP660](https://peps.python.org/pep-0660/) since upgrade to setuptools v64+, detail infomation at [setuptools#3518](https://github.com/pypa/setuptools/issues/3518), a workaround for vscode with pylance:
+Static analysis don't support import hook used in editable install for
+[PEP660](https://peps.python.org/pep-0660/) since upgrade to setuptools v64+,
+detail information at [setuptools#3518](https://github.com/pypa/setuptools/issues/3518),
+a workaround for vscode with pylance:
 
 ```json
 {
-    "python.analysis.extraPaths": ["/path/to/this/project"]
+  "python.analysis.extraPaths": ["/path/to/this/project"]
 }
 ```
 
 ## LICENSE
 
-This work is licensed under a <a rel="license" href="https://www.apache.org/licenses/">Apache-2.0</a>.
+This work is licensed under a
+<a rel="license" href="https://www.apache.org/licenses/">Apache-2.0</a>.
 
 Copyright (c) 2022-present, Zexin Yuan

{swcgeom-0.16.0 → swcgeom-0.18.3}/README.md

@@ -25,16 +25,20 @@ pip install build
 pip install --editable .
 ```
 
-Static analysis don't support import hook used in editable install for [PEP660](https://peps.python.org/pep-0660/) since upgrade to setuptools v64+, detail infomation at [setuptools#3518](https://github.com/pypa/setuptools/issues/3518), a workaround for vscode with pylance:
+Static analysis don't support import hook used in editable install for
+[PEP660](https://peps.python.org/pep-0660/) since upgrade to setuptools v64+,
+detail information at [setuptools#3518](https://github.com/pypa/setuptools/issues/3518),
+a workaround for vscode with pylance:
 
 ```json
 {
-    "python.analysis.extraPaths": ["/path/to/this/project"]
+  "python.analysis.extraPaths": ["/path/to/this/project"]
 }
 ```
 
 ## LICENSE
 
-This work is licensed under a <a rel="license" href="https://www.apache.org/licenses/">Apache-2.0</a>.
+This work is licensed under a
+<a rel="license" href="https://www.apache.org/licenses/">Apache-2.0</a>.
 
 Copyright (c) 2022-present, Zexin Yuan

{swcgeom-0.16.0 → swcgeom-0.18.3}/pyproject.toml

@@ -1,14 +1,10 @@
-[build-system]
-requires = ["setuptools>=64", "setuptools_scm[toml]>=6.2"]
-build-backend = "setuptools.build_meta"
-
 [project]
 name = "swcgeom"
-dynamic = ["version"]
+version = "0.18.3"
 description = "Neuron geometry library for swc format"
 readme = "README.md"
 requires-python = ">=3.10"
-authors = [{ name = "yzx9", email = "yuan.zx@outlook.com" }]
+authors = [{ name = "yzx9", email = "pypi@yzx9.xyz" }]
 keywords = ["neuronscience", "neuron", "neuroanatomy", "neuron-morphology"]
 license = { text = "Apache-2.0" }
 dependencies = [
@@ -16,14 +12,14 @@ dependencies = [
     "matplotlib>=3.5.2",
     "numpy>=1.22.3",
     "pandas>=1.4.2",
-    "pynrrd>=1.0.0",
+    "pynrrd>=1.1.0",
     "scipy>=1.9.1",
     "sdflit>=0.2.1",
     "seaborn>=0.12.0",
     "tifffile>=2022.8.12",
     "typing_extensions>=4.4.0",
     "tqdm>=4.46.1",
-    "v3d-py-helper>=0.1.0",
+    "v3d-py-helper>=0.4.1",
 ]
 
 [project.optional-dependencies]
@@ -38,6 +34,3 @@ all = [
 
 [project.urls]
 repository = "https://github.com/yzx9/swcgeom"
-
-[tool.setuptools_scm]
-write_to = "swcgeom/_version.py"

swcgeom-0.18.3/swcgeom/__init__.py

@@ -0,0 +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.analysis import draw
+from swcgeom.core import BranchTree, Population, Populations, Tree
+
+__all__ = [
+    "analysis",
+    "core",
+    "images",
+    "transforms",
+    "draw",
+    "BranchTree",
+    "Population",
+    "Populations",
+    "Tree",
+]

swcgeom-0.18.3/swcgeom/analysis/__init__.py

@@ -0,0 +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.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-0.16.0 → swcgeom-0.18.3}/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-0.18.3/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()