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

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):

swcgeom/utils/plotter_2d.py

@@ -15,8 +15,6 @@
 
 """2D Plotting utils."""
 
-from typing import Optional
-
 import matplotlib.pyplot as plt
 import numpy as np
 import numpy.typing as npt
@@ -43,18 +41,14 @@ def draw_lines(
 ) -> LineCollection:
     """Draw lines.
 
-    Parameters
-    ----------
-    ax : ~matplotlib.axes.Axes
-    lines : A collection of coords of lines
-        Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
-        and the axis-3 holds the coordinates (x, y, z).
-    camera : Camera
-        Camera position.
-    **kwargs : dict[str, Unknown]
-        Forwarded to `~matplotlib.collections.LineCollection`.
+    Args:
+        ax: The plot axes.
+        lines: A collection of coords of lines
+            Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
+            and the axis-3 holds the coordinates (x, y, z).
+        camera: Camera position.
+        **kwargs: Forwarded to `~matplotlib.collections.LineCollection`.
     """
-
     T = camera.MVP
     T = translate3d(*camera.position).dot(T)  # keep origin
 
@@ -113,8 +107,8 @@ def draw_circles(
     x: npt.NDArray,
     y: npt.NDArray,
     *,
-    y_min: Optional[float] = None,
-    y_max: Optional[float] = None,
+    y_min: float | None = None,
+    y_max: float | None = None,
     cmap: str | Colormap = "viridis",
 ) -> PatchCollection:
     """Draw a sequential of circles."""
@@ -140,7 +134,7 @@ def draw_circles(
 
 
 def get_fig_ax(
-    fig: Optional[Figure] = None, ax: Optional[Axes] = None
+    fig: Figure | None = None, ax: Axes | None = None
 ) -> tuple[Figure, Axes]:
     if fig is None and ax is not None:
         fig = ax.get_figure()

swcgeom/utils/plotter_3d.py

@@ -32,17 +32,15 @@ def draw_lines_3d(
 ):
     """Draw lines.
 
-    Parameters
-    ----------
-    ax : ~matplotlib.axes.Axes
-    lines : A collection of coords of lines
-        Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
-        and the axis-3 holds the coordinates (x, y, z).
-    **kwargs : dict[str, Unknown]
-        Forwarded to `~mpl_toolkits.mplot3d.art3d.Line3DCollection`.
+    Args:
+        ax: The plot axes.
+        lines: A collection of coords of lines
+            Excepting a ndarray of shape (N, 2, 3), the axis-2 holds two points,
+            and the axis-3 holds the coordinates (x, y, z).
+        **kwargs: Forwarded to `~mpl_toolkits.mplot3d.art3d.Line3DCollection`.
     """
 
     line_collection = Line3DCollection(
         lines, joinstyle=joinstyle, capstyle=capstyle, **kwargs
-    )  # type: ignore
+    )
     return ax.add_collection3d(line_collection)

swcgeom/utils/renderer.py

@@ -48,21 +48,29 @@ class Camera:
     _look_at: Vec3f
     _up: Vec3f
 
-    # fmt: off
     @property
-    def position(self) -> Vec3f:    return self._position
+    def position(self) -> Vec3f:
+        return self._position
+
     @property
-    def look_at(self) -> Vec3f:     return self._look_at
+    def look_at(self) -> Vec3f:
+        return self._look_at
+
     @property
-    def up(self) -> Vec3f:          return self._up
+    def up(self) -> Vec3f:
+        return self._up
 
     @property
-    def MV(self) -> npt.NDArray[np.float32]:    raise NotImplementedError()
+    def MV(self) -> npt.NDArray[np.float32]:
+        raise NotImplementedError()
+
     @property
-    def P(self) -> npt.NDArray[np.float32]:     raise NotImplementedError()
+    def P(self) -> npt.NDArray[np.float32]:
+        raise NotImplementedError()
+
     @property
-    def MVP(self) -> npt.NDArray[np.float32]:   return self.P.dot(self.MV)
-    # fmt: on
+    def MVP(self) -> npt.NDArray[np.float32]:
+        return self.P.dot(self.MV)
 
 
 class SimpleCamera(Camera):

swcgeom/utils/sdf.py

@@ -17,10 +17,8 @@
 
 Refs: https://iquilezles.org/articles/distfunctions/
 
-Note
-----
-This module has been deprecated since v0.14.0, and will be removed in
-the future, use `sdflit` instead.
+NOTE: This module has been deprecated since v0.14.0, and will be removed in the future,
+use `sdflit` instead.
 """
 
 import warnings
@@ -60,15 +58,11 @@ class SDF(ABC):
     def distance(self, p: npt.NDArray[np.float32]) -> npt.NDArray[np.float32]:
         """Calculate signed distance.
 
-        Parmeters
-        ---------
-        p: ArrayLike
-            Hit point p of shape (N, 3).
+        Args:
+            p: Hit point p of shape (N, 3).
 
