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

swcgeom/core/swc_utils/subtree.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.
+
+
 """Cut subtree.
 
 This module provides a series of low-level topological subtree methods,
@@ -6,7 +21,7 @@ but in more cases, you can use the high-level methods provided in
 high-level API.
 """
 
-from typing import Tuple, cast
+from typing import cast
 
 import numpy as np
 import numpy.typing as npt
@@ -18,7 +33,7 @@ __all__ = ["REMOVAL", "to_sub_topology", "propagate_removal"]
 REMOVAL = -2  # A marker in utils, place in the ids to mark it removal
 
 
-def to_sub_topology(sub: Topology) -> Tuple[Topology, npt.NDArray[np.int32]]:
+def to_sub_topology(sub: Topology) -> tuple[Topology, npt.NDArray[np.int32]]:
     """Create sub tree from origin tree.
 
     Mark the node to be removed, then use this method to get a child

swcgeom/core/tree.py

@@ -1,25 +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.
+
+
 """Neuron tree."""
 
 import itertools
 import os
-import warnings
-from typing import (
-    Callable,
-    Dict,
-    Iterable,
-    Iterator,
-    List,
-    Literal,
-    Optional,
-    Tuple,
-    TypeVar,
-    Union,
-    overload,
-)
+from collections.abc import Callable, Iterable, Iterator
+from typing import Literal, Optional, TypeVar, Union, overload
 
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
+from typing_extensions import deprecated
 
 from swcgeom.core.branch import Branch
 from swcgeom.core.compartment import Compartment, Compartments
@@ -44,17 +48,17 @@ class Tree(DictSWC):
         def parent(self) -> Union["Tree.Node", None]:
             return Tree.Node(self.attach, self.pid) if self.pid != -1 else None
 
-        def children(self) -> List["Tree.Node"]:
+        def children(self) -> list["Tree.Node"]:
             children = self.attach.id()[self.attach.pid() == self.id]
             return [Tree.Node(self.attach, idx) for idx in children]
 
         def branch(self) -> "Tree.Branch":
-            ns: List["Tree.Node"] = [self]
-            while not ns[-1].is_bifurcation() and (p := ns[-1].parent()) is not None:
+            ns: list["Tree.Node"] = [self]
+            while not ns[-1].is_furcation() and (p := ns[-1].parent()) is not None:
                 ns.append(p)
 
             ns.reverse()
-            while not (ns[-1].is_bifurcation() or ns[-1].is_tip()):
+            while not (ns[-1].is_furcation() or ns[-1].is_tip()):
                 ns.append(ns[-1].children()[0])
 
             return Tree.Branch(self.attach, [n.id for n in ns])
@@ -68,7 +72,7 @@ class Tree(DictSWC):
 
             Parameters
             ----------
-            out_mapping : List of int or Dict[int, int], optional
+            out_mapping : List of int or dict[int, int], optional
                 Map from new id to old id.
             """
 
@@ -160,7 +164,7 @@ class Tree(DictSWC):
 
     # fmt:off
     @overload
-    def __getitem__(self, key: slice) -> List[Node]: ...
+    def __getitem__(self, key: slice) -> list[Node]: ...
     @overload
     def __getitem__(self, key: int) -> Node: ...
     @overload
@@ -199,18 +203,30 @@ class Tree(DictSWC):
             raise ValueError(f"no soma found in: {self.source}")
         return n
 
-    def get_bifurcations(self) -> List[Node]:
-        """Get all node of bifurcations."""
-        bifurcations: List[int] = []
+    def get_furcations(self) -> list[Node]:
+        """Get all node of furcations."""
+        furcations: list[int] = []
 
-        def collect_bifurcations(n: Tree.Node, children: List[None]) -> None:
+        def collect_furcations(n: Tree.Node, children: list[None]) -> None:
             if len(children) > 1:
-                bifurcations.append(n.id)
+                furcations.append(n.id)
+
+        self.traverse(leave=collect_furcations)
+        return [self.node(i) for i in furcations]
 
-        self.traverse(leave=collect_bifurcations)
-        return [self.node(i) for i in bifurcations]
+    @deprecated("Use `get_furcations` instead")
+    def get_bifurcations(self) -> list[Node]:
+        """Get all node of furcations.
+
+        Notes
+        -----
+        Deprecated due to the wrong spelling of furcation. For now, it
+        is just an alias of `get_furcations` and raise a warning. It
+        will be change to raise an error in the future.
+        """
+        return self.get_furcations()
 
