Mobility#

Mobility / OD matrix utilities.

This module introduces the public function od_matrix_to_graph which converts Origin-Destination (OD) data (adjacency matrices or edge lists) into spatial graph representations used throughout the city2graph ecosystem.

Notes

This module includes a complete implementation of od_matrix_to_graph: input validation, zone alignment, conversion to a canonical edgelist, thresholding and self-loop handling, optional geometry creation, and an optional NetworkX export path.

Examples

See the function docstring for usage examples with adjacency matrices, NumPy arrays and edge lists (single/multi weight columns).

od_matrix_to_graph(od_data, zones_gdf, zone_id_col=None, *, matrix_type='edgelist', source_col='source', target_col='target', weight_cols=None, threshold=None, threshold_col=None, include_self_loops=False, compute_edge_geometry=True, directed=True, as_nx=False)[source]#

Convert OD data (edge list or adjacency matrix) into graph structures.

Creates spatially-aware graphs from OD data following city2graph’s GeoDataFrame-first design. Supports adjacency matrices (DataFrame or ndarray) and edgelists with one or multiple numeric weight columns. By default, this function returns a pair of GeoDataFrames representing nodes and edges. When directed=False, the output is undirected: for each unordered pair {u, v}, the edge weight equals the sum of directed weights in both directions (u->v plus v->u). When a threshold is provided in undirected mode, it is applied after this summation. By default edges are directed and thresholded with the rule weight >= threshold (or, when no threshold provided, strictly > 0). Optionally, it can return a NetworkX graph when as_nx=True.

Parameters:

  • od_data (pandas.DataFrame | numpy.ndarray) –

    • When matrix_type='adjacency': a square DataFrame whose index & columns are zone IDs, or a square ndarray whose ordering matches zones_gdf.

    • When matrix_type='edgelist': a DataFrame containing origin, destination and one or more numeric flow columns.

  • zones_gdf (geopandas.GeoDataFrame) – GeoDataFrame of zones. Must contain unique identifiers in zone_id_col.

  • zone_id_col (str, optional) – Name of the zone ID column in zones_gdf (required in this initial skeleton; automatic inference may be added later).

  • matrix_type ({'edgelist','adjacency'}, default 'edgelist') – Declares how to interpret od_data.

  • source_col (str, default 'source','target') – Column names for origins / destinations when using an edge list.

  • target_col (str, default 'source','target') – Column names for origins / destinations when using an edge list.

  • weight_cols (Sequence[str] | None) – Edge list weight (flow) columns to preserve. A single column acts as the canonical weight. If multiple columns are provided a threshold_col must be designated in the full implementation.

  • threshold (float, optional) – Minimum flow retained (>=) applied to threshold_col (future logic).

  • threshold_col (str, optional) – Column among weight_cols used for thresholding & canonical weight (required when len(weight_cols) > 1 in full implementation).

  • include_self_loops (bool, default False) – Keep flows where origin == destination (defaults drop when False).

  • compute_edge_geometry (bool, default True) – Whether to build LineString geometries from zone centroids.

  • directed (bool, default True) – Whether to build a directed graph. If False, reciprocal edges are merged by summing their weights (and all provided weight columns).

  • as_nx (bool, default False) – If True, final output will be an NetworkX graph (nx.DiGraph when directed=True; otherwise nx.Graph).

Return type:

tuple[GeoDataFrame, GeoDataFrame] | Graph | DiGraph

Returns:

  • tuple of (geopandas.GeoDataFrame, geopandas.GeoDataFrame) – The nodes and edges GeoDataFrames. The nodes GeoDataFrame index is aligned with the zone identifier (zone_id_col when provided, else the original zones_gdf.index). The edges GeoDataFrame uses a pandas MultiIndex on (source_id, target_id) and does not carry separate ‘source’/’target’ columns, to comply with gdf_to_nx/gdf_to_pyg.

  • networkx.DiGraph – When as_nx=True, a directed graph with node and edge attributes.

  • networkx.Graph – When as_nx=True and directed=False, an undirected graph with node and edge attributes.

On this page

This Page