Introduction

To get started quickly, use

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.

See also

cdd.NumberTypeable
A general purpose class for objects which admit different numerical representations.
cdd.get_number_type_from_value()
Determine the number type from values.

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

Table Of Contents

Previous topic

Getting Started

Next topic

Lower Previsions

This Page