momepy.shannon#

momepy.shannon(y, graph, binning='HeadTailBreaks', categorical=False, categories=None, **classification_kwds)[source]#

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

\[H^{\prime}=-\sum_{i=1}^{R} p_{i} \ln p_{i}\]
Parameters:
ySeries

A DataFrame or Series containing the values to be analysed.

graphlibpysal.graph.Graph

A spatial weights matrix for the data.

binningstr (default ‘HeadTailBreaks’)

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

categoricalbool (default False)

Treat values as categories (will not use binning).

categorieslist-like (default None)

A list of categories. If None, values.unique() is used.

**classification_kwdsdict

Keyword arguments for classification scheme For details see mapclassify documentation.

Returns:
Series

A Series containing resulting values.

Notes

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

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 indexed by
 [0, 1, 2, 3, 4, ...]>

Shannon index of building area within 5 nearest neighbors:

>>> momepy.shannon(buildings.area, knn5)
focal
0     -0.000000
1      0.500402
2      1.054920
3      0.500402
4      0.500402
        ...
139    0.500402
140    0.950271
141    0.950271
142   -0.000000
143    0.673012
Length: 144, dtype: float64

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

>>> momepy.shannon(buildings.area, knn5, binning="fisher_jenks", k=8)
focal
0      1.332179
1      0.500402
2      1.054920
3      0.500402
4      0.500402
        ...
139    0.950271
140    1.332179
141    1.332179
142   -0.000000
143    1.609438
Length: 144, dtype: float64