transport_frames.frame

Module for creating and weighting transport frame

Functions

add_region_attr(n, regions, polygon_buffer)

Add a 'border_region' attribute to nodes based on their intersection with region polygons.

get_frame(graph, admin_centers, ...[, ...])

Creates frame from graph.

mark_exits(frame, area_polygon, ...)

Assign the 'exit', 'exit_country' and 'boorder_region' attribute to nodes in a GeoDataFrame based on their intersection with city boundaries.

plot_frame(frame[, zoom_out_factor])

Plot the transport frame with exit points, city nodes, and categorized roads.

plot_weighted_roads(weighted_graph[, ...])

Visualize a weighted road network on a map.

weigh_roads(frame[, restricted_terr_gdf])

Assigns and normalizes weights for roads in the network based on their proximity to exits.

Classes

CentersSchema(*args, **kwargs)

Schema for validating central cities.

PointSchema(*args, **kwargs)

Schema for validating points.
class transport_frames.frame.PointSchema(*args, **kwargs)[source]

Bases: BaseSchema

Schema for validating points.

Variables:

_geom_types (list) – List of allowed geometry types for the points, default is [shapely.Point]

class Config

Bases: Config

name = 'PointSchema'
class transport_frames.frame.CentersSchema(*args, **kwargs)[source]

Bases: BaseSchema

Schema for validating central cities.

Variables:

_geom_types (list) – List of allowed geometry types for the blocks, default is [shapely.Polygon]

name: Series[str] = 'name'
class Config

Bases: Config

