allocator 1.0.0__py3-none-any.whl

allocator/__init__.py

@@ -0,0 +1,154 @@
+"""
+Allocator v1.0: Optimally Allocate Geographically Distributed Tasks
+
+A modern Python package for geographic task allocation, clustering, and routing optimization.
+
+Key Features:
+- Cluster geographic points into balanced groups
+- Find optimal routes through locations (TSP solving)
+- Assign points to closest workers/centers
+- Multiple distance metrics (euclidean, haversine, OSRM, Google Maps)
+- Clean API with structured results and rich metadata
+- Unified CLI with beautiful terminal output
+
+Quick Start:
+    >>> import allocator
+    >>> import pandas as pd
+    >>>
+    >>> # Create sample data
+    >>> data = pd.DataFrame({
+    ...     'longitude': [101.0, 101.1, 101.2],
+    ...     'latitude': [13.0, 13.1, 13.2]
+    ... })
+    >>>
+    >>> # Cluster locations
+    >>> result = allocator.cluster(data, n_clusters=2)
+    >>> print(result.labels)
+    >>>
+    >>> # Find optimal route
+    >>> route = allocator.shortest_path(data, method='ortools')
+    >>> print(route.route)
+
+For more examples: https://geosensing.github.io/allocator/
+"""
+
+import logging
+import sys
+
+# Import modern API
+from .api import (
+    ClusterResult,
+    ComparisonResult,
+    RouteResult,
+    SortResult,
+    assign_to_closest,
+    cluster,
+    distance_assignment,
+    kmeans,
+    shortest_path,
+    sort_by_distance,
+    tsp_christofides,
+    tsp_google,
+    tsp_ortools,
+    tsp_osrm,
+)
+
+# Import utilities for advanced users
+from .distances import (
+    euclidean_distance_matrix,
+    get_distance_matrix,
+    google_distance_matrix,
+    haversine_distance_matrix,
+    latlon2xy,
+    osrm_distance_matrix,
+    xy2latlog,
+)
+
+# Import visualization functions
+from .viz.plotting import plot_assignments, plot_clusters, plot_comparison, plot_route
+
+# Version
+__version__ = "1.0.0"
+
+# Export public API
+__all__ = [
+    # Result types
+    "ClusterResult",
+    "ComparisonResult",
+    "RouteResult",
+    "SortResult",
+    "assign_to_closest",
+    # Main functions
+    "cluster",
+    "distance_assignment",
+    "euclidean_distance_matrix",
+    # Distance utilities
+    "get_distance_matrix",
+    "get_logger",
+    "google_distance_matrix",
+    "haversine_distance_matrix",
+    # Specific methods
+    "kmeans",
+    "latlon2xy",
+    "osrm_distance_matrix",
+    "plot_assignments",
+    # Visualization
+    "plot_clusters",
+    "plot_comparison",
+    "plot_route",
+    # Logging utilities
+    "setup_logging",
+    "shortest_path",
+    "sort_by_distance",
+    "tsp_christofides",
+    "tsp_google",
+    "tsp_ortools",
+    "tsp_osrm",
+    "xy2latlog",
+]
+
+
+def setup_logging(level=logging.INFO):
+    """
+    Set up logging configuration for the allocator package.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR)
+    """
+    # Create formatter
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+    # Get root logger for allocator package
+    logger = logging.getLogger("allocator")
+    logger.setLevel(level)
+
+    # Remove existing handlers to avoid duplicates
+    for handler in logger.handlers[:]:
+        logger.removeHandler(handler)
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+
+    return logger
+
+
+def get_logger(name):
+    """
+    Get a logger instance for a specific module.
+
+    Args:
+        name: Module name (typically __name__)
+
+    Returns:
+        Logger instance
+    """
+    return logging.getLogger(f"allocator.{name}")
+
+
+# Set up default logging
+setup_logging()

allocator/api/__init__.py

