rand¶

A collection of functions for performing non-uniform random operations.

Many functions rely of weight 2-tuples of the form (outcome, strength) where strength is a number and outcome is either a number or any type depending on the function.

exception blur.rand.ProbabilityUndefinedError¶: Exception raised when the probability of a system is undefined.

blur.rand.bound_weights(weights, minimum=None, maximum=None)¶

Bound a weight list so that all outcomes fit within specified bounds.

The probability distribution within the minimum and maximum values remains the same. Weights in the list with outcomes outside of minimum and maximum are removed. If weights are removed from either end, attach weights at the modified edges at the same weight (y-axis) position they had interpolated in the original list.

If neither minimum nor maximum are set, weights will be returned unmodified. If both are set, minimum must be less than maximum.

Parameters:	weights (list) – the list of weights where each weight is a `tuple` of form `(float, float)` corresponding to `(outcome, weight)`. Must be sorted in increasing order of outcomes minimum (float) – Lowest allowed outcome for the weight list maximum (float) – Highest allowed outcome for the weight list
Returns:	list – A list of 2-tuples of form `(float, float)`, the bounded weight list.
Raises:	`ValueError` – if `maximum < minimum`

Example

>>> weights = [(0, 0), (2, 2), (4, 0)]
>>> bound_weights(weights, 1, 3)
[(1, 1), (2, 2), (3, 1)]

blur.rand.normal_distribution(mean, variance, minimum=None, maximum=None, weight_count=23)¶

Return a list of weights approximating a normal distribution.

Parameters:	mean (float) – The mean of the distribution variance (float) – The variance of the distribution minimum (float) – The minimum outcome possible to bound the output distribution to maximum (float) – The maximum outcome possible to bound the output distribution to weight_count (int) – The number of weights that will be used to approximate the distribution
Returns:	list – a list of `(float, float)` weight tuples approximating a normal distribution.
Raises:	`ValueError` – `if maximum < minimum` `TypeError` – if both `minimum` and `maximum` are `None`

Example

>>> weights = normal_distribution(10, 3,
...                               minimum=0, maximum=20,
...                               weight_count=5)
>>> rounded_weights = [(round(value, 2), round(strength, 2))
...                    for value, strength in weights]
>>> rounded_weights
[(1.34, 0.0), (4.8, 0.0), (8.27, 0.14), (11.73, 0.14), (15.2, 0.0)]

blur.rand.prob_bool(probability)¶

Return True or False depending on probability.

Parameters:	probability (float) – Probability between `0` and `1` to return `True` where `0` is guaranteed to return `False` and `1` is guaranteed to return `True`.
Returns:	bool – `True` or `False` depending on `probability`.

Example

>>> prob_bool(0.9)                                     
# Usually will be...
True
>>> prob_bool(0.1)                                     
# Usually will be...
False

blur.rand.percent_possible(percent)¶

Return True percent / 100 times.

Parameters:	percent (int or float) – percent possibility to return True
Returns:	bool – Either `True` or `False` depending on `percent`

Example

>>> percent_possible(90)                               
# Usually will be...
True
>>> percent_possible(10)                               
# Usually will be...
False

blur.rand.pos_or_neg(value, prob_pos=0.5)¶

Return either positive or negative value based on prob_pos.

This is equivalent to abs(value) * pos_or_neg_1(prob_pos).

Parameters:	value (int or float) – the value to operate on prob_pos (float) – The probability to return positive. where `prob_pos = 0` is guaranteed to return negative and `prob_pos = 1` is guaranteed to return positive. Default value is `0.5`.
Returns:	int or float – `value` either positive or negative

Example

>>> pos_or_neg(42, 0.9)                                
# Usually will be...
42
>>> pos_or_neg(42, 0.1)                                
# Usually will be...
-42

blur.rand.pos_or_neg_1(prob_pos=0.5)¶

Return either 1 with probability of prob_pos, otherwise -1.

Parameters:	prob_pos (float) – The probability to return positive `1` where `prob_pos = 0` is guaranteed to return negative and `prob_pos = 1` is guaranteed to return positive. Default value is `0.5`.
Returns:	int – either `1` or `-1`

Example

>>> pos_or_neg_1(0.9)                                  
# Usually will be...
1
>>> pos_or_neg_1(0.1)                                  
# Usually will be...
-1

blur.rand.weighted_rand(weights, round_result=False)¶

Generate a non-uniform random value based on a list of weight tuples.

Treats weights as coordinates for a probability distribution curve and rolls accordingly. Constructs a piece-wise linear curve according to coordinates given in weights and rolls random values in the curve’s bounding box until a value is found under the curve

Weight tuples should be of the form: (outcome, strength).

Parameters:

weights – (list): the list of weights where each weight is a tuple of form (float, float) corresponding to (outcome, strength). Weights with strength 0 or less will have no chance to be rolled. The list must be sorted in increasing order of outcomes.
round_result (bool) – Whether or not to round the resulting value to the nearest integer.

Returns:

float – A weighted random number

int: A weighted random number rounded to the nearest int

Example

>>> weighted_rand([(-3, 4), (0, 10), (5, 1)])          
-0.650612268193731
>>> weighted_rand([(-3, 4), (0, 10), (5, 1)])          
-2

blur.rand.weighted_choice(weights, as_index_and_value_tuple=False)¶

Generate a non-uniform random choice based on a list of option tuples.

Treats each outcome as a discreet unit with a chance to occur.

Parameters:

weights (list) – a list of options where each option is a tuple of form (Any, float) corresponding to (outcome, strength). Outcome values may be of any type. Options with strength 0 or less will have no chance to be chosen.
as_index_and_value_tuple (bool) – Option to return an (index, value) tuple instead of just a single value. This is useful when multiple outcomes in weights are the same and you need to know exactly which one was picked.

Returns:

Any – If as_index_and_value_tuple is False, any one of the items in the outcomes of weights

tuple (int, Any): If as_index_and_value_tuple is True, a 2-tuple of form (int, Any) corresponding to (index, value). the index as well as value of the item that was picked.

Example

>>> choices = [('choice one', 10), ('choice two', 3)]
>>> weighted_choice(choices)                           
# Often will be...
'choice one'
>>> weighted_choice(choices,
...                 as_index_and_value_tuple=True)     
# Often will be...
(0, 'choice one')

blur.rand.weighted_order(weights)¶

Non-uniformally order a list according to weighted priorities.

weights is a list of tuples of form (Any, float or int) corresponding to (item, strength). The output list is constructed by repeatedly calling weighted_choice() on the weights, adding items to the end of the list as they are picked.

Higher strength weights will have a higher chance of appearing near the beginning of the output list.

A list weights with uniform strengths is equivalent to calling random.shuffle() on the list of items.

If any weight strengths are <= 0, a ProbabilityUndefinedError is be raised.

Passing an empty list will return an empty list.

Parameters:	weights (list) – a list of tuples of form `(Any, float or int)` corresponding to `(item, strength)`. The output list is constructed by repeatedly calling `weighted_choice()` on the weights, appending items to the output list as they are picked.
Returns:	list – the newly ordered list
Raises:	`ProbabilityUndefinedError` – if any weight’s strength is below 0.

Example

>>> weights = [('Probably Earlier', 100),
...            ('Probably Middle', 20),
...            ('Probably Last', 1)]
>>> weighted_order(weights)                            
['Probably Earlier', 'Probably Middle', 'Probably Last']