User reference¶

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

The standard way to import the GrowBikeNet package is via import growbikenet as gbn. The main growbikenet() function below is then called via gbn.growbikenet(), see the Minimum working example.

growbikenet.growbikenet¶

growbikenet.growbikenet.growbikenet(city_query, ranking='betweenness_centrality', seed_point_type='auto', seed_point_grid_spacing='auto', seed_point_linking='auto', existing_network_spacing=None, export_data=True, city_id=None, export_plots=False, allow_edge_overlaps=False, import_files={}, seed_point_tags=None)[source]¶

Creates a list of urban street network edges ordered by a 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]_. The original paper [1] uses minimum weight triangulation, but Delaunay triangulation is implemented much faster and in practice gives identical results. Triangulation and metrics (betweenness, closeness) are calculated for the unrouted, abstract network for which egde lengths are taken from the routed network.

Parameters:

city_querystr

Search string for the city that the analysis should be performed on. This is the query used to fetch the data from nominatim. Overruled for data fetching if city_boundary or street_network is set.

rankingstr, default ‘betweenness_centrality’

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

If set to ‘auto’, selects ‘grid_square’ or ‘grid_triangle’ automatically depending on the street network’s orientation entropy, see [3]. If set to ‘grid_square’, creates a square grid. If set to ‘grid_triangle’, creates a triangle grid. In this case, seed_point_linking must not be set to ‘quadrangulate’. If set to ‘rail’, uses railway stations and halts. If set to ‘school’, uses kindergartens, schools, colleges, and universities. If set to ‘park’, uses parks, gardens, nature reserves, and public bathing places. If set to ‘file’, imports seed_point. If set to ‘tags’, uses geocodable seed_point_tags, see [4].

seed_point_grid_spacing‘auto’ | int, default ‘auto’

If seed_point_type is set to ‘grid_square’ or ‘grid_triangle’, this is the spacing between seed points, in meters. Auto-value for seed_point_type ‘grid_square’ with seed_point_linking ‘triangulate_delaunay’: 1707 Auto-value for seed_point_type ‘grid_square’ with seed_point_linking ‘quadrangulate’: 1000 Auto-value for seed_point_type ‘grid_triangle’: 1154 Auto-value otherwise: 1707 These values ensure that any point in the city is always within 500m of the network (under perfect conditions). For case 1707, see [1].

seed_point_linkingstr (‘auto’ | ‘triangulate_delaunay’ | ‘quadrangulate’), default ‘auto’

The algorithm for linking up the seed points into an unrouted, abstract network. If set to ‘auto’, selects ‘triangulate_delaunay’ or ‘quadrangulate’ automatically depending on the street network’s orientation entropy, see [3]. If set to ‘triangulate_delaunay’, uses Delaunay triangulation. If set to ‘quadrangulate’, uses quadrangulation, which only works for seed_point_type ‘grid_square’ and existing_network_spacing None. Useful for grid-like street networks like Manhattan or Barcelona.

existing_network_spacingNone | ‘auto’ | int, 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. existing_network_spacing is recommended to be smaller than seed_point_grid_spacing, ideally around 50%, to ensure that the existing bicycle network is built first. Option ‘auto’ sets existing_network_spacing to 50% of the seed_point_grid_spacing.

export_databool, default True

If set to True, data is saved to a file. The filename is [slug]-[ranking]-[seed_point_type].[settings.export_file_format], where slug is a string id made out of city_query.

city_idstr | None, default None

If set, the slugified city_id is used as the filename of the data export. For example, a city_id “Athens” will turn to “athens” in filenames. If set to None, the slugified city_query is used as the filename of the data export. It is useful to set a city_id for cities where the city_query is not the city name, for example to set for a city_query “Municipality of Athens” the city_id to “Athens”.

export_plotsbool, default False

If set to True, plots are saved to files, overwriting existing ones.

allow_edge_overlapsbool, default False

If set to False, removes edge overlaps in consecutive growth stages and deletes growth stages that do not add anything new.

import_files: dict, default {}

The following key:value entries can be set:

