Quickstart

This is a quickstart guide to get you up and running with the random_events library.

Installation

To install the library, run the following command

pip install random-events

Next, import the necessary functionality:

from random_events.variable import Symbolic, Continuous, Integer
from random_events.product_algebra import SimpleEvent, Event
from random_events.interval import SimpleInterval, Interval, closed, closed_open, open_closed, open
from random_events.set import SetElement, Set
import plotly
import plotly.graph_objects as go

Preface

The random_events library is a Python library for working with sigma algebras. For every algebra, there are two kinds of sets, the simple sets and the composite sets. Simple sets are sets that can be represented as single objects. Composite sets are sets that are composed of multiple, sorted simple sets.

Intervals

Intervals are a fundamental concept in the random_events library. They are used to represent the range of possible values that a numeric variable can take. There are two classes to interact with intervals: SimpleInterval and Interval. However, it is strongly recommended to use the Interval class, as it provides an API implementing all set operations. First, create two simple intervals:

si1 = SimpleInterval(0, 1)
si2 = SimpleInterval(0.5, 1.5)
si1, si2

((0.0, 1.0), (0.5, 1.5))

Simple sets of any kind can be converted to composite sets using the .as_composite_set() method.

i1 = si1.as_composite_set()
i2 = si2.as_composite_set()
i1, i2

((0.0, 1.0), (0.5, 1.5))

All set operations are supported for composite sets. All set operations automatically return simple and disjoint representations of the resulting set.

print(i1.intersection_with(i2))
print(i1.union_with(i2))
print(i1.difference_with(i2))
print(i1.complement())

(0.5, 1.0)
(0.0, 1.5)
(0.0, 0.5]
[1.0, inf) u (-inf, 0.0]

Set operations can also be invoked by calling the built-in methods.

print(i1 & i2)
print(i1 | i2)
print(i1 - i2)
print(~i1)

(0.5, 1.0)
(0.0, 1.5)
(0.0, 0.5]
[1.0, inf) u (-inf, 0.0]

Intervals can also be created using shortcuts for the most common types of intervals.

print(closed(0, 1))
print(closed_open(0, 1)) 
print(open_closed(0, 1))
print(open(0, 1))

[0.0, 1.0]
[0.0, 1.0)
(0.0, 1.0]
(0.0, 1.0)

Sets

Since a sigma algebra requires more information than it is stored in regular python sets, the SetElement and Set classes are used. A set element is a simple set, and a set is a composite set. Whenever you want to create a set, just pass it some iterable, for example, an enum.

from enum import IntEnum

class Symbol(IntEnum):
    APPLE = 0
    DOG = 1
    RAIN = 2

Now you can interact with sets and set elements.

s1 = SetElement(Symbol.APPLE, Symbol).as_composite_set()
s2 = SetElement(Symbol.DOG, Symbol).as_composite_set()
print(s1)
print(~s1)
print(s1 & s2)
print(s1 | s2)

0
1 u 2
∅
0 u 1

Variables

Describing multidimensional algebras requires variables that describe the type of dimension. Variables are either Symbolic, Integer or Continuous. Symbolic variables need a class that inherits from SetElement to describe the possible values. Integer and Continuous variables need no specification of their domain.

a = Symbolic("a", Set.from_iterable(Symbol))
x = Continuous("x")
y = Continuous("y")
z = Integer("z")
a, x, y, z

(Symbolic(a), Continuous(x), Continuous(y), Integer(z))

Events

Describing events requires the use of the SimpleEvent and Event classes. Events are elements of the product algebra. Simple events are dictionary like objects that describe the values of the variables.

e1 = SimpleEvent({a: Symbol.APPLE, x: closed(0, 1), y: closed(2, 3), z: closed(0, 10)}).as_composite_set()
e2 = SimpleEvent({a: (Symbol.APPLE, Symbol.DOG), x: closed(0, 4), y: closed(0, 5), z: closed(0, 20)}).as_composite_set()
print(e1)
print(e1 & e2)
print(e1 | e2)
print(e2 - e1)

