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

swcgeom/analysis/sholl.py

@@ -1,13 +1,29 @@
+# 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
-from typing import List, Literal, Optional, Tuple
+from typing import Literal, Optional
 
 import numpy as np
 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
@@ -23,10 +39,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
@@ -79,18 +100,18 @@ class Sholl:
 
     def plot(  # pylint: disable=too-many-arguments
         self,
-        steps: List[float] | int = 20,
+        steps: list[float] | int = 20,
         plot_type: str | None = None,
         kind: Literal["bar", "linechart", "circles"] = "circles",
         fig: Figure | None = None,
         ax: Axes | None = None,
         **kwargs,
-    ) -> Tuple[Figure, Axes]:
+    ) -> tuple[Figure, Axes]:
         """Plot Sholl analysis.
 
         Parameters
         ----------
-        steps : int or List[float], default to 20
+        steps : int or list[float], default to 20
             Steps of raius of circle. If steps is int, then it will be
             evenly divided into n radii.
         kind : "bar" | "linechart" | "circles", default `circles`
@@ -155,37 +176,42 @@ class Sholl:
 
         return self.get_rs(self.rmax, steps)
 
+    @deprecated("Use `Sholl.get(x)` instead")
     def get_count(self) -> npt.NDArray[np.int32]:
-        warnings.warn(
-            "`Sholl.get_count` has been renamed to `get` since v0.5.0, "
-            "and will be removed in next version",
-            DeprecationWarning,
-        )
+        """Get the count of intersection.
+
+        .. deprecated:: 0.5.0
+            Use :meth:`Sholl(x).get()` instead.
+        """
+
         return self.get().astype(np.int32)
 
+    @deprecated("Use `Shool(x).get().mean()` instead")
     def avg(self) -> float:
-        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,
-        )
+        """Get the average of the count of intersection.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`Shool(x).get().mean()` instead.
+        """
+
         return self.get().mean()
 
+    @deprecated("Use `Shool(x).get().std()` instead")
     def std(self) -> float:
-        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,
-        )
+        """Get the std of the count of intersection.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`Shool(x).get().std()` instead.
+        """
+
         return self.get().std()
 
+    @deprecated("Use `Shool(x).get().sum()` instead")
     def sum(self) -> int:
-        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,
-        )
+        """Get the sum of the count of intersection.
+
+        .. deprecated:: 0.6.0
+            Use :meth:`Shool(x).get().sum()` instead.
+        """
+
         return self.get().sum()

swcgeom/analysis/trunk.py

@@ -1,9 +1,25 @@
+# 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
 
+from collections.abc import Iterable
 from itertools import chain
-from typing import Any, Dict, Iterable, List, Literal, Optional, Tuple, cast
+from typing import Any, Literal, Optional, cast
 
 import numpy as np
 import numpy.typing as npt
@@ -28,28 +44,28 @@ def draw_trunk(
     *,
     fig: Optional[Figure] = None,
     ax: Optional[Axes] = None,
-    bound: Bounds | Tuple[Bounds, Dict[str, Any]] | None = "ellipse",
-    point: bool | Dict[str, Any] = True,
+    bound: Bounds | tuple[Bounds, dict[str, Any]] | None = "ellipse",
+    point: bool | dict[str, Any] = True,
     projection: Projection = "2d",
     cmap: Any = "viridis",
     **kwargs,
-) -> Tuple[Figure, Axes]:
+) -> tuple[Figure, Axes]:
     """Draw trunk tree.
 
     Parameters
     ----------
     t : Tree
-    florets : List of (int | List of int)
+    florets : List of (int | list of int)
         The florets that needs to be removed, each floret can be a
         subtree or multiple subtrees (e.g., dendrites are a bunch of
         subtrees), each number is the id of a tree node.
     fig : ~matplotlib.figure.Figure, optional
     ax : ~matplotlib.axes.Axes, optional
-    bound : Bounds | (Bounds, Dict[str, Any]) | None, default 'ellipse'
+    bound : Bounds | (Bounds, dict[str, Any]) | None, default 'ellipse'
         Kind of bound, support 'aabb', 'ellipse'. If bound is None, no
         bound will be drawn. If bound is a tuple, the second item will
         used as kwargs and forward to draw function.
