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

swcgeom/core/{segment.py → compartment.py}

@@ -1,6 +1,22 @@
+# 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 typing import Generic, Iterable, List, TypeVar
+from collections.abc import Iterable
+from typing import Generic, TypeVar
 
 import numpy as np
 import numpy.typing as npt
@@ -9,11 +25,11 @@ from swcgeom.core.path import Path
 from swcgeom.core.swc import DictSWC, SWCTypeVar
 from swcgeom.core.swc_utils import SWCNames, get_names
 
-__all__ = ["Segment", "Segments"]
+__all__ = ["Compartment", "Compartments", "Segment", "Segments"]
 
 
-class Segment(Path, Generic[SWCTypeVar]):
-    r"""Segment attached to external object."""
+class Compartment(Path, Generic[SWCTypeVar]):
+    r"""Compartment attached to external object."""
 
     attach: SWCTypeVar
     idx: npt.NDArray[np.int32]
@@ -27,7 +43,7 @@ class Segment(Path, Generic[SWCTypeVar]):
     def get_ndata(self, key: str) -> npt.NDArray:
         return self.attach.get_ndata(key)[self.idx]
 
-    def detach(self) -> "Segment[DictSWC]":
+    def detach(self) -> "Compartment[DictSWC]":
         """Detach from current attached object."""
         # pylint: disable=consider-using-dict-items
         attact = DictSWC(
@@ -37,18 +53,18 @@ class Segment(Path, Generic[SWCTypeVar]):
         )
         attact.ndata[self.names.id] = self.id()
         attact.ndata[self.names.pid] = self.pid()
-        return Segment(attact, 0, 1)
+        return Compartment(attact, 0, 1)
 
 
-SegmentT = TypeVar("SegmentT", bound=Segment)
+T = TypeVar("T", bound=Compartment)
 
 
-class Segments(List[SegmentT]):
-    r"""Segments contains a set of segments."""
+class Compartments(list[T]):
+    r"""Comparments contains a set of comparment."""
 
     names: SWCNames
 
-    def __init__(self, segments: Iterable[SegmentT]) -> None:
+    def __init__(self, segments: Iterable[T]) -> None:
         super().__init__(segments)
         self.names = self[0].names if len(self) > 0 else get_names()
 
@@ -94,3 +110,8 @@ class Segments(List[SegmentT]):
         The order of axis 1 is (parent, current node).
         """
         return np.array([s.get_ndata(key) for s in self])
+
+
+# Aliases
+Segment = Compartment
+Segments = Compartments

swcgeom/core/node.py

@@ -1,10 +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 node."""
 
-import warnings
-from typing import Any, Generic, Iterable
+from collections.abc import Iterable
+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,16 +111,21 @@ class Node(Generic[SWCTypeVar]):
         items = [self.id, self.type, x, y, z, r, self.pid]
         return " ".join(map(str, items))
 
-    def child_ids(self) -> npt.NDArray[np.int32]:
-        warnings.warn(
-            "`Node.child_ids` has been deprecated since v0.3.1 and "
-            "will be removed in next version",
-            DeprecationWarning,
-        )
-        return self.attach.id()[self.attach.pid() == self.id]
+    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:
-        return np.count_nonzero(self.attach.pid() == self.id) > 1
+        """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,9 +1,26 @@
-"""Nueron node."""
-
-from typing import Generic, Iterable, Iterator, List, overload
+# 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."""
+
+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
@@ -12,9 +29,9 @@ __all__ = ["Path"]
 
 
 class Path(SWCLike, Generic[SWCTypeVar]):
-    """Neural path.
+    """Neuron path.
 
