# cityseer.metrics.layers

## assign_gdf_to_network

Assign a `GeoDataFrame`

to a `structures.NetworkStructure`

. A `NetworkStructure`

provides the backbone for the calculation of land-use and statistical aggregations over the network. Data points will be assigned to the two closest network nodes — one in either direction — based on the closest adjacent street edge. This facilitates a dynamic spatial aggregation strategy which will select the shortest distance to a data point relative to either direction of approach.

### Parameters

A `GeoDataFrame`

representing data points. The coordinates of data points should correspond as precisely as possible to the location of the feature in space; or, in the case of buildings, should ideally correspond to the location of the building entrance.

The maximum distance to consider when assigning respective data points to the nearest adjacent network nodes.

An optional column name for data point keys. This is used for deduplicating points representing a shared source of information. For example, where a single greenspace is represented by many entrances as datapoints, only the nearest entrance (from a respective location) will be considered (during aggregations) when the points share a datapoint identifier.

### Returns

A `structures.DataMap`

instance.

The input `data_gdf`

is returned with two additional columns: `nearest_assigned`

and `next_neareset_assign`

.

## compute_landuses

Please use the compute_accessibilities or compute_mixed_uses functions instead.

## compute_accessibilities

Compute land-use accessibilities for the specified land-use classification keys. See `compute_landuses`

for additional information.

### Parameters

A `GeoDataFrame`

representing data points. The coordinates of data points should correspond as precisely as possible to the location of the feature in space; or, in the case of buildings, should ideally correspond to the location of the building entrance.

The column label from which to take landuse categories, e.g. a column labelled “landuse_categories” might contain “shop”, “pub”, “school”, etc., landuse categories.

Land-use keys for which to compute accessibilities. The keys should be selected from the same land-use schema used for the `landuse_labels`

parameter, e.g. “retail”. The calculations will be performed in both `weighted`

and `non_weighted`

variants.

A `GeoDataFrame`

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

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

, which is then returned from the function.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

function.

The maximum distance to consider when assigning respective data points to the nearest adjacent network nodes.

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.

An optional column name for data point keys. This is used for deduplicating points representing a shared source of information. For example, where a single greenspace is represented by many entrances as datapoints, only the nearest entrance (from a respective location) will be considered (during aggregations) when the points share a datapoint identifier.

Tolerance in metres indicating a spatial buffer for datapoint accuracy. Intended for situations where datapoint locations are not precise. If greater than zero, weighted functions will clip the spatial impedance curve above weights corresponding to the given spatial tolerance and normalises to the new range. For background, see `distance_from_beta`

.

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.

### Returns

The input `node_gdf`

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

The input `data_gdf`

is returned with two additional columns: `nearest_assigned`

and `next_neareset_assign`

.

## compute_mixed_uses

Compute landuse metrics. This function wraps the underlying `numba`

optimised functions for aggregating and computing various mixed-use and land-use accessibility measures. These are computed simultaneously for any required combinations of measures (and distances). Situations requiring only a single measure can instead make use of the simplified `hill_diversity`

, `hill_branch_wt_diversity`

, and `compute_accessibilities`

functions.

See the accompanying paper on `arXiv`

for additional information about methods for computing mixed-use measures at the pedestrian scale.

The data is aggregated and computed over the street network, with the implication that mixed-use and land-use accessibility aggregations are generated from the same locations as for centrality computations, which can therefore be correlated or otherwise compared. The outputs of the calculations are written to the corresponding node indices in the same `node_gdf`

`GeoDataFrame`

used for centrality methods, and which will display the calculated metrics under correspondingly labelled columns.

### Parameters

A `GeoDataFrame`

representing data points. The coordinates of data points should correspond as precisely as possible to the location of the feature in space; or, in the case of buildings, should ideally correspond to the location of the building entrance.

The column label from which to take landuse categories, e.g. a column labelled “landuse_categories” might contain “shop”, “pub”, “school”, etc., landuse categories.

A `GeoDataFrame`

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

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

, which is then returned from the function.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

function.

The maximum distance to consider when assigning respective data points to the nearest adjacent network nodes.

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.

