Как построить пространственный граф и предсказать функции городских объектов с помощью city2graph

В этом руководстве показано, как с помощью city2graph построить конвейер пространственного обучения на графах. Он включает сбор данных о городских объектах (POI) и уличной сети из OpenStreetMap, создание пространственных признаков и графов близости, а затем классификацию категорий объектов моделью GraphSAGE. Если получить данные OpenStreetMap не удаётся, используется синтетический набор, чтобы показать этапы построения графа без выгрузки OpenStreetMap.

Установка библиотек и импорт модулей

Сначала установим необходимые библиотеки и импортируем инструменты для обработки геоданных, построения графов и машинного обучения. Также зададим начальное значение генератора случайных чисел, чтобы сделать разбиение данных и результаты модели более воспроизводимыми.

!pip -q install "city2graph[cpu]" osmnx contextily scikit-learn 2>/dev/null
import warnings, numpy as np, pandas as pd, geopandas as gpd
warnings.filterwarnings("ignore")
from shapely.geometry import Point
import matplotlib.pyplot as plt
import city2graph as c2g
print("city2graph version:", getattr(c2g, "__version__", "unknown"))
print("PyTorch / PyG available:", c2g.is_torch_available())
import torch
import torch.nn.functional as F
from torch_geometric.nn import SAGEConv, to_hetero
from torch_geometric.utils import to_undirected
from sklearn.preprocessing import StandardScaler
from sklearn.neighbors import NearestNeighbors
from sklearn.metrics import accuracy_score, f1_score
from sklearn.decomposition import PCA
SEED = 42
np.random.seed(SEED); torch.manual_seed(SEED)

Сбор данных OpenStreetMap и резервный синтетический набор

Пример использует POI в районе Сибуя в Токио. Объекты распределяются по четырём категориям: заведения общепита, торговля, образование и здравоохранение. Для анализа городской формы также загружается пешеходная уличная сеть. Если запрос к OpenStreetMap не удаётся или не возвращает POI, создаётся синтетический набор сгруппированных точек.

CENTER = (35.6595, 139.7005)
DIST_M = 1100
TAG_QUERIES = {
   "food":      {"amenity": ["restaurant", "cafe", "fast_food", "bar", "pub"]},
   "retail":    {"shop": True},
   "education": {"amenity": ["school", "university", "college", "kindergarten", "library"]},
   "health":    {"amenity": ["hospital", "clinic", "pharmacy", "doctors", "dentist"]},
}
def to_points(gdf):
   g = gdf.copy()
   g["geometry"] = g.geometry.representative_point()
   return g
poi_gdf, segments_gdf = None, None
try:
   import osmnx as ox
   ox.settings.use_cache = True
   ox.settings.log_console = False
   frames = []
   for label, tags in TAG_QUERIES.items():
       try:
           f = ox.features_from_point(CENTER, tags=tags, dist=DIST_M)
           f = f[f.geometry.notna()]
           if len(f):
               f = to_points(f)[["geometry"]].copy()
               f["category"] = label
               frames.append(f)
       except Exception as e:
           print(f"  (skip {label}: {e})")
   if not frames:
       raise RuntimeError("No POIs returned from Overpass.")
   poi_gdf = gpd.GeoDataFrame(pd.concat(frames, ignore_index=True), crs="EPSG:4326")
   G = ox.graph_from_point(CENTER, dist=DIST_M, network_type="walk")
   segments_gdf = ox.graph_to_gdfs(G, nodes=False, edges=True).reset_index(drop=True)[["geometry"]]
   print(f"OSM acquisition OK -> {len(poi_gdf)} POIs, {len(segments_gdf)} street segments")
except Exception as e:
   print(f"OSM unavailable ({e}) -> generating synthetic clustered POIs.")
   rng = np.random.default_rng(SEED)
   cats = list(TAG_QUERIES.keys())
   centers = rng.uniform(-0.01, 0.01, size=(8, 2)) + np.array(CENTER[::-1])
   rows = []
   for ci, c in enumerate(centers):
       dom = cats[ci % len(cats)]
       n = rng.integers(40, 90)
       pts = c + rng.normal(0, 0.0016, size=(n, 2))
       for (lon, lat) in pts:
           cat = dom if rng.random() < 0.75 else rng.choice(cats)
           rows.append({"geometry": Point(lon, lat), "category": cat})
   poi_gdf = gpd.GeoDataFrame(rows, crs="EPSG:4326")
   segments_gdf = None
   print(f"Synthetic dataset -> {len(poi_gdf)} POIs")
