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

swcgeom/transforms/neurolucida_asc.py

@@ -18,8 +18,9 @@
 import os
 import re
 from enum import Enum, auto
-from io import TextIOBase
-from typing import Any, NamedTuple, Optional, cast
+from typing import IO, Any, NamedTuple, cast
+
+from typing_extensions import override
 
 from swcgeom.core import Tree
 from swcgeom.core.swc_utils import SWCNames, SWCTypes, get_names, get_types
@@ -31,6 +32,7 @@ __all__ = ["NeurolucidaAscToSwc"]
 class NeurolucidaAscToSwc(Transform[str, Tree]):
     """Convert neurolucida asc format to swc format."""
 
+    @override
     def __call__(self, x: str) -> Tree:
         return self.convert(x)
 
@@ -42,7 +44,7 @@ class NeurolucidaAscToSwc(Transform[str, Tree]):
         return tree
 
     @classmethod
-    def from_stream(cls, x: TextIOBase, *, source: str = "") -> Tree:
+    def from_stream(cls, x: IO[str], *, source: str = "") -> Tree:
         parser = Parser(x, source=source)
         ast = parser.parse()
         tree = cls.from_ast(ast)
@@ -52,8 +54,8 @@ class NeurolucidaAscToSwc(Transform[str, Tree]):
     def from_ast(
         ast: "AST",
         *,
-        names: Optional[SWCNames] = None,
-        types: Optional[SWCTypes] = None,
+        names: SWCNames | None = None,
+        types: SWCTypes | None = None,
     ) -> Tree:
         names = get_names(names)
         types = get_types(types)
@@ -129,8 +131,8 @@ class ASTNode:
         self,
         type: ASTType,
         value: Any = None,
-        tokens: Optional[list["Token"]] = None,
-        children: Optional[list["ASTNode"]] = None,
+        tokens: list["Token"] | None = None,
+        children: list["ASTNode"] | None = None,
     ):
         self.type = type
         self.value = value
