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
andmaximum
values remains the same. Weights in the list with outcomes outside ofminimum
andmaximum
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
normaximum
are set,weights
will be returned unmodified. If both are set,minimum
must be less thanmaximum
.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
– ifmaximum < minimum
Example
>>> weights = [(0, 0), (2, 2), (4, 0)] >>> bound_weights(weights, 1, 3) [(1, 1), (2, 2), (3, 1)]
- weights (list) – the list of weights where each weight
is a
-
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 bothminimum
andmaximum
areNone
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
orFalse
depending onprobability
.Parameters: probability (float) – Probability between 0
and1
to returnTrue
where0
is guaranteed to returnFalse
and1
is guaranteed to returnTrue
.Returns: bool – True
orFalse
depending onprobability
.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
orFalse
depending onpercent
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 onprob_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 andprob_pos = 1
is guaranteed to return positive. Default value is0.5
.
Returns: int or float –
value
either positive or negativeExample
>>> 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 ofprob_pos
, otherwise-1
.Parameters: prob_pos (float) – The probability to return positive 1
whereprob_pos = 0
is guaranteed to return negative andprob_pos = 1
is guaranteed to return positive. Default value is0.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 curveWeight 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 strength0
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
- weights – (list): the list of weights where each weight
is a tuple of form
-
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 strength0
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 singlevalue
. This is useful when multiple outcomes inweights
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 ofweights
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')
- weights (list) – a list of options where each option
is a tuple of form
-
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 callingweighted_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
, aProbabilityUndefinedError
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 callingweighted_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']