if len(poi_gdf) > 700:
   poi_gdf = poi_gdf.sample(700, random_state=SEED).reset_index(drop=True)
metric_crs = poi_gdf.estimate_utm_crs()
poi_gdf = poi_gdf.to_crs(metric_crs).reset_index(drop=True)
if segments_gdf is not None:
   segments_gdf = segments_gdf.to_crs(metric_crs)
print("Class balance:\n", poi_gdf["category"].value_counts())

Пространственные признаки и графы близости

Для каждого POI рассчитываются координаты в проекции, локальная плотность объектов в радиусе 150 метров и расстояние до ближайшего уличного сегмента. Затем категориям присваиваются числовые метки. Для одного набора объектов строятся шесть типов графов близости: KNN, Делоне, Габриэля, относительных окрестностей (RNG), евклидово минимальное остовное дерево (EMST) и Ваксмана. Сравниваются число рёбер и средняя степень вершин; несколько топологий визуализируются.

poi_gdf["cx"] = poi_gdf.geometry.x
poi_gdf["cy"] = poi_gdf.geometry.y
coords = poi_gdf[["cx", "cy"]].to_numpy()
nn = NearestNeighbors(radius=150.0).fit(coords)
poi_gdf["local_density"] = [len(idx) - 1 for idx in nn.radius_neighbors(coords, return_distance=False)]
if segments_gdf is not None and len(segments_gdf):
   try:
       joined = gpd.sjoin_nearest(poi_gdf[["geometry"]], segments_gdf[["geometry"]], distance_col="dist_street")
       poi_gdf["dist_street"] = joined.groupby(level=0)["dist_street"].min().reindex(poi_gdf.index).fillna(0.0)
   except Exception:
       poi_gdf["dist_street"] = 0.0
else:
   poi_gdf["dist_street"] = 0.0
poi_gdf["category"] = poi_gdf["category"].astype("category")
poi_gdf["label"] = poi_gdf["category"].cat.codes.astype(int)
CLASS_NAMES = list(poi_gdf["category"].cat.categories)
print("Classes:", CLASS_NAMES)
def graph_stats(name, builder):
   try:
       nodes, edges = builder()
       deg = pd.Series(np.r_[edges.index.get_level_values(0), edges.index.get_level_values(1)]).value_counts()
       return name, len(edges), round(deg.mean(), 2), (nodes, edges)
   except Exception as e:
       return name, f"ERR: {e}", None, None
builders = {
   "KNN (k=8)":  lambda: c2g.knn_graph(poi_gdf, distance_metric="euclidean", k=8, as_nx=False),
   "Delaunay":   lambda: c2g.delaunay_graph(poi_gdf, as_nx=False),
   "Gabriel":    lambda: c2g.gabriel_graph(poi_gdf, as_nx=False),
   "RNG":        lambda: c2g.relative_neighborhood_graph(poi_gdf, as_nx=False),
   "EMST":       lambda: c2g.euclidean_minimum_spanning_tree(poi_gdf, as_nx=False),
   "Waxman":     lambda: c2g.waxman_graph(poi_gdf, distance_metric="euclidean", r0=150, beta=0.6),
}
print("\n--- Proximity graph comparison ---")
print(f"{'graph':<14}{'#edges':>10}{'avg_degree':>12}")
built = {}
for nm, b in builders.items():
   name, ne, avgdeg, payload = graph_stats(nm, b)
   print(f"{name:<14}{str(ne):>10}{str(avgdeg):>12}")
   if payload: built[nm] = payload
fig, axes = plt.subplots(1, 3, figsize=(16, 5))
for ax, key in zip(axes, ["KNN (k=8)", "Delaunay", "EMST"]):
   if key in built:
       n_, e_ = built[key]
       e_.plot(ax=ax, linewidth=0.4, color="#3b7dd8", alpha=0.6)
       poi_gdf.plot(ax=ax, markersize=4, color="#d83b5c")
       ax.set_title(key); ax.set_axis_off()
plt.suptitle("Spatial graph topologies on the same POI set", y=1.02)
plt.tight_layout(); plt.show()

Гетерогенный и однородный графы в PyTorch Geometric

В гетерогенном графе POI разделяются на типы узлов по категориям, а ближайшие узлы разных типов соединяются рёбрами-мостами. Результат преобразуется в формат HeteroData. Затем строится однородный KNN-граф: к его узлам добавляются степень и рассчитанные пространственные признаки, которые стандартизируются. Полученная структура Data используется для обучения GraphSAGE.

