Utils Module

The utils module provides core utility functions for graph conversion, validation, and visualization.

Conversion Functions

Core Utilities Module.

This module provides essential utilities for graph conversion, data validation, and spatial analysis operations. It serves as the foundation for the city2graph package, offering a standardized data format for handling geospatial relations across GeoPandas, NetworkX objects, and eventually PyTorch Geometric objects. The module enables seamless integration between different graph representations and geospatial data formats through robust data structures and conversion functions.

Functions:

Name	Description
gdf_to_nx	Convert GeoDataFrames of nodes and edges to a NetworkX graph.
nx_to_gdf	Convert a NetworkX graph to GeoDataFrames for nodes and/or edges.
nx_to_rx	Convert a NetworkX graph to a rustworkx graph.
rx_to_nx	Convert a rustworkx graph to a NetworkX graph.

gdf_to_nx

gdf_to_nx(
    nodes=None, edges=None, keep_geom=True, multigraph=False, directed=False
)

Convert GeoDataFrames of nodes and edges to a NetworkX graph.

This function provides a high-level interface to convert geospatial data, represented as GeoDataFrames, into a NetworkX graph. It supports both homogeneous and heterogeneous graphs.

For homogeneous graphs, provide a single GeoDataFrame for nodes and edges. For heterogeneous graphs, provide dictionaries mapping type names to GeoDataFrames.

Parameters:

Name	Type	Description	Default
nodes	GeoDataFrame or dict[str, GeoDataFrame]	Node data. For homogeneous graphs, a single GeoDataFrame. For heterogeneous graphs, a dictionary mapping node type names to GeoDataFrames. Node IDs are taken from the GeoDataFrame index.	None
edges	GeoDataFrame or dict[tuple[str, str, str], GeoDataFrame]	Edge data. For homogeneous graphs, a single GeoDataFrame. For heterogeneous graphs, a dictionary mapping edge type tuples (source_type, relation_type, target_type) to GeoDataFrames. Edge relationships are defined by a MultiIndex on the edge GeoDataFrame (source ID, target ID). For MultiGraphs, a third level in the index can be used for edge keys.	None
keep_geom	bool	If True, the geometry of the nodes and edges GeoDataFrames will be preserved as attributes in the NetworkX graph.	True
multigraph	bool	If True, a networkx.MultiGraph is created, which can store multiple edges between the same two nodes.	False
directed	bool	If True, a directed graph (networkx.DiGraph or networkx.MultiDiGraph) is created. Otherwise, an undirected graph is created.	False

Returns:

Type	Description
Graph or MultiGraph or DiGraph or MultiDiGraph	A NetworkX graph object representing the spatial network. Graph-level metadata, such as CRS and heterogeneity information, is stored in graph.graph.

See Also

nx_to_gdf : Convert a NetworkX graph back to GeoDataFrames.

Examples:

>>> # Homogeneous graph
>>> import geopandas as gpd
>>> import pandas as pd
>>> from shapely.geometry import Point, LineString
>>> nodes_gdf = gpd.GeoDataFrame(
...     geometry=[Point(0, 0), Point(1, 1)],
...     index=pd.Index([10, 20], name="node_id")
... )
>>> edges_gdf = gpd.GeoDataFrame(
...     {"length": [1.414]},
...     geometry=[LineString([(0, 0), (1, 1)])],
...     index=pd.MultiIndex.from_tuples([(10, 20)], names=["u", "v"])
... )
>>> G = gdf_to_nx(nodes=nodes_gdf, edges=edges_gdf)
>>> print(G.nodes(data=True))
>>> [(0, {'geometry': <POINT (0 0)>,
...       '_original_index': 10,
...       'pos': (0.0, 0.0)}),
...  (1, {'geometry': <POINT (1 1)>,
...       '_original_index': 20,
...       'pos': (1.0, 1.0)})]
>>> print(G.edges(data=True))
>>> [(0, 1, {'length': 1.414,
...          'geometry': <LINESTRING (0 0, 1 1)>,
...          '_original_edge_index': (10, 20)})]