“city_boundary”str | None, default None: If not set to None, the study area is selected from the (Multi)Polygon provided in the city_boundary shape or gpkg file, ideally in unprojected latitude-longitude degrees (EPSG:4326), but EPSG:3857 also works. For example, “./tests/test_data/copenhagen_city_boundary.shp”.
“street_network”str | None, default None: If not set to None, the street network is loaded from this file. Must be a gpkg file in unprojected crs EPSG:4326 with layers nodes and edges, with the structure that an undirected osmnx street network g has after saved via ox.io.save_graph_geopackage(). For example: >>> g = ox.graph_from_place(“Barcelona”, network_type=’drive’) >>> g = nx.MultiGraph(ox.convert.to_digraph(g)) >>> ox.io.save_graph_geopackage(g, “Barcelona_streets.gpkg”).
“bike_network”str | None, default None: If not set to None, the existing bike network is loaded from this file. Must be a gpkg file in unprojected crs EPSG:4326 with layers nodes and edges, with the structure that an undirected osmnx bike network has after saved via ox.io.save_graph_geopackage().
“seed_points”str | None, default None: If not set to None, the seed points is loaded from this file. Must be a gpkg file in unprojected crs EPSG:4326 containing only point objects. For example, “./tests/test_data/oelde_seed_points.shp”. seed_point_type must be set to ‘file’.
“point_data”str | None, default None: If not set to None, an additional data set of points will be loaded from this file, representing point events like crashes or citizen feedback to improve bike infrastructure. Must be a gpkg file in unprojected crs EPSG:4326 containing only point objects, optionally with an int “num” column that encodes the number of point events. To be used in future versions of growbikenet.
“trip_data”str | None, default None: If not set to None, an additional data set of trips will be loaded from this file, representing trip events for prioritizing bike infrastructure growth. Must be a csv file in unprojected crs EPSG:4326 containing the following fields: o_lat, o_lon, d_lat, d_lon. Optionally there can be an int “num” field that encodes the number of trips between each origin and destination. To be used in future versions of growbikenet.

seed_point_tagsNone | dict[str, bool | str | list[str]], default None

If not None, must be a geocodable seed_point_tags, see [4], and seed_point_type must be set to ‘tags’. For example, seed_point_tags={“railway”: [“station”, “halt”]} retrieves exactly the same as seed_point_type=’rail’.

Returns:

edges_rankedgeopandas.geodataframe.GeoDataFrame: ordered geodataframe of all edges in street network

References

[1] (1,2,3)

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

[2]

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)

[3] (1,2)

Boeing, “Urban spatial order: Street network orientation, configuration, and entropy”, Applied Network Science 4, 67 (2019)

[4] (1,2)

https://osmnx.readthedocs.io/en/stable/user-reference.html#osmnx.features.features_from_place

Examples

Minimum working example: Grow a bicycle network from scratch in Lyon.

>>> edges_ranked = gbn.growbikenet("Lyon")

Grow a bicycle network from scratch in Copenhagen, providing a study area polygon to include also Frederiksberg and Amager.

>>> edges_ranked = gbn.growbikenet("Copenhagen", import_files={'city_boundary':"./tests/test_data/copenhagen_city_boundary.shp"}) 

Expand the existing bicycle network of Lyon, connecting all educational institutions.

>>> edges_ranked = gbn.growbikenet("Lyon", seed_point_type='school', existing_network_spacing='auto') 

Grow a bicycle network in Oelde from scratch, working offline by importing the street network and custom seed points from file.

>>> edges_ranked = gbn.growbikenet("Oelde", seed_point_type='file', import_files={'street_network':"./tests/test_data/oelde_street_network.gpkg", 'seed_points':"./tests/test_data/oelde_seed_points.gpkg"})

growbikenet.settings¶

Global settings for growbikenet that can be configured by the user.

export_pathdict(str | Path): Paths to results, plots, and video folders to save data, plots, and videos.
import_pathstr | Path: Path to import files (as defined in growbikenet’s import_files parameter).
crs_projectedstr, default ‘3857’: EPSG code of the 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) or ‘54030’ (Robinson) is better.
export_file_formatstr (‘geojson’ | ‘gpkg’), default ‘gpkg’: File format for the data export, relevant if export_data set to True. 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.
seed_point_snap_distance‘auto’ | int, default ‘auto’: Maximum distance between raw seed points and osm nodes for snapping, in meters. Auto-value is ceil(seed_point_grid_spacing*constants._SEED_POINT_SNAP_DISTANCE_FACTOR). If integer, must be positive.
random_seedint: Random number generator seed for reproducibility
vizdict: Dictionary of visualization settings