Random Variables

aGrUM/pyAgrum is currently dedicated for discrete probability distributions.

There are 4 types of discrete random variables in aGrUM/pyAgrum: LabelizedVariable, DiscretizedVariable, IntegerVariable and RangeVariable. The 4 types are mainly provided in order to ease modelization. Derived from DiscreteVariable, they share a common API. They essentially differ by the means to create, name and access to their modalities.

Common API for Random Discrete Variables

class pyAgrum.DiscreteVariable(*args, **kwargs)

DiscreteVariable is the (abstract) base class for discrete random variables.

description()
Returns

the description of the variable

Return type

str

domain()
Returns

the domain of the variable

Return type

str

domainSize()
Returns

the number of modalities in the variable domain

Return type

int

empty()
Returns

True if the domain size < 2

Return type

bool

index(label)
Parameters

label (str) – a label

Returns

the indice of the label

Return type

int

label(i)
Parameters

i (int) – the index of the label we wish to return

Returns

the indice-th label

Return type

str

Raises

pyAgrum.OutOfBounds – If the variable does not contain the label

labels()
Returns

a tuple containing the labels

Return type

tuple

name()
Returns

the name of the variable

Return type

str

numerical(indice)
Parameters

indice (int) – an index

Returns

the numerical representation of the indice-th value

Return type

float

setDescription(theValue)

set the description of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

setName(theValue)

sets the name of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

stype()
Return type

str

toDiscretizedVar()
Returns

the discretized variable

Return type

pyAgrum.DiscretizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a DiscretizedVariable

toIntegerVar()
Return type

IntegerVariable

toLabelizedVar()
Returns

the labelized variable

Return type

pyAgrum.LabelizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a LabelizedVariable

toRangeVar()
Returns

the range variable

Return type

pyAgrum.RangeVariable

Raises

pyAgrum.RuntimeError – If the variable is not a RangeVariable

toStringWithDescription()
Returns

a description of the variable

Return type

str

varType()

returns the type of variable

Returns

the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable

Return type

int

Concrete classes for Random Discrete Variables

LabelizedVariable

class pyAgrum.LabelizedVariable(*args)

LabelizedVariable is a discrete random variable with a customizable sequence of labels.

LabelizedVariable(aName, aDesc=’’, nbrLabel=2) -> LabelizedVariable
Parameters:
  • aName (str) – the name of the variable

  • aDesc (str) – the (optional) description of the variable

  • nbrLabel (int) – the number of labels to create (2 by default)

LabelizedVariable(aLDRV) -> LabelizedVariable
Parameters:
  • aLDRV (pyAgrum.LabelizedVariable) – The pyAgrum.LabelizedVariable that will be copied

Examples

>>> import pyAgrum as gum
>>> # creating a variable with 3 labels : '0', '1' and '2'
>>> va=gum.LabelizedVariable('a','a labelized variable',3)
>>> print(va)
a:Labelized(<0,1,2>)
>>> va.addLabel('foo')
("pyAgrum.LabelizedVariable"@0x7fc4c840dd90) a:Labelized(<0,1,2,foo>)
>>> va.changeLabel(1,'bar')
>>> print(va)
a:Labelized(<0,bar,2,foo>)
>>> vb=gum.LabelizedVariable('b','b',0).addLabel('A').addLabel('B').addLabel('C')
>>> print(vb)
b:Labelized(<A,B,C>)
>>> vb.labels()
('A', 'B', 'C')
>>> vb.isLabel('E')
False
>>> vb.label(2)
'C'
>>> vc=gum.LabelizedVariable('b','b',['one','two','three'])
>>> vc
("pyAgrum.LabelizedVariable"@0x7fc4c840c130) b:Labelized(<one,two,three>)
addLabel(*args)

Add a label with a new index (we assume that we will NEVER remove a label).

Parameters

aLabel (str) – the label to be added to the labelized variable

Returns

the labelized variable

Return type

pyAgrum.LabelizedVariable

Raises

pyAgrum.DuplicateElement – If the variable already contains the label

changeLabel(pos, aLabel)

Change the label at the specified index

Parameters
  • pos (int) – the index of the label to be changed

  • aLabel (str) – the label to be added to the labelized variable

Raises
Return type

None

description()
Returns

the description of the variable

Return type

str

domain()
Returns

the domain of the variable as a string

Return type

str

domainSize()
Returns

the number of modalities in the variable domain

Return type

int

empty()
Returns

True if the domain size < 2

Return type

bool

eraseLabels()

Erase all the labels from the variable.

Return type

None

index(label)
Parameters

label (str) – a label

Returns

the indice of the label

Return type

int

isLabel(aLabel)

Indicates whether the variable already has the label passed in argument

Parameters

aLabel (str) – the label to be tested

Returns

True if the label already exists

Return type

bool

label(i)
Parameters

i (int) – the index of the label we wish to return

