Developer reference

This is the complete developer reference for the GrowBikeNet package. If you are looking for an introduction to GrowBikeNet, read the Getting started guide.

growbikenet.growbikenet

growbikenet.growbikenet.growbikenet(city_name, proj_crs='3857', ranking='betweenness_centrality', seed_point_type='grid', seed_point_grid_spacing=1707, seed_point_delta=500, existing_network_spacing=None, export_data=True, export_data_slug=None, export_file_format='geojson', export_plots=False, export_video=False, allow_edge_overlaps=False, city_boundary_file=None)

Creates a list of edges ordered by a specified ranking method.

The edges form a subnetwork of a city’s street network, interpreted as a growing bicycle network following [1]. By default, growth is from scratch, but the existing bicycle network can also be used as a starting point[Raf425b00f903-2]_. Note that the original paper [1] uses minimum weight triangulation, but Delaunay triangulation is much faster due to the Delaunay scipy function and gives in most cases identical results. Triangulation and metrics (betweenness, closeness) are calculated for the abstract network for which egde lengths are taken from the routed network.

Parameters:

city_namestr

Name of the city that the analysis should be performed on. This is the query string used to fetch the data from nominatim. Overruled (for data fetching) if city_boundary_file is set.

proj_crsstr, default ‘3857’

Coordinate reference system that is used to project osm data. Default is ‘3857’ (WGS 84 / Pseudo-Mercator). If this web mercator projection is not needed, then for Europe ‘3035’ (LAEA) and globally ‘54035’ (Equal Earth) is better.

rankingstr, default ‘betweenness_centrality’

Method used to rank edges. Must be ‘betweenness_centrality’ (default), ‘closeness_centrality’, or ‘random’.

seed_point_typestr, optional, default ‘grid’

If set to ‘grid’, creates a square grid If set to ‘rail’, uses rail stations

seed_point_grid_spacingint, optional, default 1707

If seed_point_type is set to ‘grid’, this is the spacing between seed points, in meters

seed_point_deltaint, optional, default 500

Maximum distance between generated seed points and osm nodes for snapping

existing_network_spacingint, optional, default None

Spacing between seed points, in meters, only on the existing bicycle network. If not set to a positive integer, the existing network is ignored.

export_databool, optional, default True

If set to True, data will be saved to a file. The filename is [slug]-[ranking]-[seed_point_type].gpkg, where slug is a string id made out of city_name.

export_data_slugstr, optional, default None

If not set to None, the city_name will be slugified and used as the slug in the filename of the data export

export_file_formatstr, optional, default “geojson”

File format for the data export, relevant if export_data set to True. Default “geojson”, also possible “gpkg”. If exporting as geojson, generates extra files for seed points and city boundary. If exporting as gkpg, these are added all in one file as extra layers.

export_plotsbool, optional, default False

If set to True, plots will be saved to files. Will overwrite previous files.

export_videobool, optional, default False

If set to True, video will be saved to a file (only possible if export_plots is set to True). Will overwrite previous files.

allow_edge_overlapsbool, default False

If set to False, removes edge overlaps in consecutive growth stages. In this case, growth stages that do not add anything new are deleted.

city_boundary_file(str | None), default None

If not set to None, the study area will be selected from the (Multi)Polygon provided in the city_boundary_file shape file, ideally in unprojected latitude-longitude degrees (EPSG:4326), but EPSG:3857 also works. For example, “./tests/test_data/copenhagen.shp”.

Returns:

a_edgesgeopandas.geodataframe.GeoDataFrame

ordered geodataframe of all edges in street network

References

[1] (1,2)

13. Szell, S. Mimar, T. Perlman, G. Ghoshal, R. Sinatra, “Growing urban bicycle networks”, Scientific Reports 12, 6765 (2022)

[2]

16. Folco, L. Gauvin, M. Tizzoni, M. Szell, “Data-driven micromobility network planning for demand and safety”, Environment and planning B: Urban analytics and city science 50(8), 2087-2102 (2023)

growbikenet.functions

Utility functions for growbikenet

growbikenet.functions.add_path_to_df(df, edges, g)

Parameters:

df: pandas.DataFrame

Dataframe with information about edges

edges: geopandas.geodataframe.GeoDataFrame