-    A path is a linear set of points without bifurcations.
+    A path is a linear set of points without furcations.
     """
 
     attach: SWCTypeVar
@@ -31,7 +48,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
         self.source = self.attach.source
 
     def __iter__(self) -> Iterator[Node]:
-        return (self.get_node(i) for i in range(len(self)))
+        return (self.node(i) for i in range(len(self)))
 
     def __len__(self) -> int:
         return self.id().shape[0]
@@ -43,14 +60,14 @@ class Path(SWCLike, Generic[SWCTypeVar]):
     @overload
     def __getitem__(self, key: int) -> Node: ...
     @overload
-    def __getitem__(self, key: slice) -> List[Node]: ...
+    def __getitem__(self, key: slice) -> list[Node]: ...
     @overload
     def __getitem__(self, key: str) -> npt.NDArray: ...
     # fmt:on
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return [self.get_node(i) for i in range(*key.indices(len(self)))]
+            return [self.node(i) for i in range(*key.indices(len(self)))]
 
         if isinstance(key, (int, np.integer)):
             length = len(self)
@@ -60,7 +77,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
             if key < 0:  # Handle negative indices
                 key += length
 
-            return self.get_node(key)
+            return self.node(key)
 
         if isinstance(key, str):
             return self.get_ndata(key)
@@ -73,7 +90,17 @@ 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.
+
+        .. deprecated:: 0.16.0
+            Use :meth:`path.node` instead.
+        """
+
+        return self.node(idx)
+
+    def node(self, idx: int | np.integer) -> Node:
         return self.Node(self, idx)
 
     def detach(self) -> "Path[DictSWC]":
@@ -129,7 +156,7 @@ class Path(SWCLike, Generic[SWCTypeVar]):
         The end-to-end straight-line distance between start point and
         end point.
         """
-        return np.linalg.norm(self.get_node(-1).xyz() - self.get_node(0).xyz()).item()
+        return np.linalg.norm(self.node(-1).xyz() - self.node(0).xyz()).item()
 
     def tortuosity(self) -> float:
         """Tortuosity of path.

swcgeom/core/population.py

@@ -1,22 +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.
+
+
 """Neuron population is a set of tree."""
 
 import os
 import warnings
+from collections.abc import Callable, Iterable, Iterator
+from concurrent.futures import ProcessPoolExecutor
 from functools import reduce
-from typing import (
-    Any,
-    Dict,
-    Iterable,
-    Iterator,
-    List,
-    Optional,
-    Protocol,
-    cast,
-    overload,
-)
+from typing import Any, Optional, Protocol, TypeVar, cast, overload
 
 import numpy as np
 import numpy.typing as npt
+from tqdm.contrib.concurrent import process_map
+from typing_extensions import Self
 
 from swcgeom.core.swc import eswc_cols
 from swcgeom.core.tree import Tree
@@ -24,6 +33,9 @@ from swcgeom.core.tree import Tree
 __all__ = ["LazyLoadingTrees", "ChainTrees", "Population", "Populations"]
 
 
+T = TypeVar("T")
+
+
 class Trees(Protocol):
     """Trees protocol support index and len."""
 
@@ -36,18 +48,19 @@ class Trees(Protocol):
 class LazyLoadingTrees:
     """Lazy loading trees."""
 
-    swcs: List[str]
-    trees: List[Tree | None]
-    kwargs: Dict[str, Any]
+    swcs: list[str]
+    trees: list[Tree | None]
+    kwargs: dict[str, Any]
 
     def __init__(self, swcs: Iterable[str], **kwargs) -> None:
         """
         Paramters
         ---------
         swcs : List of str
-        kwargs : Dict[str, Any]
+        kwargs : dict[str, Any]
             Forwarding to `Tree.from_swc`
         """
+
         super().__init__()
         self.swcs = list(swcs)
         self.trees = [None for _ in swcs]
@@ -61,6 +74,9 @@ class LazyLoadingTrees:
     def __len__(self) -> int:
         return len(self.swcs)
 
+    def __iter__(self) -> Iterator[Tree]:
+        return (self[i] for i in range(self.__len__()))
+
     def load(self, key: int) -> None:
         if self.trees[key] is None:
             self.trees[key] = Tree.from_swc(self.swcs[key], **self.kwargs)
