Cityseer Recipes

This section contains a collection of recipes illustrating 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 answer in another (typically preceding) recipe.

Open an issue to request additional examples for a given use-case.

Tip

New to Python or geospatial analysis? Start with the Python 101 section first. These recipes assume familiarity with geopandas, coordinate reference systems, and basic Python. See the Glossary for definitions of key terms.

Network Preparation

cityseer uses networkx MultiGraphs to represent pedestrian networks. Spatial information is embedded in the graph nodes and edges so that cityseer 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 a custom boundary file;
  • geopandas data including 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.

Computing Metrics

cityseer converts the network into a rust data structure prior to computing derivative metrics. This improves performance so that analyses scale to larger cities with correspondingly larger datasets and networks.

This conversion is done using the network_structure_from_nx function from the cityseer io module. You will see this method used across all of the following examples. It produces three data structures:

  • A nodes GeoDataFrame containing the graph’s nodes. This stores the outputs of calculations and makes it easy to export results to files for use in QGIS or other GIS workflows.
  • An edges GeoDataFrame containing the graph’s edges, including derived properties such as metric and angular distances, entry and exit angles, and overall bearing.
  • A NetworkStructure object used internally by cityseer for computing measures.

Once prepared, the NetworkStructure object can be reused to calculate a variety of centrality, accessibility, mixed-use, and statistical metrics over the street network. It only needs to be recreated if the input network changes.

Use of the dual representation is optional but recommended. When using a dual representation, the nodes GeoDataFrame will contain both the dual nodes (midpoints of streets) and the primal edges (street geometries). The primal edges are set as the default geometry so that outputs can be visualised using street geometries.

Note that all distances used when computing metrics are network distances (shortest paths along the network), not Euclidean distances. For weighted variants, the weighting is based on network distance from each point of measure to the individual data points (such as land uses) under consideration.

Distance Thresholds

Most cityseer functions accept a distances parameter specifying the network distance thresholds (in metres) at which to compute metrics. You can compute multiple thresholds simultaneously. Common choices and their approximate real-world meaning:

Distance Walking time Typical use
200m ~2.5 min Immediate neighbourhood
400m ~5 min Local walkability
800m ~10 min Neighbourhood-scale access
1600m ~20 min District-scale patterns
5000m+ ~60 min+ City-wide structural analysis

Computing metrics at multiple distances simultaneously reveals how urban structure varies across scales. For example, a street may be highly central at 800m (locally important) but not at 5000m (not a major through-route). The minutes parameter can also be used as an alternative to specifying distances directly.

Centrality

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

Accessibility

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

Statistics

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

Visibility

See the Visibility page for examples of how to calculate visibility metrics from building footprint data.

Continuity

Street continuity metrics assess how consistently named routes, road classifications, or route numbers extend through the network. See the Continuity page for examples.

Edge Rolloff

When calculating network or layer metrics, the network must be buffered by a distance equal to the maximum distance threshold used by the algorithms. This prevents distorted results arising from edge rolloff effects. For example, if running analysis at distances of 500, 1000, and 2000m, then the network must be buffered by at least 2000m. Data layers should cover these buffered extents as well.

The live node attribute controls this. Nodes within the original (non-buffered) extents are set to live=True, while nodes in the surrounding buffer are set to live=False. The shortest-path algorithms have access to both, preventing edge rolloff, but derivative metrics are only computed for live=True nodes. This eliminates edge rolloff effects, reduces unnecessary computation, and clearly distinguishes the analysis area from the buffer zone. If boundary rolloff is not a concern, the default behaviour sets all nodes 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.