momepy.simpson

momepy.simpson(y, graph, binning='HeadTailBreaks', gini_simpson=False, inverse=False, categorical=False, **classification_kwds)[source]

Calculates the Simpson’s diversity index of values within neighbours defined in graph. Uses mapclassify.classifiers under the hood for binning. Requires mapclassify>=.2.1.0 dependency.

\[\lambda=\sum_{i=1}^{R} p_{i}^{2}\]

Adapted from [Feliciotti, 2018].

Notes

The index of y must match the index along which the graph is built.

Parameters:
y : Series

A DataFrame or Series containing the values to be analysed.

graph : libpysal.graph.Graph

A spatial weights matrix for the data.

binning : str (default 'HeadTailBreaks')

One of mapclassify classification schemes. For details see mapclassify API documentation.

gini_simpson : bool (default False)

Return Gini-Simpson index instead of Simpson index (1 - λ).

inverse : bool (default False)

Return Inverse Simpson index instead of Simpson index (1 / λ).

categorical : bool (default False)

Treat values as categories (will not use binning).

**classification_kwds : dict

Keyword arguments for the classification scheme. For details see mapclassify documentation.

Returns:

A Series containing resulting values.

Return type:

Series

Examples

>>> from libpysal import graph
>>> path = momepy.datasets.get_path("bubenec")
>>> buildings = geopandas.read_file(path, layer="buildings")
>>> buildings.head()
   uID                                           geometry
0    1  POLYGON ((1603599.221 6464369.816, 1603602.984...
1    2  POLYGON ((1603042.88 6464261.498, 1603038.961 ...
2    3  POLYGON ((1603044.65 6464178.035, 1603049.192 ...
3    4  POLYGON ((1603036.557 6464141.467, 1603036.969...
4    5  POLYGON ((1603082.387 6464142.022, 1603081.574...

Define spatial graph:

>>> knn5 = graph.Graph.build_knn(buildings.centroid, k=5)
>>> knn5
<Graph of 144 nodes and 720 nonzero edges (1 component, 0 isolates) indexed by
 [0, 1, 2, 3, 4, ...]>

Simpson index of building area within 5 nearest neighbors:

>>> momepy.simpson(buildings.area, knn5)
focal
0      1.00
1      0.68
2      0.36
3      0.68
4      0.68
    ...
139    0.68
140    0.44
141    0.44
142    1.00
143    0.52
Length: 144, dtype: float64

In some occasions, you may want to override the binning method:

>>> momepy.simpson(buildings.area, knn5, binning="fisher_jenks", k=8)
focal
0      0.28
1      0.68
2      0.36
3      0.68
4      0.68
    ...
139    0.44
140    0.28
141    0.28
142    1.00
143    0.20
Length: 144, dtype: float64

See also

momepy.simpson_diversity

Calculates the Simpson’s diversity index of data.