sgptools 1.2.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

sgptools/utils/misc.py

@@ -1,162 +1,196 @@
-from .metrics import get_distance
-
 from scipy.optimize import linear_sum_assignment
 from sklearn.metrics import pairwise_distances
 from scipy.cluster.vq import kmeans2
 from shapely import geometry
 import geopandas as gpd
 
-import matplotlib.pyplot as plt
 import numpy as np
+from typing import Tuple, Optional, Union
 
 
-def get_inducing_pts(data, num_inducing, orientation=False, random=False):
-    """Selects a subset of the data points to be used as inducing points. 
-    The default approach uses kmeans to select the subset. 
+def get_inducing_pts(data: np.ndarray,
+                     num_inducing: int,
+                     orientation: bool = False,
+                     random: bool = False) -> np.ndarray:
+    """
+    Selects a subset of data points to be used as inducing points.
+    By default, it uses k-means clustering to select representative points.
+    Alternatively, it can select points randomly.
+    If `orientation` is True, an additional dimension representing a rotation angle
+    is appended to each inducing point.
 
     Args:
-        data (ndarray): (n, 2); Data points to select the inducing points from 
-        num_inducing (int): Number of inducing points
-        orientation (bool): If True, add an additional dimension to model the sensor 
-                            FoV rotation angle
-        random (bool): If True, the subset of inducing points are selected randomly 
-                       instead of using kmeans
+        data (np.ndarray): (n, d_in); Input data points from which to select inducing points.
+                           `n` is the number of data points, `d_in` is the input dimensionality.
+        num_inducing (int): The desired number of inducing points to select.
+        orientation (bool): If True, a random orientation angle (in radians, from 0 to 2*pi)
+                            is added as an additional dimension to each inducing point.
+                            Defaults to False.
+        random (bool): If True, inducing points are selected randomly from `data`.
+                       If False, k-means clustering (`kmeans2`) is used for selection.
+                       Defaults to False.
 
     Returns:
-        Xu (ndarray): (m, d); Inducing points in the position and orientation space.
-                        `m` is the number of inducing points, 
-                        `d` is the dimension of the space (x, y, optional - angle in radians)
+        np.ndarray: (m, d_out); Inducing points. `m` is `num_inducing`.
+                    `d_out` is `d_in` if `orientation` is False, or `d_in + 1` if `orientation` is True.
+                    If `orientation` is True, the last dimension contains angles in radians.
+
+    Usage:
+        ```python
+        import numpy as np
+        from sgptools.utils.misc import get_inducing_pts
+
+        # Example data (1000 2D points)
+        data_points = np.random.rand(1000, 2) * 100
+
+        # 1. Select 50 inducing points using k-means (default)
+        inducing_points_kmeans = get_inducing_pts(data_points, 50)
+
+        # 2. Select 20 inducing points randomly with orientation
+        inducing_points_random_oriented = get_inducing_pts(data_points, 20, orientation=True, random=True)
+        ```
     """
     if random:
-        idx = np.random.randint(len(data), size=num_inducing)
+        # Randomly select `num_inducing` indices from the data
+        idx = np.random.choice(len(data), size=num_inducing, replace=False)
         Xu = data[idx]
     else:
+        # Use k-means clustering to find `num_inducing` cluster centers
+        # `minit="points"` initializes centroids by picking random data points
         Xu = kmeans2(data, num_inducing, minit="points")[0]
+
     if orientation:
+        # Generate random angles between 0 and 2*pi (radians)
         thetas = np.random.uniform(0, 2 * np.pi, size=(Xu.shape[0], 1))
+        # Concatenate the points with their corresponding angles
         Xu = np.concatenate([Xu, thetas], axis=1)
+
     return Xu
 
-def cont2disc(Xu, candidates, candidate_labels=None):
-    """Map continuous space locations to a discrete set of candidate location
+
+def cont2disc(
+    Xu: np.ndarray,
+    candidates: np.ndarray,
+    candidate_labels: Optional[np.ndarray] = None
+) -> Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
+    """
+    Maps continuous space locations (`Xu`) to the closest points in a discrete
+    set of candidate locations (`candidates`) using a Hungarian algorithm
+    (linear sum assignment) for optimal matching. This ensures each `Xu` point
+    is matched to a unique candidate.
 
     Args:
-        Xu (ndarray): (m, 2); Continuous space points
-        candidates (ndarray): (n, 2); Discrete set of candidate locations
-        candidate_labels (ndarray): (n, 1); Labels corresponding to the discrete set of candidate locations
+        Xu (np.ndarray): (m, d); Continuous space points (e.g., optimized sensor locations).
+                         `m` is the number of points, `d` is the dimensionality.
+        candidates (np.ndarray): (n, d); Discrete set of candidate locations.
+                                 `n` is the number of candidates, `d` is the dimensionality.
+        candidate_labels (Optional[np.ndarray]): (n, 1); Optional labels corresponding to
+                                                the discrete set of candidate locations.
+                                                If provided, the matched labels are also returned.
+                                                Defaults to None.
 
     Returns:
-        Xu_x (ndarray): Discrete space points' locations 
-        Xu_y (ndarray): Labels of the discrete space points. Returned only if `candidate_labels`
-                        was passed to the function
-
+        Union[np.ndarray, Tuple[np.ndarray, np.ndarray]]:
+        - If `candidate_labels` is None:
+            np.ndarray: (m, d); Discrete space points' locations (`Xu_X`),
+                        where each point in `Xu` is mapped to its closest
+                        unique point in `candidates`.
+        - If `candidate_labels` is provided:
+            Tuple[np.ndarray, np.ndarray]: (`Xu_X`, `Xu_y`).
+            `Xu_X` (np.ndarray): (m, d); The matched discrete locations.
+            `Xu_y` (np.ndarray): (m, 1); The labels corresponding to `Xu_X`.
+
+    Usage:
+        ```python
+        import numpy as np
+        from sgptools.utils.misc import cont2disc
+
+        # Example continuous points
+        continuous_points = np.array([[0.1, 0.1], [0.9, 0.9], [0.5, 0.5]])
+        # Example discrete candidates
+        discrete_candidates = np.array([[0.0, 0.0], [1.0, 1.0], [0.4, 0.6]])
+        # Example candidate labels (optional)
+        discrete_labels = np.array([[10.0], [20.0], [15.0]])
+
+        # 1. Map without labels
+        mapped_points = cont2disc(continuous_points, discrete_candidates)
+
+        # 2. Map with labels
+        mapped_points_X, mapped_points_y = cont2disc(continuous_points, discrete_candidates, discrete_labels)
+        ```
     """
