allocator 0.1.7__tar.gz → 1.0.0__tar.gz

allocator-1.0.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: allocator
+Version: 1.0.0
+Summary: Modern Python package for geographic task allocation, clustering, and routing optimization
+Keywords: geographic,allocation,clustering,routing,optimization,tsp,kmeans,geospatial,logistics,shortest-path
+Author: Suriyan Laohaprapanon, Gaurav Sood
+Author-email: Suriyan Laohaprapanon <suriyant@gmail.com>, Gaurav Sood <gsood07@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: utm>=0.7.0
+Requires-Dist: haversine>=2.8.0
+Requires-Dist: networkx>=3.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: googlemaps>=4.6.0
+Requires-Dist: ortools>=9.5.0
+Requires-Dist: matplotlib>=3.6.0
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: scipy>=1.10.0 ; extra == 'algorithms'
+Requires-Dist: christofides>=1.0.0 ; extra == 'algorithms'
+Requires-Dist: allocator[algorithms,geo] ; extra == 'all'
+Requires-Dist: allocator[all,dev,test,docs] ; extra == 'complete'
+Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.5.0 ; extra == 'dev'
+Requires-Dist: black>=23.0.0 ; extra == 'dev'
+Requires-Dist: isort>=5.12.0 ; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0 ; extra == 'dev'
+Requires-Dist: sphinx>=7.0.0 ; extra == 'docs'
+Requires-Dist: furo>=2023.9.10 ; extra == 'docs'
+Requires-Dist: myst-parser>=2.0.0 ; extra == 'docs'
+Requires-Dist: linkify-it-py>=2.0.0 ; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints>=1.24.0 ; extra == 'docs'
+Requires-Dist: sphinx-design>=0.5.0 ; extra == 'docs'
+Requires-Dist: folium>=0.14.0 ; extra == 'geo'
+Requires-Dist: polyline>=2.0.0 ; extra == 'geo'
+Requires-Dist: pytest>=7.4.0 ; extra == 'test'
+Requires-Dist: pytest-cov>=4.1.0 ; extra == 'test'
+Requires-Dist: pytest-xdist>=3.3.0 ; extra == 'test'
+Requires-Dist: coverage>=7.2.0 ; extra == 'test'
+Requires-Dist: hypothesis>=6.82.0 ; extra == 'test'
+Maintainer: Gaurav Sood
+Maintainer-email: Gaurav Sood <gsood07@gmail.com>
+Requires-Python: >=3.11
+Project-URL: Bug Reports, https://github.com/geosensing/allocator/issues
+Project-URL: Changelog, https://github.com/geosensing/allocator/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://geosensing.github.io/allocator/
+Project-URL: Homepage, https://github.com/geosensing/allocator
+Project-URL: Repository, https://github.com/geosensing/allocator.git
+Project-URL: Source Code, https://github.com/geosensing/allocator
+Provides-Extra: algorithms
+Provides-Extra: all
+Provides-Extra: complete
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: geo
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# allocator: Efficiently collect data from geographically distributed locations
+
+[![PyPI version](https://img.shields.io/pypi/v/allocator.svg)](https://pypi.python.org/pypi/allocator)
+[![Downloads](https://pepy.tech/badge/allocator)](https://pepy.tech/project/allocator)
+[![CI](https://github.com/geosensing/allocator/actions/workflows/ci.yml/badge.svg)](https://github.com/geosensing/allocator/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-github.io-blue)](https://geosensing.github.io/allocator/)
+
+**Allocator** provides a modern, Pythonic API for geographic task allocation, clustering, and routing optimization.
+
+## Key Features
+
+- **🎯 Clustering**: Group geographic points into balanced zones
+- **🛣️ Routing**: Find optimal paths through locations (TSP solving)  
+- **📍 Assignment**: Connect points to closest workers/centers
+- **🚀 Performance**: Optimized algorithms with NumPy and scikit-learn
+- **📦 Modern API**: Clean Python interface + unified CLI
+
+## Quick Start
+
+```bash
+pip install allocator
+```
+
+```python
+import allocator
+import pandas as pd
+
+# Geographic locations
+locations = pd.DataFrame({
+    'longitude': [100.5018, 100.5065, 100.5108],
+    'latitude': [13.7563, 13.7590, 13.7633]
+})
+
+# Group into zones
+clusters = allocator.cluster(locations, n_clusters=2)
+
+# Find optimal route
+route = allocator.shortest_path(locations)
+
+# Assign to service centers
+centers = pd.DataFrame({
+    'longitude': [100.50, 100.52],
+    'latitude': [13.75, 13.77]
+})
+assignments = allocator.assign(locations, centers)
+```
+
+## Documentation & Examples
+
+- **📖 [Full Documentation](https://geosensing.github.io/allocator/)**
+- **🚀 [Installation & Tutorial](https://geosensing.github.io/allocator/quickstart.html)**  
+- **🔧 [API Reference](https://geosensing.github.io/allocator/api/clustering.html)**
+- **💡 [Real-World Examples](https://geosensing.github.io/allocator/examples/overview.html)**
+
+## License & Contributing
+
+MIT License. Contributions welcome - see [Contributing Guide](https://geosensing.github.io/allocator/contributing.html).

allocator-1.0.0/README.md

@@ -0,0 +1,57 @@
+# allocator: Efficiently collect data from geographically distributed locations
+
+[![PyPI version](https://img.shields.io/pypi/v/allocator.svg)](https://pypi.python.org/pypi/allocator)
+[![Downloads](https://pepy.tech/badge/allocator)](https://pepy.tech/project/allocator)
+[![CI](https://github.com/geosensing/allocator/actions/workflows/ci.yml/badge.svg)](https://github.com/geosensing/allocator/actions/workflows/ci.yml)
+[![Documentation](https://img.shields.io/badge/docs-github.io-blue)](https://geosensing.github.io/allocator/)
+
+**Allocator** provides a modern, Pythonic API for geographic task allocation, clustering, and routing optimization.
+
+## Key Features
+
+- **🎯 Clustering**: Group geographic points into balanced zones
+- **🛣️ Routing**: Find optimal paths through locations (TSP solving)  
+- **📍 Assignment**: Connect points to closest workers/centers
+- **🚀 Performance**: Optimized algorithms with NumPy and scikit-learn
+- **📦 Modern API**: Clean Python interface + unified CLI
+
+## Quick Start
+
+```bash
+pip install allocator
+```
+
+```python
+import allocator
+import pandas as pd
+
+# Geographic locations
+locations = pd.DataFrame({
+    'longitude': [100.5018, 100.5065, 100.5108],
+    'latitude': [13.7563, 13.7590, 13.7633]
+})
+
+# Group into zones
+clusters = allocator.cluster(locations, n_clusters=2)
+
+# Find optimal route
+route = allocator.shortest_path(locations)
+
+# Assign to service centers
+centers = pd.DataFrame({
+    'longitude': [100.50, 100.52],
+    'latitude': [13.75, 13.77]
+})
+assignments = allocator.assign(locations, centers)
+```
+
+## Documentation & Examples
+
+- **📖 [Full Documentation](https://geosensing.github.io/allocator/)**
+- **🚀 [Installation & Tutorial](https://geosensing.github.io/allocator/quickstart.html)**  
+- **🔧 [API Reference](https://geosensing.github.io/allocator/api/clustering.html)**
+- **💡 [Real-World Examples](https://geosensing.github.io/allocator/examples/overview.html)**
+
+## License & Contributing
+
+MIT License. Contributions welcome - see [Contributing Guide](https://geosensing.github.io/allocator/contributing.html).

allocator-1.0.0/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-1.0.0/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-1.0.0/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,
+        },
+    )