Improved docstrings

Author: lucasimi

src/tdamapper/app.py

@@ -533,7 +533,7 @@ def _init_draw_settings(self):
         ).classes("w-full")
 
     def _init_footnotes(self):
-        ui.label(text=("Made in Rome, with ❤️ and ☕️.")).classes(
+        ui.label(text="Made in Rome, with ❤️ and ☕️.").classes(
             "text-caption text-gray-500"
         ).classes("text-caption text-gray-500")
 
@@ -543,7 +543,7 @@ def _init_draw_area(self):
 
     def get_mapper_config(self):
         return MapperConfig(
-            lens_type=str(self.lens_type.value) if self.lens_type.value else LENS_PCA,
+            lens_type=(str(self.lens_type.value) if self.lens_type.value else LENS_PCA),
             cover_type=(
                 str(self.cover_type.value) if self.cover_type.value else COVER_CUBICAL
             ),

src/tdamapper/core.py

@@ -31,7 +31,16 @@
 from __future__ import annotations
 
 import logging
-from typing import Any, Callable, Dict, Generator, List, Optional, Protocol, Union
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Generator,
+    List,
+    Optional,
+    Protocol,
+    Union,
+)
 
 import networkx as nx
 import numpy as np

src/tdamapper/cover.py

@@ -19,7 +19,12 @@
 
 from tdamapper._common import ParamsMixin
 from tdamapper.core import ArrayLike, PointLike, SpatialSearch
-from tdamapper.search import BallSearch, CubicalLandmarks, CubicalSearch, KNNSearch
+from tdamapper.search import (
+    BallSearch,
+    CubicalLandmarks,
+    CubicalSearch,
+    KNNSearch,
+)
 
 
 class ProximityNet(ABC, ParamsMixin):
@@ -454,13 +459,11 @@ def _get_cubical_cover(self):
         )
         if self.algorithm == "proximity":
             return ProximityCubicalCover(**params)
-        elif self.algorithm == "standard":
+        if self.algorithm == "standard":
             return StandardCubicalCover(**params)
-        else:
-            raise ValueError(
-                "The only possible values for algorithm are 'standard' and "
-                "'proximity'."
-            )
+        raise ValueError(
+            "The only possible values for algorithm are 'standard' and 'proximity'."
+        )
 
     def fit(self, X: ArrayLike) -> CubicalCover:
         """

src/tdamapper/heap.py

@@ -152,7 +152,10 @@ def _fix_down(self, i: int) -> int:
     def _fix_up(self, i: int) -> int:
         parent = _parent(i)
         if self._heap[parent] < self._heap[i]:
-            self._heap[i], self._heap[parent] = self._heap[parent], self._heap[i]
+            self._heap[i], self._heap[parent] = (
+                self._heap[parent],
+                self._heap[i],
+            )
             return parent
         return i
 

src/tdamapper/metrics.py

@@ -31,12 +31,25 @@
 
 import numpy as np
 
-import tdamapper._metrics as _metrics
+from tdamapper._metrics import (
+    chebyshev as _chebyshev,
+    cosine as _cosine,
+    euclidean as _euclidean,
+    manhattan as _manhattan,
+    minkowski as _minkowski,
+)
 
 _MINKOWSKI_P = "p"
 
 
 class Metric(str, Enum):
+    """
+    Enum representing supported distance metrics.
+
+    Each metric corresponds to a specific distance function that can be
+    used to compute distances between vectors.
+    """
+
     EUCLIDEAN = "euclidean"
     MANHATTAN = "manhattan"
     MINKOWSKI = "minkowski"
@@ -54,7 +67,7 @@ def euclidean(*args, **kwargs) -> Callable:
     :return: The Euclidean distance function.
     :rtype: callable
     """
-    return _metrics.euclidean
+    return _euclidean
 
 
 def manhattan(*args, **kwargs) -> Callable:
@@ -67,7 +80,7 @@ def manhattan(*args, **kwargs) -> Callable:
     :return: The Manhattan distance function.
     :rtype: callable
     """
-    return _metrics.manhattan
+    return _manhattan
 
 
 def chebyshev(*args, **kwargs) -> Callable:
@@ -80,7 +93,7 @@ def chebyshev(*args, **kwargs) -> Callable:
     :return: The Chebyshev distance function.
     :rtype: callable
     """
-    return _metrics.chebyshev
+    return _chebyshev
 
 
 def minkowski(*args, **kwargs) -> Callable:
@@ -105,7 +118,7 @@ def minkowski(*args, **kwargs) -> Callable:
         return chebyshev()
 
     def dist(x, y):
-        return _metrics.minkowski(p, x, y)
+        return _minkowski(p, x, y)
 
     return dist
 