-    # Sanity check to ensure that there are sensing locations and candidates to match
-    if len(candidates)==0 or len(Xu)==0:
+    # Sanity check to handle empty inputs gracefully
+    if len(candidates) == 0 or len(Xu) == 0:
         if candidate_labels is not None:
-            return [], []
+            return np.empty((0, Xu.shape[1])), np.empty((0, 1))
         else:
-            return []
-    
+            return np.empty((0, Xu.shape[1]))
+
+    # Compute pairwise Euclidean distances between candidates and Xu
     dists = pairwise_distances(candidates, Y=Xu, metric='euclidean')
-    row_ind, _ = linear_sum_assignment(dists)
+
+    # Use the Hungarian algorithm (linear_sum_assignment) to find the optimal
+    # assignment of rows (candidates) to columns (Xu points) that minimizes
+    # the total cost (distances). `row_ind` gives the indices of the rows
+    # (candidates) chosen, `col_ind` gives the corresponding indices of `Xu`.
+    row_ind, col_ind = linear_sum_assignment(dists)
+
+    # Select the candidate locations that were matched to Xu points
     Xu_X = candidates[row_ind].copy()
+
     if candidate_labels is not None:
+        # If labels are provided, select the corresponding labels as well
         Xu_y = candidate_labels[row_ind].copy()
         return Xu_X, Xu_y
     else:
         return Xu_X
 
-def plot_paths(paths, candidates=None, title=None):
-    """Function to plot the IPP solution paths
 
-    Args:
-        paths (ndarray): (r, m, 2); `r` paths with `m` waypoints each
-        candidates (ndarray): (n, 2); Candidate unlabeled locations used in the SGP-based sensor placement approach
-        title (str): Title of the plot
+def polygon2candidates(vertices: np.ndarray,
+                       num_samples: int = 5000,
+                       random_seed: Optional[int] = None) -> np.ndarray:
     """
