# cityseer.metrics.networks

Cityseer networks module for calculating network centralities using optimised JIT compiled functions.

There are two network centrality methods available depending on whether you’re using a node-based or segment-based approach:

These methods wrap the underlying `numba`

optimised functions for computing centralities, and provides access to all of the underlying node-based or segment-based centrality methods. Multiple selected measures and distances are computed simultaneously to reduce the amount of time required for multi-variable and multi-scalar strategies.

See the accompanying paper on `arXiv`

for additional information about methods for computing centrality measures.

The reasons for picking one approach over another are varied:

- Node based centralities compute the measures relative to each reachable node within the threshold distances. For
this reason, they can be susceptible to distortions caused by messy graph topologies such redundant and varied
concentrations of degree=2 nodes (e.g. to describe roadway geometry) or needlessly complex representations of
street intersections. In these cases, the network should first be cleaned using methods such as those available in
the
`graph`

module (see the graph cleaning guide for examples). If a network topology has varied intensities of nodes but the street segments are less spurious, then segmentised methods can be preferable because they are based on segment distances: segment aggregations remain the same regardless of the number of intervening nodes, however, are not immune from situations such as needlessly complex representations of roadway intersections or a proliferation of walking paths in greenspaces; - Node-based
`harmonic`

centrality can be problematic on graphs where nodes are erroneously placed too close together or where impedances otherwise approach zero, as may be the case for simplest-path measures or small distance thesholds. This happens because the outcome of the division step can balloon towards $\infty$ once impedances decrease below 1. - Note that
`cityseer`

’s implementation of simplest (angular) measures work on both primal (node or segment based) and dual graphs (node only). - Measures should only be directly compared on the same topology because different topologies can otherwise affect the expression of a measure. Accordingly, measures computed on dual graphs cannot be compared to measures computed on primal graphs because this does not account for the impact of differing topologies. Dual graph representations can have substantially greater numbers of nodes and edges for the same underlying street network; for example, a four-way intersection consisting of one node with four edges translates to four nodes and six edges on the dual. This effect is amplified for denser regions of the network.
- Segmentised versions of centrality measures should not be computed on dual graph topologies because street segment lengths would be duplicated for each permutation of dual edge spanning street intersections. By way of example, the contribution of a single edge segment at a four-way intersection would be duplicated three times.
- Global closeness is strongly discouraged because it does not behave suitably for localised graphs. Harmonic closeness or improved closeness should be used instead. Note that Global closeness ($\frac{nodes}{farness}$) and improved closeness ($\frac{nodes}{farness / nodes}$) can be recovered from the available metrics, if so desired, through additional (manual) steps.
- Network decomposition can be a useful strategy when working at small distance thresholds, and confers advantages such as more regularly spaced snapshots and fewer artefacts at small distance thresholds where street edges intersect distance thresholds. However, the regular spacing of the decomposed segments will introduce spikes in the distributions of node-based centrality measures when working at very small distance thresholds. Segmentised versions may therefore be preferable when working at small thresholds on decomposed networks.

## distance_from_beta

Map decay parameters $\beta$ to equivalent distance thresholds $d_{max}$ at the specified cutoff weight $w_{min}$.

It is generally not necessary to utilise this function directly.

### Parameters

$\beta$ value/s to convert to distance thresholds $d_{max}$.

An optional cutoff weight $w_{min}$ at which to set the distance threshold $d_{max}$.

### Returns

A numpy array of distance thresholds $d_{max}$.

## beta_from_distance

Map distance thresholds $d_{max}$ to equivalent decay parameters $\beta$ at the specified cutoff weight $w_{min}$. See `distance_from_beta`

for additional discussion.

It is generally not necessary to utilise this function directly.

### Parameters

$d_{max}$ value/s to convert to decay parameters $\beta$.

The cutoff weight $w_{min}$ on which to model the decay parameters $\beta$.

### Returns

A numpy array of decay parameters $\beta$.

## avg_distance_for_beta

Calculate the mean distance for a given $\beta$ parameter.

### Parameters

$\beta$ representing a spatial impedance / distance decay for which to compute the average walking distance.

The cutoff weight $w_{min}$ on which to model the decay parameters $\beta$.

### Returns

The average walking distance for a given $\beta$.

## pair_distances_betas

Pair distances and betas, where one or the other parameter is provided.

### Parameters

Distances corresponding to the local $d_{max}$ thresholds to be used for calculations. The $\beta$ parameters (for distance-weighted metrics) will be determined implicitly. If the `distances`

parameter is not provided, then the `beta`

parameter must be provided instead.

