momepy.theil

momepy.theil(y, graph, q=None)

Calculates the Theil measure of inequality of values within neighbours defined in graph.

Uses inequality.theil.Theil under the hood. Requires ‘inequality’ package.

\[T = \sum_{i=1}^n \left( \frac{y_i}{\sum_{i=1}^n y_i} \ln \left[ N \frac{y_i} {\sum_{i=1}^n y_i} \right] \right)\]

Parameters:

ySeries

A DataFrame or Series containing the values to be analysed.

graphlibpysal.graph.Graph

A spatial weights matrix for the data.

qtuple, list, optional (default (0,100)))

A two-element sequence containing floats between 0 and 100 (inclusive) that are the percentiles over which to compute the range. The order of the elements is not important.

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, ...]>

Theil index of building area within 5 nearest neighbors:

>>> momepy.theil(buildings.area, knn5)
focal
0      0.106079
1      0.023256
2      0.800522
3      0.016015
4      0.013829
        ...
139    0.547522
140    0.041755
141    0.098827
142    0.159690
143    0.068131
Length: 144, dtype: float64

To eliminate the effect of outliers, you can take into account only values within a specified percentile range (q).

>>> momepy.theil(buildings.area, knn5, q=(25, 75))
focal
0      1.144550e-02
1      3.121656e-06
2      1.295882e-02
3      1.772730e-07
4      2.913017e-06
        ...
139    5.402548e-01
140    6.658486e-03
141    3.330720e-02
142    1.433583e-03
143    2.096421e-02
Length: 144, dtype: float64