-    plt.figure()
-    for i, path in enumerate(paths):
-        plt.plot(path[:, 0], path[:, 1], 
-                    c='r', label='Path', zorder=1, marker='o')
-        plt.scatter(path[0, 0], path[0, 1], 
-                    c='g', label='Start', zorder=2, marker='o')
-        if candidates is not None:
-            plt.scatter(candidates[:, 0], candidates[:, 1], 
-                        c='k', s=1, label='Unlabeled Train-Set Points', zorder=0)
-        if i==0:
-            plt.legend(bbox_to_anchor=(1.0, 1.02))
-    if title is not None:
-        plt.title(title)
-    plt.gca().set_aspect('equal')
-    plt.xlabel('X')
-    plt.ylabel('Y')
-
-def interpolate_path(waypoints, sampling_rate=0.05):
-    """Interpolate additional points between the given waypoints to simulate continuous sensing robots
+    Samples a specified number of candidate points randomly within a polygon defined by its vertices.
+    This function leverages `geopandas` for geometric operations.
 
     Args:
-        waypoints (n, d): Waypoints of the robot's path
-        sampling_rate (float): Distance between each pair of interpolated points
+        vertices (np.ndarray): (v, 2); A NumPy array where each row represents the (x, y)
+                               coordinates of a vertex defining the polygon. `v` is the
+                               number of vertices. The polygon is closed automatically if
+                               the first and last vertices are not identical.
+        num_samples (int): The desired number of candidate points to sample within the polygon.
+                           Defaults to 5000.
+        random_seed (Optional[int]): Seed for reproducibility of the random point sampling.
+                                     Defaults to None.
 
     Returns:
-        path (ndarray): (p, d) Interpolated path, `p` depends on the sampling_rate rate
-    """
-    interpolated_path = []
-    for i in range(2, len(waypoints)+1):
-        dist = get_distance(waypoints[i-2:i])
-        num_samples = int(dist / sampling_rate)
-        points = np.linspace(waypoints[i-1], waypoints[i-2], num_samples)
-        interpolated_path.extend(points)
-    return np.array(interpolated_path)
-
-def _reoder_path(path, waypoints):
-    """Reorder the waypoints to match the order of the points in the path.
-    The waypoints are mathched to the closest points in the path. Used by project_waypoints.
+       np.ndarray: (n, 2); A NumPy array where each row represents the (x, y) coordinates
+                   of a sampled candidate sensor placement location. `n` is `num_samples`.
 
-    Args:
-        path (n, d): Robot path, i.e., waypoints in the path traversal order
-        waypoints (n, d): Waypoints that need to be reordered to match the target path
-
-    Returns:
-        waypoints (n, d): Reordered waypoints of the robot's path
-    """
-    dists = pairwise_distances(path, Y=waypoints, metric='euclidean')
-    _, col_ind = linear_sum_assignment(dists)
-    Xu = waypoints[col_ind].copy()
-    return Xu
-
-def project_waypoints(waypoints, candidates):
-    """Project the waypoints back to the candidate set while retaining the 
-    waypoint visitation order.
+    Usage:
+        ```python
+        import numpy as np
+        # from sgptools.utils.misc import polygon2candidates
 
-    Args:
-        waypoints (n, d): Waypoints of the robot's path
-        candidates (ndarray): (n, 2); Discrete set of candidate locations
+        # Define vertices for a square polygon
+        square_vertices = np.array([[0, 0], [10, 0], [10, 10], [0, 10]])
 
-    Returns:
-        waypoints (n, d): Projected waypoints of the robot's path
+        # Sample 100 candidate points within the square
+        sampled_candidates = polygon2candidates(square_vertices, num_samples=100, random_seed=42)
+        ```
     """
-    waypoints_disc = cont2disc(waypoints, candidates)
-    waypoints_valid = _reoder_path(waypoints, waypoints_disc)
-    return waypoints_valid
+    # Create a shapely Polygon object from the provided vertices
+    poly = geometry.Polygon(vertices)
 
-def ploygon2candidats(vertices, 
-                      num_samples=5000, 
-                      random_seed=2024):
-    """Sample unlabeled candidates within a polygon
+    # Create a GeoSeries containing the polygon, which enables sampling points
+    sampler = gpd.GeoSeries([poly])
 
-    Args:
-        vertices (ndarray): (v, 2) of vertices that define the polygon
-        num_samples (int): Number of samples to generate
-        random_seed (int): Random seed for reproducibility
+    # Sample random points within the polygon
+    candidates_geoseries = sampler.sample_points(
+        size=num_samples,
+        rng=random_seed)  # `rng` is for random number generator seed
 
-    Returns:
-       candidates (ndarray): (n, 2); Candidate sensor placement locations
-    """
-    poly = geometry.Polygon(vertices)
-    sampler = gpd.GeoSeries([poly])
-    candidates = sampler.sample_points(size=num_samples,
-                                       rng=random_seed)
-    candidates = candidates.get_coordinates().to_numpy()
-    return candidates
+    # Extract coordinates from the GeoSeries of points and convert to a NumPy array
+    candidates_array = candidates_geoseries.get_coordinates().to_numpy()
+
+    return candidates_array