Random Variables

aGrUM/pyAgrum is currently dedicated for discrete probability distributions.

There are 3 types of discrete random variables in aGrUM/pyAgrum: LabelizedVariable, DiscretizedVariable and RangeVariable. The 3 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 base class for discrete random variable.

Available ructors:

DiscreteVariable(aName, aDesc='') -> DiscreteVariable

DiscreteVariable(aDRV) -> DiscreteVariable

Parameters:
  • aName (str) – The name of the variable
  • aDesc (str) – The (optional) description of the variable
  • aDRV (pyAgrum.DiscreteVariable) – Another DiscreteVariable that will be copied
description(self)
Returns:the description of the variable
Return type:str
domain(self)
Returns:the domain of the variable
Return type:str
domainSize(self)
Returns:the number of modalities in the variable domain
Return type:int
empty(self)
Returns:True if the domain size < 2
Return type:bool
index(self, label)
Parameters:label (str) – a label
Returns:the indice of the label
Return type:int
label(self, i)
Parameters:i (int) – the index of the label we wish to return
Returns:the indice-th label
Return type:str
Raises:gum.OutOfBound – If the variable does not contain the label
labels(self)
Returns:a tuple containing the labels
Return type:tuple
name(self)
Returns:the name of the variable
Return type:str
numerical(self, indice)
Parameters:indice (int) – an index
Returns:the numerical representation of the indice-th value
Return type:float
setDescription(self, theValue)

set the description of the variable.

Parameters:theValue (str) – the new description of the variable
setName(self, theValue)

sets the name of the variable.

Parameters:theValue (str) – the new description of the variable
thisown

The membership flag

toDiscretizedVar(self)
Returns:the discretized variable
Return type:pyAgrum.DiscretizedVariable
Raises:gum.RuntimeError – If the variable is not a DiscretizedVariable
toLabelizedVar(self)
Returns:the labelized variable
Return type:pyAgrum.LabelizedVariable
Raises:gum.RuntimeError – If the variable is not a LabelizedVariable
toRangeVar(self)
Returns:the range variable
Return type:pyAgrum.RangeVariable
Raises:gum.RuntimeError – If the variable is not a RangeVariable
toStringWithDescription(self)
Returns:a description of the variable
Return type:str
varType(self)

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.

Available ructors:

LabelizedVariable(aName, aDesc='', nbrLabel=2) -> LabelizedVariable

LabelizedVariable(aName, aDesc='') -> LabelizedVariable

LabelizedVariable(aLDRV) -> 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)
  • aLDRV (pyAgrum.LabelizedVariable) – Another 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<0,1,2>