The street network, in a projected coordinate reference system

g: networkx.graph undirected

graph to use for routing

Returns:

df: pandas.DataFrame

Dataframe with added path nodes and path edges

growbikenet.functions.count_and_merge(n, bearings)

Double, then merge bins to avoid edge effects

Make twice as many bins as desired, then merge them in pairs. Prevents bin-edge effects around common values like 0° and 90°. Adapted from: https://github.com/gboeing/osmnx-examples/blob/v0.11/notebooks/17-street-network-orientations.ipynb

Parameters:

n: int

Number of bins

bearings: pandas.Series

Series of bearings

Returns:

bearings_merged: numpy.ndarray, dtype=int

The frequencies of the new merged bearings

growbikenet.functions.create_delaunay_edges(nodes_gdf)

Create df with edges that are part of Delaunay triangulation

Note that the original paper [1] uses minimum weight triangulation, but Delaunay triangulation is much faster due to the Delaunay scipy function and gives in most cases identical results. Triangulation and metrics (betweenness, closeness) are calculated for the abstract network for which egde lengths are taken from the routed network.

Parameters:

nodes_gdf: geopandas.geodataframe.GeoDataFrame

seed points with osmid and corresponding point geometry

Returns:

dfpandas.DataFrame

DataFrame with Edge pairs and singled out source and target nodes

References

[1]

13. Szell, S. Mimar, T. Perlman, G. Ghoshal, R. Sinatra, “Growing urban bicycle networks”, Scientific Reports 12, 6765 (2022)

growbikenet.functions.create_gdf_with_geoms(df, edges)

Parameters:

df: pandas.DataFrame

Dataframe with path nodes and path edges

edges: geopandas.GeoDataFrame

The street network, in a projected coordinate reference system

Returns:

gdf: geopandas.GeoDataFrame

projected GeoDataFrame with path nodes and path edges and merged geometries

growbikenet.functions.df_from_graph(A, method)

Create a dataframe from an input graph

Parameters:

A: networkx.graph

Graph created from triangulation edge list

method: str

Method used to rank edges. Must be ‘betweenness_centrality’ (default), ‘closeness_centrality’, or ‘random’.

Returns:

df: pandas.DataFrame

Dataframe with source and target information for each edge, as well as edge attributes as columns

growbikenet.functions.filter_seed_points(seed_points_snapped, seed_point_delta)

remove seed_points that are further than delta away from an actual osm node Parameters ———- seed_points_snapped: geopandas.geodataframe.GeoDataFrame

seed_points with additional information about geometries of osm nodes that seed nodes were snapped to

seed_point_delta: int

maximum distance a seed_point may be removed from an actual osm node

Returns:

seed_points_snapped: geopandas.geodataframe.GeoDataFrame

seed_points within delta away from an actual osm node, only columns are osmid and the associated osm geometry

growbikenet.functions.get_correct_edgetuples(edge_gdf, nodelist)

Helper function that maps a node list (output of nx.shortest_paths) to the correct set of edge tuples that can be used for INDEXING THE EDGE GDF

Parameters:

edge_gdf: geopandas.geodataframe.GeoDataFrame

The street network, in a projected coordinate reference system

nodelist: list

A list of nodes that make up source and targets of edges

Returns:

edgelist_final: list

List of edge tuples that can be used for INDEXING THE EDGE GDF

growbikenet.functions.get_existing_network_seed_points(nodes_exnw, existing_network_spacing)

Get seed points on an existing bicycle network

Start with the first (arbitrary) node from nodes_exnw. Then, for each node: Delete all other nodes closer than existing_network_spacing, proceed with the closest of the remaining nodes. Finish once all nodes are found or deleted.

Parameters:

nodes_exnw: geopandas.geodataframe.GeoDataFrame

Nodes of the existing bicycle network, in a projected coordinate reference system.

existing_network_spacing: int

Distance between seed points, in meters.

Returns

——-

seed_points_exnw: geopandas.geodataframe.GeoDataFrame

Seed points, already part of the network, in the same projected coordinate reference system as edges

growbikenet.functions.get_grid_seed_points(edges, seed_point_spacing, principal_bearing)

Get grid seed points for street network, rotated by principal bearing

