Morphology#

Module for creating morphological graphs from urban data.

This module provides comprehensive functionality for analyzing urban morphology through graph representations, focusing on the relationships between private spaces (buildings and their tessellations) and public spaces (street segments). It creates heterogeneous graphs that capture the complex spatial relationships inherent in urban environments. Both GeoDataFrame and NetworkX objects can be converted to PyTorch Geometric Data or HeteroData by functions from graph.py.

The module specializes in three types of spatial relationships: 1. Private-to-private: Adjacency relationships between building tessellations 2. Public-to-public: Topological connectivity between street segments 3. Private-to-public: Interface relationships between private and public spaces

morphological_graph(buildings_gdf, segments_gdf, center_point=None, distance=None, clipping_buffer=inf, primary_barrier_col='barrier_geometry', contiguity='queen', keep_buildings=False, tolerance=1e-06, as_nx=False)[source]#

Create a morphological graph from buildings and street segments.

This function creates a comprehensive morphological graph that captures relationships between private spaces (building tessellations) and public spaces (street segments). The graph includes three types of relationships: private-to-private adjacency, public-to-public connectivity, and private-to-public interfaces.

The ‘private_id’ for tessellation cells is derived from ‘tess_id’ (generated by create_tessellation) or assigned sequentially if ‘tess_id’ doesn’t directly map. The ‘public_id’ for street segments is taken directly from the index of segments_gdf.

Parameters:

  • buildings_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing building polygons. Should contain Polygon or MultiPolygon geometries.

  • segments_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing street segments. Should contain LineString geometries.

  • center_point (geopandas.GeoSeries or geopandas.GeoDataFrame, optional) – Center point(s) for spatial filtering. If provided with distance parameter, only segments within the specified distance will be included.

  • distance (float, optional) – Maximum distance from center_point for spatial filtering. When specified, street segments beyond this shortest-path distance are removed and tessellation cells are kept only if their own distance via these segments does not exceed this value.

  • clipping_buffer (float, default=math.inf) – Buffer distance to ensure adequate context for generating tessellation. Must be non-negative.

  • primary_barrier_col (str, optional) – Column name containing alternative geometry for public spaces. If specified and exists, this geometry will be used instead of the main geometry column for tessellation barriers.

  • contiguity (str, default="queen") – Type of spatial contiguity for private-to-private connections. Must be either “queen” or “rook”.

  • keep_buildings (bool, default=False) – If True, preserves building information in the tessellation output.

  • tolerance (float, default=1e-6) – Buffer distance for public geometries when creating private-to-public connections. This parameter controls how close private spaces need to be to public spaces to establish a connection.

  • as_nx (bool, default=False) – If True, convert the output to a NetworkX graph.

Returns:

A tuple containing: - nodes: Dictionary with keys “private” and “public” containing node GeoDataFrames - edges: Dictionary with relationship type keys containing edge GeoDataFrames If as_nx is True, returns a NetworkX graph.

Return type:

tuple[dict[str, geopandas.GeoDataFrame], dict[tuple[str, str, str], geopandas.GeoDataFrame]] | networkx.Graph

Raises:

  • TypeError – If buildings_gdf or segments_gdf are not GeoDataFrames.

  • ValueError – If contiguity parameter is not “queen” or “rook”. If clipping_buffer is negative.

See also

private_to_private_graph

Create adjacency between private spaces.

private_to_public_graph

Create connections between private and public spaces.

public_to_public_graph

Create connectivity between public spaces.

Notes

The function first filters the street network by distance (resulting in segs). A segs_buffer GeoDataFrame is also created for tessellation context, potentially filtered by distance + clipping_buffer or distance if center_point and distance are provided. This segs_buffer is used to create enclosures and tessellations. It then establishes three types of relationships: 1. Private-to-private: Adjacency between tessellation cells (handled by private_to_private_graph) 2. Public-to-public: Topological connectivity between street segments 3. Private-to-public: Spatial interfaces between tessellations and streets

The output follows a heterogeneous graph structure suitable for network analysis of urban morphology.

Examples

>>> # Create morphological graph from buildings and segments
>>> nodes, edges = morphological_graph(buildings_gdf, segments_gdf)
>>> private_nodes = nodes['private']
>>> public_nodes = nodes['public']
private_to_private_graph(private_gdf, group_col=None, contiguity='queen', as_nx=False)[source]#

Create edges between contiguous private polygons based on spatial adjacency.

This function identifies spatial adjacency relationships between private polygons (e.g., tessellation cells) using either Queen or Rook contiguity criteria. Optionally groups connections within specified groups (e.g., enclosures). The input private_gdf is expected to have a ‘private_id’ column.

Parameters:

  • private_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing private space polygons. Must contain a ‘private_id’ column.

  • group_col (str, optional) – Column name for grouping connections. Only polygons within the same group will be connected. If None, all polygons are considered as one group.

  • contiguity (str, default="queen") – Type of spatial contiguity to use. Must be either “queen” or “rook”. Queen contiguity includes vertex neighbors, Rook includes only edge neighbors.

  • as_nx (bool, default=False) – If True, convert the output to a NetworkX graph.

Returns:

A tuple containing: - Nodes of the private graph (the input private_gdf). - Edges of the private graph (adjacency connections). If as_nx is True, returns a NetworkX graph.

Return type:

tuple[geopandas.GeoDataFrame, geopandas.GeoDataFrame] | networkx.Graph

Raises:

  • TypeError – If private_gdf is not a GeoDataFrame.

  • ValueError – If contiguity not in {“queen”, “rook”}, or if group_col doesn’t exist.

See also

morphological_graph

Main function that creates comprehensive morphological graphs.

private_to_public_graph

Create connections between private and public spaces.

public_to_public_graph

Create connectivity between public spaces.

Notes

The function uses libpysal’s spatial weights to determine adjacency relationships. Edge geometries are created as LineStrings connecting polygon centroids. Self-connections and duplicate edges are automatically filtered out. The input private_gdf is expected to have a ‘private_id’ column.

Examples

>>> # Create private-to-private adjacency graph
>>> nodes, edges = private_to_private_graph(tessellation_gdf)
>>> # With grouping by enclosures
>>> nodes, edges = private_to_private_graph(tessellation_gdf, group_col='enclosure_id')
private_to_public_graph(private_gdf, public_gdf, primary_barrier_col=None, tolerance=1e-06, as_nx=False)[source]#

Create edges between private polygons and nearby public geometries.

This function identifies spatial relationships between private spaces (tessellations) and public spaces (street segments) by finding intersections between buffered public geometries and private polygons. Input GDFs are expected to have ‘private_id’ and ‘public_id’ columns respectively.

Parameters:

  • private_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing private space polygons. Expected to have a ‘private_id’ column.

  • public_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing public space geometries (typically LineStrings). Expected to have a ‘public_id’ column.

  • primary_barrier_col (str, optional) – Column name for alternative public geometry. If specified and exists, this geometry will be used instead of the main geometry column.

  • tolerance (float, default=1e-6) – Buffer distance for public geometries to detect proximity to private spaces.

  • as_nx (bool, default=False) – If True, convert the output to a NetworkX graph.

Returns:

A tuple containing: - Nodes of the private and public graphs (the input private_gdf and public_gdf). - Edges of the private-public graph (connections between private polygons and public geometries). If as_nx is True, returns a NetworkX graph.

Return type:

tuple[geopandas.GeoDataFrame, geopandas.GeoDataFrame] | networkx.Graph

Raises:

  • TypeError – If private_gdf or public_gdf are not GeoDataFrames.

  • ValueError – If ‘private_id’ or ‘public_id’ columns are missing from input GDFs.

See also

morphological_graph

Main function that creates comprehensive morphological graphs.

private_to_private_graph

Create adjacency between private spaces.

public_to_public_graph

Create connectivity between public spaces.

Notes

Edge geometries are created as LineStrings connecting the centroids of private polygons and public geometries. The function uses spatial joins to identify overlapping areas within the specified tolerance. Input GDFs are expected to have ‘private_id’ and ‘public_id’ columns respectively.

Examples

>>> # Create private-to-public interface graph
>>> nodes, edges = private_to_public_graph(tessellation_gdf, segments_gdf)
>>> # With custom tolerance
>>> nodes, edges = private_to_public_graph(tessellation_gdf, segments_gdf, tolerance=2.0)
public_to_public_graph(public_gdf, as_nx=False)[source]#

Create edges between connected public segments based on topological connectivity.

This function identifies topological connections between public space geometries (typically street segments) using the dual graph approach to find segments that share endpoints or connection points. The function automatically creates a unique identifier for each row if needed.

Parameters:

  • public_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing public space geometries (typically LineString).

  • as_nx (bool, default=False) – If True, convert the output to a NetworkX graph.

Returns:

A tuple containing: - Nodes of the public graph (the input public_gdf). - Edges of the public graph (connectivity). If as_nx is True, returns a NetworkX graph.

Return type:

tuple[geopandas.GeoDataFrame, gpd.GeoDataFrame] | networkx.Graph

Raises:

TypeError – If public_gdf is not a GeoDataFrame.

See also

morphological_graph

Main function that creates comprehensive morphological graphs.

private_to_private_graph

Create adjacency between private spaces.

private_to_public_graph

Create connections between private and public spaces.

Notes

The function uses the dual graph approach where each LineString becomes a node, and edges represent topological connections between segments. Edge geometries are created as LineStrings connecting the centroids of connected segments.

Examples

>>> # Create public-to-public connectivity graph
>>> nodes, edges = public_to_public_graph(segments_gdf)
>>> # Convert to NetworkX format
>>> graph = public_to_public_graph(segments_gdf, as_nx=True)