theil_index

cellseg_gsontools.diversity.theil_index(x)

Compute the Theil index of inequality for species.

Theil-index: $$ 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) $$

where \(y_i\) is the count of species \(i\) and \(N\) is the total count of species.

Parameters:

Name	Type	Description	Default
x	Sequence	The input value-vector. Shape (n, )	required

Returns:

Name	Type	Description
float	float	The computed Theil index.

Source code in cellseg_gsontools/diversity.py

def theil_index(x: Sequence) -> float:
    """Compute the Theil index of inequality for species.

    **Theil-index:**
    $$
    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)
    $$

    where $y_i$ is the count of species $i$ and $N$ is the total count of species.

    Parameters:
        x (Sequence):
            The input value-vector. Shape (n, )

    Returns:
        float:
            The computed Theil index.
    """
    n = len(x)
    x = x + SMALL * (x == 0)  # can't have 0 values
    xt = np.sum(x, axis=0) + SMALL
    s = x / (xt * 1.0)
    lns = np.log(n * s)
    slns = s * lns
    t = np.sum(slns)

    return t