>>>
>>> va.addLabel('foo')
>>> print(va)
>>> ## a<0,1,2,foo>
>>>
>>> va.chgLabel(1,'bar')
>>> print(va)
>>> a<0,bar,2,foo>
>>>
>>> vb=gum.LabelizedVariable('b','b',0).addLabel('A').addLabel('B').addLabel('C')
>>> print(vb)
>>> ## b<A,B,C>
>>>
>>> vb.labels()
>>> ## ('A', 'B', 'C')
>>>
>>> vb.isLabel('E')
>>> ## False
>>>
>>> vb.label(2)
>>> ## 'B'
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:gum.DuplicateElement – If the variable already contains the label
changeLabel(self, 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:
  • gum.DuplicatedElement – If the variable already contains the new label
  • gum.OutOfBounds – If the index is greater than the size of the variable
description(self)
Returns:the description of the variable
Return type:str
domain(self)
Returns:the domain of the variable as a string
Return type:str
domainSize(self)
Returns:the number of modalities in the variable domain
Return type:int
empty(self)
Returns:True if the domain size < 2
Return type:bool
eraseLabels(self)

Erase all the labels from the variable.

index(self, label)
Parameters:label (str) – a label
Returns:the indice of the label
Return type:int
isLabel(self, 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(self, i)
Parameters:i (int) – the index of the label we wish to return
Returns:the indice-th label
Return type:str
Raises:gum.OutOfBound – If the variable does not contain the label
labels(self)
Returns:a tuple containing the labels
Return type:tuple
name(self)
Returns:the name of the variable
Return type:str
numerical(self, indice)
Parameters:indice (int) – an index
Returns:the numerical representation of the indice-th value
Return type:float
posLabel(self, label)
setDescription(self, theValue)

set the description of the variable.

Parameters:theValue (str) – the new description of the variable
setName(self, theValue)

sets the name of the variable.

Parameters:theValue (str) – the new description of the variable
thisown

The membership flag

toDiscretizedVar(self)
Returns:the discretized variable
Return type:pyAgrum.DiscretizedVariable
Raises:gum.RuntimeError – If the variable is not a DiscretizedVariable
toLabelizedVar(self)
Returns:the labelized variable
Return type:pyAgrum.LabelizedVariable
Raises:gum.RuntimeError – If the variable is not a LabelizedVariable
toRangeVar(self)
Returns:the range variable
Return type:pyAgrum.RangeVariable
Raises:gum.RuntimeError – If the variable is not a RangeVariable
toStringWithDescription(self)
Returns:a description of the variable
Return type:str
varType(self)

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.

Available ructors:

DiscretizedVariable(aName, aDesc='') -> DiscretizedVariable

DiscretizedVariable(aDDRV) -> DiscretizedVariable

Parameters:
  • aName (str) – The name of the variable
  • aDesc (str) – The (optional) description of the variable
  • aDDRV (pyAgrum.DiscretizedVariable) – Another DiscretizedVariable that will be copied

Examples

>>> import pyAgrum as gum
>>>
>>> vX=gum.DiscretizedVariable('X','X has been discretized')
>>> vX.addTick(1).addTick(2).addTick(3).addTick(3.1415) #doctest: +ELLIPSIS
>>> ## <pyAgrum.pyAgrum.DiscretizedVariable;...>
>>> print(vX)
>>> ## X<[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 (double) – the Tick to be added
Returns:the discretized variable
Return type:pyAgrum.DiscretizedVariable
Raises:gum.DefaultInLabel – If the tick is already defined
description(self)
Returns:the description of the variable
Return type:str
domain(self)
Returns:the domain of the variable as a string
Return type:str
domainSize(self)
Returns:the number of modalities in the variable domain
Return type:int
empty(self)
Returns:True if the domain size < 2
Return type:bool
eraseTicks(self)

erase all the Ticks

index(self, label)
Parameters:label (str) – a label
Returns:the indice of the label
Return type:int
isTick(self, aTick)
Parameters:aTick (double) – the Tick to be tested
Returns:True if the Tick already exists
Return type:bool
label(self, i)
Parameters:i (int) – the index of the label we wish to return
Returns:the indice-th label
Return type:str
Raises:gum.OutOfBound – If the variable does not contain the label
labels(self)
Returns:a tuple containing the labels
Return type:tuple
name(self)
Returns:the name of the variable
Return type:str
numerical(self, indice)
Parameters:indice (int) – an index
Returns:the numerical representation of the indice-th value
Return type:float
setDescription(self, theValue)

set the description of the variable.

Parameters:theValue (str) – the new description of the variable
setName(self, theValue)

sets the name of the variable.

Parameters:theValue (str) – the new description of the variable
thisown

The membership flag

tick(self, i)

Indicate the index of the Tick

Parameters:i (int) – the index of the Tick
Returns:aTick – the index-th Tick
Return type:double
Raises:gum.NotFound – If the index is greater than the number of Ticks
ticks(self)
Returns:a tuple containing all the Ticks
Return type:tuple
toDiscretizedVar(self)
Returns:the discretized variable
Return type:pyAgrum.DiscretizedVariable
Raises:gum.RuntimeError – If the variable is not a DiscretizedVariable
toLabelizedVar(self)
Returns:the labelized variable
Return type:pyAgrum.LabelizedVariable
Raises:gum.RuntimeError – If the variable is not a LabelizedVariable
toRangeVar(self)
Returns:the range variable
Return type:pyAgrum.RangeVariable
Raises:gum.RuntimeError – If the variable is not a RangeVariable
toStringWithDescription(self)
Returns:a description of the variable
Return type:str
varType(self)

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.

Available ructors:

RangeVariable(aName, aDesc='',minVal, maxVal) -> RangeVariable

RangeVariable(aName, aDesc='',minVal) -> RangeVariable

RangeVariable(aName, aDesc='') -> RangeVariable

RangeVariable(aRV) -> RangeVariable

Parameters:
  • aName (str) – The name of the variable
  • aDesc (str) – The (optional) description of the variable
  • minVal (int) – The minimal integer of the interval
  • maxVal (int) – The maximal integer of the interval
  • aDV (pyAgrum.RangeVariable) – Another RangeVariable that will be copied

Examples

>>> import pyAgrum as gum
>>>
>>> vI=gum.gum.RangeVariable('I','I in [4,10]',4,10)
>>> print(vI)
>>> ## I[4-10]
>>>
>>> vX.maxVal()
>>> ## 10
>>>
>>> vX.belongs(1)
>>> ## False
>>>
>>> # where is the value 5 ?
>>> vX.index('5')
>>> ## 1
>>>
>>> vi.labels()
>>> ## ('4', '5', '6', '7', '8', '9', '10')
belongs(self, val)
Parameters:val (long) – the value to be tested
Returns:True if the value in parameters belongs to the variable’s interval.
Return type:bool
description(self)
Returns:the description of the variable
Return type:str
domain(self)
Returns:the domain of the variable
Return type:str
domainSize(self)
Returns:the number of modalities in the variable domain
Return type:int
empty(self)
Returns:True if the domain size < 2
Return type:bool
index(self, arg2)
Parameters:arg2 (str) – a label
Returns:the indice of the label
Return type:int
label(self, indice)
Parameters:indice (int) – the index of the label we wish to return
Returns:the indice-th label
Return type:str
Raises:gum.OutOfBound – If the variable does not contain the label
labels(self)
Returns:a tuple containing the labels
Return type:tuple
maxVal(self)
Returns:the upper bound of the variable.
Return type:long
minVal(self)
Returns:the lower bound of the variable
Return type:long
name(self)
Returns:the name of the variable
Return type:str
numerical(self, indice)
Parameters:indice (int) – an index
Returns:the numerical representation of the indice-th value
Return type:float
setDescription(self, theValue)

set the description of the variable.

Parameters:theValue (str) – the new description of the variable
setMaxVal(self, maxVal)

Set a new value of the upper bound

Parameters:maxVal (long) – The new value of the upper bound

Warning

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

setMinVal(self, minVal)

Set a new value of the lower bound

Parameters:minVal (long) – The new value of the lower bound

Warning

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

setName(self, theValue)

sets the name of the variable.

Parameters:theValue (str) – the new description of the variable
thisown

The membership flag

toDiscretizedVar(self)
Returns:the discretized variable
Return type:pyAgrum.DiscretizedVariable
Raises:gum.RuntimeError – If the variable is not a DiscretizedVariable
toLabelizedVar(self)
Returns:the labelized variable
Return type:pyAgrum.LabelizedVariable
Raises:gum.RuntimeError – If the variable is not a LabelizedVariable
toRangeVar(self)
Returns:the range variable
Return type:pyAgrum.RangeVariable
Raises:gum.RuntimeError – If the variable is not a RangeVariable
toStringWithDescription(self)
Returns:a description of the variable
Return type:str
varType(self)

returns the type of variable

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