Returns

the indice-th label

Return type

str

Raises

pyAgrum.OutOfBounds – If the variable does not contain the label

labels()
Returns

a tuple containing the labels

Return type

tuple

name()
Returns

the name of the variable

Return type

str

numerical(index)
Parameters
  • indice (int) – an index

  • index (int) –

Returns

the numerical representation of the indice-th value

Return type

float

posLabel(label)
Parameters

label (str) –

Return type

int

setDescription(theValue)

set the description of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

setName(theValue)

sets the name of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

stype()
Return type

str

toDiscretizedVar()
Returns

the discretized variable

Return type

pyAgrum.DiscretizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a DiscretizedVariable

toIntegerVar()
Return type

IntegerVariable

toLabelizedVar()
Returns

the labelized variable

Return type

pyAgrum.LabelizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a LabelizedVariable

toRangeVar()
Returns

the range variable

Return type

pyAgrum.RangeVariable

Raises

pyAgrum.RuntimeError – If the variable is not a RangeVariable

toStringWithDescription()
Returns

a description of the variable

Return type

str

varType()

returns the type of variable

Returns

the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable

Return type

int

DiscretizedVariable

class pyAgrum.DiscretizedVariable(*args)

DiscretizedVariable is a discrete random variable with a set of ticks defining intervalls.

