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

swcgeom/transforms/images.py

@@ -17,7 +17,7 @@
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import deprecated
+from typing_extensions import deprecated, override
 
 from swcgeom.transforms.base import Identity, Transform
 
@@ -49,12 +49,14 @@ class ImagesCenterCrop(Transform[NDArrayf32, NDArrayf32]):
             else (shape_out, shape_out, shape_out)
         )
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         diff = np.subtract(x.shape[:3], self.shape_out)
         s = diff // 2
         e = np.add(s, self.shape_out)
         return x[s[0] : e[0], s[1] : e[1], s[2] : e[2], :]
 
+    @override
     def extra_repr(self) -> str:
         return f"shape_out=({','.join(str(a) for a in self.shape_out)})"
 
@@ -73,9 +75,11 @@ class ImagesScale(Transform[NDArrayf32, NDArrayf32]):
         super().__init__()
         self.scaler = scaler
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return self.scaler * x
 
+    @override
     def extra_repr(self) -> str:
         return f"scaler={self.scaler}"
 
@@ -85,9 +89,11 @@ class ImagesClip(Transform[NDArrayf32, NDArrayf32]):
         super().__init__()
         self.vmin, self.vmax = vmin, vmax
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return np.clip(x, self.vmin, self.vmax)
 
+    @override
     def extra_repr(self) -> str:
         return f"vmin={self.vmin}, vmax={self.vmax}"
 
@@ -99,9 +105,11 @@ class ImagesFlip(Transform[NDArrayf32, NDArrayf32]):
         super().__init__()
         self.axis = axis
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return np.flip(x, axis=self.axis)
 
+    @override
     def extra_repr(self) -> str:
         return f"axis={self.axis}"
 
@@ -109,15 +117,13 @@ class ImagesFlip(Transform[NDArrayf32, NDArrayf32]):
 class ImagesFlipY(ImagesFlip):
     """Flip image stack along Y-axis.
 
-    See Also
-    --------
-    ~.images.io.TeraflyImageStack:
-        Terafly and Vaa3d use a especial right-handed coordinate system
-        (with origin point in the left-top and z-axis points front),
-        but we flip y-axis to makes it a left-handed coordinate system
-        (with orgin point in the left-bottom and z-axis points front).
-        If you need to use its coordinate system, remember to FLIP
-        Y-AXIS BACK.
+    See Also:
+        ~.images.io.TeraflyImageStack:
+            Terafly and Vaa3d use a especial right-handed coordinate system (with
+            origin point in the left-top and z-axis points front), but we flip y-axis
+            to makes it a left-handed coordinate system (with origin point in the
+            left-bottom and z-axis points front). If you need to use its coordinate
+            system, remember to FLIP Y-AXIS BACK.
     """
 
     def __init__(self, axis: int = 1, /) -> None:
@@ -127,6 +133,7 @@ class ImagesFlipY(ImagesFlip):
 class ImagesNormalizer(Transform[NDArrayf32, NDArrayf32]):
     """Normalize image stack."""
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         mean = np.mean(x)
         variance = np.var(x)
@@ -136,9 +143,8 @@ class ImagesNormalizer(Transform[NDArrayf32, NDArrayf32]):
 class ImagesMeanVarianceAdjustment(Transform[NDArrayf32, NDArrayf32]):
     """Adjust image stack mean and variance.
 
-    See Also
-    --------
-    ~swcgeom.images.ImageStackFolder.stat
+    See Also:
+        ~swcgeom.images.ImageStackFolder.stat
     """
 
     def __init__(self, mean: float, variance: float) -> None:
@@ -146,9 +152,11 @@ class ImagesMeanVarianceAdjustment(Transform[NDArrayf32, NDArrayf32]):
         self.mean = mean
         self.variance = variance
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return (x - self.mean) / self.variance
 
+    @override
     def extra_repr(self) -> str:
         return f"mean={self.mean}, variance={self.variance}"
 
@@ -159,14 +167,10 @@ class ImagesScaleToUnitRange(Transform[NDArrayf32, NDArrayf32]):
     def __init__(self, vmin: float, vmax: float, *, clip: bool = True) -> None:
         """Scale image stack to unit range.
 
-        Parameters
-        ----------
-        vmin : float
-            Minimum value.
-        vmax : float
-            Maximum value.
-        clip : bool, default True
-            Clip values to [0, 1] to avoid numerical issues.
+        Args:
+            vmin: Minimum value.
+            vmax: Maximum value.
+            clip: Clip values to [0, 1] to avoid numerical issues.
         """
 
         super().__init__()
@@ -176,9 +180,11 @@ class ImagesScaleToUnitRange(Transform[NDArrayf32, NDArrayf32]):
         self.clip = clip
         self.post = ImagesClip(0, 1) if self.clip else Identity()
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         return self.post((x - self.vmin) / self.diff)
 
+    @override
     def extra_repr(self) -> str:
         return f"vmin={self.vmin}, vmax={self.vmax}, clip={self.clip}"
 
@@ -186,15 +192,15 @@ class ImagesScaleToUnitRange(Transform[NDArrayf32, NDArrayf32]):
 class ImagesHistogramEqualization(Transform[NDArrayf32, NDArrayf32]):
     """Image histogram equalization.
 
-    References
-    ----------
-    http://www.janeriksolem.net/histogram-equalization-with-python-and.html
+    References:
+        http://www.janeriksolem.net/histogram-equalization-with-python-and.html
     """
 
     def __init__(self, bins: int = 256) -> None:
         super().__init__()
         self.bins = bins
 
+    @override
     def __call__(self, x: NDArrayf32) -> NDArrayf32:
         # get image histogram
         hist, bin_edges = np.histogram(x.flatten(), self.bins, density=True)