@@ -129,7 +142,7 @@ def cosine(*args, **kwargs) -> Callable:
     :return: The cosine distance function.
     :rtype: callable
     """
-    return _metrics.cosine
+    return _cosine
 
 
 def _get_supported_metrics() -> List[str]:
@@ -152,13 +165,13 @@ def get_metric_function(metric: Metric, *args, **kwargs) -> Callable:
     """
     if metric == Metric.EUCLIDEAN:
         return euclidean(*args, **kwargs)
-    elif metric == Metric.MANHATTAN:
+    if metric == Metric.MANHATTAN:
         return manhattan(*args, **kwargs)
-    elif metric == Metric.MINKOWSKI:
+    if metric == Metric.MINKOWSKI:
         return minkowski(*args, **kwargs)
-    elif metric == Metric.CHEBYSHEV:
+    if metric == Metric.CHEBYSHEV:
         return chebyshev(*args, **kwargs)
-    elif metric == Metric.COSINE:
+    if metric == Metric.COSINE:
         return cosine(*args, **kwargs)
     raise ValueError(
         f"Unsupported metric: {metric}. "

src/tdamapper/plot_plotly.py

@@ -86,53 +86,46 @@ def _to_cmaps(cmap: Optional[Union[str, List[str]]]) -> List[str]:
         return [DEFAULT_CMAP]
     if isinstance(cmap, str):
         return [cmap]
-    elif isinstance(cmap, list):
+    if isinstance(cmap, list):
         return cmap
-    else:
-        raise ValueError(f"Invalid cmap type: {type(cmap)}. Expected str or list[str].")
+    raise ValueError(f"Invalid cmap type: {type(cmap)}. Expected str or list[str].")
 
 
 def _to_colors(colors: Union[np.ndarray, List[float]]) -> np.ndarray:
     """Convert colors to a numpy array."""
     colors_arr = np.array(colors)
     if colors_arr.ndim == 1:
         return colors_arr.reshape(-1, 1)
-    elif colors_arr.ndim == 2:
+    if colors_arr.ndim == 2:
         return colors_arr
-    else:
-        raise ValueError(
-            f"Invalid colors shape: {colors_arr.shape}. Expected 1D or 2D array."
-        )
+    raise ValueError(
+        f"Invalid colors shape: {colors_arr.shape}. Expected 1D or 2D array."
+    )
 
 
 def _to_titles(title: Optional[Union[str, List[str]]], colors_num: int) -> List[str]:
     if title is None:
         return [f"{i}" for i in range(colors_num)]
-    elif isinstance(title, str):
+    if isinstance(title, str):
         if colors_num == 1:
             return [title]
-        else:
-            return [f"{title} [{i}]" for i in range(colors_num)]
-    elif isinstance(title, list) and len(title) == colors_num:
+        return [f"{title} [{i}]" for i in range(colors_num)]
+    if isinstance(title, list) and len(title) == colors_num:
         return title
-    else:
-        raise ValueError(
-            f"Invalid title type: {type(title)}. Expected str or list[str]."
-        )
+    raise ValueError(f"Invalid title type: {type(title)}. Expected str or list[str].")
 
 
 def _to_node_sizes(
     node_size: Optional[Union[int, float, List[Union[int, float]]]],
 ) -> List[float]:
     if isinstance(node_size, (int, float)):
         return [node_size]
-    elif isinstance(node_size, list):
+    if isinstance(node_size, list):
         return node_size
-    else:
-        raise ValueError(
-            f"Invalid node_size type: {type(node_size)}. "
-            "Expected int, float or list[int, float]."
-        )
+    raise ValueError(
+        f"Invalid node_size type: {type(node_size)}. "
+        "Expected int, float or list[int, float]."
+    )
 
 
 def _get_cmap_rgb(cmap: str):
@@ -152,6 +145,19 @@ def plot_plotly(
     width: Optional[int] = None,
     height: Optional[int] = None,
 ) -> go.Figure:
+    """
+    Plot a Mapper graph using Plotly.
+
+    :param mapper_plot: The Mapper plot object containing the graph and positions.
+    :param colors: Colors for the nodes, can be a 1D or 2D numpy array or a list.
+    :param node_size: Size of the nodes, can be a single value or a list of values.
+    :param title: Title for the color bar, can be a string or a list of strings.
+    :param agg: Aggregation function to apply to the colors, defaults to np.nanmean.
+    :param cmap: Colormap to use for the nodes, can be a string or a list of strings.
+    :param width: Width of the plot, defaults to None (auto).
+    :param height: Height of the plot, defaults to None (auto).
+    :return: A Plotly Figure object containing the Mapper graph.
+    """
     cmaps = _to_cmaps(cmap)
     colors = _to_colors(colors)
     colors_num = colors.shape[1]

src/tdamapper/vptree_flat/ball_search.py

@@ -1,9 +1,10 @@
 """
 VP-tree Ball Search Module.
 
-This module provides a BallSearch class for searching points within a specified distance (epsilon)
-from a given point in a VP-tree. It uses an iterative approach to traverse the VP-tree
-and collect points that meet the distance criteria.
+This module provides a BallSearch class for searching points within a specified
+distance (epsilon) from a given point in a VP-tree. It uses an iterative
+approach to traverse the VP-tree and collect points that meet the distance
+criteria.
 """
 
 from typing import Generic, List, TypeVar
@@ -18,16 +19,16 @@ class BallSearch(Generic[T]):
     BallSearch class for searching points within a specified distance (epsilon)
     from a given point in a VP-tree.
 
-    This class performs a search in a VP-tree to find all points that are within
-    a specified distance (epsilon) from a given point. It uses an iterative
-    approach to traverse the VP-tree and collect points that meet the distance
-    criteria.
+    This class performs a search in a VP-tree to find all points that are
+    within a specified distance (epsilon) from a given point. It uses an
+    iterative approach to traverse the VP-tree and collect points that meet the
+    distance criteria.
 
     :param vpt: VPTreeType instance containing distance function and parameters.
     :param point: The point from which the search is performed.
     :param eps: The distance threshold (epsilon) for the search.
-    :param inclusive: If True, points exactly at distance eps are included in the
-        results. If False, they are excluded. Defaults to True.
+    :param inclusive: If True, points exactly at distance eps are included in
+        the results. If False, they are excluded. Defaults to True.
     """
 
     def __init__(
@@ -45,13 +46,14 @@ def __init__(
 
     def search(self) -> List[T]:
         """
-        Perform the search for points within the specified distance from the point.
+        Perform the search for points within the specified distance from the
+        point.
 
         This method initiates the search process and returns a list of points
         that are within the specified distance (epsilon) from the given point.
 
-        :return: A list of points that are within the specified distance from the
-            given point.
+        :return: A list of points that are within the specified distance from
+            the given point.
         """
         return self._search_iter()
 

src/tdamapper/vptree_flat/builder.py

@@ -1,7 +1,9 @@
 """
-VP-tree Builder Module
-This module provides a Builder class for constructing a VP-tree from a collection of items.
-It supports different pivoting strategies and allows customization of the tree's parameters.
+VP-tree Builder Module.
+
+This module provides a Builder class for constructing a VP-tree from a
+collection of items. It supports different pivoting strategies and allows
+customization of the tree's parameters.
 """
 
 from __future__ import annotations
@@ -25,10 +27,11 @@ class Builder(Generic[T]):
     """
     Builder for constructing a VP-tree from a collection of items.
 
-    This class takes a VPTreeType and an iterable of items, and builds a VP-tree
-    using the specified pivoting strategy and parameters.
+    This class takes a VPTreeType and an iterable of items, and builds a
+    VP-tree using the specified pivoting strategy and parameters.
 
-    :param vpt: VPTreeType instance containing distance function and parameters.
+    :param vpt: VPTreeType instance containing distance function and
+        parameters.
     :param items: Iterable of items to be included in the VP-tree.
     """
 
@@ -92,9 +95,12 @@ def _update(self, start: int, end: int) -> None:
 
     def build(self) -> VPArray[T]:
         """
-        Build the VP-tree from the given items.
+        Build the VP-tree from the items provided during initialization.
+
+        This method constructs the VP-tree iteratively, starting from the root
+        node.
 
-        :return: VPArray containing the VP-tree structure.
+        :return: The VPArray instance containing the constructed VP-tree.
         """
         self._build_iter()
         return self._arr

src/tdamapper/vptree_flat/common.py

@@ -1,8 +1,23 @@
-""" """
+"""
+Common types and structures for VP-tree implementation.
+
+This module defines the basic types and structures used in the VP-tree
+implementation, including the VPArray for managing the dataset and distances,
+the Node and Leaf classes for representing the tree structure, and the
+VPTreeType protocol for type checking.
+"""
 
 from __future__ import annotations
 
-from typing import Callable, Generic, Iterable, List, Optional, Protocol, TypeVar
+from typing import (
+    Callable,
+    Generic,
+    Iterable,
+    List,
+    Optional,
+    Protocol,
+    TypeVar,
+)
 
 import numpy as np
 from numpy.typing import NDArray
@@ -78,7 +93,7 @@ class VPArray(Generic[T]):
     :param dataset: A list of points of type T.
     :param distances: A NumPy array of distances corresponding to the points.
     :param indices: A NumPy array of indices mapping points to their positions
-        in the dataset
+        in the dataset.
     :param is_terminal: A NumPy array indicating whether each point is terminal
         (True) or not (False). A terminal point is a leaf node in the VP-tree.
         It is used to determine if a point is a leaf node in the VP-tree.