Mobility Module¶

The mobility module provides functions for processing Origin-Destination (OD) matrices and creating mobility networks for urban flow analysis.

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).

Functions:

Name	Description
`od_matrix_to_graph`	Convert OD data (edge list or adjacency matrix) into graph structures.

od_matrix_to_graph ¶

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
)

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:

Name	Type	Description	Default
`od_data`	`DataFrame \| 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.	required
`zones_gdf`	`GeoDataFrame`	GeoDataFrame of zones. Must contain unique identifiers in `zone_id_col`.	required
`zone_id_col`	`str`	Name of the zone ID column in `zones_gdf` (required in this initial skeleton; automatic inference may be added later).	`None`
`matrix_type`	`('edgelist', 'adjacency')`	Declares how to interpret `od_data`.	`'edgelist','adjacency'`
`source_col`	`str`	Column names for origins / destinations when using an edge list.	`'source','target'`
`target_col`	`str`	Column names for origins / destinations when using an edge list.	`'source','target'`
`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.	`None`
`threshold`	`float`	Minimum flow retained (>=) applied to `threshold_col` (future logic).	`None`
`threshold_col`	`str`	Column among `weight_cols` used for thresholding & canonical weight (required when `len(weight_cols) > 1` in full implementation).	`None`
`include_self_loops`	`bool`	Keep flows where origin == destination (defaults drop when False).	`False`
`compute_edge_geometry`	`bool`	Whether to build LineString geometries from zone centroids.	`True`
`directed`	`bool`	Whether to build a directed graph. If False, reciprocal edges are merged by summing their weights (and all provided weight columns).	`True`
`as_nx`	`bool`	If True, final output will be an NetworkX graph (`nx.DiGraph` when `directed=True`; otherwise `nx.Graph`).	`False`

Returns:

Type Description

tuple[GeoDataFrame, GeoDataFrame] or Graph or DiGraph

The graph representation in the requested format:

When as_nx=False (default): Returns a tuple (nodes, edges) of GeoDataFrames. The nodes GeoDataFrame index is aligned with the zone identifier. The edges GeoDataFrame uses a pandas MultiIndex on (source_id, target_id).
When as_nx=True: Returns a NetworkX graph. A networkx.DiGraph is returned if directed=True, otherwise a networkx.Graph.