UtilMasks Module¶

poisson_approval.utils.UtilMasks.
masks_area
(inf, sup, masks)[source]¶ Area of some masks (recursive divide and conquer implementation).
We denote by d the dimension of the Euclidean space under study.
Parameters:  inf (list of Number) – A list of d numbers. The inf limit of the bounding rectangle in each dimension.
 sup (list of Number) – A list of d numbers. The sup limit of the bounding rectangle in each dimension.
 masks (list of list of tuple) – A list of masks. Each mask is a list of d pairs
(lim, direction)
, wherelim
is the limit of the mask, anddirection
is a Boolean:True
(respFalse
) means that the points of the mask meet the conditionx_d >= lim
(resp.x_d <= lim
).
Returns: The area of
Intersection(bounding rectangle, Union(masks))
.Return type: float
Examples
In the following example, the bounding rectangle is the set of points where
0 <= x_1 <= 1 and 0 <= x_2 <= 2
. The first mask is the set of points wherex_1 >= 0.2 and x_2 <= 0.6
. The second mask is the set of points wherex_1 <= 0.3 and x_2 >= 0.4
.>>> area = masks_area(inf=[0, 0], sup=[1, 2], ... masks=[[(Fraction(2, 10), True), (Fraction(6, 10), False)], ... [(Fraction(3, 10), False), (Fraction(4, 10), True)]]) >>> area Fraction(47, 50) >>> Fraction(8, 10) * Fraction(6, 10) + Fraction(3, 10) * Fraction(16, 10)  Fraction(1, 10) * Fraction(2, 10) Fraction(47, 50)

poisson_approval.utils.UtilMasks.
masks_area_naive
(inf, sup, masks)[source]¶ Area of some masks. Naive implementation (used as a sanity test for the recursive implementation)
Notes
Same specifications as
masks_area()
.Examples
>>> area = masks_area_naive(inf=[0, 0], sup=[1, 2], ... masks=[[(Fraction(2, 10), True), (Fraction(6, 10), False)], ... [(Fraction(3, 10), False), (Fraction(4, 10), True)]]) >>> area Fraction(47, 50) >>> Fraction(8, 10) * Fraction(6, 10) + Fraction(3, 10) * Fraction(16, 10)  Fraction(1, 10) * Fraction(2, 10) Fraction(47, 50)

poisson_approval.utils.UtilMasks.
masks_distribution
(inf, sup, masks, cover_alls=0)[source]¶ Distribution of the number of masks (recursive divide and conquer implementation).
We denote by d the dimension of the Euclidean space under study.
Parameters:  inf (list of Number) – A list of d numbers. The inf limit of the bounding rectangle in each dimension.
 sup (list of Number) – A list of d numbers. The sup limit of the bounding rectangle in each dimension.
 masks (list of list of tuple) – A list of masks. Each mask is a list of d pairs
(lim, direction)
, wherelim
is the limit of the mask, anddirection
is a Boolean:True
(respFalse
) means that the points of the mask meet the conditionx_d >= lim
(resp.x_d <= lim
).  cover_alls (int, optional) – If specified, then we consider that we have this number of implicit masks (i.e. not given in the argument masks) that cover the whole area.
Returns: A list. The ith coefficient is the area covered by i masks exactly (and in the bounding rectangle).
Return type: list
Examples
In the following example, the bounding rectangle is the set of points where
0 <= x_1 <= 1 and 0 <= x_2 <= 2
. The first mask is the set of points wherex_1 >= 0.2 and x_2 <= 0.6
. The second mask is the set of points wherex_1 <= 0.3 and x_2 >= 0.4
.>>> histogram = masks_distribution(inf=[0, 0], sup=[1, 2], ... masks=[[(Fraction(2, 10), True), (Fraction(6, 10), False)], ... [(Fraction(3, 10), False), (Fraction(4, 10), True)]]) >>> histogram array([Fraction(53, 50), Fraction(23, 25), Fraction(1, 50)], dtype=object) >>> histogram = masks_distribution(inf=[0, 0], sup=[1, 2], ... masks=[[(.2, True), (.6, False)], ... [(.3, False), (.4, True)]]) >>> histogram array([1.06, 0.92, 0.02])