nodes_dict = {}
for cat in CLASS_NAMES:
   sub = poi_gdf[poi_gdf["category"] == cat].copy().reset_index(drop=True)
   nodes_dict[cat] = sub[["geometry", "cx", "cy", "local_density"]]
try:
   _, bridge_edges = c2g.bridge_nodes(nodes_dict, proximity_method="knn", k=3, distance_metric="euclidean")
   hetero = c2g.gdf_to_pyg(nodes_dict, bridge_edges,
       node_feature_cols={cat: ["cx", "cy", "local_density"] for cat in CLASS_NAMES})
   print("\nHeteroData node types:", hetero.node_types)
   print("HeteroData edge types:")
   for et in hetero.edge_types:
       print(f"   {et}: {hetero[et].edge_index.shape[1]} edges")
except Exception as e:
   hetero = None
   print("Heterogeneous build skipped:", e)
nodes, edges = c2g.knn_graph(poi_gdf, distance_metric="euclidean", k=8, as_nx=False)
deg = pd.Series(np.r_[edges.index.get_level_values(0), edges.index.get_level_values(1)]).value_counts()
nodes["degree"] = deg.reindex(nodes.index).fillna(0).astype(float)
for col in ["cx", "cy", "local_density", "dist_street", "label"]:
   if col not in nodes.columns:
       nodes[col] = poi_gdf.loc[nodes.index, col].values
FEATS = ["cx", "cy", "local_density", "dist_street", "degree"]
nodes[FEATS] = StandardScaler().fit_transform(nodes[FEATS].astype(float))
data = c2g.gdf_to_pyg(nodes, edges, node_feature_cols=FEATS, node_label_cols=["label"])
data.edge_index = to_undirected(data.edge_index)
data.x = data.x.float()
y = data.y.long().view(-1)
N, num_classes = data.num_nodes, int(y.max()) + 1
print(f"\nHomogeneous Data: {N} nodes, {data.edge_index.shape[1]} directed-edges, {data.x.shape[1]} features, {num_classes} classes")

Модель GraphSAGE и обучение классификатора

Узлы случайным образом распределяются между обучающей, валидационной и тестовой выборками в пропорции 60%, 20% и 20%. Двухслойная модель GraphSAGE использует признаки узлов и структуру графа. Обучение длится 200 эпох; каждые 20 эпох проверяются точность и макроусреднённая F1-мера на валидационной выборке. Сохраняется вариант с лучшей валидационной точностью. Обучающие и тестовые узлы остаются в одном графе, поэтому эксперимент проверяет предсказание меток на этом графе. Для оценки переноса нужны отдельные районы или города.

perm = torch.randperm(N, generator=torch.Generator().manual_seed(SEED))
n_tr, n_va = int(0.6 * N), int(0.2 * N)
train_mask = torch.zeros(N, dtype=torch.bool); train_mask[perm[:n_tr]] = True
val_mask = torch.zeros(N, dtype=torch.bool); val_mask[perm[n_tr:n_tr + n_va]] = True
test_mask = torch.zeros(N, dtype=torch.bool); test_mask[perm[n_tr + n_va:]] = True
class GraphSAGE(torch.nn.Module):
   def __init__(self, in_dim, hidden, out_dim, p=0.3):
       super().__init__()
       self.c1 = SAGEConv(in_dim, hidden)
       self.c2 = SAGEConv(hidden, hidden)
       self.lin = torch.nn.Linear(hidden, out_dim)
       self.p = p
   def forward(self, x, ei, return_emb=False):
       h = F.relu(self.c1(x, ei))
       h = F.dropout(h, p=self.p, training=self.training)
       h = F.relu(self.c2(h, ei))
       out = self.lin(h)
       return (out, h) if return_emb else out
model = GraphSAGE(data.x.shape[1], 64, num_classes)
opt = torch.optim.Adam(model.parameters(), lr=0.01, weight_decay=5e-4)
def evaluate(mask):
   model.eval()
   with torch.no_grad():
       pred = model(data.x, data.edge_index).argmax(1)
   yt, yp = y[mask].numpy(), pred[mask].numpy()
   return accuracy_score(yt, yp), f1_score(yt, yp, average="macro")