>>> # Heterogeneous graph
>>> buildings_gdf = gpd.GeoDataFrame(geometry=[Point(0, 0)], index=pd.Index(['b1'], name="b_id"))
>>> streets_gdf = gpd.GeoDataFrame(geometry=[Point(1, 1)], index=pd.Index(['s1'], name="s_id"))
>>> connections_gdf = gpd.GeoDataFrame(
...     geometry=[LineString([(0,0), (1,1)])],
...     index=pd.MultiIndex.from_tuples([('b1', 's1')])
... )
>>> nodes_dict = {"building": buildings_gdf, "street": streets_gdf}
>>> edges_dict = {("building", "connects_to", "street"): connections_gdf}
>>> H = gdf_to_nx(nodes=nodes_dict, edges=edges_dict)
>>> print(H.nodes(data=True))
>>> [(0, {'geometry': <POINT (0 0)>,
...       'node_type': 'building',
...       '_original_index': 'b1',
...       'pos': (0.0, 0.0)}),
...  (1, {'geometry': <POINT (1 1)>,
...       'node_type': 'street',
...       '_original_index': 's1',
...       'pos': (1.0, 1.0)})]
>>> print(H.edges(data=True))
>>> [(0, 1, {'geometry': <LINESTRING (0 0, 1 1)>,
...          'full_edge_type': ('building', 'connects_to', 'street'),
...          '_original_edge_index': ('b1', 's1')})]

nx_to_gdf

nx_to_gdf(G, nodes=True, edges=True, set_missing_pos_from=('x', 'y'))

Convert a NetworkX graph to GeoDataFrames for nodes and/or edges.

This function reconstructs GeoDataFrames from a NetworkX graph that was created by gdf_to_nx or follows a similar structure. It can handle both homogeneous and heterogeneous graphs, extracting node and edge attributes and reconstructing geometries from position data.

Parameters:

Name	Type	Description	Default
G	Graph or MultiGraph	The NetworkX graph to convert. It is expected to have metadata stored in G.graph to guide the conversion, including CRS and heterogeneity information. Node positions are expected in a 'pos' attribute.	required
nodes	bool	If True, a GeoDataFrame for nodes will be created and returned.	True
edges	bool	If True, a GeoDataFrame for edges will be created and returned.	True
set_missing_pos_from	tuple[str, ...] | None	If provided (or None implies ("x", "y")) set missing node 'pos' from the given attribute name(s). With two names use them as x/y; with one name expect a 2-length coordinate.	("x", "y")

Returns:

Type

Description

GeoDataFrame or tuple

The reconstructed GeoDataFrames. The return type depends on the graph structure (homogeneous vs heterogeneous) and the requested components (nodes, edges). Homogeneous Graphs: If nodes=True and edges=True: Returns (nodes_gdf, edges_gdf) where both are geopandas.GeoDataFrame. If only nodes=True: Returns nodes_gdf (geopandas.GeoDataFrame). If only edges=True: Returns edges_gdf (geopandas.GeoDataFrame). Heterogeneous Graphs: Returns (nodes_dict, edges_dict) where: nodes_dict is dict[str, geopandas.GeoDataFrame] mapping node types to GeoDataFrames. edges_dict is dict[tuple[str, str, str], geopandas.GeoDataFrame] mapping edge types to GeoDataFrames. Note: For heterogeneous graphs, the return value is always a tuple of dictionaries, even if only one component is requested (the other will be an empty dict).

Raises:

Type	Description
ValueError	If both nodes and edges are False.

See Also

gdf_to_nx : Convert GeoDataFrames to a NetworkX graph.

Examples:

>>> import networkx as nx
>>> # Create a simple graph with spatial attributes
>>> G = nx.Graph(is_hetero=False, crs="EPSG:4326")
>>> G.add_node(0, pos=(0, 0), population=100, geometry=Point(0,0))
>>> G.add_node(1, pos=(1, 1), population=200, geometry=Point(1,1))
>>> G.add_edge(0, 1, weight=1.5, geometry=LineString([(0, 0), (1, 1)]))
>>> # Convert back to GeoDataFrames
>>> nodes_gdf, edges_gdf = nx_to_gdf(G)
>>> print(nodes_gdf)
>>> print(edges_gdf)
>>>           population     geometry
... 0         100           POINT (0 0)
... 1         200           POINT (1 1)
...           weight        geometry
... 0 1       1.5           LINESTRING (0 0, 1 1)

nx_to_rx

nx_to_rx(graph)

Convert a NetworkX graph to a rustworkx graph.

This function converts a NetworkX graph object into a rustworkx graph object, preserving node, edge, and graph attributes. It handles both directed and undirected graphs, as well as multigraphs.

