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}\]

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.

categorical : bool (default False)

Treat values as categories (will not use binning).

categories : list-like (default None)

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

**classification_kwds : dict

Keyword arguments for 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, ...]>

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