Metapath Module¶

The metapath module provides functions for adding metapath-derived edges to heterogeneous graphs.

Module for metapath-based graph operations.

This module provides functionality for adding metapath-derived edges to heterogeneous graphs, supporting both weighted and structural metapaths.

Functions:

Name	Description
`add_metapaths`	Add metapath-derived edges to a heterogeneous graph.
`add_metapaths_by_weight`	Connect nodes of a specific type if they are reachable within a cost threshold band.

add_metapaths ¶

add_metapaths(
    graph=None,
    nodes=None,
    edges=None,
    sequence=None,
    new_relation_name=None,
    edge_attr=None,
    edge_attr_agg="sum",
    directed=False,
    trace_path=False,
    multigraph=False,
    as_nx=False,
    **_
)

Add metapath-derived edges to a heterogeneous graph.

The operation multiplies typed adjacency tables to connect terminal node pairs and can aggregate additional numeric edge attributes along the way.

Parameters:

Name	Type	Description	Default
`graph`	`tuple or Graph or MultiGraph`	Heterogeneous graph input expressed as typed GeoDataFrame dictionaries or a city2graph-compatible NetworkX graph.	`None`
`nodes`	`dict[str, GeoDataFrame]`	Dictionary of node GeoDataFrames.	`None`
`edges`	`dict[tuple[str, str, str], GeoDataFrame]`	Dictionary of edge GeoDataFrames.	`None`
`sequence`	`list[tuple[str, str, str]]`	Sequence of metapath specifications; every edge type is a `(src_type, relation, dst_type)` tuple and the path must contain at least two steps.	`None`
`new_relation_name`	`str`	Target edge relation name for the new metapath edges. If None (default), edges are named `metapath_0`.	`None`
`edge_attr`	`str \| list[str] \| None`	Numeric edge attributes to aggregate along metapaths. When `None`, only path weights are produced.	`None`
`edge_attr_agg`	`str \| object \| None`	Aggregation strategy for `edge_attr` columns. Supported values are `"sum"` and `"mean"` (default `"sum"`).	`'sum'`
`directed`	`bool`	Treat metapaths as directed when `True`; otherwise both edge directions are accepted when available in the input graph.	`False`
`trace_path`	`bool`	When `True`, attempt to create traced geometries. Currently ignored but retained for API compatibility.	`False`
`multigraph`	`bool`	When returning NetworkX data, build a `networkx.MultiGraph` if `True`.	`False`
`as_nx`	`bool`	Return the result as a NetworkX graph when `True`.	`False`
`**_`	`object`	Ignored placeholder for future keyword extensions.	`{}`

Returns:

Type	Description
`tuple[dict[str, GeoDataFrame], dict[tuple[str, str, str], GeoDataFrame]] \| Graph \| MultiGraph`	The graph with metapath-derived edges. If as_nx is False (default), returns a tuple of node and edge GeoDataFrames. If as_nx is True, returns a NetworkX graph (Graph or MultiGraph).

Notes

Legacy scaffolding for path-tracing geometries has been removed because it was never executed. The trace_path argument is preserved for API compatibility but remains a no-op while straight-line geometries are generated for all metapath edges.

add_metapaths_by_weight ¶

add_metapaths_by_weight(
    graph=None,
    nodes=None,
    edges=None,
    weight=None,
    threshold=None,
    new_relation_name=None,
    min_threshold=0.0,
    edge_types=None,
    endpoint_type=None,
    directed=False,
    multigraph=False,
    as_nx=False,
)

Connect nodes of a specific type if they are reachable within a cost threshold band.

This function dynamically adds metapaths (edges) between nodes of a specified endpoint_type if they are reachable within a given cost band [min_threshold, threshold] based on edge weights (e.g., travel time). It uses Dijkstra's algorithm for path finding via scipy.sparse.csgraph for efficiency.

Parameters:

Name	Type	Description	Default
`graph`	`tuple or Graph or MultiGraph`	Input graph. Can be a tuple of (nodes_dict, edges_dict) or a NetworkX graph.	`None`
`nodes`	`dict[str, GeoDataFrame]`	Dictionary of node GeoDataFrames.	`None`
`edges`	`dict[tuple[str, str, str], GeoDataFrame]`	Dictionary of edge GeoDataFrames.	`None`
`weight`	`str`	The edge attribute to use as weight (e.g., 'travel_time').	`None`
`threshold`	`float`	The maximum cost threshold for connection.	`None`
`new_relation_name`	`str`	Name of the new edge relation.	`None`
`min_threshold`	`float`	The minimum cost threshold for connection.	`0.0`
`edge_types`	`list[tuple[str, str, str]]`	List of edge types to consider for traversal. If None, all edges are used.	`None`
`endpoint_type`	`str`	The node type to connect (e.g., 'building').	`None`
`directed`	`bool`	If True, creates a directed graph for traversal.	`False`
`multigraph`	`bool`	If True, returns a MultiGraph (only relevant if as_nx=True).	`False`
`as_nx`	`bool`	If True, returns a NetworkX graph.	`False`

Returns:

Type	Description
`Graph or MultiGraph or tuple`	The graph with added metapaths. Format depends on `as_nx` parameter.