|
| 1 | +""" |
| 2 | +API for random walk itinerary generation on road networks. |
| 3 | +""" |
| 4 | + |
| 5 | +from typing import Any |
| 6 | + |
| 7 | +import networkx as nx |
| 8 | +import numpy as np |
| 9 | +import pandas as pd |
| 10 | + |
| 11 | +from ..core.random_walk import ( |
| 12 | + generate_walks, |
| 13 | + get_largest_connected_component, |
| 14 | + validate_graph, |
| 15 | +) |
| 16 | +from .types import RandomWalkResult |
| 17 | + |
| 18 | + |
| 19 | +def random_walk( |
| 20 | + graph: nx.Graph, |
| 21 | + n_walks: int = 15, |
| 22 | + walk_length_m: float = 5000.0, |
| 23 | + start_points: list[Any] | None = None, |
| 24 | + seed: int | None = None, |
| 25 | + use_largest_component: bool = True, |
| 26 | +) -> RandomWalkResult: |
| 27 | + """ |
| 28 | + Generate self-weighting random walk itineraries on a road network graph. |
| 29 | +
|
| 30 | + Random walks on road networks have a self-weighting property: at each |
| 31 | + intersection of degree d, choosing the next edge uniformly (probability 1/d) |
| 32 | + ensures that the time-average along the walk converges to a length-weighted |
| 33 | + spatial average. This eliminates the need for explicit inclusion probabilities. |
| 34 | +
|
| 35 | + Args: |
| 36 | + graph: NetworkX graph from OSMnx or geo-sampling. Must have: |
| 37 | + - Node attributes: x/y, lon/lat, or longitude/latitude |
| 38 | + - Edge attributes: length (in meters) |
| 39 | + n_walks: Number of independent walks to generate (default 15) |
| 40 | + walk_length_m: Target length of each walk in meters (default 5000.0) |
| 41 | + start_points: Optional list of starting node IDs. If provided, walks |
| 42 | + cycle through these points (useful for GRTS-selected starting locations). |
| 43 | + If None, random nodes are chosen uniformly. |
| 44 | + seed: Random seed for reproducibility |
| 45 | + use_largest_component: If True (default), use only the largest connected |
| 46 | + component of the graph to avoid getting stuck in disconnected regions. |
| 47 | +
|
| 48 | + Returns: |
| 49 | + RandomWalkResult containing: |
| 50 | + - walks: List of walk dicts, each with: |
| 51 | + - waypoints: List of (lon, lat, cumulative_distance_m) tuples |
| 52 | + - edges_traversed: List of (from_node, to_node, length_m) tuples |
| 53 | + - total_distance_m: Actual distance walked |
| 54 | + - data: DataFrame with all waypoints: |
| 55 | + - walk_id: Walk index |
| 56 | + - sequence: Waypoint sequence number within walk |
| 57 | + - longitude: Waypoint longitude |
| 58 | + - latitude: Waypoint latitude |
| 59 | + - cumulative_distance_m: Distance from walk start |
| 60 | + - metadata: Dict with: |
| 61 | + - n_walks: Number of walks generated |
| 62 | + - walk_length_m: Target walk length |
| 63 | + - total_network_length_m: Sum of all edge lengths |
| 64 | + - n_nodes: Number of nodes in graph |
| 65 | + - n_edges: Number of edges in graph |
| 66 | + - seed: Random seed used |
| 67 | + - avg_actual_distance_m: Mean actual walk distance |
| 68 | + - start_points_provided: Whether start_points was provided |
| 69 | +
|
| 70 | + Raises: |
| 71 | + ValueError: If graph has no valid nodes or edges |
| 72 | +
|
| 73 | + Example: |
| 74 | + >>> import networkx as nx |
| 75 | + >>> import allocator |
| 76 | + >>> |
| 77 | + >>> # Create a simple test graph |
| 78 | + >>> G = nx.Graph() |
| 79 | + >>> G.add_node(0, longitude=100.0, latitude=13.0) |
| 80 | + >>> G.add_node(1, longitude=100.1, latitude=13.0) |
| 81 | + >>> G.add_edge(0, 1, length=1000.0) |
| 82 | + >>> |
| 83 | + >>> result = allocator.random_walk(G, n_walks=5, walk_length_m=500.0, seed=42) |
| 84 | + >>> len(result.walks) |
| 85 | + 5 |
| 86 | + """ |
| 87 | + validation = validate_graph(graph) |
| 88 | + if not validation["valid"]: |
| 89 | + raise ValueError(f"Invalid graph: {'; '.join(validation['errors'])}") |
| 90 | + |
| 91 | + working_graph = graph |
| 92 | + if use_largest_component: |
| 93 | + working_graph = get_largest_connected_component(graph) |
| 94 | + if working_graph.number_of_nodes() < graph.number_of_nodes(): |
| 95 | + validation = validate_graph(working_graph) |
| 96 | + |
| 97 | + rng = np.random.default_rng(seed) |
| 98 | + |
| 99 | + walks = generate_walks( |
| 100 | + working_graph, |
| 101 | + n_walks=n_walks, |
| 102 | + walk_length_m=walk_length_m, |
| 103 | + start_points=start_points, |
| 104 | + rng=rng, |
| 105 | + ) |
| 106 | + |
| 107 | + rows = [] |
| 108 | + for walk_id, walk in enumerate(walks): |
| 109 | + for seq, (lon, lat, cum_dist) in enumerate(walk["waypoints"]): |
| 110 | + rows.append( |
| 111 | + { |
| 112 | + "walk_id": walk_id, |
| 113 | + "sequence": seq, |
| 114 | + "longitude": lon, |
| 115 | + "latitude": lat, |
| 116 | + "cumulative_distance_m": cum_dist, |
| 117 | + } |
| 118 | + ) |
| 119 | + |
| 120 | + data = pd.DataFrame(rows) |
| 121 | + |
| 122 | + actual_distances = [w["total_distance_m"] for w in walks] |
| 123 | + |
| 124 | + metadata = { |
| 125 | + "n_walks": len(walks), |
| 126 | + "walk_length_m": walk_length_m, |
| 127 | + "total_network_length_m": validation["total_network_length_m"], |
| 128 | + "n_nodes": validation["n_nodes"], |
| 129 | + "n_edges": validation["n_edges"], |
| 130 | + "seed": seed, |
| 131 | + "avg_actual_distance_m": float(np.mean(actual_distances)) if walks else 0.0, |
| 132 | + "start_points_provided": start_points is not None, |
| 133 | + } |
| 134 | + |
| 135 | + return RandomWalkResult( |
| 136 | + walks=walks, |
| 137 | + data=data, |
| 138 | + metadata=metadata, |
| 139 | + ) |
0 commit comments