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, ordering='betweenness', 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, import_files={}, seed_point_tags=None)

Creates a list of urban street network edges ordered by an ordering 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 [2].

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 growable_network is set.

ordering{‘betweenness’, ‘closeness’, ‘random’}, default ‘betweenness’

Method used to order the edges.

seed_point_type{‘auto’, ‘grid_square’, ‘grid_triangle’, ‘rail’, ‘school’, ‘park’, ‘file’, ‘tags’}, default ‘auto’

• ‘auto’ selects ‘grid_square’ or ‘grid_triangle’ automatically depending on the street network’s orientation entropy, see [3].

• ‘grid_square’ creates a square grid.

• ‘grid_triangle’ creates a triangle grid. In this case, seed_point_linking must not be set to ‘quadrangulate’.

• ‘rail’, uses railway stations and halts.

• ‘school’ uses kindergartens, schools, colleges, and universities.

• ‘park’ uses parks, gardens, nature reserves, and public bathing places.

• ‘file’ imports seed_point. In this case, the name of the seed points in the exported file name is controlled via settings.seed_point_type_name.

• ‘tags’ uses geocodable seed_point_tags, see [4].

seed_point_grid_spacing‘auto’ or 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-values for seed_point_type.

• ‘grid_square’ with seed_point_linking ‘triangulate_delaunay’: 1707

• ‘grid_square’ with seed_point_linking ‘quadrangulate’: 1000

• ‘grid_triangle’: 1154

• otherwise: 1707

These values ensure that any point in the city is always within 500m of the network (under perfect conditions). For the explanation of case 1707 see [1].

seed_point_linking{‘auto’, ‘triangulate_delaunay’, ‘quadrangulate’}, default ‘auto’

The algorithm for linking up the seed points into an unrouted, abstract network.

• ‘auto’ selects ‘triangulate_delaunay’ or ‘quadrangulate’ automatically depending on the street network’s orientation entropy, see [3].

• ‘triangulate_delaunay’ uses Delaunay triangulation.

• ‘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 or ‘auto’ or int, default None

Spacing between seed points, in meters, only on the existing bicycle network. If set to None, 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. Independent of existing_network_spacing, all bicycle components shorter than constants.EXISTING_NETWORK_MINIMUM_COMPONENT_LENGTH are ignored.

export_databool, default True

If set to True, data is saved to a file. The filename is [slug]-growbikenet-[ordering]-from_scratch|from_bikenw-[seed_point_type].[settings.export_file_format], depending on the respective parameters, and where [slug] is a string id made out of city_query (or city_id if set).

city_idNone or str, default None

If set, the slugified city_id is used in the filename of the data export. For example, a city_id “Athens” will slugify into “athens” in filenames. If set to None, the slugified city_query is used in 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.

import_files: dict, default {}

The following key:value entries can be set:

• ‘city_boundary’None or str, 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’.

• ‘growable_network’None or str, default None

  If not set to None, the growable 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')
  

  To download a growable network that also includes existing bicycle infrastructure, as growbikenet does by default, replace the first line in the above example by this line:

  >>> g = ox.graph_from_place("Barcelona", custom_filter=gbn.constants.GROWABLE_NETWORK_CUSTOM_FILTER)
  

• ‘bike_network’None or str, 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’None or str, 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’. The name of the seed points in the exported file name is controlled via settings.seed_point_type_name.

• ‘point_data’None or str, default None

  If not set to None, an additional data set of points will be loaded from this file, representing point events like traffic 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. The data set is used to re-prioritize the ordering of the network links, controlled with settings.import_data_impact and settings.import_data_trip_point_balance, following [2].

• ‘trip_data’None or str, 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. The data set is used to re-prioritize the ordering of the network links, controlled with settings.import_data_impact and settings.import_data_trip_point_balance, following [2].

seed_point_tagsNone or dict[str, bool or str or 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_orderedgeopandas.geodataframe.GeoDataFrame

Geodataframe of all edges in street network ordered by the ordering method.

Notes

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.

References

[1] (1,2,3)

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

[2] (1,2,3)

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)

[3] (1,2)

7. 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_ordered = gbn.growbikenet("Lyon")

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

>>> edges_ordered = 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_ordered = 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_ordered = gbn.growbikenet("Oelde", seed_point_type='file', import_files={'growable_network':'./tests/test_data/oelde_growable_network.gpkg', 'seed_points':'./tests/test_data/oelde_seed_points.gpkg'})

growbikenet.settings

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

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.

crs_resultstr, default ‘4326’

EPSG code of the coordinate reference system for the resulting geodataframe and exported data. If ‘4326’ (WGS84) and export_file_format is set to ‘geojson’, data is exported via the RFC7946 standard.

export_pathdict(str)

Paths to results and plots folders to save data and plots.

export_file_format{‘gpkg’, ‘geojson’}, default ‘gpkg’

File format for the data export, relevant if export_data is set to True. If exporting as geojson, generates extra files for seed points, city boundary, and existing bicycle network (if relevant). If exporting as gkpg, these are added all in one file as extra layers.

import_data_impactfloat, default 9

Impact of imported trip or point data on results. Must be non-negative.

import_data_trip_point_balancefloat, default 0.5

Impact of imported trip data versus point data on results. Must be between 0 and 1, where 0 means no trip impact and full point impact, 1 means full trip impact and no point impact, and 0.5 means balanced impact of both. If only the trip data is imported, this variable is treated as 1; if only the point data is imported, this variable is treated as 0 - meaning in such a case the data impact is controlled only by settings.import_data_impact.

import_pathstr

Path to import files (as defined in growbikenet’s import_files parameter).

import_point_data_snap_distanceint, default 500

Maximum distance between point data and network links for snapping, in meters.

import_trip_data_snap_distanceint, default 500

Maximum distance between trip data and network links for snapping, in meters.

random_seedint, default 43

Random number generator seed for reproducibility

reroutebool, default True

Decide whether to add a rerouting step, which takes extra computations but removes unrealistic artefacts.

seed_point_snap_distance‘auto’ or 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. The default values for seed_point_grid_spacing of 1000/1154/1707 are: 250/289/427

seed_point_type_namestr, default ‘file’

The name of the seed points in the exported file name, when seed_point_type is set to ‘file’.

silentbool, default False

If set to True, suppresses all user feedback. Useful for batch exports.

vizdict

Dictionary of visualization settings:

• ‘bike_to_grow’dict

  Dictionary of properties for the bicycle network to grow but not yet grown.

• ‘bike_grown’dict

  Dictionary of properties for the bicycle network grown.

• ‘bike_existing’dict

  Dictionary of properties for the existing bicycle network.

• ‘seed_point’dict

  Dictionary of properties for the seed points. Set ‘markersize’ to 0 to hide them.

• ‘crs’str, default ‘auto’

  The CRS used for plotting. Option ‘auto’ sets a local azimuthal projection centered on the network. Otherwise, for Europe ‘3035’ (LAEA) and globally ‘54035’ (Equal Earth) or ‘54030’ (Robinson) also produce good results.