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 variables.

DiscreteVariable(aName, aDesc=’‘) -> DiscreteVariable

Parameters:

aName (str) – the name of the variable
aDesc (str) – the (optional) description of the variable

DiscreteVariable(aDRV) -> DiscreteVariable

Parameters:

aDRV (pyAgrum.DiscreteVariable) – the pyAgrum.DiscreteVariable that will be copied

description(Variable self)¶

Returns:	the description of the variable
Return type:	str

domain(DiscreteVariable self)¶

Returns:	the domain of the variable
Return type:	str

domainSize(DiscreteVariable self)¶

Returns:	the number of modalities in the variable domain
Return type:	int

empty(DiscreteVariable self)¶

Returns:	True if the domain size < 2
Return type:	bool

index(DiscreteVariable self, str label)¶

Parameters:	label (str) – a label
Returns:	the indice of the label
Return type:	int

label(DiscreteVariable self, int 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(DiscreteVariable self)¶

Returns:	a tuple containing the labels
Return type:	tuple

name(Variable self)¶

Returns:	the name of the variable
Return type:	str

numerical(DiscreteVariable self, int indice)¶

Parameters:	indice (int) – an index
Returns:	the numerical representation of the indice-th value
Return type:	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
Return type:	pyAgrum.DiscretizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a DiscretizedVariable

toLabelizedVar(DiscreteVariable self)¶

Returns:	the labelized variable
Return type:	pyAgrum.LabelizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a LabelizedVariable

toRangeVar(DiscreteVariable self)¶

Returns:	the range variable
Return type:	pyAgrum.RangeVariable
Raises:	`gum.RuntimeError` – If the variable is not a RangeVariable

toStringWithDescription(DiscreteVariable self)¶

Returns:	a description of the variable
Return type:	str

varType(DiscreteVariable 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.

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<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(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
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(Variable self)¶

Returns:	the description of the variable
Return type:	str

domain(LabelizedVariable self)¶

Returns:	the domain of the variable as a string
Return type:	str

domainSize(LabelizedVariable self)¶

Returns:	the number of modalities in the variable domain
Return type:	int

empty(DiscreteVariable self)¶

Returns:	True if the domain size < 2
Return type:	bool

eraseLabels(LabelizedVariable self)¶: Erase all the labels from the variable.

index(LabelizedVariable self, str label)¶

Parameters:	label (str) – a label
Returns:	the indice of the label
Return type:	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
Returns:	True if the label already exists
Return type:	bool

label(LabelizedVariable self, int 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(DiscreteVariable self)¶

Returns:	a tuple containing the labels
Return type:	tuple

name(Variable self)¶

Returns:	the name of the variable
Return type:	str

numerical(LabelizedVariable self, int indice)¶

Parameters:	indice (int) – an index
Returns:	the numerical representation of the indice-th value
Return type:	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
Return type:	pyAgrum.DiscretizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a DiscretizedVariable

toLabelizedVar(DiscreteVariable self)¶

Returns:	the labelized variable
Return type:	pyAgrum.LabelizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a LabelizedVariable

toRangeVar(DiscreteVariable self)¶

Returns:	the range variable
Return type:	pyAgrum.RangeVariable
Raises:	`gum.RuntimeError` – If the variable is not a RangeVariable

toStringWithDescription(DiscreteVariable self)¶

Returns:	a description of the variable
Return type:	str

varType(LabelizedVariable 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.

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')
>>> vX.addTick(1).addTick(2).addTick(3).addTick(3.1415) #doctest: +ELLIPSIS
>>> ## <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(Variable self)¶

Returns:	the description of the variable
Return type:	str

domain(DiscretizedVariable self)¶

Returns:	the domain of the variable as a string
Return type:	str

domainSize(DiscretizedVariable self)¶

Returns:	the number of modalities in the variable domain
Return type:	int

empty(DiscreteVariable self)¶

Returns:	True if the domain size < 2
Return type:	bool

eraseTicks(DiscretizedVariable self)¶: erase all the Ticks

index(DiscretizedVariable self, str label)¶

Parameters:	label (str) – a label
Returns:	the indice of the label
Return type:	int

isTick(DiscretizedVariable self, double aTick)¶

Parameters:	aTick (double) – the Tick to be tested
Returns:	True if the Tick already exists
Return type:	bool

label(DiscretizedVariable self, int 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(DiscreteVariable self)¶

Returns:	a tuple containing the labels
Return type:	tuple

name(Variable self)¶

Returns:	the name of the variable
Return type:	str

numerical(DiscretizedVariable self, int indice)¶

Parameters:	indice (int) – an index
Returns:	the numerical representation of the indice-th value
Return type:	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
Returns:	aTick – the index-th Tick
Return type:	double
Raises:	`gum.NotFound` – If the index is greater than the number of Ticks

ticks(DiscretizedVariable self)¶

Returns:	a tuple containing all the Ticks
Return type:	tuple

toDiscretizedVar(DiscreteVariable self)¶

Returns:	the discretized variable
Return type:	pyAgrum.DiscretizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a DiscretizedVariable

toLabelizedVar(DiscreteVariable self)¶

Returns:	the labelized variable
Return type:	pyAgrum.LabelizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a LabelizedVariable

toRangeVar(DiscreteVariable self)¶

Returns:	the range variable
Return type:	pyAgrum.RangeVariable
Raises:	`gum.RuntimeError` – If the variable is not a RangeVariable

toStringWithDescription(DiscreteVariable self)¶

Returns:	a description of the variable
Return type:	str

varType(DiscretizedVariable 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.

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.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
Returns:	True if the value in parameters belongs to the variable’s interval.
Return type:	bool

description(Variable self)¶

Returns:	the description of the variable
Return type:	str

domain(RangeVariable self)¶

Returns:	the domain of the variable
Return type:	str

domainSize(RangeVariable self)¶

Returns:	the number of modalities in the variable domain
Return type:	int

empty(DiscreteVariable self)¶

Returns:	True if the domain size < 2
Return type:	bool

index(RangeVariable self, str arg2)¶

Parameters:	arg2 (str) – a label
Returns:	the indice of the label
Return type:	int

label(RangeVariable self, int 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(DiscreteVariable self)¶

Returns:	a tuple containing the labels
Return type:	tuple

maxVal(RangeVariable self)¶

Returns:	the upper bound of the variable.
Return type:	long

minVal(RangeVariable self)¶

Returns:	the lower bound of the variable
Return type:	long

name(Variable self)¶

Returns:	the name of the variable
Return type:	str

numerical(RangeVariable self, int indice)¶

Parameters:	indice (int) – an index
Returns:	the numerical representation of the indice-th value
Return type:	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
Return type:	pyAgrum.DiscretizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a DiscretizedVariable

toLabelizedVar(DiscreteVariable self)¶

Returns:	the labelized variable
Return type:	pyAgrum.LabelizedVariable
Raises:	`gum.RuntimeError` – If the variable is not a LabelizedVariable

toRangeVar(DiscreteVariable self)¶

Returns:	the range variable
Return type:	pyAgrum.RangeVariable
Raises:	`gum.RuntimeError` – If the variable is not a RangeVariable

toStringWithDescription(DiscreteVariable self)¶

Returns:	a description of the variable
Return type:	str

varType(RangeVariable self)¶

returns the type of variable

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