-    def get_tips(self) -> List[Node]:
+    def get_tips(self) -> list[Node]:
         """Get all node of tips."""
         tip_ids = np.setdiff1d(self.id(), self.pid(), assume_unique=True)
         return [self.node(i) for i in tip_ids]
@@ -221,16 +237,16 @@ class Tree(DictSWC):
     def get_segments(self) -> Compartments[Compartment]:  # Alias
         return self.get_compartments()
 
-    def get_branches(self) -> List[Branch]:
+    def get_branches(self) -> list[Branch]:
         def collect_branches(
-            node: "Tree.Node", pre: List[Tuple[List[Tree.Branch], List[int]]]
-        ) -> Tuple[List[Tree.Branch], List[int]]:
+            node: "Tree.Node", pre: list[tuple[list[Tree.Branch], list[int]]]
+        ) -> tuple[list[Tree.Branch], list[int]]:
             if len(pre) == 1:
                 branches, child = pre[0]
                 child.append(node.id)
                 return branches, child
 
-            branches: List[Tree.Branch] = []
+            branches: list[Tree.Branch] = []
 
             for sub_branches, child in pre:
                 child.append(node.id)
@@ -244,19 +260,19 @@ class Tree(DictSWC):
         branches, _ = self.traverse(leave=collect_branches)
         return branches
 
-    def get_paths(self) -> List[Path]:
+    def get_paths(self) -> list[Path]:
         """Get all path from soma to tips."""
-        path_dic: Dict[int, List[int]] = {}
+        path_dic: dict[int, list[int]] = {}
 
-        def assign_path(n: Tree.Node, pre_path: List[int] | None) -> List[int]:
+        def assign_path(n: Tree.Node, pre_path: list[int] | None) -> list[int]:
             path = [] if pre_path is None else pre_path.copy()
             path.append(n.id)
             path_dic[n.id] = path
             return path
 
         def collect_path(
-            n: Tree.Node, children: List[List[List[int]]]
-        ) -> List[List[int]]:
+            n: Tree.Node, children: list[list[list[int]]]
+        ) -> list[list[int]]:
             if len(children) == 0:
                 return [path_dic[n.id]]
 
@@ -283,7 +299,7 @@ class Tree(DictSWC):
     @overload
     def traverse(self, *,
                  enter: Optional[Callable[[Node, T | None], T]] = ...,
-                 leave: Callable[[Node, List[K]], K],
+                 leave: Callable[[Node, list[K]], K],
                  root: int | np.integer = ..., mode: Literal["dfs"] = ...) -> K: ...
     # fmt: on
 
@@ -293,7 +309,7 @@ class Tree(DictSWC):
         Parameters
         ----------
         enter : (n: Node, parent: T | None) => T, optional
-        leave : (n: Node, children: List[T]) => T, optional
+        leave : (n: Node, children: list[T]) => T, optional
 
         See Also
         --------
@@ -355,7 +371,7 @@ class Tree(DictSWC):
 
     @classmethod
     def from_eswc(
-        cls, swc_file: str, extra_cols: Optional[List[str]] = None, **kwargs
+        cls, swc_file: str, extra_cols: Optional[list[str]] = None, **kwargs
     ) -> "Tree":
         """Read neuron tree from eswc file.
 

swcgeom/core/tree_utils.py

@@ -1,9 +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.
+
+
 """SWC util wrapper for tree."""
 
 import warnings
-from typing import Callable, Dict, Iterable, List, Optional, Tuple, TypeVar, overload
+from collections.abc import Callable, Iterable
+from typing import Optional, TypeVar, overload
 
 import numpy as np
+from typing_extensions import deprecated
 
 from swcgeom.core.swc import SWCLike
 from swcgeom.core.swc_utils import (
@@ -50,9 +67,9 @@ def sort_tree(tree: Tree) -> Tree:
 
 # fmt:off
 @overload
-def cut_tree(tree: Tree, *, enter: Callable[[Tree.Node, T | None], Tuple[T, bool]]) -> Tree: ...
+def cut_tree(tree: Tree, *, enter: Callable[[Tree.Node, T | None], tuple[T, bool]]) -> Tree: ...
 @overload
-def cut_tree(tree: Tree, *, leave: Callable[[Tree.Node, List[K]], Tuple[K, bool]]) -> Tree: ...
+def cut_tree(tree: Tree, *, leave: Callable[[Tree.Node, list[K]], tuple[K, bool]]) -> Tree: ...
 # fmt:on
 def cut_tree(tree: Tree, *, enter=None, leave=None):
     """Traverse and cut the tree.