DiscretizedVariable(aName, aDesc=’’) -> DiscretizedVariable`
Parameters:
  • aName (str) – the name of the variable

  • aDesc (str) – the (optional) description of the variable

DiscretizedVariable(aDDRV) -> DiscretizedVariable
Parameters:
  • aDDRV (pyAgrum.DiscretizedVariable) – the pyAgrum.DiscretizedVariable that will be copied

Examples

>>> import pyAgrum as gum
>>> vX=gum.DiscretizedVariable('X','X has been discretized').addTick(1).addTick(2).addTick(3).addTick(3.1415)
>>> print(vX)
X:Discretized(<[1;2[,[2;3[,[3;3.1415]>)
>>> vX.isTick(4)
False
>>> vX.labels()
('[1;2[', '[2;3[', '[3;3.1415]')
>>> # where is the real value 2.5 ?
>>> vX.index('2.5')
1
addTick(*args)
Parameters

aTick (float) – the Tick to be added

Returns

the discretized variable

Return type

pyAgrum.DiscretizedVariable

Raises

pyAgrum.DefaultInLabel – If the tick is already defined

description()
Returns

the description of the variable

Return type

str

domain()
Returns

the domain of the variable as a string

Return type

str

domainSize()
Returns

the number of modalities in the variable domain

Return type

int

empty()
Returns

True if the domain size < 2

Return type

bool

eraseTicks()

erase all the Ticks

Return type

None

index(label)
Parameters

label (str) – a label

Returns

the indice of the label

Return type

int

isTick(aTick)
Parameters

aTick (float) – the Tick to be tested

Returns

True if the Tick already exists

Return type

bool

label(i)
Parameters

i (int) – the index of the label we wish to return

Returns

the indice-th label

Return type

str

Raises

pyAgrum.OutOfBounds – If the variable does not contain the label

labels()
Returns

a tuple containing the labels

Return type

tuple

name()
Returns

the name of the variable

Return type

str

numerical(indice)
Parameters

indice (int) – an index

Returns

the numerical representation of the indice-th value

Return type

float

setDescription(theValue)

set the description of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

setName(theValue)

sets the name of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

stype()
Return type

str

tick(i)

Indicate the index of the Tick

Parameters

i (int) – the index of the Tick

Returns

aTick – the index-th Tick

Return type

float

Raises

pyAgrum.NotFound – If the index is greater than the number of Ticks

ticks()
Returns

a tuple containing all the Ticks

Return type

tuple

toDiscretizedVar()
Returns

the discretized variable

Return type

pyAgrum.DiscretizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a DiscretizedVariable

toIntegerVar()
Return type

IntegerVariable

toLabelizedVar()
Returns

the labelized variable

Return type

pyAgrum.LabelizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a LabelizedVariable

toRangeVar()
Returns

the range variable

Return type

pyAgrum.RangeVariable

Raises

pyAgrum.RuntimeError – If the variable is not a RangeVariable

toStringWithDescription()
Returns

a description of the variable

Return type

str

varType()

returns the type of variable

Returns

the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable

Return type

int

IntegerVariable

class pyAgrum.IntegerVariable(*args)
addValue(value)
Parameters

value (int) –

Return type

IntegerVariable

changeValue(old_value, new_value)
Parameters
  • old_value (int) –

  • new_value (int) –

Return type

None

description()
Returns

the description of the variable

Return type

str

domain()
Returns

the domain of the variable

Return type

str

domainSize()
Returns

the number of modalities in the variable domain

Return type

int

empty()
Returns

True if the domain size < 2

Return type

bool

eraseValue(value)
Parameters

value (int) –

Return type

None

eraseValues()
Return type

None

index(label)
Parameters

label (str) – a label

Returns

the indice of the label

Return type

int

integerDomain()
Return type

List[int]

label(index)
Parameters
  • i (int) – the index of the label we wish to return

  • index (int) –

Returns

the indice-th label

Return type

str

Raises

pyAgrum.OutOfBounds – If the variable does not contain the label

labels()
Returns

a tuple containing the labels

Return type

tuple

name()
Returns

the name of the variable

Return type

str

numerical(index)
Parameters
  • indice (int) – an index

  • index (int) –

Returns

the numerical representation of the indice-th value

Return type

float

setDescription(theValue)

set the description of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

setName(theValue)

sets the name of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

stype()
Return type

str

toDiscretizedVar()
Returns

the discretized variable

Return type

pyAgrum.DiscretizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a DiscretizedVariable

toIntegerVar()
Return type

IntegerVariable

toLabelizedVar()
Returns

the labelized variable

Return type

pyAgrum.LabelizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a LabelizedVariable

toRangeVar()
Returns

the range variable

Return type

pyAgrum.RangeVariable

Raises

pyAgrum.RuntimeError – If the variable is not a RangeVariable

toStringWithDescription()
Returns

a description of the variable

Return type

str

varType()

returns the type of variable

Returns

the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable

Return type

int

RangeVariable

class pyAgrum.RangeVariable(*args)

RangeVariable represents a variable with a range of integers as domain.

RangeVariable(aName, aDesc,minVal, maxVal) -> RangeVariable
Parameters:
  • aName (str) – the name of the variable

  • aDesc (str) – the description of the variable

  • minVal (int) – the minimal integer of the interval

  • maxVal (int) – the maximal integer of the interval

RangeVariable(aName, aDesc=’’) -> RangeVariable
Parameters:
  • aName (str) – the name of the variable

  • aDesc (str) – the description of the variable

By default minVal=0 and maxVal=1

RangeVariable(aRV) -> RangeVariable
Parameters:
  • aDV (RangeVariable) – the pyAgrum.RangeVariable that will be copied

Examples

>>> import pyAgrum as gum
>>> vI=gum.RangeVariable('I','I in [4,10]',4,10)
>>> print(vI)
I:Range([4,10])
>>> vI.maxVal()
10
>>> vI.belongs(1)
False
>>> # where is the value 5 ?
>>> vI.index('5')
1
>>> vI.labels()
('4', '5', '6', '7', '8', '9', '10')
belongs(val)
Parameters

val (int) – the value to be tested

Returns

True if the value in parameters belongs to the variable’s interval.

Return type

bool

description()
Returns

the description of the variable

Return type

str

domain()
Returns

the domain of the variable

Return type

str

domainSize()
Returns

the number of modalities in the variable domain

Return type

int

empty()
Returns

True if the domain size < 2

Return type

bool

index(arg2)
Parameters

arg2 (str) – a label

Returns

the indice of the label

Return type

int

label(index)
Parameters
  • indice (int) – the index of the label we wish to return

  • index (int) –

Returns

the indice-th label

Return type

str

Raises

pyAgrum.OutOfBounds – If the variable does not contain the label

labels()
Returns

a tuple containing the labels

Return type

tuple

maxVal()
Returns

the upper bound of the variable.

Return type

int

minVal()
Returns

the lower bound of the variable

Return type

int

name()
Returns

the name of the variable

Return type

str

numerical(index)
Parameters
  • indice (int) – an index

  • index (int) –

Returns

the numerical representation of the indice-th value

Return type

float

setDescription(theValue)

set the description of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

setMaxVal(maxVal)

Set a new value of the upper bound

Parameters

maxVal (int) – The new value of the upper bound

Warning

An error should be raised if the value is lower than the lower bound.

Return type

None

setMinVal(minVal)

Set a new value of the lower bound

Parameters

minVal (int) – The new value of the lower bound

Warning

An error should be raised if the value is higher than the upper bound.

Return type

None

setName(theValue)

sets the name of the variable.

Parameters

theValue (str) – the new description of the variable

Return type

None

stype()
Return type

str

toDiscretizedVar()
Returns

the discretized variable

Return type

pyAgrum.DiscretizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a DiscretizedVariable

toIntegerVar()
Return type

IntegerVariable

toLabelizedVar()
Returns

the labelized variable

Return type

pyAgrum.LabelizedVariable

Raises

pyAgrum.RuntimeError – If the variable is not a LabelizedVariable

toRangeVar()
Returns

the range variable

Return type

pyAgrum.RangeVariable

Raises

pyAgrum.RuntimeError – If the variable is not a RangeVariable

toStringWithDescription()
Returns

a description of the variable

Return type

str

varType()

returns the type of variable

Returns

the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable

Return type

int