inequality.theil – Theil inequality and decomposition measures

The inequality.theil module provides Theil inequality based measures

New in version 1.0.

Theil Inequality metrics

Author(s):

Serge Rey srey@asu.edu

class pysal.inequality.theil.Theil(y)

Classic Theil measure of inequality

Parameters:

y : array (n,t) or (n,)

with n taken as the observations across which inequality is calculated. If y is (n,) then a scalar inequality value is determined. If y is (n,t) then an array of inequality values are determined, one value for each column in y.

Notes

This computation involves natural logs. To prevent ln[0] from occurring, a small value is added to each element of y before beginning the computation.

Examples

>>> import pysal
>>> f=pysal.open("../examples/mexico.csv")
>>> vnames=["pcgdp%d"%dec for dec in range(1940,2010,10)]
>>> y=np.transpose(np.array([f.by_col[v] for v in vnames]))
>>> theil_y=Theil(y)
>>> theil_y.T
array([ 0.20894344,  0.15222451,  0.10472941,  0.10194725,  0.09560113,
        0.10511256,  0.10660832])

Attributes

T

array (t,) or (1,)

Theil’s T for each column of y

class pysal.inequality.theil.TheilD(y, partition)

Decomposition of Theil’s T based on partitioning of observations into exhaustive and mutually exclusive groups

Parameters:

y : array (n,t) or (n, )

with n taken as the observations across which inequality is calculated If y is (n,) then a scalar inequality value is determined. If y is (n,t) then an array of inequality values are determined, one value for each column in y.

partition : array (n, )

elements indicating which partition each observation belongs to. These are assumed to be exhaustive.

Examples

>>> import pysal
>>> f=pysal.open("../examples/mexico.csv")
>>> vnames=["pcgdp%d"%dec for dec in range(1940,2010,10)]
>>> y=np.transpose(np.array([f.by_col[v] for v in vnames]))
>>> regimes=np.array(f.by_col('hanson98'))
>>> theil_d=TheilD(y,regimes)
>>> theil_d.bg
array([ 0.0345889 ,  0.02816853,  0.05260921,  0.05931219,  0.03205257,
        0.02963731,  0.03635872])
>>> theil_d.wg
array([ 0.17435454,  0.12405598,  0.0521202 ,  0.04263506,  0.06354856,
        0.07547525,  0.0702496 ])

Attributes

T	array (n,t) or (n,)	global inequality T
bg	array (n,t) or (n,)	between group inequality
wg	array (n,t) or (n,)	within group inequality

class pysal.inequality.theil.TheilDSim(y, partition, permutations=99)

Random permutation based inference on Theil’s inequality decomposition.

Provides for computationally based inference regarding the inequality decomposition using random spatial permutations. [R1]

Parameters:

y : array (n,t) or (n, )

with n taken as the observations across which inequality is calculated If y is (n,) then a scalar inequality value is determined. If y is (n,t) then an array of inequality values are determined, one value for each column in y.

partition : array (n, )

elements indicating which partition each observation belongs to. These are assumed to be exhaustive.

permutations : int

Number of random spatial permutations for computationally based inference on the decomposition.

References

[R1]	(1, 2) Rey, S.J. (2004) “Spatial analysis of regional economic growth, inequality and change,” in M.F. Goodchild and D.G. Jannelle (eds.) Spatially Integrated Social Science. Oxford University Press: Oxford. Pages 280-299.

Examples

>>> import pysal
>>> f=pysal.open("../examples/mexico.csv")
>>> vnames=["pcgdp%d"%dec for dec in range(1940,2010,10)]
>>> y=np.transpose(np.array([f.by_col[v] for v in vnames]))
>>> regimes=np.array(f.by_col('hanson98'))
>>> np.random.seed(10)
>>> theil_ds=TheilDSim(y,regimes,999)
>>> theil_ds.bg_pvalue
array([ 0.4  ,  0.344,  0.001,  0.001,  0.034,  0.072,  0.032])

Attributes

observed	array (n,t) or (n,)	TheilD instance for the observed data.
bg	array (permutations+1,t)	between group inequality
bg_pvalue	array (t,1)	p-value for the between group measure. Measures the percentage of the realized values that were greater than or equal to the observed bg value. Includes the observed value.
wg	array (size=permutations+1)	within group inequality Depending on the shape of y, 1 or 2-dimensional