Introduction¶

To get started quickly, use

float or str for values,
int or list for possibility spaces,
list or dict for gambles, and
list for events.

The library supports many more modes of operation, to which we turn next.

Values¶

Throughout the library, you can choose (slow) exact arithmetic with fractions.Fraction (rational numbers), or (fast) approximate arithmetic with float (limited precision reals).

Numbers can be specified directly as instances of fractions.Fraction (e.g. fractions.Fraction(1, 3)) or float (e.g. 1.23). You can also use int (e.g. 20), or str in the form of for instance '1.23' or '1/3'—these are internally converted to their exact representation if you work with fractions, or their approximate representation if you work with floats.

The constructors of lower previsions and gambles have an optional number_type keyword argument: if it is 'float' then float arithmetic is used, and if it is 'fraction' then rational arithmetic is used.

If you do not specify a number_type on construction, then 'float' is used, unless all values are fractions.Fraction or str.

Possibility Spaces¶

Any collections.Iterable of immutable objects can be used to specify a possibility space. Effectively, an collections.Iterable pspace is interpreted as an ordered set.

For convenience, you can also construct a possibility space from any integer n—this is equivalent to specifying range(n).

For further convenience, you can construct Cartesian products simply by specifying multiple iterables or integers.

class improb.PSpace(*args)¶

An immutable possibility space, derived from collections.Set and collections.Hashable. This is effectively an immutable ordered set with a fancy constructor.

__init__(*args)¶

Convert args into a possibility space.

Parameters:	args (`collections.Iterable` or `int`) – The components of the space.

Some examples of how components can be specified:

A range of integers.

>>> list(PSpace(xrange(2, 15, 3)))
[2, 5, 8, 11, 14]

A string.

>>> list(PSpace('abcdefg'))
['a', 'b', 'c', 'd', 'e', 'f', 'g']

A list of strings.

>>> list(PSpace('rain cloudy sunny'.split(' ')))
['rain', 'cloudy', 'sunny']

As a special case, you can also specify just a single integer. This will be converted to a tuple of integers of the corresponding length.
```
>>> list(PSpace(3))
[0, 1, 2]
```

If multiple arguments are specified, the product is calculated:

>>> list(PSpace(3, 'abc')) 
[(0, 'a'), (0, 'b'), (0, 'c'),
 (1, 'a'), (1, 'b'), (1, 'c'),
 (2, 'a'), (2, 'b'), (2, 'c')]
>>> list(PSpace(('rain', 'cloudy', 'sunny'), ('cold', 'warm'))) 
[('rain', 'cold'), ('rain', 'warm'),
 ('cloudy', 'cold'), ('cloudy', 'warm'),
 ('sunny', 'cold'), ('sunny', 'warm')]

Duplicates are automatically removed:

>>> list(PSpace([2, 2, 5, 3, 9, 5, 1, 2]))
[2, 5, 3, 9, 1]

__repr__()¶

>>> PSpace([2, 4, 5])
PSpace([2, 4, 5])
>>> PSpace([0, 1, 2])
PSpace(3)

__str__()¶

>>> print(PSpace([2, 4, 5]))
2 4 5

classmethod make(pspace)¶

If pspace is a PSpace, then returns pspace. Otherwise, converts pspace to a PSpace.

Parameters:	pspace (`list` or similar; see Possibility Spaces) – The possibility space.
Returns:	A possibility space.
Return type:	`PSpace`

make_event(*args, **kwargs)¶

If event is a Event, then checks possibility space and returns event. Otherwise, converts event to a Event.

If you wish to construct an event on a product space, which is itself composed of a product of events, specify its components as separate arguments—in this case, each of the components must be a sequence.

Parameters:	event (`list` or similar; see Events) – The event. name (`str`) – The name of the event (used for pretty printing).
Returns:	A event.
Return type:	`Event`
Raises :	`ValueError` if possibility spaces do not match

>>> pspace = PSpace(2, 3)
>>> print(pspace.make_event([(1, 2), (0, 1)]))
(0, 0) : 0
(0, 1) : 1
(0, 2) : 0
(1, 0) : 0
(1, 1) : 0
(1, 2) : 1
>>> print(pspace.make_event((0, 1), (2,)))
(0, 0) : 0
(0, 1) : 0
(0, 2) : 1
(1, 0) : 0
(1, 1) : 0
(1, 2) : 1

make_gamble(gamble, number_type=None)¶

If gamble is

a Gamble, then checks possibility space and number type and returns gamble; if number type does not correspond, returns a copy of gamble with requested number type,
an Event, then checks possibility space and returns the indicator of gamble with the correct number type,
anything else, then construct a Gamble using gamble as data.