-    point : bool | Dict[str, Any], default True
+    point : bool | dict[str, Any], default True
         Draw point at the start of a subtree. If point is False, no
         point will be drawn. If point is a dict, this will used a
         kwargs and forward to draw function.
@@ -57,7 +73,7 @@ def draw_trunk(
         Colormap, any value supported by ~matplotlib.cm.Colormap. We
         will use the ratio of the length of the subtree to the total
         length of the tree to determine the color.
-    **kwargs : Dict[str, Any]
+    **kwargs : dict[str, Any]
         Forward to ~swcgeom.analysis.draw.
     """
     # pylint: disable=too-many-locals
@@ -83,14 +99,14 @@ def draw_trunk(
 
 def split_florets(
     t: Tree, florets: Iterable[int | Iterable[int]]
-) -> Tuple[Tree, List[List[Tree]]]:
+) -> tuple[Tree, list[list[Tree]]]:
     florets = [[i] if isinstance(i, (int, np.integer)) else i for i in florets]
     subtrees = [[get_subtree(t, ff) for ff in f] for f in florets]
     trunk = to_subtree(t, chain(*florets))
     return trunk, subtrees
 
 
-def get_length_ratio(t: Tree, tss: List[List[Tree]]) -> Any:
+def get_length_ratio(t: Tree, tss: list[list[Tree]]) -> Any:
     lens = np.array([sum(t.length() for t in ts) for ts in tss])
     return lens / t.length()
 
@@ -101,7 +117,7 @@ def get_length_ratio(t: Tree, tss: List[List[Tree]]) -> Any:
 def draw_bound(
     ts: Iterable[Tree],
     ax: Axes,
-    bound: Bounds | Tuple[Bounds, Dict[str, Any]],
+    bound: Bounds | tuple[Bounds, dict[str, Any]],
     projection: Projection,
     **kwargs,
 ) -> None:

swcgeom/analysis/visualization.py

@@ -1,8 +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.
+
+
 """Painter utils."""
 
 import os
 import weakref
-from typing import Any, Dict, List, Literal, Optional, Tuple
+from typing import Any, Literal, Optional
 
 import numpy as np
 from matplotlib.axes import Axes
@@ -21,15 +36,15 @@ from swcgeom.utils import (
 
 __all__ = ["draw"]
 
-Positions = Literal["lt", "lb", "rt", "rb"] | Tuple[float, float]
-locations: Dict[Literal["lt", "lb", "rt", "rb"], Tuple[float, float]] = {
+Positions = Literal["lt", "lb", "rt", "rb"] | tuple[float, float]
+locations: dict[Literal["lt", "lb", "rt", "rb"], tuple[float, float]] = {
     "lt": (0.10, 0.90),
     "lb": (0.10, 0.10),
     "rt": (0.90, 0.90),
     "rb": (0.90, 0.10),
 }
 
-ax_weak_memo = weakref.WeakKeyDictionary[Axes, Dict[str, Any]]({})
+ax_weak_memo = weakref.WeakKeyDictionary[Axes, dict[str, Any]]({})
 
 
 def draw(
@@ -39,7 +54,7 @@ def draw(
     ax: Optional[Axes] = None,
     show: bool | None = None,
     camera: CameraOptions = "xy",
-    color: Optional[Dict[int, str] | str] = None,
+    color: Optional[dict[int, str] | str] = None,
     label: str | bool = True,
     direction_indicator: Positions | Literal[False] = "rb",
     unit: Optional[str] = None,
@@ -64,7 +79,7 @@ def draw(
         vector, then then threat it as (look-at, up), so camera is
         ((0, 0, 0), look-at, up). An easy way is to use the presets
         "xy", "yz" and "zx".
-    color : Dict[int, str] | "vaa3d" | str, optional
+    color : dict[int, str] | "vaa3d" | str, optional
         Color map. If is dict, segments will be colored by the type of
         parent node.If is string, the value will be use for any type.
     label : str | bool, default True
@@ -120,14 +135,14 @@ def draw(
     return fig, ax
 
 
-def get_ax_swc(ax: Axes) -> List[SWCLike]:
+def get_ax_swc(ax: Axes) -> list[SWCLike]:
     ax_weak_memo.setdefault(ax, {})
     return ax_weak_memo[ax]["swc"]
 
 
 def get_ax_color(
-    ax: Axes, swc: SWCLike, color: Optional[Dict[int, str] | str] = None
-) -> str | List[str]:
+    ax: Axes, swc: SWCLike, color: Optional[dict[int, str] | str] = None
+) -> str | list[str]:
     if color == "vaa3d":
         color = palette.vaa3d
     elif isinstance(color, str):

swcgeom/analysis/visualization3d.py

@@ -0,0 +1,100 @@
+# 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
+-----
+This is a experimental function, it may be changed in the future.
+"""
+
+from typing import Optional
+
+import numpy as np
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+from mpl_toolkits.mplot3d import Axes3D
+
+from swcgeom.analysis.visualization import (
+    _set_ax_memo,
+    get_ax_color,
+    get_ax_swc,
+    set_ax_legend,
+)
+from swcgeom.core import SWCLike, Tree
+from swcgeom.utils.plotter_3d import draw_lines_3d
+
+__all__ = ["draw3d"]
+
+
+# TODO: support Camera
+def draw3d(
+    swc: SWCLike | str,
+    *,
+    ax: Axes,
+    show: bool | None = None,
+    color: Optional[dict[int, str] | str] = None,
+    label: str | bool = True,
+    **kwargs,
+) -> tuple[Figure, Axes]:
+    r"""Draw neuron tree.
+
+    Parameters
+    ----------
+    swc : SWCLike | str
+        If it is str, then it is treated as the path of swc file.
+    fig : ~matplotlib.axes.Figure, optional
+    ax : ~matplotlib.axes.Axes, optional
+    show : bool | None, default `None`
+        Wheather to call `plt.show()`. If not specified, it will depend
+        on if ax is passed in, it will not be called, otherwise it will
+        be called by default.
+    color : dict[int, str] | "vaa3d" | str, optional
+        Color map. If is dict, segments will be colored by the type of
+        parent node.If is string, the value will be use for any type.
+    label : str | bool, default True
+        Label of legend, disable if False.
+    **kwargs : dict[str, Unknown]
+        Forwarded to `~mpl_toolkits.mplot3d.art3d.Line3DCollection`.
+    """
+
+    assert isinstance(ax, Axes3D), "only support 3D axes."
+
+    swc = Tree.from_swc(swc) if isinstance(swc, str) else swc
+
+    show = (show is True) or (show is None and ax is None)
+    my_color = get_ax_color(ax, swc, color)  # type: ignore
+
+    xyz = swc.xyz()
+    starts, ends = swc.id()[1:], swc.pid()[1:]
+    lines = np.stack([xyz[starts], xyz[ends]], axis=1)
+    collection = draw_lines_3d(ax, lines, color=my_color, **kwargs)
+
+    min_vals = lines.reshape(-1, 3).min(axis=0)
+    max_vals = lines.reshape(-1, 3).max(axis=0)
+    ax.set_xlim(min_vals[0], max_vals[0])
+    ax.set_ylim(min_vals[1], max_vals[1])
+    ax.set_zlim(min_vals[2], max_vals[2])
+
+    _set_ax_memo(ax, swc, label=label, handle=collection)
+
+    if len(get_ax_swc(ax)) == 1:
+        # ax.set_aspect(1)
+        ax.spines[["top", "right"]].set_visible(False)
+    else:
+        set_ax_legend(ax, loc="upper right")  # enable legend
+
+    fig = ax.figure
+    return fig, ax  # type: ignore

swcgeom/analysis/volume.py

@@ -1,6 +1,21 @@
+# 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 Dict, List, Literal
+from typing import Literal
 
 import numpy as np
 from sdflit import ColoredMaterial, ObjectsScene, SDFObject, UniformSampler
@@ -11,7 +26,7 @@ from swcgeom.utils import VolFrustumCone, VolSphere
 __all__ = ["get_volume"]
 
 ACCURACY_LEVEL = Literal["low", "middle", "high"]
-ACCURACY_LEVELS: Dict[ACCURACY_LEVEL, int] = {"low": 3, "middle": 5, "high": 8}
+ACCURACY_LEVELS: dict[ACCURACY_LEVEL, int] = {"low": 3, "middle": 5, "high": 8}
 
 
 def get_volume(
@@ -93,7 +108,7 @@ def _get_volume_frustum_cone(tree: Tree, *, accuracy: int) -> float:
 
     volume = 0.0
 
-    def leave(n: Tree.Node, children: List[VolSphere]) -> VolSphere:
+    def leave(n: Tree.Node, children: list[VolSphere]) -> VolSphere:
         sphere = VolSphere(n.xyz(), n.r)
         cones = [VolFrustumCone(n.xyz(), n.r, c.center, c.radius) for c in children]
 
@@ -129,7 +144,7 @@ def _get_volume_frustum_cone_mc_only(tree: Tree) -> float:
     scene = ObjectsScene()
     scene.set_background((0, 0, 0))
 
-    def leave(n: Tree.Node, children: List[VolSphere]) -> VolSphere:
+    def leave(n: Tree.Node, children: list[VolSphere]) -> VolSphere:
         sphere = VolSphere(n.xyz(), n.r)
         scene.add_object(SDFObject(sphere.sdf, material).into())
 

swcgeom/core/__init__.py

@@ -1,11 +1,34 @@
+# 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
-from swcgeom.core.branch import *
-from swcgeom.core.branch_tree import *
-from swcgeom.core.node import *
-from swcgeom.core.path import *
-from swcgeom.core.population import *
-from swcgeom.core.swc import *
-from swcgeom.core.tree import *
-from swcgeom.core.tree_utils import *
+from swcgeom.core import swc_utils as swc_utils
+from swcgeom.core.branch import *  # noqa: F403
+from swcgeom.core.branch_tree import *  # noqa: F403
+
+# Segment and Segments don't expose
+from swcgeom.core.compartment import (
+    Compartment as Compartment,
+)
+from swcgeom.core.compartment import (
+    Compartments as Compartments,
+)
+from swcgeom.core.node import *  # noqa: F403
+from swcgeom.core.path import *  # noqa: F403
+from swcgeom.core.population import *  # noqa: F403
+from swcgeom.core.swc import *  # noqa: F403
+from swcgeom.core.tree import *  # noqa: F403
+from swcgeom.core.tree_utils import *  # noqa: F403

swcgeom/core/branch.py

@@ -1,12 +1,28 @@
+# 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 typing import Generic, Iterable, List
+from collections.abc import Iterable
+from typing import Generic
 
 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 +40,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 +54,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."""
@@ -87,7 +108,7 @@ class Branch(Path, Generic[SWCTypeVar]):
     @classmethod
     def from_xyzr_batch(
         cls, xyzr_batch: npt.NDArray[np.float32]
-    ) -> List["Branch[DictSWC]"]:
+    ) -> list["Branch[DictSWC]"]:
         r"""Create list of branch form ~numpy.ndarray.
 
         Parameters
@@ -107,7 +128,7 @@ class Branch(Path, Generic[SWCTypeVar]):
             )
             xyzr_batch = np.concatenate([xyzr_batch, ones], axis=2)
 
-        branches: List[Branch[DictSWC]] = []
+        branches: list[Branch[DictSWC]] = []
         for xyzr in xyzr_batch:
             n_nodes = xyzr.shape[0]
             idx = np.arange(0, n_nodes, step=1, dtype=np.int32)

swcgeom/core/branch_tree.py

@@ -1,7 +1,21 @@
+# 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
-from typing import Dict, List
 
 import numpy as np
 import pandas as pd
@@ -19,13 +33,13 @@ class BranchTree(Tree):
     A branch tree that contains only soma, branch, and tip nodes.
     """
 
-    branches: Dict[int, List[Branch]]
+    branches: dict[int, list[Branch]]
 
-    def get_origin_branches(self) -> List[Branch]:
+    def get_origin_branches(self) -> list[Branch]:
         """Get branches of original tree."""
         return list(itertools.chain(*self.branches.values()))
 
-    def get_origin_node_branches(self, idx: int) -> List[Branch]:
+    def get_origin_node_branches(self, idx: int) -> list[Branch]:
         """Get branches of node of original tree."""
         return self.branches[idx]