choices is designed to make it easy to make it easy to make things happen in a probabilistic manner. Its main API is the Choice class.

When called, a Choice object will return one of its keys according to the proability it has been assigned.

Here's an example:

>>> mood = Choice({'happy': 0.3, 'neutral': 0.6, 'sad': 0.1})
>>> mood()
'happy'
>>> mood()
'neutral'
>>> mood()
'neutral'

Creating a Choice object

There are three main ways for creating a Choice object:

• a dict of keys and probabilities
• a list of (key, probability) pairs
• a list of (key, sample_count) pairs

Each of those options is explained below.

A dict of keys and probabilities

Perhaps the simplest way to create a Choice is to provide the keys and associated probability wrapped up as a dict:

>>> mood = Choice({'happy': 0.3, 'neutral': 0.6, 'sad': 0.1})
>>> mood()
'happy'
>>> mood()
'neutral'

A list of (key, probability) pairs

As well as a dict assigning a probability to each key, you can send in a list of (key,value) pairs as lists or tuples. This allows for lots of flexibility, including non-hashable types to be used. This means that you can provide objects such as functions to be used as keys.

Let's say we wanted to create an NPC for a game and wanted some scripted responses. Why not encode moods as functions and then pass them togetheer as a Choice.

>>> def grumpy(news):
... return ':/'
>>> def happy(news):
... return ':)'
>>> react = Choice([(grumpy, 0.7), (happy, 0.3)])
>>> reaction = react()
>>> reaction("We're getting married!")
':/'

A list of (key, sample_count) pairs

You are not restricted to adding p to 1. If you only have samples, and wish to calculate a probablilty distribution, you can provide those too:

>>> birds_spotted = {'geese': 0, 'ducks': 12, 'sparrows': 4, 'other': 39}
>>> birds = Choice(birds_spotted)
>>> birds.distribution
[('geese', 0.0), ('sparrows', 0.07272727272727272), ('ducks', 0.21818181818181817), ('other', 0.7090909090909091)]

Usage

Making decisions

To return a new value, simply call the Choice object.

>>> where_to_go = Choice({"Paris": 0.4, "London": 0.4, "Copenhagen": 0.1, "Barcelona": 0.1 })
>>> where_to_go()
'Copenhagen'

Finding probabilities

You can retrieve the distribution of how those values are applied by accessing the distribution attribute:

>>> mood.distribution
[('happy', 0.3), ('neutral', 0.6), ('sad', 0.1)]
>>> where_to_go.distribution
[('Paris': 0.4), ('London', 0.4), ('Copenhagen', 0.1), ('Barcelona', 0.1)]

Retrieving the probability of a particular key is supported:

>>> birds['geese']
0.0