Cookbook

This repository contains examples for the cityseer package.

Cookbook

This cookbook contains a collection of recipes to illustrate typical usage scenarios for cityseer.

The recipes build on each other, so if you are wondering why or how to do something, you may find the answers in another (typically preceding) recipe.

Please open an issue to request the addition of further examples for a given use-case.

Datasets

The datasets used from the recipes are available on the datasets page, where you can also find information on the sources.

Installation

To install cityseer, you can use pip:

pip install --upgrade cityseer

Or, from a notebook:

!pip install --upgrade cityseer

The examples in this cookbook also use packages such as geopandas, networkx, and matplotlib. You can install them using the same method.

Recipes

Network Preparation

cityseer uses networkx MultiGraphs to represent pedestrian networks. In doing so, it embeds spatial information in the graph nodes and edges so that it can accurately manipulate the graphs and calculate derivative metrics.

See the Network Preparation page for examples of how to create a cityseer compatible networkx graph from:

  • OSM data using bounding boxes, radii around points, or from a custom boundary file;
  • geopandas data including the use of geopandas to open and import files such as geopackages and shapefiles;
  • Imports from momepy and osmnx;
  • Automatic and manual network simplification;
  • Casting primal networks to dual representations to model and visualise metrics using streets instead of intersections.

Metrics

cityseer converts the network into a rust data structure prior to computing derivative metrics. This is done to improve performance so that it can be used for larger cities with correspondingly larger data sets and networks.

This is done using network_structure_from_nx function which is available in the cityseer io module. You will see this method used in all of the following examples. Use of this method will result in three derivative data structures:

  • A nodes GeoDataFrame with the graph’s nodes. This is used for saving the outputs of calculations, and makes it easy to export the outputs of calculations to files that can be used from QGIS or other GIS software and workflows.
  • An edges GeoDataFrame with the graph’s edges, including information that has been generated for the graph’s edges such as metric and angular distances, entry and exit angles, and the overall bearing of the edge.
  • A cityseer NetworkStructure object which is used by cityseer for calculating the measures.

Once you’ve prepared the NetworkStructure object, you can use it over-and-over again to calculate a variety of centrality, accessibility, mixed-uses, and statistical metrics over the street network. The exception to this is when you change the input network, in which case you need to re-create the NetworkStructure object.

Use of the dual representation is optional, but recommended. Keep in mind that if you’ve converted your networkx network into a dual representation, then the nodes GeoDataFrame will contain both the dual nodes (midpoints of streets) the primal edges. The primal edges will be set to the default geometry so that outputs can be visualised using the primal street geometries.

Note that distances used when computing accessibilities, statistics, or other measures are all based on distances over the network. In the case of weighted variants, the distances used for the weighting process are the distances from each point of measure to the individual data points (such as land uses) under consideration.

Centrality

See the Network Centrality page for examples of how to calculate a variety of shortest “metric” and simplest “angular” centrality metrics.

Accessibility

See the Accessibility page for examples of how to calculate a variety of landuse accessibility and mixed-use metrics.

Statistics

See the Statistics page for examples of how to calculate statistical metrics over the network.

Edge Rolloff

When calculating network or layer metrics, the network has to be buffered by a distance equal to the maximum distance threshold being considered by the algorithms. This prevents problematic results arising due to edge roll-off effects. For example, if running analysis using distances of 500, 1000, 2000m, then the network must be buffered by 2000m. When using data layers, the data points should — for the same reasons — cover these buffered extents as well.

The live=True node attribute is used for identifying nodes falling within the original non-buffered graph extents as opposed to the live=False nodes that fall within the surrounding buffered area. The underlying shortest-path algorithms will have access to both live=True and live=False nodes (thus preventing edge rolloff), but derivative metrics are only tabulated for live=True nodes. This eliminates edge roll-off effects, reduces unnecessary computation, and cleanly identifies which nodes are or are not in the buffered roll-off area. If some other post-processing step will be used for filtering the nodes, or if boundary roll-off is not being considered, then use the default behaviour where all nodes automatically set to live=True.

Here is an example of how to set node status to live or not based on whether it intersects the original boundary.