-        Returns
-        -------
-        distance : npt.NDArray[np.float32]
-            Distance array of shape (3,).
+        Returns:
+            distance: Distance array of shape (3,).
         """
         raise NotImplementedError()
 
@@ -84,11 +78,9 @@ class SDF(ABC):
     def is_in_bounding_box(self, p: npt.NDArray[np.float32]) -> npt.NDArray[np.bool_]:
         """Is p in bounding box.
 
-        Returns
-        -------
-        is_in : npt.NDArray[np.bool_]
-            Array of shape (N,), if bounding box is `None`, `True` will
-            be returned.
+        Returns:
+            is_in: Array of shape (N,).
+                If bounding box is `None`, `True` will be returned.
         """
 
         if self.bounding_box is None:
@@ -285,12 +277,9 @@ class SDFRoundCone(SDF):
     ) -> None:
         """SDF of round cone.
 
-        Parmeters
-        ---------
-        a, b : ArrayLike
-            Coordinates of point A/B of shape (3,).
-        ra, rb : float
-            Radius of point A/B.
+        Args:
+            a, b: Coordinates of point A/B of shape (3,).
+            ra, rb: Radius of point A/B.
         """
 
         self.a = np.array(a, dtype=np.float32)

swcgeom/utils/solid_geometry.py

@@ -28,6 +28,15 @@ __all__ = [
 
 
 def find_unit_vector_on_plane(normal_vec3: npt.NDArray) -> npt.NDArray:
+    """Find a random unit vector on the plane defined by the normal vector.
+
+    >>> normal = np.array([0, 0, 1])
+    >>> u = find_unit_vector_on_plane(normal)
+    >>> np.allclose(np.dot(u, normal), 0)  # Should be perpendicular
+    True
+    >>> np.allclose(np.linalg.norm(u), 1)  # Should be unit length
+    True
+    """
     r = np.random.rand(3)
     r /= np.linalg.norm(r)
     while np.allclose(r, normal_vec3) or np.allclose(r, -normal_vec3):
@@ -45,6 +54,21 @@ def find_sphere_line_intersection(
     line_point_a: npt.NDArray,
     line_point_b: npt.NDArray,
 ) -> list[tuple[float, npt.NDArray[np.float64]]]:
+    """Find intersection points between a sphere and a line.
+
+    >>> center = np.array([0, 0, 0])
+    >>> radius = 1.0
+    >>> p1 = np.array([-2, 0, 0])
+    >>> p2 = np.array([2, 0, 0])
+    >>> intersections = find_sphere_line_intersection(center, radius, p1, p2)
+    >>> len(intersections)
+    2
+    >>> np.allclose(intersections[0][1], [-1, 0, 0])
+    True
+    >>> np.allclose(intersections[1][1], [1, 0, 0])
+    True
+    """
+
     A = np.array(line_point_a)
     B = np.array(line_point_b)
     C = np.array(sphere_center)
@@ -74,8 +98,20 @@ def find_sphere_line_intersection(
 
 
 def project_point_on_line(
-    point_a: npt.ArrayLike, direction_vector: npt.ArrayLike, point_p: npt.ArrayLike
+    point_a: npt.ArrayLike,
+    direction_vector: npt.ArrayLike,
+    point_p: npt.ArrayLike,
 ) -> npt.NDArray:
+    """Project a point onto a line defined by a point and direction vector.
+
+    >>> a = np.array([0, 0, 0])
+    >>> d = np.array([1, 0, 0])
+    >>> p = np.array([1, 1, 0])
+    >>> projection = project_point_on_line(a, d, p)
+    >>> np.allclose(projection, [1, 0, 0])
+    True
+    """
+
     A = np.array(point_a)
     n = np.array(direction_vector)
     P = np.array(point_p)
@@ -86,6 +122,14 @@ def project_point_on_line(
 
 
 def project_vector_on_vector(vec: npt.ArrayLike, target: npt.ArrayLike) -> npt.NDArray:
+    """Project one vector onto another.
+
+    >>> v = np.array([1, 1, 0])
+    >>> t = np.array([1, 0, 0])
+    >>> proj = project_vector_on_vector(v, t)
+    >>> np.allclose(proj, [1, 0, 0])
+    True
+    """
     v = np.array(vec)
     n = np.array(target)
 
@@ -95,8 +139,20 @@ def project_vector_on_vector(vec: npt.ArrayLike, target: npt.ArrayLike) -> npt.N
 
 
 def project_vector_on_plane(
-    vec: npt.ArrayLike, plane_normal_vec: npt.ArrayLike
+    vec: npt.ArrayLike,
+    plane_normal_vec: npt.ArrayLike,
 ) -> npt.NDArray:
+    """Project a vector onto a plane defined by its normal vector.
+
+    >>> v = np.array([1, 1, 1])
+    >>> n = np.array([0, 0, 1])
+    >>> proj = project_vector_on_plane(v, n)
+    >>> np.allclose(proj, [1, 1, 0])  # Z component removed
+    True
+    >>> np.allclose(np.dot(proj, n), 0)  # Should be perpendicular to normal
+    True
+    """
+
     v = np.array(vec)
     n = np.array(plane_normal_vec)