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), where lim is the limit of the mask, and direction is a Boolean: True (resp False) means that the points of the mask meet the condition x_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 where x_1 >= 0.2 and x_2 <= 0.6. The second mask is the set of points where x_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), where lim is the limit of the mask, and direction is a Boolean: True (resp False) means that the points of the mask meet the condition x_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 i-th 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 where x_1 >= 0.2 and x_2 <= 0.6. The second mask is the set of points where x_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 masks_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 i-th 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 where x_1 >= 0.2 and x_2 <= 0.6, where the winner can be {'a'}. The second mask is the set of points where x_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.  ])