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

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/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

swcgeom/utils/neuromorpho.py

@@ -15,10 +15,7 @@
 
 """NeuroMorpho.org.
 
-Examples
---------
-
-Metadata:
+Metadata Example:
 
 ```json
 {
@@ -80,9 +77,7 @@ Metadata:
 }
 ```
 
-Notes
------
-All denpendencies need to be installed, try:
+NOTE: All denpendencies need to be installed, try:
 
 ```sh
 pip install swcgeom[all]
@@ -97,7 +92,7 @@ import math
 import os
 import urllib.parse
 from collections.abc import Callable, Iterable
-from typing import Any, Literal, Optional
+from typing import Any, Literal
 
 from tqdm import tqdm
 
@@ -140,7 +135,7 @@ DOWNLOAD_CONFIGS: dict[RESOURCES, tuple[str, int]] = {
     "log_source": (URL_LOG_SOURCE, 512 * GB),
 }
 
-# fmt:off
+# fmt: off
 # Test version: 8.5.25 (2023-08-01)
 # No ETAs for future version
 invalid_ids = [
@@ -166,7 +161,7 @@ def neuromorpho_is_valid(metadata: dict[str, Any]) -> bool:
 
 
 def neuromorpho_convert_lmdb_to_swc(
-    root: str, dest: Optional[str] = None, *, verbose: bool = False, **kwargs
+    root: str, dest: str | None = None, *, verbose: bool = False, **kwargs
 ) -> None:
     nmo = NeuroMorpho(root, verbose=verbose)
     nmo.convert_lmdb_to_swc(dest, **kwargs)
@@ -182,11 +177,9 @@ class NeuroMorpho:
         self, root: str, *, url_base: str = URL_BASE, verbose: bool = False
     ) -> None:
         """
-        Parameters
-        ----------
-        root : str
-        verbose : bool, default False
-            Show verbose log.
+        Args:
+            root: str
+            verbose: Show verbose log.
         """
 
         super().__init__()
@@ -252,34 +245,15 @@ class NeuroMorpho:
     # pylint: disable-next=too-many-locals
     def convert_lmdb_to_swc(
         self,
-        dest: Optional[str] = None,
+        dest: str | None = None,
         *,
-        group_by: Optional[str | Callable[[dict[str, Any]], str | None]] = None,
-        where: Optional[Callable[[dict[str, Any]], bool]] = None,
+        group_by: str | Callable[[dict[str, Any]], str | None] | None = None,
+        where: Callable[[dict[str, Any]], bool] | None = None,
         encoding: str | None = "utf-8",
     ) -> None:
         r"""Convert lmdb format to SWCs.
 
-        Parameters
-        ----------
-        path : str
-        dest : str, optional
-            If None, use `path/swc`.
-        group_by : str | (metadata: dict[str, Any]) -> str | None, optional
-            Group neurons by metadata. If a None is returned then no
-            grouping. If a string is entered, use it as a metadata
-            attribute name for grouping, e.g.: `archive`, `species`.
-        where : (metadata: dict[str, Any]) -> bool, optional
-            Filter neurons by metadata.
-        encoding : str | None, default to `utf-8`
-            Change swc encoding, part of the original data is not utf-8
-            encoded. If is None, keep the original encoding format.
-        verbose : bool, default False
-            Print verbose info.
-
-        Notes
-        -----
-        We are asserting the following folder.
+        NOTE: We are asserting the following folder.
 
         ```text
         |- root
@@ -289,10 +263,23 @@ class NeuroMorpho:
         | | |- groups   # output of groups if grouped
         ```
 