Parameters:

Name	Type	Description	Default
graph	Graph or MultiGraph	The NetworkX graph to convert.	required

Returns:

Type	Description
PyGraph or PyDiGraph	The converted rustworkx graph.

See Also

rx_to_nx : Convert a rustworkx graph back to NetworkX.

Examples:

>>> rx_G = nx_to_rx(G)

rx_to_nx

rx_to_nx(graph)

Convert a rustworkx graph to a NetworkX graph.

This function converts a rustworkx graph object into a NetworkX graph object, restoring node, edge, and graph attributes.

Parameters:

Name	Type	Description	Default
graph	PyGraph or PyDiGraph	The rustworkx graph to convert.	required

Returns:

Type	Description
Graph or MultiGraph	The converted NetworkX graph.

See Also

nx_to_rx : Convert a NetworkX graph to rustworkx.

Examples:

>>> # Assuming rx_G is a rustworkx graph
>>> nx_G = rx_to_nx(rx_G)

Validation Functions

Core Utilities Module.

This module provides essential utilities for graph conversion, data validation, and spatial analysis operations. It serves as the foundation for the city2graph package, offering a standardized data format for handling geospatial relations across GeoPandas, NetworkX objects, and eventually PyTorch Geometric objects. The module enables seamless integration between different graph representations and geospatial data formats through robust data structures and conversion functions.

Functions:

Name	Description
validate_gdf	Validate node and edge GeoDataFrames with type detection.
validate_nx	Validate a NetworkX graph with comprehensive type checking.

validate_gdf

validate_gdf(nodes_gdf=None, edges_gdf=None, allow_empty=True)

Validate node and edge GeoDataFrames with type detection.

This function validates both homogeneous and heterogeneous GeoDataFrame inputs, performs type checking, and determines whether the input represents a heterogeneous graph structure.

Parameters:

Name	Type	Description	Default
nodes_gdf	GeoDataFrame or dict[str, GeoDataFrame]	The GeoDataFrame containing node data to validate, or a dictionary mapping node type names to GeoDataFrames for heterogeneous graphs.	None
edges_gdf	GeoDataFrame or dict[tuple[str, str, str], GeoDataFrame]	The GeoDataFrame containing edge data to validate, or a dictionary mapping edge type tuples to GeoDataFrames for heterogeneous graphs.	None
allow_empty	bool	If True, allows the GeoDataFrames to be empty. If False, raises an error.	True

Returns:

Type	Description
tuple	A tuple containing: validated nodes_gdf (same type as input) validated edges_gdf (same type as input) is_hetero: boolean indicating if this is a heterogeneous graph

Raises:

Type	Description
TypeError	If an input is not a GeoDataFrame or appropriate dictionary type.
ValueError	If the input types are inconsistent or invalid.

See Also

validate_nx : Validate a NetworkX graph.

Examples:

>>> import geopandas as gpd
>>> from shapely.geometry import Point, LineString
>>> nodes = gpd.GeoDataFrame(geometry=[Point(0, 0)])
>>> edges = gpd.GeoDataFrame(geometry=[LineString([(0, 0), (1, 1)])])
>>> try:
...     validated_nodes, validated_edges, is_hetero = validate_gdf(nodes, edges)
...     print(f"Validation successful. Heterogeneous: {is_hetero}")
... except (TypeError, ValueError) as e:
...     print(f"Validation failed: {e}")
Validation successful. Heterogeneous: False

validate_nx

validate_nx(graph)

Validate a NetworkX graph with comprehensive type checking.

Checks if the input is a NetworkX graph, ensures it is not empty (i.e., it has both nodes and edges), and verifies that it contains the necessary metadata for conversion back to GeoDataFrames or PyG objects.

Parameters:

Name	Type	Description	Default
graph	Graph or MultiGraph	The NetworkX graph to validate.	required

Returns:

Type	Description
None	This function does not return a value.

Raises:

Type	Description
TypeError	If the input is not a NetworkX graph.
ValueError	If the graph has no nodes, no edges, or is missing essential metadata.

See Also

validate_gdf : Validate GeoDataFrames for graph conversion.

Examples:

>>> import networkx as nx
>>> from shapely.geometry import Point
>>> G = nx.Graph(is_hetero=False, crs="EPSG:4326")
>>> G.add_node(0, pos=(0, 0))
>>> G.add_node(1, pos=(1, 1))
>>> G.add_edge(0, 1)
>>> try:
...     validate_nx(G)
...     print("Validation successful.")
... except (TypeError, ValueError) as e:
...     print(f"Validation failed: {e}")
Validation successful.

Graph Operations

Core Utilities Module.

This module provides essential utilities for graph conversion, data validation, and spatial analysis operations. It serves as the foundation for the city2graph package, offering a standardized data format for handling geospatial relations across GeoPandas, NetworkX objects, and eventually PyTorch Geometric objects. The module enables seamless integration between different graph representations and geospatial data formats through robust data structures and conversion functions.

Functions:

Name	Description
dual_graph	Convert a primal graph represented by nodes and edges GeoDataFrames to its dual graph.
filter_graph_by_distance	Filter a graph to include only elements within a specified threshold from a center point.

dual_graph

dual_graph(
    graph,
    edge_id_col=None,
    keep_original_geom=False,
    source_col=None,
    target_col=None,
    as_nx=False,
)

Convert a primal graph represented by nodes and edges GeoDataFrames to its dual graph.

In the dual graph, original edges become nodes and original nodes become edges connecting adjacent original edges.

Parameters:

Name	Type	Description	Default
graph	tuple[GeoDataFrame, GeoDataFrame] or Graph or MultiGraph	A graph containing nodes and edges GeoDataFrames or a NetworkX graph of the primal graph.	required
edge_id_col	str	The name of the column in the edges GeoDataFrame to be used as unique identifiers for dual graph nodes. If None, the index of the edges GeoDataFrame is used. Default is None.	None
keep_original_geom	bool	If True, preserve the original geometry of the edges in a new column named 'original_geometry' in the dual nodes GeoDataFrame.	False
source_col	str	Name of the column or index level representing the source node ID in the edges GeoDataFrame. If provided, it overrides automatic detection.	None
target_col	str	Name of the column or index level representing the target node ID in the edges GeoDataFrame. If provided, it overrides automatic detection.	None
as_nx	bool	If True, return the dual graph as a NetworkX graph instead of GeoDataFrames.	False

Returns:

Type

Description

tuple[GeoDataFrame, GeoDataFrame]

A tuple containing the nodes and edges of the dual graph as GeoDataFrames. Dual nodes GeoDataFrame: Nodes represent original edges. The geometry is the centroid of the original edge's geometry. The index is derived from edge_id_col or the original edge index. Dual edges GeoDataFrame: Edges represent adjacency between original edges (i.e., they shared a node in the primal graph). The geometry is a LineString connecting the centroids of the two dual nodes. The index is a MultiIndex of the connected dual node IDs.

See Also

segments_to_graph : Convert LineString segments to a graph structure.

Examples:

>>> import geopandas as gpd
>>> import pandas as pd
>>> from shapely.geometry import Point, LineString
>>> # Primal graph nodes
>>> nodes = gpd.GeoDataFrame(
...     {"node_id": [0, 1, 2]},
...     geometry=[Point(0, 0), Point(1, 1), Point(1, 0)],
...     crs="EPSG:32633"
... ).set_index("node_id")
>>> # Primal graph edges
>>> edges = gpd.GeoDataFrame(
...     {"u": [0, 1], "v": [1, 2]},
...     geometry=[LineString([(0, 0), (1, 1)]), LineString([(1, 1), (1, 0)])],
...     crs="EPSG:32633"
... )
>>> # Convert to dual graph
>>> dual_nodes, dual_edges = dual_graph((nodes, edges))

filter_graph_by_distance

filter_graph_by_distance(
    graph, center_point, threshold, edge_attr="length", node_id_col=None
)

Filter a graph to include only elements within a specified threshold from a center point.

This function calculates the shortest path from a center point to all nodes in the graph and returns a subgraph containing only the nodes (and their induced edges) that are within the given threshold. The input can be a NetworkX graph or an edges GeoDataFrame.

Parameters:

Name	Type	Description	Default
graph	GeoDataFrame or Graph or MultiGraph	The graph to filter. If a GeoDataFrame, it represents the edges of the graph and will be converted to a NetworkX graph internally.	required
center_point	Point or GeoSeries or GeoDataFrame	The origin point(s) for the distance calculation. If multiple points are provided, the filter will include nodes reachable from any of them.	required
threshold	float	The maximum shortest-path distance (or cost) for a node to be included in the filtered graph.	required
edge_attr	str	The name of the edge attribute to use as weight for shortest path calculations (e.g., 'length', 'travel_time').	"length"
node_id_col	str	The name of the node identifier column if the input graph is a GeoDataFrame. Defaults to the index.	None

