# 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(Variable self)
Returns: the description of the variable str
domain(DiscreteVariable self)
Returns: the domain of the variable str
domainSize(DiscreteVariable self)
Returns: the number of modalities in the variable domain int
empty(DiscreteVariable self)
Returns: True if the domain size < 2 bool
index(DiscreteVariable self, str label)
Parameters: label (str) – a label the indice of the label int
label(DiscreteVariable self, int i)
Parameters: i (int) – the index of the label we wish to return the indice-th label str gum.OutOfBound – If the variable does not contain the label
labels(DiscreteVariable self)
Returns: a tuple containing the labels tuple
name(Variable self)
Returns: the name of the variable str
numerical(DiscreteVariable self, int indice)
Parameters: indice (int) – an index the numerical representation of the indice-th value float
setDescription(Variable self, str theValue)

set the description of the variable.

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

sets the name of the variable.

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

returns the type of variable

Returns: the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable 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>
>>>
>>> print(va)
>>> ## a<0,1,2,foo>
>>>
>>> va.chgLabel(1,'bar')
>>> print(va)
>>> a<0,bar,2,foo>
>>>
>>> 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 the labelized variable pyAgrum.LabelizedVariable gum.DuplicateElement – If the variable already contains the label
changeLabel(LabelizedVariable self, int pos, str 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 gum.DuplicatedElement – If the variable already contains the new label gum.OutOfBounds – If the index is greater than the size of the variable
description(Variable self)
Returns: the description of the variable str
domain(LabelizedVariable self)
Returns: the domain of the variable as a string str
domainSize(LabelizedVariable self)
Returns: the number of modalities in the variable domain int
empty(DiscreteVariable self)
Returns: True if the domain size < 2 bool
eraseLabels(LabelizedVariable self)

Erase all the labels from the variable.

index(LabelizedVariable self, str label)
Parameters: label (str) – a label the indice of the label int
isLabel(LabelizedVariable self, str aLabel)

Indicates whether the variable already has the label passed in argument

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

set the description of the variable.

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

sets the name of the variable.

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

returns the type of variable

Returns: the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable 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')
>>> ## <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 the discretized variable pyAgrum.DiscretizedVariable gum.DefaultInLabel – If the tick is already defined
description(Variable self)
Returns: the description of the variable str
domain(DiscretizedVariable self)
Returns: the domain of the variable as a string str
domainSize(DiscretizedVariable self)
Returns: the number of modalities in the variable domain int
empty(DiscreteVariable self)
Returns: True if the domain size < 2 bool
eraseTicks(DiscretizedVariable self)

erase all the Ticks

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

set the description of the variable.

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

sets the name of the variable.

Parameters: theValue (str) – the new description of the variable
tick(DiscretizedVariable self, int i)

Indicate the index of the Tick

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

returns the type of variable

Returns: the type of the variable, 0: DiscretizedVariable, 1: LabelizedVariable, 2: RangeVariable 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(RangeVariable self, long val)
Parameters: val (long) – the value to be tested True if the value in parameters belongs to the variable’s interval. bool
description(Variable self)
Returns: the description of the variable str
domain(RangeVariable self)
Returns: the domain of the variable str
domainSize(RangeVariable self)
Returns: the number of modalities in the variable domain int
empty(DiscreteVariable self)
Returns: True if the domain size < 2 bool
index(RangeVariable self, str arg2)
Parameters: arg2 (str) – a label the indice of the label int
label(RangeVariable self, int indice)
Parameters: indice (int) – the index of the label we wish to return the indice-th label str gum.OutOfBound – If the variable does not contain the label
labels(DiscreteVariable self)
Returns: a tuple containing the labels tuple
maxVal(RangeVariable self)
Returns: the upper bound of the variable. long
minVal(RangeVariable self)
Returns: the lower bound of the variable long
name(Variable self)
Returns: the name of the variable str
numerical(RangeVariable self, int indice)
Parameters: indice (int) – an index the numerical representation of the indice-th value float
setDescription(Variable self, str theValue)

set the description of the variable.

Parameters: theValue (str) – the new description of the variable
setMaxVal(RangeVariable self, long 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(RangeVariable self, long 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(Variable self, str theValue)

sets the name of the variable.

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

returns the type of variable

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