@@ -69,7 +85,7 @@ class LazyLoadingTrees:
 class ChainTrees:
     """Chain trees."""
 
-    trees: List[Trees]
+    trees: list[Trees]
     cumsum: npt.NDArray[np.int64]
 
     def __init__(self, trees: Iterable[Trees]) -> None:
@@ -92,6 +108,22 @@ class ChainTrees:
     def __len__(self) -> int:
         return self.cumsum[-1].item()
 
+    def __iter__(self) -> Iterator[Tree]:
+        return (self[i] for i in range(self.__len__()))
+
+
+class NestTrees:
+    def __init__(self, trees: Trees, idx: Iterable[int], /) -> None:
+        super().__init__()
+        self.trees = trees
+        self.idx = list(idx)
+
+    def __getitem__(self, key: int, /) -> Tree:
+        return self.trees[self.idx[key]]
+
+    def __len__(self) -> int:
+        return len(self.idx)
+
 
 class Population:
     """Neuron population."""
@@ -131,13 +163,14 @@ class Population:
 
     # fmt:off
     @overload
-    def __getitem__(self, key: slice) -> List[Tree]: ...
+    def __getitem__(self, key: slice) -> Trees: ...
     @overload
     def __getitem__(self, key: int) -> Tree: ...
     # fmt:on
-    def __getitem__(self, key):
+    def __getitem__(self, key: int | slice):
         if isinstance(key, slice):
-            return [cast(Tree, self.trees[i]) for i in range(*key.indices(len(self)))]
+            trees = NestTrees(self.trees, range(*key.indices(len(self))))
+            return cast(Trees, trees)
 
         if isinstance(key, (int, np.integer)):
             return cast(Tree, self.trees[int(key)])
@@ -153,15 +186,40 @@ class Population:
     def __repr__(self) -> str:
         return f"Neuron population in '{self.root}'"
 
+    def map(
+        self,
+        fn: Callable[[Tree], T],
+        *,
+        max_worker: Optional[int] = None,
+        verbose: bool = False,
+    ) -> Iterator[T]:
+        """Map a function to all trees in the population.
+
+        This is a straightforward interface for parallelizing
+        computations. The parameters are intentionally kept simple and
+        user-friendly. For more advanced control, consider using
+        `concurrent.futures` directly.
+        """
+
+        trees = (t for t in self.trees)
+
+        if verbose:
+            results = process_map(fn, trees, max_workers=max_worker)
+        else:
+            with ProcessPoolExecutor(max_worker) as p:
+                results = p.map(fn, trees)
+
+        return results
+
     @classmethod
-    def from_swc(cls, root: str, ext: str = ".swc", **kwargs) -> "Population":
+    def from_swc(cls, root: str, ext: str = ".swc", **kwargs) -> Self:
         if not os.path.exists(root):
             raise FileNotFoundError(
                 f"the root does not refers to an existing directory: {root}"
             )
 
         swcs = cls.find_swcs(root, ext)
-        return Population(LazyLoadingTrees(swcs, **kwargs), root=root)
+        return cls(LazyLoadingTrees(swcs, **kwargs), root=root)
 
     @classmethod
     def from_eswc(
@@ -170,15 +228,15 @@ class Population:
         ext: str = ".eswc",
         extra_cols: Optional[Iterable[str]] = None,
         **kwargs,
-    ) -> "Population":
+    ) -> Self:
         extra_cols = list(extra_cols) if extra_cols is not None else []
         extra_cols.extend(k for k, t in eswc_cols)
         return cls.from_swc(root, ext, extra_cols=extra_cols, **kwargs)
 
     @staticmethod
-    def find_swcs(root: str, ext: str = ".swc", relpath: bool = False) -> List[str]:
+    def find_swcs(root: str, ext: str = ".swc", relpath: bool = False) -> list[str]:
         """Find all swc files."""
