The cityseer Python package for pedestrian-scale network-based urban analysis

Online documentation is available from cityseer.benchmarkurbanism.com and the github repository is available at github.com/benchmark-urbanism/cityseer-api. See this blog post for some background reading on how the package came about.

Abstract

cityseer-api is a Python package consisting of computational tools for fine-grained street network and land-use analysis, helpful in assessing the morphological precursors to vibrant neighbourhoods. It is underpinned by network-based methods developed from the ground-up for localised urban analysis at the pedestrian scale to provide contextually specific metrics for any given street-front location. cityseer-api computes a variety of node or segment-based network centrality methods, land-use accessibility and mixed-use measures, and statistical aggregations. Aggregations are computed dynamically — directly over the street network while taking the direction of approach into account — and can optionally incorporate spatial impedances and network decomposition to accentuate spatial precision. The use of Python facilitates compatibility with popular computational tools for network manipulation (NetworkX), geospatial topology (shapely), and the numpy stack of scientific packages. The provision of graph cleaning tools aids the incorporation of Open Street Map derived network topologies. Underlying loop-intensive algorithms are implemented in Numba JIT compiled code so that the methods scale efficiently to larger networks.

Overview

cityseer-api is a network-based spatial analysis package for contextually precise urban analytic workflows. The implemented methods are primarily intended for application at pedestrian walking tolerances, commonly up to 800m and infrequently exceeding 1600m. cityseer-api provides distance-weighted metrics that can — optionally — be combined with network ‘decomposition’ to generate observations at an exceptionally high spatial resolution. These forms of contextually sensitive urban analytic workflows aid the comparative analysis of urban development while providing a tool to gauge the impact of design decisions on considerations such as walkability or pedestrian accessibility to land-uses for a given location.

Computational methods for network-based centrality and land-use analysis rely extensively on shortest-path algorithms, presenting substantial computational complexity due to nested computational loops. Pure Python network-based measures, such as those implemented in NetworkX (Hagberg et al. 2008), can consequently become prohibitively slow if applied to street networks for larger towns and cities. Computational speed improvements can be attained through the use of Python packages such as Graph-Tool (Peixoto 2014), which wrap underlying optimised C or C++ code libraries, and this was the approach adopted by the author before the development of cityseer-api. Nevertheless, whereas high-performance graph-analysis packages can be co-opted for generic forms of network analysis, they do not necessarily offer the degree of extensibility required for convenient experimentation with the underlying algorithmic considerations more specific to analytics from an urbanist’s perspective. Accordingly, attempts to co-opt existing off-the-shelf packages for unanticipated purposes incurs a sufficient degree of code complexity to create a bottleneck to furthered development while causing computational speed advantages to dissipate. This conundrum prompted the development of the codebase that has become formalised as the cityseer-api package, adopting an approach leveraging pure Python and NumPy (Harris et al. 2020), but with computationally intensive algorithms optimised through use of Numba JIT (just-in-time) compilation (Lam et al. 2015). This strategy allows for wide-ranging experimentation and the ensuing customisation of underlying algorithms, thereby facilitating code abstraction, reducing duplicitous code, improving code maintenance through ongoing development and upgrade cycles, and adopting paradigms specifically suited to pedestrian-scale urban analysis. This approach has allowed for a range of particular issues to be addressed:

• Localised analysis is based on network methods applied over the graph through means of a ‘moving-window’, whereby the graph is isolated at specified distance thresholds before localised analysis of the currently windowed node’s context. These thresholds are conventionally based on either crow-flies euclidean distances or actual network distances (Cooper 2015). cityseer-api takes the position that true network distances are more representative when working at smaller pedestrian distance thresholds, particularly when applied to land-use accessibilities and mixed-use calculations;
• It is common to use either shortest-distance or simplest-path (shortest angular ‘distance’) impedance heuristics. When using simplest-path heuristics, it is necessary to modify the underlying shortest-path algorithms to prevent side-stepping of sharp angular turns; otherwise, two smaller side-steps can be combined to ‘short-cut’ sharp corners (Turner 2007). It is also common for methods to be applied to either primal graph representations, generally used with shortest-path methods such as those applied by multiple centrality assessment analysis (Porta et al. 2006), or dual graph representations, typically used with simplest-path methods in the tradition of space syntax (Hillier & Hanson 1984);
• There is a range of possible centrality and mixed-use methods, many of which can be weighted by distances or street lengths. Some conventional methods, even if widely used, have not necessarily proved suitable for localised urban network analysis workflows: for example, conventional formulations of closeness centrality do not behave as anticipated on windowed graphs, and mixed-use analysis methods utilising larger-scale zoned or gridded aggregations are problematic if interpreted at the scale of streets. These methods and their implications are explored in detail in related papers on centrality methods and mixed-use methods;
• Centrality methods are susceptible to topological distortions arising from ‘messy’ graph representations as well as due to the conflation of topological and geometrical properties of street networks. cityseer-api addresses these through the inclusion of graph cleaning functions; procedures for splitting geometrical properties from topological representations; and the inclusion of segmented centrality measures, which are less susceptible to distortions introduced by varying intensities of nodes;
• Pedestrian-scale analysis requires approaches facilitating the evaluation of respective measures at finely-spaced intervals along street fronts. Further, granular evaluation of land-use accessibilities and mixed-uses requires that land-uses be assigned to the street network in a contextually precise manner. These are addressed in cityseer-api through the application of network decomposition combined with algorithms allowing for bidirectional assignment and aggregation of data points to network nodes based on the closest adjacent street edge and the direction of approach.

cityseer-api includes a variety of convenience methods for the general preparation of networks and their conversion into (and out of) the lower-level data structures used by the underlying algorithms. These graph utility methods are designed to work with NetworkX to facilitate ease of use. Broad overviews of these methods and how they can be used as part of typical workflows are provided in the paper, and in the detailed package documentation directly available at cityseer.benchmarkurbanism.com.

A complement of code tests maintains the integrity of the code-base through general package maintenance and upgrade cycles and, as of the time of writing, is based on Python 3.9. Shortest-path algorithms, harmonic closeness, and betweenness algorithms are tested against NetworkX. Mock data and test plots have been used to visually confirm the intended behaviour for divergent simplest and shortest-path heuristics and for testing the assignment of data points to nearby network nodes given various scenarios.

Please see the linked preprint paper for additional information.