Mixed-use metrics to compute, containing any combination of the `key`

values from the following table. See examples below for additional information.

An optional pairwise `NxN`

disparity matrix numerically describing the degree of disparity between any pair of distinct land-uses. This parameter is only required if computing mixed-uses using `hill_pairwise_disparity`

or `raos_pairwise_disparity`

.

The values of `q`

for which to compute Hill diversity. This parameter is only required if computing one of the Hill diversity mixed-use measures and is otherwise ignored.

Tolerance in metres indicating a spatial buffer for datapoint accuracy. Intended for situations where datapoint locations are not precise. If greater than zero, weighted functions will clip the spatial impedance curve above weights corresponding to the given spatial tolerance and normalises to the new range. For background, see `distance_from_beta`

.

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.

### Returns

The input `node_gdf`

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

The input `data_gdf`

is returned with two additional columns: `nearest_assigned`

and `next_neareset_assign`

.

## hill_diversity

Compute hill diversity for the provided `landuse_labels`

at the specified values of `q`

. See `compute_landuses`

for additional information.

### Parameters

`GeoDataFrame`

representing data points. The coordinates of data points should correspond as precisely as possible to the location of the feature in space; or, in the case of buildings, should ideally correspond to the location of the building entrance.

The column label from which to take landuse categories, e.g. a column labelled “landuse_categories” might contain “shop”, “pub”, “school”, etc., landuse categories.

A `GeoDataFrame`

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

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

, which is then returned from the function.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

function.

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 values of `q`

for which to compute Hill diversity. This parameter is only required if computing one of the Hill diversity mixed-use measures and is otherwise ignored.

Tolerance in metres indicating a spatial buffer for datapoint accuracy. Intended for situations where datapoint locations are not precise. If greater than zero, weighted functions will clip the spatial impedance curve above weights corresponding to the given spatial tolerance and normalises to the new range. For background, see `distance_from_beta`

.

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.

### Returns

The input `node_gdf`

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

`data_gdf`

is returned with two additional columns: `nearest_assigned`

and `next_neareset_assign`

.

## hill_branch_wt_diversity

Compute distance-weighted hill diversity for the provided `landuse_labels`

at the specified values of `q`

. See `compute_landuses`

for additional information.

### Parameters

`GeoDataFrame`

representing data points. The coordinates of data points should correspond as precisely as possible to the location of the feature in space; or, in the case of buildings, should ideally correspond to the location of the building entrance.

`GeoDataFrame`

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

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

, which is then returned from the function.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

function.

`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 values of `q`

for which to compute Hill diversity. This parameter is only required if computing one of the Hill diversity mixed-use measures and is otherwise ignored.

`distance_from_beta`

.

`jitter_scale`

is passed to the `scale`

parameter of `np.random.normal`

.

### Returns

`node_gdf`

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

`data_gdf`

is returned with two additional columns: `nearest_assigned`

and `next_neareset_assign`

.

## compute_stats

Compute stats. This function wraps the underlying `numba`

optimised functions for computing statistical measures. The data is aggregated and computed over the street network relative to the network nodes, with the implication that statistical aggregations are generated from the same locations as for centrality computations, which can therefore be correlated or otherwise compared.

### Parameters

`GeoDataFrame`

representing data points. The coordinates of data points should correspond as precisely as possible to the location of the feature in space; or, in the case of buildings, should ideally correspond to the location of the building entrance.

The column labels corresponding to the columns in `data_gdf`

from which to take numerical information.

`GeoDataFrame`

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

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

, which is then returned from the function.

A `structures.NetworkStructure`

. Best generated with the `graphs.network_structure_from_nx`

function.

`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.

An optional column name for data point keys. This is used for deduplicating points representing a shared source of information. For example, where a single greenspace is represented by many entrances as datapoints, only the nearest entrance (from a respective location) will be considered (during aggregations) when the points share a datapoint identifier.

`jitter_scale`

is passed to the `scale`

parameter of `np.random.normal`

.

### Returns

`node_gdf`

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

`data_gdf`

is returned with two additional columns: `nearest_assigned`

and `next_neareset_assign`

.