Parameters:	gamble (`dict` or similar; see Gambles) – The gamble. number_type (`str`) – The type to use for numbers: `'float'` or `'fraction'`. If omitted, then `get_number_type_from_sequences()` is used to determine the number type.
Returns:	A gamble.
Return type:	`Gamble`
Raises :	`ValueError` if possibility spaces or number types do not match

>>> from improb import PSpace, Event, Gamble
>>> pspace = PSpace('abc')
>>> event = Event(pspace, 'ac')
>>> gamble = event.indicator('fraction')
>>> fgamble = event.indicator() # float number type
>>> pevent = Event('ab', False)
>>> pgamble = Gamble('ab', [2, 5], number_type='fraction')
>>> print(pspace.make_gamble({'b': 1}, 'fraction'))
a : 0
b : 1
c : 0
>>> print(pspace.make_gamble(event, 'fraction'))
a : 1
b : 0
c : 1
>>> print(pspace.make_gamble(gamble, 'fraction'))
a : 1
b : 0
c : 1
>>> print(pspace.make_gamble(fgamble, 'fraction'))
a : 1
b : 0
c : 1
>>> print(pspace.make_gamble(pevent, 'fraction')) 
Traceback (most recent call last):
    ...
ValueError: ...
>>> print(pspace.make_gamble(pgamble, 'fraction')) 
Traceback (most recent call last):
    ...
ValueError: ...
>>> print(pspace.make_gamble({'a': 1, 'b': 0, 'c': 8}, 'fraction'))
a : 1
b : 0
c : 8
>>> print(pspace.make_gamble(range(2, 9, 3), 'fraction'))
a : 2
b : 5
c : 8

subsets(event=True, empty=True, full=True, size=None, contains=False)¶

Iterates over all subsets of the possibility space.

Parameters:	event (`list` or similar; see Events) – An event (optional). empty (`bool`) – Whether to include the empty event or not. full (`bool`) – Whether to include event or not. size (`int` or `collections.Iterable`) – Any size constraints. If specified, then empty and full are ignored. contains (`list` or similar; see Events) – An event that must be contained in all returned subsets.
Returns:	Yields all subsets.
Return type:	Iterator of `Event`.

>>> pspace = PSpace([2, 4, 5])
>>> print("\n---\n".join(str(subset) for subset in pspace.subsets()))
: 0
: 0
: 0
---
: 1
: 0
: 0
---
: 0
: 1
: 0
---
: 0
: 0
: 1
---
: 1
: 1
: 0
---
: 1
: 0
: 1
---
: 0
: 1
: 1
---
: 1
: 1
: 1
>>> print("\n---\n".join(str(subset) for subset in pspace.subsets([2, 4])))
: 0
: 0
: 0
---
: 1
: 0
: 0
---
: 0
: 1
: 0
---
: 1
: 1
: 0
>>> print("\n---\n".join(str(subset) for subset in pspace.subsets([2, 4], empty=False, full=False)))
: 1
: 0
: 0
---
: 0
: 1
: 0
>>> print("\n---\n".join(str(subset) for subset in pspace.subsets(True, contains=[4])))
: 0
: 1
: 0
---
: 1
: 1
: 0
---
: 0
: 1
: 1
---
: 1
: 1
: 1

Gambles¶

Any collections.Mapping or collections.Sequence can be used to specify a gamble. Effectively, given a possibility space pspace, a collections.Mapping mapping corresponds to the mapping (specified as Python dictionary):

{omega: mapping.get(omega, 0) for omega in pspace}

and a collections.Sequence sequence corresponds to:

{omega: value for omega, value in zip(pspace, sequence)}

This yields maximum flexibility so you can use the simplest possible specification for a gamble, depending on the situation.

Internally, the following class is used to represent gambles; it is an immutable collections.Mapping, and supports the usual pointwise arithmetic operations.

class improb.Gamble(pspace, data, number_type=None)¶

An immutable gamble.

>>> pspace = PSpace('abc')
>>> Gamble(pspace, {'a': 1, 'b': 4, 'c': 8}).number_type
'float'
>>> Gamble(pspace, [1, 2, 3]).number_type
'float'
>>> Gamble(pspace, {'a': '1/7', 'b': '4/3', 'c': '8/5'}).number_type
'fraction'
>>> Gamble(pspace, ['1', '2', '3/2']).number_type
'fraction'
>>> f1 = Gamble(pspace, {'a': 1, 'b': 4, 'c': 8}, number_type='fraction')
>>> print(f1)
a : 1
b : 4
c : 8
>>> print(f1 + 2)
a : 3
b : 6
c : 10
>>> print(f1 - 2)
a : -1
b : 2
c : 6
>>> print(f1 * 2)
a : 2
b : 8
c : 16
>>> print(f1 / 3)
a : 1/3
b : 4/3
c : 8/3
>>> [f1 * 2, f1 + 2, f1 - 2] == [2 * f1, 2 + f1, -(2 - f1)]
True
>>> f2 = Gamble(pspace, {'a': 5, 'b': 8, 'c': 7}, number_type='fraction')
>>> print(f1 + f2)
a : 6
b : 12
c : 15
>>> print(f1 - f2)
a : -4
b : -4
c : 1
>>> print(f1 * f2) 
a : 5
b : 32
c : 56
>>> print(f1 / f2) 
Traceback (most recent call last):
    ...