{
    a ∈ 0,
    x ∈ [0.0, 1.0],
    y ∈ [2.0, 3.0],
    z ∈ [0.0, 10.0]
}
{
    a ∈ 0,
    x ∈ [0.0, 1.0],
    y ∈ [2.0, 3.0],
    z ∈ [0.0, 10.0]
}
{
    a ∈ 0 u 1,
    x ∈ [0.0, 4.0],
    y ∈ [0.0, 5.0],
    z ∈ [0.0, 20.0]
}
{
    a ∈ 0,
    x ∈ [0.0, 1.0],
    y ∈ (3.0, 5.0] u [0.0, 2.0),
    z ∈ [0.0, 20.0]
} u {
    a ∈ 0,
    x ∈ [0.0, 1.0],
    y ∈ [2.0, 3.0],
    z ∈ (10.0, 20.0]
} u {
    a ∈ 1,
    x ∈ [0.0, 4.0],
    y ∈ [0.0, 5.0],
    z ∈ [0.0, 20.0]
} u {
    a ∈ 0,
    x ∈ (1.0, 4.0],
    y ∈ [0.0, 5.0],
    z ∈ [0.0, 20.0]
}

Events can also be plotted.

e3 = SimpleEvent({x: closed(0, 1) | closed(2, 2.5), y: closed(2, 3) | closed(4, 5)}).as_composite_set()
fig = go.Figure(e3.plot(), e3.plotly_layout())
fig.show()

JSON serialization is also supported for every object.

e4 = e2 - e1
print(e4.to_json())
e5 = Event.from_json(e4.to_json())
e5 == e4

{'type': 'random_events.product_algebra.Event', 'variables': [{'type': 'random_events.variable.Symbolic', 'name': 'a', 'domain': {'type': 'random_events.set.Set', 'simple_sets': [{'type': 'random_events.set.SetElement', 'value': <Symbol.APPLE: 0>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}, {'type': 'random_events.set.SetElement', 'value': <Symbol.DOG: 1>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}, {'type': 'random_events.set.SetElement', 'value': <Symbol.RAIN: 2>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}]}}, {'type': 'random_events.variable.Continuous', 'name': 'x', 'domain': {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': -inf, 'upper': inf, 'left': 'OPEN', 'right': 'OPEN'}]}}, {'type': 'random_events.variable.Continuous', 'name': 'y', 'domain': {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': -inf, 'upper': inf, 'left': 'OPEN', 'right': 'OPEN'}]}}, {'type': 'random_events.variable.Integer', 'name': 'z', 'domain': {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': -inf, 'upper': inf, 'left': 'OPEN', 'right': 'OPEN'}]}}], 'simple_sets': [{'type': 'random_events.product_algebra.SimpleEvent', 'assignments': [{'type': 'random_events.set.Set', 'simple_sets': [{'type': 'random_events.set.SetElement', 'value': <Symbol.APPLE: 0>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 1.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 3.0, 'upper': 5.0, 'left': 'OPEN', 'right': 'CLOSED'}, {'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 2.0, 'left': 'CLOSED', 'right': 'OPEN'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 20.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}]}, {'type': 'random_events.product_algebra.SimpleEvent', 'assignments': [{'type': 'random_events.set.Set', 'simple_sets': [{'type': 'random_events.set.SetElement', 'value': <Symbol.APPLE: 0>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 1.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 2.0, 'upper': 3.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 10.0, 'upper': 20.0, 'left': 'OPEN', 'right': 'CLOSED'}]}]}, {'type': 'random_events.product_algebra.SimpleEvent', 'assignments': [{'type': 'random_events.set.Set', 'simple_sets': [{'type': 'random_events.set.SetElement', 'value': <Symbol.APPLE: 0>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 1.0, 'upper': 4.0, 'left': 'OPEN', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 5.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 20.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}]}, {'type': 'random_events.product_algebra.SimpleEvent', 'assignments': [{'type': 'random_events.set.Set', 'simple_sets': [{'type': 'random_events.set.SetElement', 'value': <Symbol.DOG: 1>, 'content': [<Symbol.APPLE: 0>, <Symbol.DOG: 1>, <Symbol.RAIN: 2>]}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 4.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 5.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}, {'type': 'random_events.interval.Interval', 'simple_sets': [{'type': 'random_events.interval.SimpleInterval', 'lower': 0.0, 'upper': 20.0, 'left': 'CLOSED', 'right': 'CLOSED'}]}]}]}

True