@@ -60,11 +77,11 @@ def cut_tree(tree: Tree, *, enter=None, leave=None):
     Returning a `True` can delete the current node and its children.
     """
 
-    removals: List[int] = []
+    removals: list[int] = []
 
     if enter:
 
-        def _enter(n: Tree.Node, parent: Tuple[T, bool] | None) -> Tuple[T, bool]:
+        def _enter(n: Tree.Node, parent: tuple[T, bool] | None) -> tuple[T, bool]:
             if parent is not None and parent[1]:
                 removals.append(n.id)
                 return parent
@@ -79,7 +96,7 @@ def cut_tree(tree: Tree, *, enter=None, leave=None):
 
     elif leave:
 
-        def _leave(n: Tree.Node, children: List[K]) -> K:
+        def _leave(n: Tree.Node, children: list[K]) -> K:
             res, removal = leave(n, children)
             if removal:
                 removals.append(n.id)
@@ -94,7 +111,8 @@ def cut_tree(tree: Tree, *, enter=None, leave=None):
     return to_subtree(tree, removals)
 
 
-def to_sub_tree(swc_like: SWCLike, sub: Topology) -> Tuple[Tree, Dict[int, int]]:
+@deprecated("Use `to_subtree` instead")
+def to_sub_tree(swc_like: SWCLike, sub: Topology) -> tuple[Tree, dict[int, int]]:
     """Create subtree from origin tree.
 
     You can directly mark the node for removal, and we will remove it,
@@ -107,16 +125,9 @@ def to_sub_tree(swc_like: SWCLike, sub: Topology) -> Tuple[Tree, Dict[int, int]]
     Returns
     -------
     tree : Tree
-    id_map : Dict[int, int]
+    id_map : dict[int, int]
     """
 
-    warnings.warn(
-        "`to_sub_tree` will be removed in v0.6.0, it is replaced by "
-        "`to_subtree` beacuse it is easy to use, and this will be "
-        "removed in next version",
-        DeprecationWarning,
-    )
-
     sub = propagate_removal(sub)
     (new_id, new_pid), id_map_arr = to_sub_topology(sub)
 
@@ -145,7 +156,7 @@ def to_subtree(
     swc_like : SWCLike
     removals : List of int
         A list of id of nodes to be removed.
-    out_mapping: List of int or Dict[int, int], optional
+    out_mapping: List of int or dict[int, int], optional
         Map new id to old id.
     """
 