@@ -149,9 +151,7 @@ class ASTNode:
         """
         Compare two ASTNode objects.
 
-        Notes
-        -----
-        The `parent`, `tokens` attribute is not compared.
+        NOTE: The `parent`, `tokens` attribute is not compared.
         """
         return (
             isinstance(__value, ASTNode)
@@ -162,7 +162,7 @@ class ASTNode:
 
 
 class AST(ASTNode):
-    def __init__(self, children: Optional[list[ASTNode]] = None, source: str = ""):
+    def __init__(self, children: list[ASTNode] | None = None, source: str = ""):
         super().__init__(ASTType.ROOT, children=children)
         self.source = source
 
@@ -216,7 +216,7 @@ class AssertionTokenTypeError(Exception):
 
 
 class Parser:
-    def __init__(self, r: TextIOBase, *, source: str = ""):
+    def __init__(self, r: IO[str], *, source: str = ""):
         self.lexer = Lexer(r)
         self.next_token = None
         self.source = source
@@ -426,7 +426,7 @@ RE_FLOAT = re.compile(r"[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?")
 
 
 class Lexer:
-    def __init__(self, r: TextIOBase):
+    def __init__(self, r: IO[str]):
         self.r = r
         self.lineno = 1
         self.column = 1

swcgeom/transforms/path.py

@@ -15,6 +15,8 @@
 
 """Transformation in path."""
 
+from typing_extensions import override
+
 from swcgeom.core import Path, Tree, redirect_tree
 from swcgeom.transforms.base import Transform
 
@@ -24,6 +26,7 @@ __all__ = ["PathToTree", "PathReverser"]
 class PathToTree(Transform[Path, Tree]):
     """Transform path to tree."""
 
+    @override
     def __call__(self, x: Path) -> Tree:
         t = Tree(
             x.number_of_nodes(),
@@ -55,6 +58,7 @@ class PathReverser(Transform[Path, Path]):
         super().__init__()
         self.to_tree = PathToTree()
 
+    @override
     def __call__(self, x: Path) -> Path:
         x[0].type, x[-1].type = x[-1].type, x[0].type
         t = self.to_tree(x)

swcgeom/transforms/population.py

@@ -15,6 +15,8 @@
 
 """Transformation in population."""
 
+from typing_extensions import override
+
 from swcgeom.core import Population, Tree
 from swcgeom.transforms.base import Transform
 
@@ -28,6 +30,7 @@ class PopulationTransform(Transform[Population, Population]):
         super().__init__()
         self.transform = transform
 
+    @override
     def __call__(self, population: Population) -> Population:
         trees: list[Tree] = []
         for t in population:
@@ -38,5 +41,6 @@ class PopulationTransform(Transform[Population, Population]):
 
         return Population(trees, root=population.root)
 
+    @override
     def extra_repr(self) -> str:
         return f"transform={self.transform}"

swcgeom/transforms/tree.py

@@ -16,10 +16,9 @@
 """Transformation in tree."""
 
 from collections.abc import Callable
-from typing import Optional
 
 import numpy as np
-from typing_extensions import deprecated
+from typing_extensions import deprecated, override
 
 from swcgeom.core import Branch, BranchTree, DictSWC, Path, Tree, cut_tree, to_subtree
 from swcgeom.core.swc_utils import SWCTypes, get_types
@@ -46,6 +45,7 @@ __all__ = [
 class ToBranchTree(Transform[Tree, BranchTree]):
     """Transform tree to branch tree."""
 
+    @override
     def __call__(self, x: Tree) -> BranchTree:
         return BranchTree.from_tree(x)
 
@@ -56,6 +56,7 @@ class ToLongestPath(Transform[Tree, Path[DictSWC]]):
     def __init__(self, *, detach: bool = True) -> None:
         self.detach = detach
 
+    @override
     def __call__(self, x: Tree) -> Path[DictSWC]:
         paths = x.get_paths()
         idx = np.argmax([p.length() for p in paths])
@@ -71,6 +72,7 @@ class TreeSmoother(Transform[Tree, Tree]):  # pylint: disable=missing-class-docs
         self.n_nodes = n_nodes
         self.trans = BranchConvSmoother(n_nodes=n_nodes)
 
+    @override
     def __call__(self, x: Tree) -> Tree:
         x = x.copy()
         for br in x.get_branches():
@@ -82,6 +84,7 @@ class TreeSmoother(Transform[Tree, Tree]):  # pylint: disable=missing-class-docs
 
         return x
 
+    @override
     def extra_repr(self) -> str:
         return f"n_nodes={self.n_nodes}"
 
@@ -100,15 +103,14 @@ class CutByType(Transform[Tree, Tree]):
 
     In order to preserve the tree structure, all ancestor nodes of the node to be preserved will be preserved.
 
-    Notes
-    -----
-    Not all reserved nodes are of the specified type.
+    NOTE: Not all reserved nodes are of the specified type.
     """
 
     def __init__(self, type: int) -> None:  # pylint: disable=redefined-builtin
         super().__init__()
         self.type = type
 
+    @override
     def __call__(self, x: Tree) -> Tree:
         removals = set(x.id()[x.type() != self.type])
 
@@ -121,6 +123,7 @@ class CutByType(Transform[Tree, Tree]):
         y = to_subtree(x, removals)
         return y
 
+    @override
     def extra_repr(self) -> str:
         return f"type={self.type}"
 
@@ -128,7 +131,7 @@ class CutByType(Transform[Tree, Tree]):
 class CutAxonTree(CutByType):
     """Cut axon tree."""
 
-    def __init__(self, types: Optional[SWCTypes] = None) -> None:
+    def __init__(self, types: SWCTypes | None = None) -> None:
         types = get_types(types)
         super().__init__(type=types.axon)
 
@@ -136,7 +139,7 @@ class CutAxonTree(CutByType):
 class CutDendriteTree(CutByType):
     """Cut dendrite tree."""
 
-    def __init__(self, types: Optional[SWCTypes] = None) -> None:
+    def __init__(self, types: SWCTypes | None = None) -> None:
         types = get_types(types)
         super().__init__(type=types.basal_dendrite)  # TODO: apical dendrite
 
@@ -149,6 +152,7 @@ class CutByFurcationOrder(Transform[Tree, Tree]):
     def __init__(self, max_bifurcation_order: int) -> None:
         self.max_furcation_order = max_bifurcation_order
 
+    @override
     def __call__(self, x: Tree) -> Tree:
         return cut_tree(x, enter=self._enter)
 
@@ -169,9 +173,7 @@ class CutByFurcationOrder(Transform[Tree, Tree]):
 class CutByBifurcationOrder(CutByFurcationOrder):
     """Cut tree by bifurcation order.
 
-    Notes
-    -----
-    Deprecated due to the wrong spelling of furcation. For now, it
+    NOTE: Deprecated due to the wrong spelling of furcation. For now, it
     is just an alias of `CutByFurcationOrder` and raise a warning. It
     will be change to raise an error in the future.
     """
@@ -197,7 +199,7 @@ class CutShortTipBranch(Transform[Tree, Tree]):
     callbacks: list[Callable[[Tree.Branch], None]]
 
     def __init__(
-        self, thre: float = 5, callback: Optional[Callable[[Tree.Branch], None]] = None
+        self, thre: float = 5, callback: Callable[[Tree.Branch], None] | None = None
     ) -> None:
         self.thre = thre
         self.callbacks = []
@@ -205,6 +207,7 @@ class CutShortTipBranch(Transform[Tree, Tree]):
         if callback is not None:
             self.callbacks.append(callback)
 
+    @override
     def __call__(self, x: Tree) -> Tree:
         removals: list[int] = []
         self.callbacks.append(lambda br: removals.append(br[1].id))
@@ -212,6 +215,7 @@ class CutShortTipBranch(Transform[Tree, Tree]):
         self.callbacks.pop()
         return to_subtree(x, removals)
 
+    @override
     def extra_repr(self) -> str:
         return f"threshold={self.thre}"
 
@@ -252,6 +256,7 @@ class Resampler(Transform[Tree, Tree]):
         self.resampler = branch_resampler
         self.assembler = BranchTreeAssembler()
 
+    @override
     def __call__(self, x: Tree) -> Tree:
         t = BranchTree.from_tree(x)
         t.branches = {

swcgeom/transforms/tree_assembler.py

@@ -17,10 +17,10 @@
 
 from collections.abc import Iterable
 from copy import copy
-from typing import Optional
 
 import numpy as np
 import pandas as pd
+from typing_extensions import override
 
 from swcgeom.core import Tree
 from swcgeom.core.swc_utils import (
@@ -39,20 +39,18 @@ class LinesToTree(Transform[list[pd.DataFrame], Tree]):
 
     def __init__(self, *, thre: float = 0.2, undirected: bool = True):
         """
-        Parameters
-        ----------
-        thre : float, default `0.2`
-            Connection threshold.
-        undirected : bool, default `True`
-            Both ends of a line can be considered connection point. If
-            `False`, only the starting point.
+        Args:
+            thre: Connection threshold.
+            undirected: Both ends of a line can be considered connection point.
+                If `False`, only the starting point.
         """
         super().__init__()
         self.thre = thre
         self.undirected = undirected
 
+    @override
     def __call__(
-        self, lines: Iterable[pd.DataFrame], *, names: Optional[SWCNames] = None
+        self, lines: Iterable[pd.DataFrame], *, names: SWCNames | None = None
     ):  # TODO check this
         return self.assemble(lines, names=names)
 
@@ -61,30 +59,22 @@ class LinesToTree(Transform[list[pd.DataFrame], Tree]):
         lines: Iterable[pd.DataFrame],
         *,
         undirected: bool = True,
-        names: Optional[SWCNames] = None,
+        names: SWCNames | None = None,
     ) -> pd.DataFrame:
         """Assemble lines to a tree.
 
-        Assemble all the lines into a set of subtrees, and then connect
-        them.
-
-        Parameters
-        ----------
-        lines : List of ~pd.DataFrame
-            An array of tables containing a line, columns should
-            following the swc.
-        undirected : bool, default `True`
-            Forwarding to `self.try_assemble`.
-        names : SWCNames, optional
-            Forwarding to `self.try_assemble`.
-
-        Returns
-        -------
-        tree : ~pd.DataFrame
-
-        See Also
-        --------
-        self.try_assemble
+        Assemble all the lines into a set of subtrees, and then connect them.
+
+        Args:
+            lines: An array of tables containing a line, columns should following the swc.
+            undirected: Forwarding to `self.try_assemble`.
+            names: Forwarding to `self.try_assemble`.
+
+        Returns:
+            tree: ~pd.DataFrame
+
+        See Also:
+            self.try_assemble
         """
 
         tree, lines = self.try_assemble(
@@ -112,33 +102,25 @@ class LinesToTree(Transform[list[pd.DataFrame], Tree]):
         id_offset: int = 0,
         undirected: bool = True,
         sort_nodes: bool = True,
-        names: Optional[SWCNames] = None,
+        names: SWCNames | None = None,
     ) -> tuple[pd.DataFrame, list[pd.DataFrame]]:
         """Trying assemble lines to a tree.
 
-        Treat the first line as a tree, find a line whose shortest distance
-        between the tree and the line is less than threshold, merge it into
-        the tree, repeat until there are no line to merge, return tree and
-        the remaining lines.
-
-        Parameters
-        ----------
-        lines : List of ~pd.DataFrame
-            An array of tables containing a line, columns should follwing
-            the swc.
-        id_offset : int, default `0`
-            The offset of the line node id.
-        undirected : bool, default `True`
-            Both ends of a line can be considered connection point. If
-            `False`, only the starting point.
-        sort_nodes : bool, default `True`
-            sort nodes of subtree.
-        names : SWCNames, optional
-
-        Returns
-        -------
-        tree : ~pandas.DataFrame
-        remaining_lines : List of ~pandas.DataFrame
+        Treat the first line as a tree, find a line whose shortest distance between
+        the tree and the line is less than threshold, merge it into the tree, repeat
+        until there are no line to merge, return tree and the remaining lines.
+
+        Args:
+            lines: An array of tables containing a line, columns should following the swc.
+            id_offset: The offset of the line node id.
+            undirected: Both ends of a line can be considered connection point.
+                If `False`, only the starting point.
+            sort_nodes: sort nodes of subtree.
+            names: SWCNames, optional
+
+        Returns:
+            tree: ~pandas.DataFrame
+            remaining_lines: List of ~pandas.DataFrame
         """
 
         names = get_names(names)
@@ -185,5 +167,6 @@ class LinesToTree(Transform[list[pd.DataFrame], Tree]):
 
         return tree, lines
 
+    @override
     def extra_repr(self) -> str:
         return f"thre={self.thre}, undirected={self.undirected}"

swcgeom/utils/__init__.py

@@ -15,15 +15,15 @@
 
 """Utils."""
 
-from swcgeom.utils.debug import *
-from swcgeom.utils.dsu import *
-from swcgeom.utils.ellipse import *
-from swcgeom.utils.file import *
-from swcgeom.utils.neuromorpho import *
-from swcgeom.utils.numpy_helper import *
-from swcgeom.utils.plotter_2d import *
-from swcgeom.utils.renderer import *
-from swcgeom.utils.sdf import *
-from swcgeom.utils.solid_geometry import *
-from swcgeom.utils.transforms import *
-from swcgeom.utils.volumetric_object import *
+from swcgeom.utils.debug import *  # noqa: F403
+from swcgeom.utils.dsu import *  # noqa: F403
+from swcgeom.utils.ellipse import *  # noqa: F403
+from swcgeom.utils.file import *  # noqa: F403
+from swcgeom.utils.neuromorpho import *  # noqa: F403
+from swcgeom.utils.numpy_helper import *  # noqa: F403
+from swcgeom.utils.plotter_2d import *  # noqa: F403
+from swcgeom.utils.renderer import *  # noqa: F403
+from swcgeom.utils.sdf import *  # noqa: F403
+from swcgeom.utils.solid_geometry import *  # noqa: F403
+from swcgeom.utils.transforms import *  # noqa: F403
+from swcgeom.utils.volumetric_object import *  # noqa: F403

swcgeom/utils/download.py

@@ -15,9 +15,7 @@
 
 """Download helpers.
 
-Notes
------
-All denpendencies need to be installed, try:
+NOTE: All denpendencies need to be installed, try:
 
 ```sh
 pip install swcgeom[all]
@@ -67,16 +65,11 @@ def clone_index_page(
 
     E.g: `https://download.brainimagelibrary.org/biccn/zeng/luo/fMOST/cells/`
 
-    Parameters
-    ----------
-    index_url : str
-        URL of index page.
-    dist_dir : str
-        Directory of dist.
-    override : bool, default `False`
-        Override existing file, skip file if `False`.
-    multiprocess : int, default `4`
-        How many process are available for download.
+    Args:
+        index_url: URL of index page.
+        dist_dir: Directory of dist.
+        override: Override existing file, skip file if `False`.
+        multiprocess: How many process are available for download.
     """
     files = get_urls_in_index_page(index_url)
     logging.info("downloader: search `%s`, found %s files.", index_url, len(files))
@@ -95,7 +88,7 @@ def _clone_index_page(url: str, index_url: str, dist_dir: str, override: bool) -
     dist = os.path.join(dist_dir, filepath)
     if os.path.exists(dist):
         if not override:
-            logging.info("downloader: file `%s` exits, skiped.", dist)
+            logging.info("downloader: file `%s` exits, skipped.", dist)
             return
 
         logging.info("downloader: file `%s` exits, deleted.", dist)

swcgeom/utils/dsu.py

@@ -22,6 +22,18 @@ class DisjointSetUnion:
     """Disjoint Set Union.
 
     DSU with path compression and union by rank.
+
+    >>> dsu = DisjointSetUnion(3)
+    >>> dsu.is_same_set(0, 1)
+    False
+    >>> dsu.union_sets(0, 1)
+    >>> dsu.is_same_set(0, 1)
+    True
+    >>> dsu.is_same_set(0, 2)
+    False
+    >>> dsu.union_sets(1, 2)
+    >>> dsu.is_same_set(0, 2)
+    True
     """
 
     def __init__(self, node_number: int):

swcgeom/utils/ellipse.py

@@ -85,29 +85,41 @@ class Ellipse:
 
 
 def mvee(points: npt.NDArray[np.floating], tol: float = 1e-3) -> Ellipse:
-    A, centroid = _mvee(points, tol=tol)
-    return Ellipse(A, centroid)
+    """Finds the Minimum Volume Enclosing Ellipsoid.
 
+    >>> # Create a set of 2D points
+    >>> points = np.array([[0, 0], [1, 0], [0, 1], [1, 1]], dtype=np.float64)
+    >>> ellipse = mvee(points)
 
-def _mvee(
-    points: npt.NDArray[np.floating], tol: float = 1e-3
-) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
-    """Finds the Minimum Volume Enclosing Ellipsoid.
+    >>> # Check centroid is at center of points
+    >>> np.allclose(ellipse.centroid, [0.5, 0.5])
+    True
 
-    Returns
-    -------
-    A : matrix of shape (d, d)
-        The ellipse equation in the 'center form': (x-c)' * A * (x-c) = 1
-    centroid : array of shape (d,)
-        The center coordinates of the ellipse.
+    >>> # Check ellipse properties
+    >>> rx, ry = ellipse.radii
+    >>> np.allclose([rx, ry], [np.sqrt(2) / 2, np.sqrt(2) / 2], rtol=1e-5)
+    True
 
-    Reference
-    ---------
+    Reference:
     1. http://stackoverflow.com/questions/14016898/port-matlab-bounding-ellipsoid-code-to-python
     2. http://stackoverflow.com/questions/1768197/bounding-ellipse/1768440#1768440
     3. https://minillinim.github.io/GroopM/dev_docs/groopm.ellipsoid-pysrc.html
+
+    Args:
+        points: Array of shape (N, d) where N is number of points and d is dimension
+        tol: Tolerance for convergence
+
+    Returns:
+        Ellipse: An Ellipse object containing the minimum volume enclosing ellipse
     """
 
+    A, centroid = _mvee(points, tol=tol)
+    return Ellipse(A, centroid)
+
+
+def _mvee(
+    points: npt.NDArray[np.floating], tol: float = 1e-3
+) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
     N, d = points.shape
     Q = np.column_stack((points, np.ones(N))).T
     err = tol + 1.0

swcgeom/utils/file.py

@@ -15,10 +15,7 @@
 
 """File related utils.
 
-Notes
------
-If character coding is enabled, all denpendencies need to be installed,
-try:
+NOTE: If character coding is enabled, all denpendencies need to be installed, try:
 
 ```sh
 pip install swcgeom[all]
@@ -45,15 +42,13 @@ class FileReader:
     ) -> None:
         """Read file.
 
-        Parameters
-        ----------
-        fname : PathOrIO
-        encoding : str | 'detect', default `utf-8`
-            The name of the encoding used to decode the file. If is
-            `detect`, we will try to detect the character encoding.
-        low_confidence : float, default to 0.9
-            Used for detect character endocing, raising warning when
-            parsing with low confidence.
+        Args:
+            fname: PathOrIO
+            encoding: The name of the encoding used to decode the file.
+                If is `detect`, we will try to detect the character encoding.
+            low_confidence: The confidence threshold for character encoding detection.
+                Used for detect character endocing, raising warning when parsing with
+                low confidence.
         """
         # TODO: support StringIO
         self.fname, self.fb, self.f = "", None, None