name = 'CentersSchema'
transport_frames.frame.get_frame(graph: ~networkx.classes.multidigraph.MultiDiGraph, admin_centers: ~geopandas.geodataframe.GeoDataFrame, area_polygon: ~geopandas.geodataframe.GeoDataFrame, region_polygons: ~geopandas.geodataframe.GeoDataFrame, country_polygon: ~geopandas.geodataframe.GeoDataFrame =                                             geometry  ...  display_name 0  MULTIPOLYGON (((-180.00000 62.55456, -179.9932...  ...        Russia  [1 rows x 17 columns]) → MultiDiGraph[source]

Creates frame from graph. Edges are filtered based on reg [1,2]. Region point nodes are assigned with ‘city_name’ attribute. Points, connecting the roads with other regions or countries are marked with ‘exit’ and ‘exit_country’.

Parameters:

  • graph (nx.MultiDiGraph) – City network graph with classified roads and edges.

  • admin_centers (gpd.GeoDataFrame) – Administrative region centers points to assign ‘city_name’ attribute

  • region_polygons (gpd.GeoDataFrame) – Polygons or regions of the country to assign ‘border_region’ attribute to exits

  • country_polygon (gpd.GeoDataFrame) – Polygon of the country to assign ‘exit_country’ attribute

Returns:

Frame of the graph with added ‘city_node’,’exit’,’exit_country’,’border_region’ attributes

Return type:

nx.MultiDiGraph

transport_frames.frame._filter_roads(graph) → MultiDiGraph[source]

Filters the graph to include only reg_1 and reg_2 roads.

Parameters:

graph (nx.MultiDiGraph) – graph with edges, containing ‘reg’ attribute

Returns:

Frame of filtered edges with ‘reg’ in [1, 2]

Return type:

nx.MultiDiGraph

transport_frames.frame._assign_city_names_to_nodes(points, frame, max_distance=3000) → MultiDiGraph[source]

Assigns city names to nodes in the graph based on proximity to city centers.

Parameters:

  • points (gpd.GeoDataFrame) – Region centers points

  • frame (nx.MultiDiGraph) – Frame of filtered edges with ‘reg’ in [1, 2]

  • max_distance (int) – Max distance (meters) on which a node can be assigned to a city

Returns:

A frame with nodes assigned with ‘city_name’ attribute

Return type:

nx.MultiDiGraph

transport_frames.frame.mark_exits(frame: MultiDiGraph, area_polygon: GeoDataFrame, regions_polygons: GeoDataFrame, country_polygon: GeoDataFrame) → MultiDiGraph[source]

Assign the ‘exit’, ‘exit_country’ and ‘boorder_region’ attribute to nodes in a GeoDataFrame based on their intersection with city boundaries.

Parameters:

framenx.MultiDiGraph

Frame graph

area_polygongpd.GeoDataFrame

GeoDataFrame with boundary of the inverstigated region

regions_polygonsgpd.GeoDataFrame

GeoDataFrame with polygons of the regions with ‘name’ column

country_polygongpd.GeoDataFrame

GeoDataFrame with boundary of the inverstigated country

returns:

Frame with assigned ‘exit’, ‘exit_country’ and ‘boorder_region’ node attributes

rtype:

nx.MultiDiGraph

transport_frames.frame.add_region_attr(n: GeoDataFrame, regions: GeoDataFrame, polygon_buffer: GeoDataFrame) → GeoDataFrame[source]

Add a ‘border_region’ attribute to nodes based on their intersection with region polygons.

Parameters:

  • n (gpd.GeoDataFrame) – Nodes GeoDataFrame with ‘exit’ and ‘exit_country’ attributes

  • regions (GeoDataFrame) – Regions GeoDataFrame with ‘name’ column

  • polygon_buffer (gpd.GeoDataFrame) – GeoDataFrame of region of interest boundary

Returns:

Updated nodes GeoDataFrame with ‘border_region’ attribute

Return type:

gpd.GeoDataFrame

transport_frames.frame._filter_polygons_by_buffer(gdf_polygons: GeoDataFrame, polygon_buffer: Polygon, crs) → GeoDataFrame[source]

Extract and filter region polygons based on a buffer around a given polygon.

Parameters:

  • gdf_polygons (gpd.GeoDataFrame) – Gdf of regions polygons

  • polygon_buffer (Polygon) – Polygon of the buffer polygon.

Returns:

- GeoDataFrame

Return type:

Filtered GeoDataFrame of region polygons.

transport_frames.frame.plot_frame(frame: MultiDiGraph, zoom_out_factor: float = 1.1) → None[source]

Plot the transport frame with exit points, city nodes, and categorized roads.

The function visualizes the road network using a basemap and styles edges and nodes based on their attributes:

  • Edges (Road Segments): - reg == 1 → Red (Higher priority roads) - reg == 2 → Blue (Lower priority roads)

  • Nodes (Intersections & Key Points): - exit == 1 → Green (Exit points) - exit_country == 1 → Black (Country exit points) - city_name.notna() → Red (City center nodes)

Parameters:

  • frame (nx.MultiDiGraph) – The road network graph.

  • zoom_out_factor (float, optional) – Scaling factor to adjust the map extent by zooming out (default: 1.1).

Returns:

Displays a styled transport frame plot with a basemap and legend.

Return type:

None

transport_frames.frame.weigh_roads(frame: MultiDiGraph, restricted_terr_gdf: GeoDataFrame | None = None) → GeoDataFrame[source]

Assigns and normalizes weights for roads in the network based on their proximity to exits.

The function calculates road segment (edge) weights by evaluating their connections to exit points and the type of regions they traverse. If provided, restricted territories influence weight assignment. The function then normalizes weights for further analysis.

Parameters:

  • frame (nx.MultiDiGraph) – The road network graph where nodes represent intersections or exits, and edges represent road segments.

  • restricted_terr_gdf (gpd.GeoDataFrame, optional) – GeoDataFrame containing restricted territories that may influence road weight calculations (default: None).

Returns:

The updated road network graph with assigned and normalized road segment weights.

Return type:

nx.MultiDiGraph

transport_frames.frame._mark_ref_type(n: GeoDataFrame, e: GeoDataFrame, frame: MultiDiGraph) → tuple[geopandas.geodataframe.GeoDataFrame, geopandas.geodataframe.GeoDataFrame, networkx.classes.multidigraph.MultiDiGraph][source]

Assign reference types to nodes in the road network based on proximity to reference edges.

This function identifies nodes marked as exits and assigns reference values and types based on the closest reference edge. The assigned values help categorize roads according to their significance.

Parameters:

  • n (gpd.GeoDataFrame) – GeoDataFrame of road network nodes, including exit nodes to be marked with reference types.

  • e (gpd.GeoDataFrame) – GeoDataFrame of road network edges containing reference attributes used for classification.

  • frame (nx.MultiDiGraph) – The road network graph where nodes represent intersections or exits.

Returns:

  • Updated GeoDataFrame of nodes with assigned reference values and types.

  • The original GeoDataFrame of edges.

  • The updated road network graph with relabeled nodes.

Return type:

tuple[gpd.GeoDataFrame, gpd.GeoDataFrame, nx.MultiDiGraph]

transport_frames.frame._determine_ref_type(ref: str) → float[source]

Convert a reference string into a numeric classification.

This function categorizes road references based on predefined patterns, assigning a numeric value that represents the road type.

Parameters:

ref (str) – A road reference string that follows a standard naming convention.

Returns:

A numeric code corresponding to the identified reference type. If no match is found, a default classification (2.3) is assigned.

Return type:

float

transport_frames.frame._get_weight(start: float, end: float, exit: bool) → float[source]

Compute the weight for a road segment based on reference types and exit status.

This function determines the weight of a road connection by considering the reference types of the start and end nodes, as well as whether the segment represents an exit. Different weight matrices are used for exit and non-exit scenarios.

Parameters:

  • start (float) – The reference type classification of the start node.

  • end (float) – The reference type classification of the end node.

  • exit (bool) – Indicates whether the segment represents an exit (True if exit, False otherwise).

Returns:

The weight value derived from the corresponding weight matrix.

Return type:

float

transport_frames.frame.plot_weighted_roads(weighted_graph: MultiDiGraph, scaling_factor: int = 10, zoom_out_factor: float = 1.1) → None[source]

Visualize a weighted road network on a map.

This function plots a road network where the thickness of edges corresponds to their assigned weights. The visualization includes a basemap for spatial context.

Parameters:

  • weighted_graph (nx.MultiDiGraph) – The road network graph where edges contain weight attributes.

  • scaling_factor (int, optional) – Factor to scale line thickness based on edge weight (default: 10).

  • zoom_out_factor (float, optional) – Factor to slightly expand the map view beyond the network boundaries (default: 1.1).

Returns:

Displays the road network plot with weighted edges.

Return type:

None