-        swcs: List[str] = []
+        swcs: list[str] = []
         for r, _, files in os.walk(root):
             rr = os.path.relpath(r, root) if relpath else r
             fs = filter(lambda f: os.path.splitext(f)[-1] == ext, files)
@@ -191,8 +249,8 @@ class Populations:
     """A set of population."""
 
     len: int
-    populations: List[Population]
-    labels: List[str]
+    populations: list[Population]
+    labels: list[str]
 
     def __init__(
         self, populations: Iterable[Population], labels: Optional[Iterable[str]] = None
@@ -208,9 +266,9 @@ class Populations:
 
     # fmt:off
     @overload
-    def __getitem__(self, key: slice) -> List[List[Tree]]: ...
+    def __getitem__(self, key: slice) -> list[list[Tree]]: ...
     @overload
-    def __getitem__(self, key: int) -> List[Tree]: ...
+    def __getitem__(self, key: int) -> list[Tree]: ...
     # fmt:on
     def __getitem__(self, key):
         return [p[key] for p in self.populations]
@@ -219,7 +277,7 @@ class Populations:
         """Miniumn length of populations."""
         return self.len
 
-    def __iter__(self) -> Iterator[List[Tree]]:
+    def __iter__(self) -> Iterator[list[Tree]]:
         return (self[i] for i in range(self.len))
 
     def __repr__(self) -> str:
@@ -235,7 +293,7 @@ class Populations:
         return Population(ChainTrees(p.trees for p in self.populations))
 
     @classmethod
-    def from_swc(  # pylint: disable=too-many-arguments
+    def from_swc(
         cls,
         roots: Iterable[str],
         ext: str = ".swc",
@@ -243,12 +301,12 @@ class Populations:
         check_same: bool = False,
         labels: Optional[Iterable[str]] = None,
         **kwargs,
-    ) -> "Populations":
+    ) -> Self:
         """Get population from dirs.
 
         Parameters
         ----------
-        roots : list of str
+        roots : List of str
         intersect : bool, default `True`
             Take the intersection of these populations.
         check_same : bool, default `False`
@@ -275,7 +333,7 @@ class Populations:
             )
             for i, d in enumerate(roots)
         ]
-        return Populations(populations, labels=labels)
+        return cls(populations, labels=labels)
 
     @classmethod
     def from_eswc(
@@ -285,7 +343,7 @@ class Populations:
         *,
         ext: str = ".eswc",
         **kwargs,
-    ) -> "Populations":
+    ) -> Self:
         extra_cols = list(extra_cols) if extra_cols is not None else []
         extra_cols.extend(k for k, t in eswc_cols)
         return cls.from_swc(roots, extra_cols=extra_cols, ext=ext, **kwargs)
@@ -299,3 +357,14 @@ def _get_idx(key: int, length: int) -> int:
         key += length
 
     return key
+
+
+# experimental
+def filter_population(
+    pop: Population, predicate: Callable[[Tree], bool]
+) -> "Population":
+    """Filter trees in the population."""
+
+    # TODO: how to avoid load trees
+    idx = [i for i, t in enumerate(pop) if predicate(t)]
+    return Population(NestTrees(pop.trees, idx), root=pop.root)

swcgeom/core/swc.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.
+
+
 """SWC format."""
 
 import warnings
 from abc import ABC, abstractmethod
+from collections.abc import Iterable
 from copy import deepcopy
-from typing import Any, Dict, Iterable, List, Optional, Tuple, TypeVar, overload
+from typing import Any, Optional, TypeVar, overload
 
 import numpy as np
 import numpy.typing as npt
@@ -32,7 +48,7 @@ __all__ = [
 
 
 swc_names_default = get_names()
-swc_cols: List[Tuple[str, npt.DTypeLike]] = [
+swc_cols: list[tuple[str, npt.DTypeLike]] = [
     (swc_names_default.id, np.int32),
     (swc_names_default.type, np.int32),
     (swc_names_default.x, np.float32),
@@ -42,7 +58,7 @@ swc_cols: List[Tuple[str, npt.DTypeLike]] = [
     (swc_names_default.pid, np.int32),
 ]
 
-eswc_cols: List[Tuple[str, npt.DTypeLike]] = [
+eswc_cols: list[tuple[str, npt.DTypeLike]] = [
     ("level", np.int32),
     ("mode", np.int32),
     ("timestamp", np.int32),
@@ -55,7 +71,7 @@ class SWCLike(ABC):
     """ABC of SWC."""
 
     source: str = ""
-    comments: List[str] = []
+    comments: list[str] = []
     names: SWCNames
     types: SWCTypes
 
@@ -131,15 +147,15 @@ class SWCLike(ABC):
 
     # fmt: off
     @overload
-    def to_swc(self, fname: str, *, extra_cols: List[str] | None = ..., source: bool | str = ..., id_offset: int = ...) -> None: ...
+    def to_swc(self, fname: str, *, extra_cols: list[str] | None = ..., source: bool | str = ..., id_offset: int = ...) -> None: ...
     @overload
-    def to_swc(self, *, extra_cols: List[str] | None = ..., source: bool | str = ..., id_offset: int = ...) -> str: ...
+    def to_swc(self, *, extra_cols: list[str] | None = ..., source: bool | str = ..., id_offset: int = ...) -> str: ...
     # fmt: on
     def to_swc(
         self,
         fname: Optional[str] = None,
         *,
-        extra_cols: Optional[List[str]] = None,
+        extra_cols: Optional[list[str]] = None,
         source: bool | str = True,
         comments: bool = True,
         id_offset: int = 1,
@@ -177,7 +193,7 @@ class SWCLike(ABC):
         self,
         fname: Optional[str] = None,
         swc_path: Optional[str] = None,
-        extra_cols: Optional[List[str]] = None,
+        extra_cols: Optional[list[str]] = None,
         **kwargs,
     ) -> str | None:
         if swc_path is None:
@@ -199,7 +215,7 @@ SWCTypeVar = TypeVar("SWCTypeVar", bound=SWCLike)
 class DictSWC(SWCLike):
     """SWC implementation on dict."""
 
-    ndata: Dict[str, npt.NDArray]
+    ndata: dict[str, npt.NDArray]
 
     def __init__(
         self,
@@ -221,7 +237,7 @@ class DictSWC(SWCLike):
     def values(self) -> Iterable[npt.NDArray[Any]]:
         return self.ndata.values()
 
-    def items(self) -> Iterable[Tuple[str, npt.NDArray[Any]]]:
+    def items(self) -> Iterable[tuple[str, npt.NDArray[Any]]]:
         return self.ndata.items()
 
     def get_ndata(self, key: str) -> npt.NDArray[Any]:

swcgeom/core/swc_utils/__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.
+
+
 """SWC format utils.
 
 Notes
@@ -8,10 +23,9 @@ If you use the method here, please review the code more frequently, we
 will try to flag all breaking changes but NO promises.
 """
 
-
-from swcgeom.core.swc_utils.assembler import *
-from swcgeom.core.swc_utils.base import *
-from swcgeom.core.swc_utils.checker import *
-from swcgeom.core.swc_utils.io import *
-from swcgeom.core.swc_utils.normalizer import *
-from swcgeom.core.swc_utils.subtree import *
+from swcgeom.core.swc_utils.assembler import *  # noqa: F403
+from swcgeom.core.swc_utils.base import *  # noqa: F403
+from swcgeom.core.swc_utils.checker import *  # noqa: F403
+from swcgeom.core.swc_utils.io import *  # noqa: F403
+from swcgeom.core.swc_utils.normalizer import *  # noqa: F403
+from swcgeom.core.swc_utils.subtree import *  # noqa: F403