TypeError: ...
>>> event = Event(pspace, 'ac')
>>> print(f1 + event)
a : 2
b : 4
c : 9
>>> print(f1 - event)
a : 0
b : 4
c : 7
>>> print(f1 * event)
a : 1
b : 0
c : 8
>>> print(f1 / event) 
Traceback (most recent call last):
    ...
TypeError: ...
>>> [f1 * event, f1 + event] == [event * f1, event + f1]
True
>>> print(event - f1)
a : 0
b : -4
c : -7

__repr__()¶

>>> Gamble([2, 3, 4], {2: 1, 3: 4, 4: 8}, number_type='float') 
Gamble(pspace=PSpace([2, 3, 4]),
       mapping={2: 1.0,
                3: 4.0,
                4: 8.0})
>>> Gamble([2, 3, 4], {2: '2/6', 3: '4.0', 4: 8}, number_type='fraction') 
Gamble(pspace=PSpace([2, 3, 4]),
       mapping={2: '1/3',
                3: 4,
                4: 8})

__str__()¶

>>> pspace = PSpace('rain sun clouds'.split())
>>> print(Gamble(pspace, {'rain': -14, 'sun': 4, 'clouds': 20}, number_type='float'))
rain   : -14.0
sun    : 4.0
clouds : 20.0

pspace¶: A PSpace representing the possibility space.

Events¶

Any collections.Iterable can be used to specify an event. Effectively, given a possibility space pspace, an collections.Iterable corresponds to the event (specified as a Python set):

{omega for omega in iterable}

where all elements omega must belong to the possibility space pspace.

For convenience, you can also specify an event as True (which corresponds to the full set) or False (which corresponds to the empty set).

Internally, the following class is used to represent events; it is an immutable collections.Set, and supports a few more common operations.

class improb.Event(pspace, data=False, name=None)¶

An immutable event.

>>> pspace = PSpace('abcdef')
>>> event1 = Event(pspace, 'acd')
>>> print(event1)
a : 1
b : 0
c : 1
d : 1
e : 0
f : 0
>>> event2 = Event(pspace, 'cdef')
>>> print(event2)
a : 0
b : 0
c : 1
d : 1
e : 1
f : 1
>>> print(event1 & event2)
a : 0
b : 0
c : 1
d : 1
e : 0
f : 0
>>> print(event1 | event2)
a : 1
b : 0
c : 1
d : 1
e : 1
f : 1
>>> Event(pspace, 'abz')
Traceback (most recent call last):
    ...
ValueError: event has element (z) not in possibility space

__repr__()¶

>>> pspace = PSpace([2, 3, 4])
>>> Event(pspace, [3, 4])
Event(pspace=PSpace([2, 3, 4]), elements=set([3, 4]))

__str__()¶

>>> pspace = PSpace('rain sun clouds'.split())
>>> print(Event(pspace, 'rain clouds'.split()))
rain   : 1
sun    : 0
clouds : 1

complement()¶

Calculate the complement of the event.

>>> print(Event(pspace='abcde', data='bde').complement())
a : 1
b : 0
c : 1
d : 0
e : 0

Returns:	Complement.
Return type:	`Event`

indicator(number_type=None)¶

Return indicator gamble for the event.

Parameters:	number_type (`str`) – The number type (defaults to `'float'` if omitted).
Returns:	Indicator gamble.
Return type:	`Gamble`

>>> pspace = PSpace(5)
>>> event = Event(pspace, [2, 4])
>>> event.indicator('fraction') 
Gamble(pspace=PSpace(5),
       mapping={0: 0,
                1: 0,
                2: 1,
                3: 0,
                4: 1})
>>> event.indicator() 
Gamble(pspace=PSpace(5),
       mapping={0: 0.0,
                1: 0.0,
                2: 1.0,
                3: 0.0,
                4: 1.0})

pspace¶: An PSpace representing the possibility space.

Introduction¶

Values¶

Possibility Spaces¶

Gambles¶

Events¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

Introduction¶

Values¶

Possibility Spaces¶

Gambles¶

Events¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation