Morphology#

Network analysis functions for creating and manipulating network graphs.

city2graph.morphology.morphological_graph(buildings_gdf, segments_gdf, center_point=None, distance=None, private_id_col='tess_id', public_id_col='id', public_geom_col='barrier_geometry', contiguity='queen', keep_buildings=False)[source]#

Create a morphological graph from buildings and road segments.

The private spaces are represented as tessellations, and the public spaces are represented as a dual graph of road segments.

This function performs a series of operations: 1. Creates tessellations based on buildings and road barrier geometries 2. Optionally filters the network by distance from a specified center point 3. Identifies enclosed tessellations adjacent to the segments 4. Creates three types of connections:

  • Private to private (between tessellation cells)

  • Public to public (between road segments)

  • Private to public (between tessellation cells and road segments)

Parameters:

  • buildings_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing building polygons

  • segments_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing road segments as LineStrings. Should include a ‘barrier_geometry’ column or the column specified in public_geom_col.

  • center_point (Union[Point, gpd.GeoSeries, gpd.GeoDataFrame], optional) – Optional center point for filtering the network by distance. If provided, only segments within the specified distance will be included.

  • distance (float, default=1000) – Maximum network distance from center_point to include segments, if center_point is provided. If None, no distance filtering will be applied even if center_point is provided.

  • private_id_col (str, default='tess_id') – Column name that uniquely identifies each tessellation cell (private space).

  • public_id_col (str, default='id') – Column name that uniquely identifies each road segment (public space).

  • public_geom_col (str, default='barrier_geometry') – Column name in segments_gdf containing the processed geometry to use.

  • contiguity (str, default='queen') – Type of contiguity for private-to-private connections, either ‘queen’ or ‘rook’.

  • keep_buildings (bool, default=False) – If True, performs a spatial left join between tessellation and buildings to include building attributes in the tessellation data. Building index columns are dropped.

Returns:

Dictionary containing the following elements: - ‘nodes’: Dictionary with ‘private’ and ‘public’ GeoDataFrames - ‘edges’: Dictionary with edge relationships between node types

Return type:

dict

Notes

  • If center_point is not provided, all segments will be included.

  • The barrier_geometry column should contain the processed geometries for road segments. If it doesn’t exist, the function will use the column specified in public_geom_col.

  • The function requires the city2graph package and depends on create_tessellation, filter_graph_by_distance, create_private_to_private, create_public_to_public, and create_private_to_public functions.

city2graph.morphology.private_to_private_graph(private_gdf, private_id_col=None, group_col=None, contiguity='queen')[source]#

Create contiguity matrices for private spaces.

If group_col is provided, the contiguity is calculated for each group separately.

Parameters:

  • private_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing tessellation polygons

  • private_id_col (str, default None) – Column name that uniquely identifies each private space If None, will use DataFrame index

  • group_col (str, default None) – Column name used to group tessellation polygons If None, all polygons are treated as one group

  • contiguity (str, default "queen") – Type of contiguity, either ‘queen’ or ‘rook’

Returns:

GeoDataFrame containing LineString connections between adjacent private spaces

Return type:

geopandas.GeoDataFrame

Raises:

  • TypeError – If input is not a GeoDataFrame

  • ValueError – If contiguity is not ‘queen’ or ‘rook’ or if required columns are missing

city2graph.morphology.private_to_public_graph(private_gdf, public_gdf, private_id_col=None, public_id_col=None, public_geom_col=None, tolerance=1.0)[source]#

Create connections between private spaces and public spaces.

Parameters:

  • private_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing private space polygons

  • public_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing public space linestrings

  • private_id_col (str, default None) – Column name in private_gdf that uniquely identifies each private space If None, will use DataFrame index

  • public_id_col (str, default None) – Column name in public_gdf that uniquely identifies each public space If None, will use DataFrame index

  • public_geom_col (str, default None) – Column name in public_gdf containing alternative geometry to use If None, will use the geometry column

  • tolerance (float, default 1) – Buffer tolerance for spatial joins

Returns:

GeoDataFrame containing LineString connections between private and public spaces

Return type:

geopandas.GeoDataFrame

city2graph.morphology.public_to_public_graph(public_gdf, public_id_col=None, tolerance=1e-08)[source]#

Create connections between public spaces represented as a dual graph.

Parameters:

  • public_gdf (geopandas.GeoDataFrame) – GeoDataFrame containing public space linestrings

  • public_id_col (str, default None) – Column name that uniquely identifies each public space If None, will use DataFrame index

  • tolerance (float, default 1e-8) – Distance tolerance for detecting endpoint connections

Returns:

GeoDataFrame containing LineString connections between public spaces

Return type:

geopandas.GeoDataFrame