-        See Also
-        --------
-        neuromorpho_is_valid :
-            Recommended filter function, try `where=neuromorpho_is_valid`
+        Args:
+            path: str
+            dest: If None, use `path/swc`.
+            group_by: Group neurons by metadata.
+                If None, no grouping. If a string is entered, use it as a metadata
+                attribute name for grouping, e.g.: `archive`, `species`. If a callable
+                is entered, use it as a function `(metadata: dict[str, Any]) -> str | None\
+                to get the group name.
+            where: Filter neurons by metadata.
+                (metadata: dict[str, Any]) -> bool
+            encoding: Change swc encoding, part of the original data is not utf-8 encoded.
+                If is None, keep the original encoding format.default to `utf-8`
+            verbose: Print verbose info.
+
+        See Also:
+            neuromorpho_is_valid:
+                Recommended filter function, try `where=neuromorpho_is_valid`
         """
 
         import lmdb
@@ -302,9 +289,19 @@ class NeuroMorpho:
             where = where or (lambda _: True)
             if isinstance(group_by, str):
                 key = group_by
-                group_by = lambda v: v[key]  # pylint: disable=unnecessary-lambda-assignment
+
+                def group_by_key(v):
+                    return v[key]
+
+                group_by = group_by_key
+
             elif group_by is None:
-                group_by = lambda _: None  # pylint: disable=unnecessary-lambda-assignment
+
+                def no_group(v):
+                    return None
+
+                group_by = no_group
+
             items = []
             for k, v in tx_m.cursor():
                 metadata = json.loads(v)
@@ -336,9 +333,9 @@ class NeuroMorpho:
 
                     if encoding is None:
                         with open(fs, "wb") as f:
-                            f.write(bs)  # type: ignore
+                            f.write(bs)
                     else:
-                        bs = io.BytesIO(bs)  # type: ignore
+                        bs = io.BytesIO(bs)
                         with (
                             open(fs, "w", encoding=encoding) as fw,
                             FileReader(bs, encoding="detect") as fr,
@@ -355,27 +352,20 @@ class NeuroMorpho:
         self,
         path: str,
         *,
-        pages: Optional[Iterable[int]] = None,
+        pages: Iterable[int] | None = None,
         page_size: int = API_PAGE_SIZE_MAX,
         **kwargs,
     ) -> list[int]:
         r"""Download all neuron metadata.
 
-        Parameters
-        ----------
-        path : str
-            Path to save data.
-        pages : List of int, optional
-            If is None, download all pages.
-        verbose : bool, default False
-            Show verbose log.
-        **kwargs :
-            Forwarding to `get`.
-
-        Returns
-        -------
-        err_pages : List of int
-            Failed pages.
+        Args:
+            path: Path to save data.
+            pages: If is None, download all pages.
+            verbose: Show verbose log.
+            **kwargs: Forwarding to `get`.
+
+        Returns:
+            err_pages: Failed pages.
         """
 
         # TODO: how to cache between versions?
@@ -410,32 +400,24 @@ class NeuroMorpho:
         path: str,
         path_metadata: str,
         *,
-        keys: Optional[Iterable[bytes]] = None,
+        keys: Iterable[bytes] | None = None,
         override: bool = False,
         map_size: int = 512 * GB,
         **kwargs,
     ) -> list[bytes]:
         """Download files.
 
-        Parameters
-        ----------
-        url : str
-        path : str
-            Path to save data.
-        path_metadata : str
-            Path to lmdb of metadata.
-        keys : List of bytes, optional
-            If exist, ignore `override` option. If None, download all key.
-        override : bool, default False
-            Override even exists.
-        map_size : int, default 512GB
-        **kwargs :
-            Forwarding to `get`.
-
-        Returns
-        -------
-        err_keys : List of str
-            Failed keys.
+        Args:
+            url: URL of file.
+            path: Path to save data.
+            path_metadata: Path to lmdb of metadata.
+            keys: If exist, ignore `override` option. If None, download all key.
+            override: Override even exists, default to False
+            map_size: int, default 512GB
+            **kwargs: Forwarding to `get`.
+
+        Returns:
+            err_keys: Failed keys.
         """
 
         import lmdb
@@ -445,16 +427,16 @@ class NeuroMorpho:
         if keys is None:
             with env_m.begin() as tx_m:
                 if override:
-                    keys = [k for k, v in tx_m.cursor()]
+                    keys = [k for k, _ in tx_m.cursor()]
                 else:
                     with env_c.begin() as tx:
-                        keys = [k for k, v in tx_m.cursor() if tx.get(k) is None]
+                        keys = [k for k, _ in tx_m.cursor() if tx.get(k) is None]
 
         err_keys = []
         for k in tqdm(keys) if self.verbose else keys:
             try:
                 with env_m.begin() as tx:
-                    metadata = json.loads(tx.get(k).decode("utf-8"))  # type: ignore
+                    metadata = json.loads(tx.get(k).decode("utf-8"))
 
                 swc = self._get_file(url, metadata, **kwargs)
                 with env_c.begin(write=True) as tx:
@@ -485,10 +467,8 @@ class NeuroMorpho:
     def _get_file(self, url: str, metadata: dict[str, Any], **kwargs) -> bytes:
         """Get file.
 
-        Returns
-        -------
-        bs : bytes
-            Bytes of morphology file, encoding is NOT FIXED.
+        Returns:
+            bs: Bytes of morphology file, encoding is NOT FIXED.
         """
 
         archive = urllib.parse.quote(metadata["archive"].lower())
@@ -502,7 +482,7 @@ class NeuroMorpho:
         return self._get(url, **kwargs)
 
     def _get(
-        self, url: str, *, timeout: int = 2 * 60, proxy: Optional[str] = None
+        self, url: str, *, timeout: int = 2 * 60, proxy: str | None = None
     ) -> bytes:
         if not url.startswith("http://") and not url.startswith("https://"):
             url = urllib.parse.urljoin(self.url_base, url)
@@ -529,9 +509,15 @@ class NeuroMorpho:
                 self.ssl_context = ssl_context
                 super().__init__(**kwargs)
 
-            def init_poolmanager(self, connections, maxsize, block=False):
+            def init_poolmanager(
+                self, connections, maxsize, block=False, **pool_kwargs
+            ):
                 super().init_poolmanager(
-                    connections, maxsize, block, ssl_context=self.ssl_context
+                    connections,
+                    maxsize,
+                    block,
+                    ssl_context=self.ssl_context,
+                    **pool_kwargs,
                 )
 
             def proxy_manager_for(self, proxy, **proxy_kwargs):

swcgeom/utils/numpy_helper.py

@@ -32,18 +32,21 @@ def padding1d(
 ) -> npt.NDArray:
     """Padding x to array of shape (n,).
 
-    Parameters
-    ----------
-    n : int
-        Size of vector.
-    v : np.ndarray, optional
-        Input vector.
-    padding_value : any, default to `0`.
-        If x.shape[0] is less than n, the rest will be filled with
-        padding value.
-    dtype : np.DTypeLike, optional
-        Data type of array. If specify, cast x to dtype, else dtype of
-        x will used, otherwise defaults to `~numpy.float32`.
+    >>> padding1d(5, [1, 2, 3])
+    array([1., 2., 3., 0., 0.], dtype=float32)
+    >>> padding1d(5, [1, 2, 3], padding_value=6)
+    array([1., 2., 3., 6., 6.], dtype=float32)
+    >>> padding1d(5, [1, 2, 3], dtype=np.int64)
+    array([1, 2, 3, 0, 0])
+
+    Args:
+        n: Size of vector.
+        v: Input vector.
+        padding_value: Padding value.
+            If x.shape[0] is less than n, the rest will be filled with padding value.
+        dtype: Data type of array.
+            If specify, cast x to dtype, else dtype of x will used, otherwise defaults
+            to `~numpy.float32`.
     """
 
     if not isinstance(v, np.ndarray):