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:
  • ValueErrorif 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:boolTrue 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 floatvalue 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']