@@ -170,7 +181,7 @@ def get_subtree(
     swc_like : SWCLike
     n : int
         Id of the root of the subtree.
-    out_mapping: List of int or Dict[int, int], optional
+    out_mapping: List of int or dict[int, int], optional
         Map new id to old id.
     """
 

swcgeom/core/tree_utils_impl.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.
+
+
 """SWC util wrapper for tree, split to avoid circle imports.
 
 Notes
@@ -5,7 +20,7 @@ Notes
 Do not import `Tree` and keep this file minimized.
 """
 
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Optional
 
 import numpy as np
 import numpy.typing as npt
@@ -15,8 +30,8 @@ from swcgeom.core.swc_utils import Topology, to_sub_topology, traverse
 
 __all__ = ["get_subtree_impl", "to_subtree_impl"]
 
-Mapping = Dict[int, int] | List[int]
-TreeArgs = Tuple[int, Dict[str, npt.NDArray[Any]], str, SWCNames]
+Mapping = dict[int, int] | list[int]
+TreeArgs = tuple[int, dict[str, npt.NDArray[Any]], str, SWCNames]
 
 
 def get_subtree_impl(

swcgeom/images/__init__.py

@@ -1,4 +1,19 @@
+# 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.
+
+
 """Image Stack Related."""
 
-from swcgeom.images.folder import *
-from swcgeom.images.io import *
+from swcgeom.images.folder import *  # noqa: F403
+from swcgeom.images.io import *  # noqa: F403

swcgeom/images/augmentation.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.
+
+
 """Play augment in image stack.
 
 Notes
@@ -6,7 +21,7 @@ This is expremental code, and the API is subject to change.
 """
 
 import random
-from typing import List, Literal, Optional
+from typing import Literal, Optional
 
 import numpy as np
 import numpy.typing as npt
@@ -54,7 +69,7 @@ class Augmentation:
 
     def swapaxes(self, x, mode: Optional[Literal["xy", "xz", "yz"]] = None) -> NDArrf32:
         if mode is None:
-            modes: List[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
+            modes: list[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
             mode = modes[self.rand.randint(0, 2)]
 
         match mode:
@@ -69,7 +84,7 @@ class Augmentation:
 
     def flip(self, x, mode: Optional[Literal["xy", "xz", "yz"]] = None) -> NDArrf32:
         if mode is None:
-            modes: List[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
+            modes: list[Literal["xy", "xz", "yz"]] = ["xy", "xz", "yz"]
             mode = modes[random.randint(0, 2)]
 
         match mode:

swcgeom/images/contrast.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 contrast of an image.
 
 Notes

swcgeom/images/folder.py

@@ -1,26 +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.
+
+
 """Image stack folder."""
 
 import math
 import os
 import re
-import warnings
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass
-from typing import (
-    Callable,
-    Generic,
-    Iterable,
-    List,
-    Literal,
-    Optional,
-    Tuple,
-    TypeVar,
-    overload,
-)
+from typing import Generic, Literal, Optional, TypeVar, overload
 
 import numpy as np
 import numpy.typing as npt
 from tqdm import tqdm
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 from swcgeom.images.io import ScalarType, read_imgs
 from swcgeom.transforms import Identity, Transform
@@ -33,7 +38,7 @@ T = TypeVar("T")
 class ImageStackFolderBase(Generic[ScalarType, T]):
     """Image stack folder base."""
 
-    files: List[str]
+    files: list[str]
     transform: Transform[npt.NDArray[ScalarType], T]
 
     # fmt: off
@@ -61,7 +66,10 @@ class ImageStackFolderBase(Generic[ScalarType, T]):
         return read_imgs(fname, dtype=self.dtype).get_full()  # type: ignore
 
     @staticmethod
-    def scan(root: str, *, pattern: Optional[str] = None) -> List[str]:
+    def scan(root: str, *, pattern: Optional[str] = None) -> list[str]:
+        if not os.path.isdir(root):
+            raise NotADirectoryError(f"not a directory: {root}")
+
         is_valid = re.compile(pattern).match if pattern is not None else truthly
 
         fs = []
@@ -71,6 +79,7 @@ class ImageStackFolderBase(Generic[ScalarType, T]):
         return fs
 
     @staticmethod
+    @deprecated("Use `~swcgeom.images.io.read_imgs(fname).get_full()` instead")
     def read_imgs(fname: str) -> npt.NDArray[np.float32]:
         """Read images.
 
@@ -78,14 +87,6 @@ class ImageStackFolderBase(Generic[ScalarType, T]):
             Use :meth:`~swcgeom.images.io.read_imgs(fname).get_full()` instead.
         """
 
-        warnings.warn(
-            "`ImageStackFolderBase.read_imgs` serves as a "
-            "straightforward wrapper for `~swcgeom.images.io.read_imgs(fname).get_full()`. "
-            "However, as it is not utilized within our internal "
-            "processes, it is scheduled for removal in the "
-            "forthcoming version.",
-            DeprecationWarning,
-        )
         return read_imgs(fname).get_full()
 
 
@@ -168,13 +169,13 @@ class ImageStackFolder(ImageStackFolderBase[ScalarType, T]):
 class LabeledImageStackFolder(ImageStackFolderBase[ScalarType, T]):
     """Image stack folder with label."""
 
-    labels: List[int]
+    labels: list[int]
 
     def __init__(self, files: Iterable[str], labels: Iterable[int], **kwargs):
         super().__init__(files, **kwargs)
         self.labels = list(labels)
 
-    def __getitem__(self, idx: int) -> Tuple[T, int]:
+    def __getitem__(self, idx: int) -> tuple[T, int]:
         return self._get(self.files[idx]), self.labels[idx]
 
     @classmethod
@@ -205,7 +206,7 @@ class PathImageStackFolder(ImageStackFolderBase[ScalarType, T]):
         super().__init__(files, **kwargs)
         self.root = root
 
-    def __getitem__(self, idx: int) -> Tuple[T, str]:
+    def __getitem__(self, idx: int) -> tuple[T, str]:
         relpath = os.path.relpath(self.files[idx], self.root)
         return self._get(self.files[idx]), relpath