Returns:

Type	Description
GeoDataFrame or Graph or MultiGraph	The filtered subgraph. The return type matches the input graph type. If the input was a GeoDataFrame, the output is a GeoDataFrame of the filtered edges.

See Also

create_isochrone : Generate an isochrone polygon from a graph.

Examples:

>>> import networkx as nx
>>> from shapely.geometry import Point
>>> # Create a graph
>>> G = nx.Graph()
>>> G.add_node(0, pos=(0, 0))
>>> G.add_node(1, pos=(10, 0))
>>> G.add_node(2, pos=(20, 0))
>>> G.add_edge(0, 1, length=10)
>>> G.add_edge(1, 2, length=10)
>>> # Filter the graph
>>> center = Point(1, 0)
>>> filtered_graph = filter_graph_by_distance(G, center, threshold=12)
>>> print(list(filtered_graph.nodes))
>>> [0, 1]

Spatial Operations

Core Utilities Module.

This module provides essential utilities for graph conversion, data validation, and spatial analysis operations. It serves as the foundation for the city2graph package, offering a standardized data format for handling geospatial relations across GeoPandas, NetworkX objects, and eventually PyTorch Geometric objects. The module enables seamless integration between different graph representations and geospatial data formats through robust data structures and conversion functions.

Functions:

Name	Description
create_tessellation	Create tessellations from given geometries, with optional barriers.
create_isochrone	Generate an isochrone polygon from a graph.

create_tessellation

create_tessellation(
    geometry,
    primary_barriers=None,
    shrink=0.4,
    segment=0.5,
    threshold=0.05,
    n_jobs=-1,
    **kwargs
)

Create tessellations from given geometries, with optional barriers.

This function generates either morphological or enclosed tessellations based on the input geometries. If primary_barriers are provided, it creates an enclosed tessellation; otherwise, it generates a morphological tessellation.

Parameters:

Name	Type	Description	Default
geometry	GeoDataFrame or GeoSeries	The geometries (typically building footprints) to tessellate around.	required
primary_barriers	GeoDataFrame or GeoSeries	Geometries (typically road network) to use as barriers for enclosed tessellation. If provided, momepy.enclosed_tessellation is used. Default is None.	None
shrink	float	The distance to shrink the geometry for the skeleton endpoint generation. Passed to momepy.morphological_tessellation or momepy.enclosed_tessellation.	0.4
segment	float	The segment length for discretizing the geometry. Passed to momepy.morphological_tessellation or momepy.enclosed_tessellation.	0.5
threshold	float	The threshold for snapping skeleton endpoints to the boundary. Only used for enclosed tessellation.	0.05
n_jobs	int	The number of jobs to use for parallel processing. -1 means using all available processors. Only used for enclosed tessellation.	-1
**kwargs	object	Additional keyword arguments passed to the underlying momepy tessellation function.	{}

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame containing the tessellation cells as polygons. Each cell has a unique tess_id.

Raises:

Type	Description
ValueError	If primary_barriers are not provided and the geometry is in a geographic CRS (e.g., EPSG:4326), as morphological tessellation requires a projected CRS.

See Also

momepy.morphological_tessellation : Generate morphological tessellation. momepy.enclosed_tessellation : Generate enclosed tessellation.

Examples:

>>> import geopandas as gpd
>>> from shapely.geometry import Polygon
>>> # Create some building footprints
>>> buildings = gpd.GeoDataFrame(
...     geometry=[Polygon([(0, 0), (1, 0), (1, 1), (0, 1)]),
...               Polygon([(2, 2), (3, 2), (3, 3), (2, 3)])],
...     crs="EPSG:32633"
... )
>>> # Generate morphological tessellation
>>> tessellation = create_tessellation(buildings)
>>> print(tessellation.head())

>>> # Generate enclosed tessellation with roads as barriers
>>> from shapely.geometry import LineString
>>> roads = gpd.GeoDataFrame(
...     geometry=[LineString([(0, -1), (3, -1)]), LineString([(1.5, -1), (1.5, 4)])],
...     crs="EPSG:32633"
... )
>>> enclosed_tess = create_tessellation(buildings, primary_barriers=roads)
>>> print(enclosed_tess.head())