A $\beta$, or array of $\beta$ to be used for the exponential decay function for weighted metrics. The `distance`

parameters for unweighted metrics will be determined implicitly. If the `betas`

parameter is not provided, then the `distance`

parameter must be provided instead.

The default `min_threshold_wt`

parameter can be overridden to generate custom mappings between the `distance`

and `beta`

parameters. See `distance_from_beta`

for more information.

### Returns

Distances corresponding to the local $d_{max}$ thresholds to be used for calculations. The $\beta$ parameters (for distance-weighted metrics) will be determined implicitly. If the `distances`

parameter is not provided, then the `beta`

parameter must be provided instead.

A $\beta$, or array of $\beta$ to be used for the exponential decay function for weighted metrics. The `distance`

parameters for unweighted metrics will be determined implicitly. If the `betas`

parameter is not provided, then the `distance`

parameter must be provided instead.

## clip_weights_curve

Calculate the upper bounds for clipping weights produced by spatial impedance functions. Determine the upper weights threshold of the distance decay curve for a given $\beta$ based on the `spatial_tolerance`

parameter. This is used by downstream functions to determine the upper extent at which weights derived for spatial impedance functions are flattened and normalised. This functionality is only intended for situations where the location of datapoints is uncertain for a given spatial tolerance.

Use distance based clipping with caution for smaller distance thresholds. For example, if using a 200m distance threshold clipped by 100m, then substantial distortion is introduced by the process of clipping and normalising the distance decay curve. More generally, smaller distance thresholds should generally be avoided for situations where datapoints are not located with high spatial precision.

### Parameters

An array of distances corresponding to the local $d_{max}$ thresholds to be used for calculations.

An array of $\beta$ to be used for the exponential decay function for weighted metrics.

The spatial buffer distance corresponding to the tolerance for spatial inaccuracy.

### Returns

An array of maximum weights at which curves for corresponding $\beta$ will be clipped.

## node_centrality

Compute node-based network centrality.

### Parameters

A tuple of centrality measures to compute. Centrality keys can be selected from the available centrality measure `key`

values in the table beneath. Each centrality measure will be computed for all distance thresholds $d_{max}$.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

method.

A `GeoDataFrame`

representing nodes. Best generated with the `graphs.network_structure_from_nx`

method. The outputs of calculations will be written to this `GeoDataFrame`

, which is then returned from the method.

Distances corresponding to the local $d_{max}$ thresholds to be used for calculations. The $\beta$ parameters (for distance-weighted metrics) will be determined implicitly. If the `distances`

parameter is not provided, then the `beta`

parameter must be provided instead.

A $\beta$, or array of $\beta$ to be used for the exponential decay function for weighted metrics. The `distance`

parameters for unweighted metrics will be determined implicitly. If the `betas`

parameter is not provided, then the `distance`

parameter must be provided instead.

The scale of random jitter to add to shortest path calculations, useful for situations with highly rectilinear grids. `jitter_scale`

is passed to the `scale`

parameter of `np.random.normal`

.

Whether to use a simplest-path heuristic in-lieu of a shortest-path heuristic when calculating aggregations and distances.

The default `min_threshold_wt`

parameter can be overridden to generate custom mappings between the `distance`

and `beta`

parameters. See `distance_from_beta`

for more information.

### Returns

The input `node_gdf`

parameter is returned with additional columns populated with the calcualted metrics.

## segment_centrality

Compute segment-based network centrality.

### Parameters

A tuple of centrality measures to compute. Centrality keys can be selected from the available centrality measure `key`

values in the table beneath. Each centrality measure will be computed for all distance thresholds $d_{max}$.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

method.

A `GeoDataFrame`

representing nodes. Best generated with the `graphs.network_structure_from_nx`

method. The outputs of calculations will be written to this `GeoDataFrame`

, which is then returned from the method.

`distances`

parameter is not provided, then the `beta`

parameter must be provided instead.

`distance`

parameters for unweighted metrics will be determined implicitly. If the `betas`

parameter is not provided, then the `distance`

parameter must be provided instead.

The scale of random jitter to add to shortest path calculations, useful for situations with highly rectilinear grids. `jitter_scale`

is passed to the `scale`

parameter of `np.random.normal`

.

Whether to use a simplest-path heuristic in-lieu of a shortest-path heuristic when calculating aggregations and distances.

The default `min_threshold_wt`

parameter can be overridden to generate custom mappings between the `distance`

and `beta`

parameters. See `distance_from_beta`

for more information.

### Returns

The input `node_gdf`

parameter is returned with additional columns populated with the calcualted metrics.