theil_between_group

Compute the between group Theil index.

Parameters:

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

Returns:

Name	Type	Description
float	float	The computed between group Theil index.

Source code in src/histolytics/spatial_agg/diversity.py

def theil_between_group(x: Sequence, partition: Sequence) -> float:
    """Compute the between group Theil index.

    Parameters:
        x (Sequence):
            The input value-vector. Shape (n, )
        partition (Sequence):
            The groups for each x value. Shape (n, ).

    Returns:
        float:
            The computed between group Theil index.
    """
    groups = np.unique(partition)
    x_total = x.sum(0) + SMALL

    # group totals
    g_total = np.array([x[partition == gid].sum(axis=0) for gid in groups])

    if x_total.size == 1:  # y is 1-d
        sg = g_total / (x_total * 1.0)
        sg.shape = (sg.size, 1)
    else:
        sg = np.dot(g_total, np.diag(1.0 / x_total))

    ng = np.array([np.sum(partition == gid) for gid in groups])
    ng.shape = (ng.size,)  # ensure ng is 1-d
    n = x.shape[0]

    # between group inequality
    sg = sg + (sg == 0)  # handle case when a partition has 0 for sum
    bg = np.multiply(sg, np.log(np.dot(np.diag(n * 1.0 / ng), sg))).sum(axis=0)

    return float(bg)