create_isochrone

create_isochrone(
    graph=None,
    nodes=None,
    edges=None,
    center_point=None,
    threshold=None,
    edge_attr=None,
    cut_edge_types=None,
    method="concave_hull_knn",
    **kwargs
)

Generate an isochrone polygon from a graph.

An isochrone represents the area reachable from a center point within a given travel threshold (distance or time). This function computes the set of reachable edges and nodes in a network and generates a polygon that encloses this reachable area.

Parameters:

Name	Type	Description	Default
graph	Graph or MultiGraph	The network graph.	None
nodes	GeoDataFrame or dict	Nodes of the graph.	None
edges	GeoDataFrame or dict	Edges of the graph.	None
center_point	Point or GeoSeries or GeoDataFrame	The origin point(s) for the isochrone calculation.	None
threshold	float	The maximum travel distance (or time) that defines the boundary of the isochrone.	None
edge_attr	str	The edge attribute to use for distance calculation (e.g., 'length', 'travel_time'). If None, the function will use the default edge attribute.	"travel_time"
cut_edge_types	list[tuple[str, str, str]] | None	List of edge types to remove from the graph before processing (e.g., [("bus_stop", "is_next_to", "bus_stop")]).	None
method	str	The method to generate the isochrone polygon. Options are: "concave_hull_knn": Creates a concave hull (k-NN) around reachable nodes. "concave_hull_alpha": Creates a concave hull (alpha shape) around reachable nodes. "convex_hull": Creates a convex hull around reachable nodes. "buffer": Creates a buffer around reachable edges/nodes.	"concave_hull_knn"
**kwargs	Any	Additional parameters for specific isochrone generation methods: For method="concave_hull_knn": k : int, default 100 The number of nearest neighbors to consider. For method="concave_hull_alpha": hull_ratio : float, default 0.3 The ratio for concave hull generation (0.0 to 1.0). Higher values mean tighter fit. allow_holes : bool, default False Whether to allow holes in the concave hull. For method="buffer": buffer_distance : float, default 100 The distance to buffer reachable geometries. cap_style : int, default 1 The cap style for buffering. 1=Round, 2=Flat, 3=Square. join_style : int, default 1 The join style for buffering. 1=Round, 2=Mitre, 3=Bevel. resolution : int, default 16 The resolution of the buffer (number of segments per quarter circle).	{}

Returns:

Type	Description
GeoDataFrame	A GeoDataFrame containing a single Polygon or MultiPolygon geometry that represents the isochrone.

Raises:

Type	Description
ValueError	If required inputs are missing or invalid.

Visualization

Core Utilities Module.

This module provides essential utilities for graph conversion, data validation, and spatial analysis operations. It serves as the foundation for the city2graph package, offering a standardized data format for handling geospatial relations across GeoPandas, NetworkX objects, and eventually PyTorch Geometric objects. The module enables seamless integration between different graph representations and geospatial data formats through robust data structures and conversion functions.

Functions:

Name	Description
plot_graph	Plot a graph with a unified interface.

plot_graph

plot_graph(
    graph=None,
    nodes=None,
    edges=None,
    ax=None,
    bgcolor="#000000",
    figsize=(12, 12),
    subplots=True,
    ncols=None,
    legend_position="upper left",
    labelcolor="white",
    title_color=None,
    node_color=None,
    node_alpha=None,
    node_zorder=None,
    node_edgecolor=None,
    markersize=None,
    edge_color=None,
    edge_linewidth=None,
    edge_alpha=None,
    edge_zorder=None,
    **kwargs
)

Plot a graph with a unified interface.

This function provides a unified interface for plotting spatial network data, supporting both GeoDataFrame-based and NetworkX-based inputs. NetworkX graphs are automatically converted to GeoDataFrames before plotting. It can handle homogeneous and heterogeneous graphs with customizable styling.

Parameters:

