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,
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 of items at the given ranked positions, discounted as in NDCG. |
|
Benefit and achieved equity of |
|
Gini coefficient of a burden across units. |
|
The |
|
Share of the total burden borne by the most burdened |
- milia.recommend.equity.gini(burden)#
Gini coefficient of a burden across units.
- Parameters:
burden (
ArrayLike) – Burden of each unit, not negative.- Return type:
- 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
Share of the total burden borne by the most burdened
shareof units.- Parameters:
- Return type:
- 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:
- 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
countitems of largest total benefit whose selection rates across groups have a Gini at mostbound.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:
- 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:
- Return type:
- 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]