Examples OverviewΒΆ

This section provides comprehensive examples and workflows demonstrating allocator v1.0 functionality using real-world geographic data.

Allocator Examples - Professional Demo SuiteΒΆ

This directory provides a complete demonstration suite for allocator v1.0 using real-world geographic data and production-ready workflows.

🎯 Quick Start¢

# 1. Basic API introduction (1-2 seconds)
uv run python examples/scripts/quick_start.py

# 2. Real-world performance analysis (5-10 seconds)
uv run python examples/scripts/real_world_workflow.py

# 3. Generate comprehensive visualizations (30-60 seconds)
uv run python examples/scripts/algorithm_comparison.py

# View results
open examples/outputs/latest/comparisons/reports/executive_summary.html

πŸ“ Directory StructureΒΆ

examples/
β”œβ”€β”€ inputs/                          # Source datasets
β”‚   β”œβ”€β”€ delhi-roads-1k.csv          # Delhi, India road network (1000 segments)
β”‚   β”œβ”€β”€ chonburi-roads-1k.csv       # Chonburi, Thailand road network (1000 segments)
β”‚   └── README.md                   # Data source documentation
β”‚
β”œβ”€β”€ scripts/                        # Workflow demonstrations
β”‚   β”œβ”€β”€ quick_start.py              # Basic API introduction
β”‚   β”œβ”€β”€ real_world_workflow.py      # Complete performance analysis
β”‚   β”œβ”€β”€ algorithm_comparison.py     # Comprehensive visualization generator
β”‚   β”œβ”€β”€ distance_methods.py         # Distance calculation comparison
β”‚   β”œβ”€β”€ cli_workflow_demo.py        # CLI interface demonstration
β”‚   └── README.md                   # Script documentation
β”‚
β”œβ”€β”€ outputs/                        # Generated results (timestamped)
β”‚   β”œβ”€β”€ YYYY-MM-DD_HH-MM/          # Analysis runs
β”‚   β”‚   β”œβ”€β”€ delhi/                  # Delhi analysis results
β”‚   β”‚   β”‚   β”œβ”€β”€ clustering/         # K-means clustering analysis
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ data/*.csv      # Clustering result datasets
β”‚   β”‚   β”‚   β”‚   β”œβ”€β”€ visualizations/*.png # Performance charts
β”‚   β”‚   β”‚   β”‚   └── reports/*.html  # Detailed HTML analysis
β”‚   β”‚   β”‚   └── routing/            # TSP routing analysis
β”‚   β”‚   β”‚       β”œβ”€β”€ data/*.csv      # Route solution datasets
β”‚   β”‚   β”‚       β”œβ”€β”€ visualizations/*.png # Route performance charts
β”‚   β”‚   β”‚       └── reports/*.html  # Routing analysis reports
β”‚   β”‚   β”œβ”€β”€ chonburi/               # Chonburi analysis (same structure)
β”‚   β”‚   β”œβ”€β”€ comparisons/            # Cross-city comparisons
β”‚   β”‚   β”‚   β”œβ”€β”€ data/analysis_summary.json
β”‚   β”‚   β”‚   └── reports/executive_summary.html
β”‚   β”‚   └── README.md               # Run documentation
β”‚   └── latest/                     # Symlink to most recent analysis
β”‚
└── README.md                       # This file

🌍 Real-World Data¢

Delhi Road NetworkΒΆ

  • 1,000 road segments from OpenStreetMap

  • Major roads: Mahatma Gandhi Road, Outer Circle, Grand Trunk Road

  • Coverage: Central Delhi with diverse road types

  • Applications: Urban planning, emergency services, logistics

Chonburi Road NetworkΒΆ

  • 1,000 road segments from OpenStreetMap

  • Major roads: Sukhumvit Road (ΰΈ–ΰΈ™ΰΈ™ΰΈͺΰΈΈΰΈ‚ΰΈΈΰΈ‘ΰΈ§ΰΈ΄ΰΈ—), regional highways

  • Coverage: Chonburi Province with coastal and inland areas

  • Applications: Tourism logistics, industrial planning, transportation

πŸš€ Demonstration WorkflowsΒΆ

1. Quick API IntroductionΒΆ

uv run python examples/scripts/quick_start.py

  • Purpose: Learn basic allocator functionality

  • Runtime: 1-2 seconds

  • Output: Console demonstration of clustering, routing, assignment

2. Real-World Performance AnalysisΒΆ

uv run python examples/scripts/real_world_workflow.py

  • Purpose: Production performance validation

  • Runtime: 5-10 seconds

  • Output: Performance metrics using actual city data

3. Comprehensive Visualization GenerationΒΆ

uv run python examples/scripts/algorithm_comparison.py

  • Purpose: Research, reporting, executive presentations

  • Runtime: 30-60 seconds

  • Output: Professional visualization suite with 20+ files

Generated files include:

  • πŸ“Š PNG visualizations: Performance charts, comparison plots

  • πŸ“‹ CSV datasets: Algorithm results, route solutions

  • πŸ“„ HTML reports: Executive summaries, detailed analysis

  • πŸ”§ JSON summaries: Machine-readable performance metrics

πŸ’Ύ Intermediate File Preservation: All generated outputs (PNG charts, CSV data, HTML reports) are automatically preserved in timestamped directories under examples/outputs/YYYY-MM-DD_HH-MM/ with organized structure by city and analysis type. This ensures all intermediate analysis files are retained for review, comparison, and further processing.

πŸ“Š Example OutputsΒΆ

Performance Metrics (typical results)ΒΆ

πŸ™οΈ Delhi Results Summary:
  β€’ Dataset: 1,000 road segments  
  β€’ Clustering: 5 zones in 0.05s
  β€’ Route optimization: 146.2km route in 0.18s
  β€’ Assignment: Avg 24.4km distance in 0.03s

πŸ™οΈ Chonburi Results Summary:
  β€’ Dataset: 1,000 road segments
  β€’ Clustering: 5 zones in 0.03s  
  β€’ Route optimization: 268.0km route in 0.00s
  β€’ Assignment: Avg 15.2km distance in 0.02s

Generated Visualization FilesΒΆ

  • delhi_clustering_analysis.png - Clustering performance comparison

  • chonburi_routing_analysis.png - TSP routing optimization charts

  • executive_summary.html - Professional analysis report

Business-Ready CSV OutputsΒΆ

  • kmeans_euclidean_5clusters.csv - Clustering assignments

  • tsp_ortools_15points.csv - Optimized route solutions

  • analysis_summary.json - Performance benchmarks

🎯 Business Applications¢

Urban PlanningΒΆ

  • Zone Creation: Maintenance districts, service areas

  • Infrastructure: Inspection scheduling, resource allocation

  • Development: New facility placement optimization

Logistics & DeliveryΒΆ

  • Route Optimization: Last-mile delivery, pickup scheduling

  • Territory Management: Driver assignments, coverage areas

  • Network Design: Hub placement, capacity planning

Emergency ServicesΒΆ

  • Response Zones: Ambulance, fire station coverage

  • Resource Deployment: Equipment placement, staffing

  • Evacuation Planning: Route optimization, capacity analysis

Research & DevelopmentΒΆ

  • Algorithm Validation: Performance benchmarking

  • Method Comparison: Distance metrics, optimization approaches

  • Academic Research: Geographic optimization, urban analytics

πŸ› οΈ Technical DetailsΒΆ

DependenciesΒΆ

All dependencies are defined in ../../pyproject.toml:

  • Core: pandas, numpy, scikit-learn

  • Optimization: ortools

  • Visualization: matplotlib, seaborn

  • Geographic: utm, haversine, googlemaps

  • CLI: click, rich

Performance CharacteristicsΒΆ

  • Small problems (≀50 points): Sub-second execution

  • Medium problems (50-200 points): 1-10 seconds

  • Large problems (200+ points): 10+ seconds, consider sampling

System RequirementsΒΆ

  • Python: 3.11+ (tested on 3.11-3.13)

  • Memory: 2GB+ for large datasets

  • Storage: 100MB for full analysis outputs

  • Network: Optional for OSRM/Google Maps APIs

πŸ“ˆ Scaling GuidelinesΒΆ

Development & TestingΒΆ

# Quick validation (1-2 seconds)
uv run python examples/scripts/quick_start.py

# Performance testing (5-10 seconds)  
uv run python examples/scripts/real_world_workflow.py

Production AnalysisΒΆ

# Comprehensive reporting (30-60 seconds)
uv run python examples/scripts/algorithm_comparison.py

# Custom CLI workflows
uv run allocator cluster kmeans examples/inputs/delhi-roads-1k.csv --n-clusters 7 --output results.csv

Large-Scale DeploymentΒΆ

  • Use CLI batch processing for multiple datasets

  • Consider parallel processing for multiple cities

  • Implement result caching for repeated analysis

  • Scale visualization generation for executive reporting

πŸ”— Integration ExamplesΒΆ

Python API IntegrationΒΆ

import allocator
import pandas as pd

# Load real road data  
roads = pd.read_csv('examples/inputs/delhi-roads-1k.csv')
points = pd.DataFrame({
    'longitude': roads['start_long'],
    'latitude': roads['start_lat']  
})

# Production-ready analysis
clusters = allocator.cluster(points, n_clusters=5, distance='haversine')
route = allocator.shortest_path(points.head(10), method='ortools')

CLI IntegrationΒΆ

#!/bin/bash
# Production batch processing
for city in delhi chonburi; do
    allocator cluster kmeans examples/inputs/${city}-roads-1k.csv \
        --n-clusters 5 \
        --output results/${city}_zones.csv
done

Dashboard IntegrationΒΆ

# Load analysis results for dashboard
import json
with open('examples/outputs/latest/comparisons/data/analysis_summary.json') as f:
    metrics = json.load(f)
    
# Display in web dashboard, monitoring system, etc.

πŸ† Success MetricsΒΆ

This demonstration suite validates:

  • βœ… Performance: All algorithms complete within seconds for real-world data

  • βœ… Accuracy: Haversine distance provides geographically accurate results

  • βœ… Scalability: Handles 1000+ point datasets efficiently

  • βœ… Usability: Simple API with professional visualization output

  • βœ… Production-Ready: Comprehensive error handling and documentation

πŸ“ Next StepsΒΆ

  1. Explore: Run uv run python examples/scripts/quick_start.py to understand basic functionality

  2. Validate: Use uv run python examples/scripts/real_world_workflow.py for performance insights

  3. Generate: Create professional reports with uv run python examples/scripts/algorithm_comparison.py

  4. Customize: Modify scripts for your specific datasets and requirements

  5. Scale: Implement in production systems using CLI or Python API

πŸŽ‰ Ready for production deployment! This suite demonstrates production-ready geographic optimization using real-world data from major urban areas.