milia.recommend.equity#

Equity of a selection or a burden: how evenly it falls on people or places, and selection under a bound.

A recommendation that targets the customers or places with the largest benefit can concentrate its burden, enrolment in a programme or curtailment of export, on a few of them. Equity is measured here by the Gini coefficient of the burden,

\[G(\mathbf{b}) = \frac{\sum_i \sum_j \lvert b_i - b_j \rvert}{2 n^2 \bar b},\]

zero when every unit bears the same burden and approaching one when a single unit bears it all, and by the share of the burden borne by the most burdened tenth. For ranked lists, the exposure of the item at position \(p\) follows the logarithmic discount of NDCG, \(1 / \log_2(p + 1)\) [Singh and Joachims, 2018].

select() chooses the items of largest benefit subject to a bound on the Gini coefficient of the selection rate across groups, such as the share of each transformer’s customers that is enrolled, and frontier() traces how much benefit each bound costs.

Functions

exposure(positions)

Exposure of items at the given ranked positions, discounted as in NDCG.

frontier(benefit, count, groups, bounds)

Benefit and achieved equity of select() at each bound: the price of equity.

gini(burden)

Gini coefficient of a burden across units.

select(benefit, count, groups, bound)

The count items of largest total benefit whose selection rates across groups have a Gini at most bound.

topshare(burden[, share])

Share of the total burden borne by the most burdened share of units.

milia.recommend.equity.gini(burden)#

Gini coefficient of a burden across units.

Parameters:

burden (ArrayLike) – Burden of each unit, not negative.

Return type:

float

Returns:

The Gini coefficient, zero for an even burden or for no burden at all.

Examples

>>> gini([1, 1, 1, 1])
0.0
>>> gini([0, 0, 0, 4])
0.75
milia.recommend.equity.topshare(burden, share=0.1)#

Share of the total burden borne by the most burdened share of units.

Parameters:
  • burden (ArrayLike) – Burden of each unit, not negative.

  • share (float) – Fraction of units counted, the most burdened first.

Return type:

float

Returns:

Their share of the total burden; zero when there is no burden.

Examples

>>> topshare([1, 1, 1, 1, 1, 1, 1, 1, 1, 11], share=0.1)
0.55
milia.recommend.equity.exposure(positions)#

Exposure of items at the given ranked positions, discounted as in NDCG.

Parameters:

positions (ArrayLike) – Position of each item in a ranked list, starting at 1.

Return type:

ndarray

Returns:

The exposure of each item, one at the top.

Examples

>>> exposure([1, 2, 3]).round(3).tolist()
[1.0, 0.631, 0.5]
milia.recommend.equity.select(benefit, count, groups, bound)#

The count items of largest total benefit whose selection rates across groups have a Gini at most bound.

Each group \(g\) of \(N_g\) items is capped at \(\lceil (1 + s)\, n N_g / N \rceil\) selected items, a proportional share relaxed by a slack \(s\). The items are then taken in order of benefit within the caps. With \(s = 0\) every group is selected at nearly the same rate; as \(s\) grows the caps stop binding and the selection becomes the unconstrained choice of the largest benefits. The largest slack on a grid whose selection meets the bound is kept, which gives the largest benefit the search finds under the bound.

Parameters:
  • benefit (ArrayLike) – Benefit of selecting each item, such as the violation hours its enrolment removes.

  • count (int) – Number of items to select.

  • groups (ArrayLike) – Group of each item, such as its transformer.

  • bound (float) – Largest admissible Gini coefficient of the selection rates across groups.

Return type:

ndarray

Returns:

Indices of the selected items, by decreasing benefit.

Examples

>>> import numpy as np
>>> benefit = np.array([10, 9, 8, 7, 1, 1, 1, 1])
>>> groups = np.array([0, 0, 0, 0, 1, 1, 1, 1])
>>> select(benefit, 4, groups, bound=1.0).tolist()  # unconstrained: all from group 0
[0, 1, 2, 3]
>>> select(benefit, 4, groups, bound=0.0).tolist()  # equal rates: two from each group
[0, 1, 4, 5]
milia.recommend.equity.frontier(benefit, count, groups, bounds)#

Benefit and achieved equity of select() at each bound: the price of equity.

Parameters:
  • benefit (ArrayLike) – Benefit of selecting each item.

  • count (int) – Number of items to select.

  • groups (ArrayLike) – Group of each item.

  • bounds (Sequence[float]) – Gini bounds to evaluate.

Return type:

DataFrame

Returns:

One row per bound, with the total benefit, its share of the unconstrained benefit and the Gini coefficient of the selection rates the selection achieves.

Examples

>>> import numpy as np
>>> table = frontier(np.array([10, 9, 8, 7, 1, 1, 1, 1]), 4, np.array([0] * 4 + [1] * 4), [0.0, 1.0])
>>> table["share"].round(3).tolist()
[0.618, 1.0]