print("\n--- Training GraphSAGE ---")
best_val, best_state = 0.0, None
for epoch in range(1, 201):
   model.train(); opt.zero_grad()
   out = model(data.x, data.edge_index)
   loss = F.cross_entropy(out[train_mask], y[train_mask])
   loss.backward(); opt.step()
   if epoch % 20 == 0:
       va_acc, va_f1 = evaluate(val_mask)
       if va_acc > best_val:
           best_val, best_state = va_acc, {k: v.clone() for k, v in model.state_dict().items()}
       print(f"epoch {epoch:3d} | loss {loss.item():.3f} | val_acc {va_acc:.3f} | val_f1 {va_f1:.3f}")
if best_state: model.load_state_dict(best_state)
te_acc, te_f1 = evaluate(test_mask)
print(f"\nTEST accuracy={te_acc:.3f} macro-F1={te_f1:.3f}")

Визуализация эмбеддингов и гетерогенная GNN

Обученная модель формирует эмбеддинги узлов и предсказания категорий. Эмбеддинги проецируются на двумерную плоскость методом главных компонент (PCA), а предсказанные функции объектов отображаются на карте. Если гетерогенный граф удалось построить, дополнительно выполняется прямой проход гетерогенной графовой нейросети, созданной с помощью to_hetero.

model.eval()
with torch.no_grad():
   logits, emb = model(data.x, data.edge_index, return_emb=True)
   pred = logits.argmax(1).numpy()
emb2d = PCA(n_components=2).fit_transform(emb.numpy())
fig, axes = plt.subplots(1, 2, figsize=(15, 6))
for cls in range(num_classes):
   m = y.numpy() == cls
   axes[0].scatter(emb2d[m, 0], emb2d[m, 1], s=10, label=CLASS_NAMES[cls], alpha=0.7)
axes[0].set_title("GraphSAGE node embeddings (PCA), coloured by TRUE class")
axes[0].legend(fontsize=8); axes[0].set_xticks([]); axes[0].set_yticks([])
plot_gdf = nodes.copy(); plot_gdf["pred"] = pred
plot_gdf["pred_name"] = [CLASS_NAMES[p] for p in pred]
plot_gdf.plot(ax=axes[1], column="pred_name", legend=True, markersize=12, cmap="tab10")
axes[1].set_title("Predicted urban function (mapped back to geography)")
axes[1].set_axis_off()
try:
   import contextily as ctx
   ctx.add_basemap(axes[1], crs=plot_gdf.crs, source=ctx.providers.CartoDB.Positron)
except Exception:
   pass
plt.tight_layout(); plt.show()
if hetero is not None:
   try:
       for nt in hetero.node_types:
           hetero[nt].x = hetero[nt].x.float()
       class HGNN(torch.nn.Module):
           def __init__(self, hid, out):
               super().__init__()
               self.c1 = SAGEConv((-1, -1), hid)
               self.c2 = SAGEConv((-1, -1), out)
           def forward(self, x, ei):
               x = {k: F.relu(v) for k, v in self.c1(x, ei).items()}
               return self.c2(x, ei)
       hmodel = to_hetero(HGNN(32, 16), hetero.metadata(), aggr="sum")
       out_dict = hmodel(hetero.x_dict, hetero.edge_index_dict)
       print("\nHeterogeneous GNN output embedding shapes:")
       for nt, t in out_dict.items():
           print(f"   {nt}: {tuple(t.shape)}")
   except Exception as e:
       print("Hetero GNN forward skipped:", e)
print("\nDone — proximity comparison, hetero construction, and a trained spatial GNN.")

Итоги

  • city2graph помогает преобразовать данные OpenStreetMap об объектах и улицах в пространственные графы.
  • Шесть семейств графов близости — KNN, Делоне, Габриэля, RNG, EMST и Ваксмана — по-разному соединяют один и тот же набор POI.
  • Синтетический набор сгруппированных точек позволяет продолжить работу, если данные OpenStreetMap недоступны.
  • Двухслойная модель GraphSAGE предсказывает категории городских объектов, опираясь на пространственные признаки и структуру графа.
  • Конвейер поддерживает обучение на однородном графе и эксперименты с гетерогенными графами через to_hetero.

В итоге исходные городские данные преобразуются в графы, пригодные для обучения и визуализации. В руководстве сравниваются методы построения графов близости, создаётся гетерогенный граф, обучается классификатор GraphSAGE и анализируются эмбеддинги и географические предсказания. Пример показывает, как city2graph, GeoPandas, OSMnx и PyTorch Geometric можно объединить для экспериментов с геопространственным машинным обучением.