poisson_approval.utils.UtilMasks.
masks_distribution_naive
(inf, sup, masks)[source]¶ Distribution of the number of masks. Naive implementation (used as a sanity test for the recursive implementation)
Notes
Same specifications as
mask_distribution()
.Examples
>>> histogram = masks_distribution_naive(inf=[0, 0], sup=[1, 2], ... masks=[[(Fraction(2, 10), True), (Fraction(6, 10), False)], ... [(Fraction(3, 10), False), (Fraction(4, 10), True)]]) >>> histogram array([Fraction(53, 50), Fraction(23, 25), Fraction(1, 50)], dtype=object) >>> histogram = masks_distribution_naive(inf=[0, 0], sup=[1, 2], ... masks=[[(0.2, True), (0.6, False)], ... [(0.3, False), (0.4, True)]]) >>> histogram array([1.06, 0.92, 0.02])

poisson_approval.utils.UtilMasks.
random_mask
(dim)[source]¶ Random mask.
Parameters: dim (int) – Dimension of the Euclidean space under study. Returns: A mask of dimension dim, whose limits are in [0, 1]. For the definition of a mask, cf. masks_area()
.Return type: list of tuple

poisson_approval.utils.UtilMasks.
random_masks
(dim, n_masks)[source]¶ List of random masks.
Parameters:  dim (int) – Dimension of the Euclidean space under study.
 n_masks (int) – Number of masks.
Returns: A list of n_masks masks of dimension d, whose limits are in [0, 1]. For the definition of a mask, cf.
masks_area()
.Return type: list of list of tuple
Examples
>>> dim = 6 >>> n_masks = 4 >>> masks = random_masks(dim=dim, n_masks=n_masks) >>> isclose(masks_area(inf=[0]*dim, sup=[1]*dim, masks=masks), ... masks_area_naive(inf=[0]*dim, sup=[1]*dim, masks=masks)) True

poisson_approval.utils.UtilMasks.
winners_distribution
(inf, sup, masks_winners, histogram=None, cover_alls=None)[source]¶ Distribution of the number of winners (recursive divide and conquer implementation).
We denote by d the dimension of the Euclidean space under study.
Parameters:  inf (list of Number) – A list of d numbers. The inf limit of the bounding rectangle in each dimension.
 sup (list of Number) – A list of d numbers. The sup limit of the bounding rectangle in each dimension.
 masks_winners (list of tuple) – A list of pairs
(mask, winners)
. A mask is defined as usual (cf.masks_area()
for instance). A winner is a set of winning candidates in this mask, e.g.{'a', 'b'}
.  histogram (list) – This parameter should only be used for recursive calls. If specified, then instead of creating a new list for the output, it is added to the given list histogram.
 cover_alls (set) – E.g. {‘a’, ‘b’}. This parameter should only be used for recursive calls. If specified, then we consider that we have all these candidates winning in the whole area.
Returns: A list of length 4. The ith coefficient is the area where i candidates may win.
Return type: list
Examples
In the following example, the bounding rectangle is the set of points where
0 <= x_1 <= 1 and 0 <= x_2 <= 2
. The first mask is the set of points wherex_1 >= 0.2 and x_2 <= 0.6
, where the winner can be{'a'}
. The second mask is the set of points wherex_1 <= 0.3 and x_2 >= 0.4
, where the winner can be{'b'}
.>>> histogram = winners_distribution( ... inf=[0, 0], sup=[1, 2], ... masks_winners=[([(Fraction(2, 10), True), (Fraction(6, 10), False)], {'a'}), ... ([(Fraction(3, 10), False), (Fraction(4, 10), True)], {'a', 'b'})]) >>> histogram array([Fraction(53, 50), Fraction(23, 50), Fraction(12, 25), 0], dtype=object) >>> histogram = winners_distribution( ... inf=[0, 0], sup=[1, 2], ... masks_winners=[([(.2, True), (.6, False)], {'a'}), ... ([(.3, False), (.4, True)], {'a', 'b'})]) >>> histogram array([1.06, 0.46, 0.48, 0. ])