@@ -0,0 +1,32 @@
+"""
+Public API for allocator package.
+
+This module provides a modern, Pythonic interface to the allocator package.
+"""
+
+from .cluster import cluster, kmeans
+from .distance import assign_to_closest, distance_assignment, sort_by_distance
+from .route import shortest_path, tsp_christofides, tsp_google, tsp_ortools, tsp_osrm
+from .types import ClusterResult, ComparisonResult, RouteResult, SortResult
+
+__all__ = [
+    # Result types
+    "ClusterResult",
+    "ComparisonResult",
+    "RouteResult",
+    "SortResult",
+    # Distance assignment methods
+    "assign_to_closest",
+    # Main high-level functions
+    "cluster",
+    "distance_assignment",
+    # Specific clustering methods
+    "kmeans",
+    "shortest_path",
+    "sort_by_distance",
+    # Specific routing methods
+    "tsp_christofides",
+    "tsp_google",
+    "tsp_ortools",
+    "tsp_osrm",
+]

allocator/api/cluster.py

@@ -0,0 +1,126 @@
+"""
+Modern clustering API for allocator package.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from ..core.algorithms import kmeans_cluster as _kmeans_cluster
+from ..io.data_handler import DataHandler
+from .types import ClusterResult
+
+
+def cluster(
+    data: str | pd.DataFrame | np.ndarray | list,
+    n_clusters: int = 3,
+    method: str = "kmeans",
+    distance: str = "euclidean",
+    random_state: int | None = None,
+    **kwargs,
+) -> ClusterResult:
+    """
+    Cluster geographic data points.
+
+    Args:
+        data: Input data (file path, DataFrame, numpy array, or list)
+        n_clusters: Number of clusters to create
+        method: Clustering method ('kmeans')
+        distance: Distance metric ('euclidean', 'haversine', 'osrm', 'google')
+        random_state: Random seed for reproducibility
+        **kwargs: Additional arguments for specific methods
+
+    Returns:
+        ClusterResult with labels, centroids, and metadata
+
+    Example:
+        >>> result = cluster('data.csv', n_clusters=5, method='kmeans')
+        >>> print(result.labels)  # Cluster assignments
+        >>> print(result.centroids)  # Cluster centers
+    """
+    # Load and standardize data
+    df = DataHandler.load_data(data)
+
+    if method == "kmeans":
+        return kmeans(
+            df, n_clusters=n_clusters, distance=distance, random_state=random_state, **kwargs
+        )
+    else:
+        raise ValueError(f"Unknown clustering method: {method}. Available methods: 'kmeans'")
+
+
+def kmeans(
+    data: pd.DataFrame | np.ndarray | list,
+    n_clusters: int = 3,
+    distance: str = "euclidean",
+    max_iter: int = 300,
+    random_state: int | None = None,
+    **kwargs,
+) -> ClusterResult:
+    """
+    K-means clustering of geographic data.
+
+    Args:
+        data: Input data as DataFrame or numpy array
+        n_clusters: Number of clusters
+        distance: Distance metric ('euclidean', 'haversine', 'osrm', 'google')
+        max_iter: Maximum iterations
+        random_state: Random seed for reproducibility
+        **kwargs: Additional distance-specific arguments
+
+    Returns:
+        ClusterResult with clustering information
+    """
+    # Ensure we have a DataFrame for output
+    if isinstance(data, np.ndarray):
+        df = DataHandler._from_numpy(data)
+    elif isinstance(data, list):
+        df = DataHandler._from_list(data)
+    elif isinstance(data, (str, Path)):
+        df = DataHandler.load_data(data)
+    else:
+        df = data.copy()
+
+    # Run clustering algorithm
+    result = _kmeans_cluster(
+        df,
+        n_clusters=n_clusters,
+        distance_method=distance,
+        max_iter=max_iter,
+        random_state=random_state,
+        **kwargs,
+    )
+
+    # Add cluster assignments to DataFrame
+    df_result = df.copy()
+    df_result["cluster"] = result["labels"]
+
+    # Calculate inertia (sum of squared distances to centroids)
+    inertia = None
+    if distance == "euclidean":
+        from ..distances import euclidean_distance_matrix
+
+        coords = df[["longitude", "latitude"]].values
+        distances = euclidean_distance_matrix(coords, result["centroids"])
+        inertia = np.sum(
+            [distances[i, result["labels"][i]] ** 2 for i in range(len(result["labels"]))]
+        )
+
+    return ClusterResult(
+        labels=result["labels"],
+        centroids=result["centroids"],
+        n_iter=result["iterations"],
+        inertia=inertia,
+        data=df_result,
+        converged=result["converged"],
+        metadata={
+            "method": "kmeans",
+            "distance": distance,
+            "n_clusters": n_clusters,
+            "max_iter": max_iter,
+            "random_state": random_state,
+        },
+    )

allocator/api/distance.py

@@ -0,0 +1,225 @@
+"""
+Modern distance-based assignment API for allocator package.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ..core.algorithms import sort_by_distance_assignment
+from ..io.data_handler import DataHandler
+from .types import SortResult
+
+
+def sort_by_distance(
+    points: str | pd.DataFrame | np.ndarray | list,
+    workers: str | pd.DataFrame | np.ndarray | list,
+    by_worker: bool = False,
+    distance: str = "euclidean",
+    **kwargs,
+) -> SortResult:
+    """
+    Sort points by distance to workers or vice versa.
+
+    Args:
+        points: Geographic points to assign (file path, DataFrame, numpy array, or list)
+        workers: Worker/centroid locations (file path, DataFrame, numpy array, or list)
+        by_worker: If True, sort points by worker; if False, sort workers by point
+        distance: Distance metric ('euclidean', 'haversine', 'osrm', 'google')
+        **kwargs: Additional distance-specific arguments
+
+    Returns:
+        SortResult with assignments and distance information
+
+    Example:
+        >>> result = sort_by_distance('points.csv', 'workers.csv')
+        >>> print(result.data)  # Points with worker assignments
+    """
+    # Load and standardize data
+    points_df = DataHandler.load_data(points)
+    workers_df = DataHandler.load_data(workers)
+
+    if by_worker:
+        return _sort_points_by_worker(points_df, workers_df, distance=distance, **kwargs)
+    else:
+        return _sort_workers_by_point(points_df, workers_df, distance=distance, **kwargs)
+
+
+def _sort_workers_by_point(
+    points_df: pd.DataFrame, workers_df: pd.DataFrame, distance: str = "euclidean", **kwargs
+) -> SortResult:
+    """Sort workers by distance to each point (default behavior)."""
+    from ..distances import get_distance_matrix
+
+    # Extract coordinates
+    points_coords = _extract_coordinates(points_df)
+    workers_coords = _extract_coordinates(workers_df)
+
+    # Calculate distance matrix
+    distance_matrix = get_distance_matrix(points_coords, workers_coords, method=distance, **kwargs)
+
+    # Create result DataFrame
+    result_data = []
+    for i, (_, point_row) in enumerate(points_df.iterrows()):
+        point_distances = distance_matrix[i, :]
+        sorted_worker_indices = np.argsort(point_distances)
+
+        for rank, worker_idx in enumerate(sorted_worker_indices):
+            worker_row = workers_df.iloc[worker_idx]
+            result_row = {
+                "point_id": i,
+                "worker_id": worker_idx,
+                "rank": rank + 1,
+                "distance": point_distances[worker_idx],
+            }
+            # Add point data
+            for col in points_df.columns:
+                result_row[f"point_{col}"] = point_row[col]
+            # Add worker data
+            for col in workers_df.columns:
+                result_row[f"worker_{col}"] = worker_row[col]
+            result_data.append(result_row)
+
+    result_df = pd.DataFrame(result_data)
+
+    return SortResult(
+        data=result_df,
+        distance_matrix=distance_matrix,
+        metadata={
+            "method": "sort_workers_by_point",
+            "distance": distance,
+            "n_points": len(points_df),
+            "n_workers": len(workers_df),
+        },
+    )
+
+
+def _sort_points_by_worker(
+    points_df: pd.DataFrame, workers_df: pd.DataFrame, distance: str = "euclidean", **kwargs
+) -> SortResult:
+    """Sort points by distance to each worker."""
+    from ..distances import get_distance_matrix
+
+    # Extract coordinates
+    points_coords = _extract_coordinates(points_df)
+    workers_coords = _extract_coordinates(workers_df)
+
+    # Calculate distance matrix
+    distance_matrix = get_distance_matrix(points_coords, workers_coords, method=distance, **kwargs)
+
+    # Create result DataFrame
+    result_data = []
+    for j, (_, worker_row) in enumerate(workers_df.iterrows()):
+        worker_distances = distance_matrix[:, j]
+        sorted_point_indices = np.argsort(worker_distances)
+
+        for rank, point_idx in enumerate(sorted_point_indices):
+            point_row = points_df.iloc[point_idx]
+            result_row = {
+                "worker_id": j,
+                "point_id": point_idx,
+                "rank": rank + 1,
+                "distance": worker_distances[point_idx],
+            }
+            # Add worker data
+            for col in workers_df.columns:
+                result_row[f"worker_{col}"] = worker_row[col]
+            # Add point data
+            for col in points_df.columns:
+                result_row[f"point_{col}"] = point_row[col]
+            result_data.append(result_row)
+
+    result_df = pd.DataFrame(result_data)
+
+    return SortResult(
+        data=result_df,
+        distance_matrix=distance_matrix,
+        metadata={
+            "method": "sort_points_by_worker",
+            "distance": distance,
+            "n_points": len(points_df),
+            "n_workers": len(workers_df),
+        },
+    )
+
+
+def distance_assignment(
+    points: str | pd.DataFrame | np.ndarray | list,
+    workers: str | pd.DataFrame | np.ndarray | list,
+    distance: str = "euclidean",
+    **kwargs,
+) -> SortResult:
+    """
+    Assign each point to its closest worker (alias for assign_to_closest).
+
+    Args:
+        points: Geographic points to assign
+        workers: Worker/centroid locations
+        distance: Distance metric
+        **kwargs: Additional distance-specific arguments
+
+    Returns:
+        SortResult with point assignments
+    """
+    return assign_to_closest(points, workers, distance=distance, **kwargs)
+
+
+def assign_to_closest(
+    points: str | pd.DataFrame | np.ndarray | list,
+    workers: str | pd.DataFrame | np.ndarray | list,
+    distance: str = "euclidean",
+    **kwargs,
+) -> SortResult:
+    """
+    Assign each point to its closest worker.
+
+    Args:
+        points: Geographic points to assign
+        workers: Worker/centroid locations
+        distance: Distance metric
+        **kwargs: Additional distance-specific arguments
+
+    Returns:
+        SortResult with point assignments
+    """
+    # Load and standardize data
+    points_df = DataHandler.load_data(points)
+    workers_df = DataHandler.load_data(workers)
+
+    # Extract coordinates
+    workers_coords = _extract_coordinates(workers_df)
+
+    # Get assignments using core algorithm
+    labels = sort_by_distance_assignment(
+        points_df, workers_coords, distance_method=distance, **kwargs
+    )
+
+    # Create result DataFrame
+    result_df = points_df.copy()
+    result_df["assigned_worker"] = labels
+
+    # Add worker info
+    for i, label in enumerate(labels):
+        worker_row = workers_df.iloc[label]
+        for col in workers_df.columns:
+            result_df.loc[i, f"worker_{col}"] = worker_row[col]
+
+    return SortResult(
+        data=result_df,
+        distance_matrix=None,
+        metadata={
+            "method": "assign_to_closest",
+            "distance": distance,
+            "n_points": len(points_df),
+            "n_workers": len(workers_df),
+        },
+    )
+
+
+def _extract_coordinates(df: pd.DataFrame) -> np.ndarray:
+    """Extract longitude/latitude coordinates from DataFrame."""
+    if "longitude" in df.columns and "latitude" in df.columns:
+        return df[["longitude", "latitude"]].values
+    else:
+        raise ValueError("DataFrame must contain 'longitude' and 'latitude' columns")