Adapted from: https://github.com/gboeing/osmnx-examples/blob/v0.11/notebooks/17-street-network-orientations.ipynb

Parameters:

edges: geopandas.geodataframe.GeoDataFrame

The street network, in a projected coordinate reference system

seed_point_spacing: int

Distance between seed points, in meters

principal_bearing: float

Principal bearing (most common bearing of streets)

Returns:

seed_points: geopandas.geodataframe.GeoDataFrame

Seed points, rotated by principal bearing, to be snapped to the street network, in the same projected coordinate reference system as edges

growbikenet.functions.get_principal_bearing(G)

Determine the most common (principal) bearing, for the best grid orientation.

Adapted from: https://github.com/gboeing/osmnx-examples/blob/v0.11/notebooks/17-street-network-orientations.ipynb The bearing is determined from edges weighted by length.

Parameters:

Gnetworkx MultiGraph (undirected)

The graph from which to determine the principal bearing. Its coordinate reference system must be geographical, not projected.

Returns:

principal_bearing: float

The principal bearing, precise to 5 degrees.

growbikenet.functions.get_rail_seed_points(city_name, proj_crs, city_boundary_geometry=None)

Get rail seed points for a city

Parameters:

city_namestr

Name of the city that the analysis should be performed on. This is the query string used to fetch the data from nominatim. Overruled (for data fetching) if city_boundary_geometry is set.

proj_crsstr

Coordinate reference system that is used to project osm data. Default is ‘3857’ (WGS 84 / Pseudo-Mercator). If this web mercator projection is not needed, then for Europe ‘3035’ (LAEA) and globally ‘54035’ (Equal Earth) is better.

city_boundary_geometry(shapely Polygon | shapely MultiPolygon | None), default None

If not set to None, the study area will be selected from this geometry.

Returns:

seed_points: geopandas.geodataframe.GeoDataFrame

Seed points, rotated by principal bearing, to be snapped to the street network, in the same projected coordinate reference system as edges

growbikenet.functions.intersects_properly(geom1, geom2)

Helper function to check whether newly to be added edge intersects with already added edges for 2 shapely geometries, check whether they “properly intersect” (i.e. intersect but not touch, i.e. don’t share endpoints)

Parameters:

geom1shapely geometry

A shapely geometry, for example shapely.geometry.Point() or shapely.geometry.LineString()

geom2shapely geometry

A shapely geometry, for example shapely.geometry.Point() or shapely.geometry.LineString()

Returns:

boolean

Returns true if the two provided geometries intersect but do not touch

growbikenet.functions.node_to_edge_attributes(values_nodes, edges)

Map node to edge attributes.

Creates edge attributes by taking the average values of adjacent node attributes.

Parameters:

values_nodesdict

Keys: node ids, Values: Node attributes (for example a scalar)

edgesnetworkx.classes.reportviews.EdgeView

A view of edge attributes of a networkx graph. Could also be a list of tuples of node ids.

Returns:

values_edges: dict

Keys: tuples of node ids, Values: Edge attributes

growbikenet.functions.nx_to_nodes_edges(G, proj_crs)

Get nodes and projected edges from networkX graph

Parameters:

Gnetworkx.classes.multigraph.MultiGraph

networkX graph, undirected

proj_crsstr

Coordinate reference system that is used to project osm data.

Returns:

nodesgeopandas.geodataframe.GeoDataFrame

Extracted OSM nodes, projected, osmid is index

edgesgeopandas.geodataframe.GeoDataFrame

Extracted OSM edges, projected

growbikenet.functions.prepare_network(city_name, proj_crs, network_type='all_public', custom_filter=None, retain_all=True, city_boundary_geometry=None)

Download and prepare a street network from OSM via OSMnx Downloads a network with a given network_type and custom_filter using ox.graph_from_place. Then, stores the undirected OSM data in gdfs and projects using proj_crs. Parameters ———- city_name : str

Name of the city that the analysis should be performed on. Overruled (for data fetching) if city_boundary_geometry is set.

proj_crsstr

Coordinate reference system that is used to project osm data.

network_type{“all”, “all_public”, “bike”, “drive”, “drive_service”, “walk”}

What type of street network to retrieve if custom_filter is None.

custom_filter(str | list[str] | None)