@@ -205,5 +211,6 @@ class ImagesHistogramEqualization(Transform[NDArrayf32, NDArrayf32]):
         equalized = np.interp(x.flatten(), bin_edges[:-1], cdf)
         return equalized.reshape(x.shape).astype(np.float32)
 
+    @override
     def extra_repr(self) -> str:
         return f"bins={self.bins}"

swcgeom/transforms/mst.py

@@ -16,12 +16,12 @@
 """Minimum spanning tree."""
 
 import warnings
-from typing import Optional
 
 import numpy as np
 import pandas as pd
 from numpy import ma
 from numpy import typing as npt
+from typing_extensions import override
 
 from swcgeom.core import Tree, sort_tree
 from swcgeom.core.swc_utils import SWCNames, SWCTypes, get_names, get_types
@@ -36,8 +36,7 @@ class PointsToCuntzMST(Transform[npt.NDArray[np.float32], Tree]):
     Creates trees corresponding to the minimum spanning tree keeping
     the path length to the root small (with balancing factor bf).
 
-    References
-    ----------
+    References:
     .. [1] Cuntz, H., Forstner, F., Borst, A. & Häusser, M. One Rule to
        Grow Them Al: A General Theory of Neuronal Branching and Its
        Practical Application. PLOS Comput Biol 6, e1000877 (2010).
@@ -52,21 +51,15 @@ class PointsToCuntzMST(Transform[npt.NDArray[np.float32], Tree]):
         furcations: int = 2,
         exclude_soma: bool = True,
         sort: bool = True,
-        names: Optional[SWCNames] = None,
-        types: Optional[SWCTypes] = None,
+        names: SWCNames | None = None,
+        types: SWCTypes | None = None,
     ) -> None:
         """
-        Parameters
-        ----------
-        bf : float, default `0.4`
-            Balancing factor between 0~1.
-        furcations : int, default `2`
-            Suppress multi-furcations which more than k. If set to -1,
-            no suppression.
-        exclude_soma : bool, default `True`
-            Suppress multi-furcations exclude soma.
-        names : SWCNames, optional
-        types : SWCTypes, optional
+        Args:
+            bf: Balancing factor between 0~1.
+            furcations: Suppress multi-furcations which more than k.
+                If set to -1, no suppression.
+            exclude_soma: Suppress multi-furcations exclude soma.
         """
         self.bf = np.clip(bf, 0, 1)
         self.furcations = furcations
@@ -75,29 +68,26 @@ class PointsToCuntzMST(Transform[npt.NDArray[np.float32], Tree]):
         self.names = get_names(names)
         self.types = get_types(types)
 
+    @override
     def __call__(  # pylint: disable=too-many-locals
         self,
         points: npt.NDArray[np.floating],
-        soma: Optional[npt.ArrayLike] = None,
+        soma: npt.ArrayLike | None = None,
         *,
-        names: Optional[SWCNames] = None,
+        names: SWCNames | None = None,
     ) -> Tree:
         """
-        Paramters
-        ---------
-        points : array of shape (N, 3)
-            Positions of points cloud.
-        soma : array of shape (3,), default `None`
-            Position of soma. If none, use the first point as soma.
-        names : SWCNames, optional
+        Args:
+            points: Positions of points cloud.
+            soma: Position of soma. If none, use the first point as soma.
         """
         if names is None:
             names = self.names
         else:
             warnings.warn(
-                "`PointsToCuntzMST(...)(names=...)` has been "
-                "replaced by `PointsToCuntzMST(...,names=...)` since "
-                "v0.12.0, and will be removed in next version",
+                "`PointsToCuntzMST(...)(names=...)` has been replaced by "
+                "`PointsToCuntzMST(...,names=...)` since v0.12.0, and will be removed "
+                "in next version",
                 DeprecationWarning,
             )
             names = get_names(names)  # TODO: remove it
@@ -155,6 +145,7 @@ class PointsToCuntzMST(Transform[npt.NDArray[np.float32], Tree]):
             t = sort_tree(t)
         return t
 
+    @override
     def extra_repr(self) -> str:  # TODO: names, types
         return f"bf={self.bf:.4f}, furcations={self.furcations}, exclude_soma={self.exclude_soma}, sort={self.sort}"
 
@@ -166,22 +157,17 @@ class PointsToMST(PointsToCuntzMST):  # pylint: disable=too-few-public-methods
         self,
         furcations: int = 2,
         *,
-        k_furcations: Optional[int] = None,
+        k_furcations: int | None = None,
         exclude_soma: bool = True,
-        names: Optional[SWCNames] = None,
-        types: Optional[SWCTypes] = None,
+        names: SWCNames | None = None,
+        types: SWCTypes | None = None,
         **kwargs,
     ) -> None:
         """
-        Parameters
-        ----------
-        furcations : int, default `2`
-            Suppress multifurcations which more than k. If set to -1,
-            no suppression.
-        exclude_soma : bool, default `True`
-            Suppress multi-furcations exclude soma.
-        names : SWCNames, optional
-        types : SWCTypes, optional
+        Args:
+            furcations: Suppress multifurcations which more than k.
+                If set to -1, no suppression.
+            exclude_soma: Suppress multi-furcations exclude soma.
         """
 
         if k_furcations is not None:
@@ -202,5 +188,6 @@ class PointsToMST(PointsToCuntzMST):  # pylint: disable=too-few-public-methods
             **kwargs,
         )
 
+    @override
     def extra_repr(self) -> str:
         return f"furcations-{self.furcations}, exclude-soma={self.exclude_soma}"

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 = {