Name	Type	Description	Default
graph	Graph or MultiGraph	The NetworkX graph to plot. If provided without nodes/edges, the function will convert it to GeoDataFrames before plotting.	None
nodes	GeoDataFrame or dict[str, GeoDataFrame]	Nodes to plot. Can be a single GeoDataFrame (homogeneous) or a dictionary mapping node type names to GeoDataFrames (heterogeneous).	None
edges	GeoDataFrame or dict[tuple[str, str, str], GeoDataFrame]	Edges to plot. Can be a single GeoDataFrame (homogeneous) or a dictionary mapping edge type tuples (src_type, rel_type, dst_type) to GeoDataFrames (heterogeneous).	None
ax	Axes or ndarray	The axes on which to plot. If None, a new figure and axes are created.	None
bgcolor	str	Background color for the plot (Black theme).	"#000000"
figsize	tuple[float, float]	Figure size as (width, height) in inches.	(12, 12)
subplots	bool	If True and the graph is heterogeneous, plot each node/edge type in a separate subplot. Uses 'ax' as array of subplots if provided.	True
ncols	int	Number of columns (subplots per row) when plotting heterogeneous graphs with subplots=True. If None, defaults to min(3, number_of_edge_types).	None
legend_position	str or None	Position of the legend for heterogeneous graphs. Common values include "upper left", "upper right", "lower left", "lower right", "center", etc. If None, no legend is displayed.	"upper left"
labelcolor	str	Color of the legend text labels.	"white"
title_color	str	Color for subplot titles when subplots=True. Falls back to a white title on black backgrounds if not provided.	None
node_color	str, float, pd.Series, or dict	Color for nodes. Can be a scalar, column name, Series, or a dictionary mapping node types to colors for heterogeneous graphs.	None
node_alpha	float, pd.Series, or dict	Transparency for nodes (0.0-1.0). Can be a scalar, column name, Series, or a dictionary mapping node types to transparency values.	None
node_zorder	int, pd.Series, or dict	Drawing order for nodes. Can be a scalar, column name, Series, or a dictionary mapping node types to zorder values.	None
node_edgecolor	str, pd.Series, or dict	Color for node borders. Can be a scalar, column name, Series, or a dictionary mapping node types to edge colors.	None
markersize	float, pd.Series, or dict	Size of the node markers. Can be a scalar, column name, Series, or a dictionary mapping node types to marker sizes.	None
edge_color	str, float, pd.Series, or dict	Color for edges. Can be a scalar, column name, Series, or a dictionary mapping edge types to colors for heterogeneous graphs.	None
edge_linewidth	float, pd.Series, or dict	Line width for edges. Can be a scalar, column name, Series, or a dictionary mapping edge types to line widths.	None
edge_alpha	float, pd.Series, or dict	Transparency for edges (0.0-1.0). Can be a scalar, column name, Series, or a dictionary mapping edge types to transparency values.	None
edge_zorder	int, pd.Series, or dict	Drawing order for edges. Can be a scalar, column name, Series, or a dictionary mapping edge types to zorder values.	None
**kwargs	Any	Additional keyword arguments passed to the GeoPandas plotting functions. Supports attribute-based styling where parameters can be specified as: Scalar values (str/float): Applied uniformly to all geometries Column names (str): If the string matches a column in the GeoDataFrame, that column's values are used for styling pd.Series: Direct values for each geometry Other common options: etc.	{}

Returns:

Type	Description
Axes or ndarray or None	The axes object(s) used for plotting.

Raises:

Type	Description
ImportError	If matplotlib is not installed.
ValueError	If no valid input is provided (all parameters are None).
TypeError	If the input data types are not supported.

Examples:

>>> import geopandas as gpd
>>> import pandas as pd
>>> import networkx as nx
>>> # Plot from NetworkX graph (automatically converted to GeoDataFrames)
>>> G = nx.Graph()
>>> G.add_node(0, pos=(0, 0))
>>> G.add_edge(0, 1)
>>> plot_graph(graph=G)
>>> # Plot from GeoDataFrames with scalar styling
>>> plot_graph(nodes=nodes_gdf, edges=edges_gdf, node_color='red')
>>> # Plot with attribute-based node colors (by column name)
>>> plot_graph(nodes=nodes_gdf, edges=edges_gdf, node_color='building_type')
>>> # Plot with pd.Series for edge linewidth
>>> edge_widths = pd.Series([1.0, 2.0, 1.5], index=edges_gdf.index)
>>> plot_graph(nodes=nodes_gdf, edges=edges_gdf, edge_linewidth=edge_widths)
>>> # Plot heterogeneous graph
>>> plot_graph(nodes=nodes_dict, edges=edges_dict)