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(city_name, crs_projected='3857', ranking='betweenness_centrality', seed_point_type='auto', seed_point_grid_spacing='auto', seed_point_delta='auto', seed_point_linking='auto', existing_network_spacing=None, export_data=True, export_file_format='geojson', export_data_slug=None, export_plots=False, allow_edge_overlaps=False, city_boundary_file=None, street_network_file=None, seed_point_file=None, 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_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 or street_network_file is set.

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) is better.

rankingstr, default ‘betweenness_centrality’

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

seed_point_typestr (‘auto’ | ‘grid_square’ | ‘grid_triangle’ | ‘rail’ | ‘school’ | ‘park’ | ‘file’ | ‘tags’), default ‘auto’

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_file. 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_delta‘auto’ | int, default ‘auto’

Maximum distance between raw seed points and osm nodes for snapping, in meters. Auto-value is round(seed_point_grid_spacing/4).

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_spacingint, 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 25%, to ensure that the existing bicycle network is built first.

export_databool, default True

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

export_file_formatstr (‘geojson’ | ‘gpkg’), 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_data_slugstr | None, 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_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.

city_boundary_filestr | 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”. city_boundary_file and street_network_file cannot both be set.

street_network_filestr | None, default None

If not set to None, the street network will be loaded from this file. Must be a gpkg file in unprojected crs EPSG:4326 with layers nodes and edges, with the structure that a osmnx street network g has after saved its undirected version via ox.io.save_graph_geopackage(). For example: >>> g = ox.graph_from_place(“Barcelona”, network_type=’drive’) >>> ox.io.save_graph_geopackage(g.to_undirected(), “Barcelona_streets.gpkg”). city_boundary_file and street_network_file cannot both be set.

seed_point_filestr | None, default None

If not set to None, the seed points will be 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’.

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”]} will retrieve 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)

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

[2]

  1. 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)

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

Examples

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

>>> edges_ranked = growbikenet("Lyon")

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

>>> edges_ranked = growbikenet("Copenhagen", city_boundary_file="./tests/test_data/copenhagen.shp")

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

>>> edges_ranked = growbikenet("Lyon", seed_point_type='school', existing_network_spacing=500)

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

>>> edges_ranked = growbikenet("Oelde", street_network_file="./tests/test_data/oelde_streets.gpkg", seed_point_type='file', seed_point_file="./tests/test_data/oelde_seed_points.gpkg")