User Guide¶

PyProbs answers one question: given a probability, did the event happen? This guide walks through the ways to ask it, from a single call to an instance that keeps score.

Drawing outcomes¶

Probability.prob() is a static method, so you can call it straight on the class. Each call draws a new outcome, which is True with the probability you give:

>>> from pyprobs import Probability as pr
>>> pr.prob(0.5)
False

Pass num to draw several outcomes at once. They come back as a list:

>>> pr.prob("50%", num=8)
[False, True, True, False, True, False, True, True]

When you pass more than one probability, the outcomes of all of them are returned in one flat list, in order:

>>> pr.prob(1, 0, num=2)
[True, True, False, False]

Writing probabilities¶

Every function accepts the same forms, so write a probability whichever way reads best where you use it:

A value outside the 0 to 1 range raises ProbabilityRangeError:

>>> pr.prob("150%")
Traceback (most recent call last):
  ...
pyprobs.exceptions.ProbabilityRangeError: The probability of an event must be between 0 and 1.

A value that cannot be read as a probability at all raises ProbabilityTypeError:

>>> pr.prob("half")
Traceback (most recent call last):
  ...
pyprobs.exceptions.ProbabilityTypeError: 'half' is not a valid probability. Use a percentage ('25%'), a fraction ('1/4') or a number ('0.25').

Keeping a history¶

Create an instance when you want to keep track of what was drawn. Its iprob() method works like prob(), and also records every outcome in history, under the probability it was drawn for:

>>> p = pr()
>>> p.iprob("3/4", 0.5, num=2)
[[False, True], [True, False]]
>>> p.history
{'3/4': [False, True], 0.5: [True, False]}

Unlike prob(), iprob() keeps the outcomes of each probability apart:

Outcomes for the same probability add up across calls. A fraction or percentage is stored without the spaces around it, so " 3 / 4 " and "3/4" share one entry:

>>> p.iprob(" 3 / 4 ", num=4)
[False, False, False, True]
>>> p.history["3/4"]
[False, True, False, False, False, True]

count_values() counts the outcomes of the last iprob() call, or of the whole history with "all":

>>> p.count_values()
{True: 1, False: 3}
>>> p.count_values("all")
{True: 3, False: 5}

clear() empties the history:

>>> p.clear()
>>> p.history
{}

Setting a constant¶

When an instance always draws with the same probability, set it once with set_constant() and call iprob() without arguments. A probability you pass to iprob() still takes precedence:

>>> coin = pr()
>>> coin.set_constant("50%")
>>> coin.iprob(num=4)
[False, False, False, True]
>>> coin.iprob(0)
False

Pass mutable=False to lock the constant. Any later attempt to change it raises ImmutableConstantVariableError:

>>> d20 = pr()
>>> d20.set_constant("1/20", mutable=False)
>>> d20.set_constant("1/2")
Traceback (most recent call last):
  ...
pyprobs.exceptions.ImmutableConstantVariableError: The mutable parameter has been set False before. You cannot set a constant again.

get() returns the constant and the mutable flag, together or one at a time:

>>> d20.get()
{'constant': '1/20', 'mutable': False}
>>> d20.get("constant")
'1/20'
>>> d20.get("mutable")
False

Combining instances¶

Instances with a constant work with a few Python operators. + returns a new instance whose constant is the sum of both, capped at 1, and float() gives the constant as a number:

>>> rolls_one = pr()
>>> rolls_one.set_constant("1/6")
>>> rolls_two = pr()
>>> rolls_two.set_constant("1/6")
>>> rolls_one_or_two = rolls_one + rolls_two
>>> float(rolls_one_or_two)
0.3333333333333333

== compares the constants as they were written, together with the mutable flag. So "50%" and 0.5 are not equal, even though they describe the same chance:

>>> half = pr()
>>> half.set_constant("50%")
>>> also_half = pr()
>>> also_half.set_constant(0.5)
>>> half == also_half
False

Handling errors¶

Every exception PyProbs raises derives from ProbabilityError, so one except clause covers them all:

>>> from pyprobs.exceptions import ProbabilityError
>>> try:
...     pr.prob("lots")
... except ProbabilityError as error:
...     print(f"Could not draw: {error}")
Could not draw: 'lots' is not a valid probability. Use a percentage ('25%'), a fraction ('1/4') or a number ('0.25').

Reproducible results¶

PyProbs draws with Python's random module, so seeding it makes the outcomes repeat. This is handy in tests and in simulations you want to rerun:

>>> import random
>>> random.seed(42)
>>> pr.prob("50%", num=5)
[False, True, True, True, False]
>>> random.seed(42)
>>> pr.prob("50%", num=5)
[False, True, True, True, False]