A custom ways filter to be used instead of the network_type presets

retain_allbool, default True

If True, return the entire graph even if it is not connected, useful for disconnected bicycle networks. If False, retain only the largest weakly connected component, useful for road networks.

city_boundary_geometry(shapely Polygon | shapely MultiPolygon | None), default None

If not set to None, the study area will be selected from this geometry.

Returns:

nodesgeopandas.geodataframe.GeoDataFrame

Extracted OSM nodes, projected

edgesgeopandas.geodataframe.GeoDataFrame

Extracted OSM edges, projected

g_undirnetworkx.classes.multigraph.MultiGraph

Extracted networkX graph, undirected

growbikenet.functions.rank_df(df, method)

Rank dataframe by specified method

Parameters:

df: pandas.DataFrame

Dataframe with source and target information for each edge, as well as edge attributes as columns

method: str

Method used to rank edges. Must be ‘betweenness_centrality’ (default), ‘closeness_centrality’, or ‘random’.

growbikenet.functions.remove_edge_overlaps(edges_in)

In the grown network, remove edge overlaps stepwise

Parameters:

edges_in: geopandas.geodataframe.GeoDataFrame

The grown bike network, in a projected coordinate reference system

Returns:

edges_out: geopandas.geodataframe.GeoDataFrame

The grown bike network without edge overlaps, in a projected coordinate reference system

growbikenet.functions.reverse_bearing(x)

Reverse bearing.

Adapted from: https://github.com/gboeing/osmnx-examples/blob/v0.11/notebooks/17-street-network-orientations.ipynb

Parameters:

x: float

The bearing to reverse

Returns:

x_rev: float

The reversed bearing

growbikenet.functions.snap_seed_points(seed_points, nodes)

snap generated seed_points to actual osm nodes Parameters ———- seed_points: geopandas.geodataframe.GeoDataFrame

Seed points that were created within city area, to be snapped to actual osm nodes

nodes: geopandas.geodataframe.GeoDataFrame

actual osm nodes, downloaded from osmnx

Returns:

seed_points_snapped: geopandas.geodataframe.GeoDataFrame

seed_points with additional information about geometries of osm nodes that seed nodes were snapped to

growbikenet.functions.update_seed_points_with_existing_bike_network(seed_points_snapped, nodes_exnw, existing_network_spacing, proj_crs)

Update seed points with existing bike network

Updates given snapped seed points by incorporating seed points from an existing bike network.

Parameters:

seed_points_snappedgeopandas.geodataframe.GeoDataFrame

Snapped seed points on the street network, constructed with seed_point_grid_spacing

nodes_exnwgeopandas.geodataframe.GeoDataFrame

Nodes of the existing bike network

existing_network_spacingint

Positive integer denoting spacing between seed points, in meters, only on the existing bicycle network.

proj_crsstr

Coordinate reference system that is used to project osm data.

Returns:

seed_points_snappedgeopandas.geodataframe.GeoDataFrame

Snapped seed points incorporating both street grid and existing bike network

growbikenet.functions.update_with_existing_bike_network(city_name, proj_crs, g_undir, city_boundary_geometry=None)

Update street network with existing bike network

Downloads a network of protected bike infrastructure from OSM (retaining all connected components) and merges it to a given street network graph g_undir.

Parameters:

city_namestr

Name of the city that the analysis should be performed on. Overruled (for data fetching) if city_boundary_geometry is set.

proj_crsstr

Coordinate reference system that is used to project osm data.

g_undirnetworkx.classes.multigraph.MultiGraph

Street network networkX graph, undirected

city_boundary_geometry(shapely Polygon | shapely MultiPolygon | None), default None

If not set to None, the study area will be selected from this geometry.

Returns:

nodesgeopandas.geodataframe.GeoDataFrame

Updated OSM nodes of the street network, projected

edgesgeopandas.geodataframe.GeoDataFrame

Updated OSM edges of the street network, projected

g_undirnetworkx.classes.multigraph.MultiGraph

Updated street networkX graph, undirected

nodes_exnwgeopandas.geodataframe.GeoDataFrame

OSM nodes of the corresponding bike network, projected

edges_exnwgeopandas.geodataframe.GeoDataFrame

OSM edges of the corresponding bike network, projected