Potential and Instantiation¶
pyAgrum.Potential
is a multi-dimensional array with a pyAgrum.DiscreteVariable
associated to each dimension.
It is used to represent probabilities and utilities tables in aGrUMs’ multidimensional (graphical) models with some conventions.
The data are stored by iterating over each variable in the sequence.
>>> a=gum.RangeVariable("A","variable A",1,3)
>>> b=gum.RangeVariable("B","variable B",1,2)
>>> p=gum.Potential().add(a).add(b).fillWith([1,2,3,4,5,6]);
>>> print(p)
<A:1|B:1> :: 1 /<A:2|B:1> :: 2 /<A:3|B:1> :: 3 /<A:1|B:2> :: 4 /<A:2|B:2> :: 5 /<A:3|B:2> :: 6
If a
pyAgrum.Potential
with the sequence ofpyAgrum.DiscreteVariable
X,Y,Z represents a conditional probability Table (CPT), it will be P(X|Y,Z).
>>> print(p.normalizeAsCPT())
<A:1|B:1> :: 0.166667 /<A:2|B:1> :: 0.333333 /<A:3|B:1> :: 0.5 /<A:1|B:2> :: 0.266667 /<A:2|B:2> :: 0.333333 /<A:3|B:2> :: 0.4
For addressing and looping in a
pyAgrum.Potential
structure, pyAgrum providesInstantiation
class which represents a multi-dimensionnal index.
>>> I=gum.Instantiation(p)
>>> print(I)
<A:1|B:1>
>>> I.inc();print(I)
<A:2|B:1>
>>> I.inc();print(I)
<A:3|B:1>
>>> I.inc();print(I)
<A:1|B:2>
>>> I.setFirst();print(f"{I} -> {p.get(I)}")
<A:1|B:1> -> 0.16666666666666666
>>> I["B"]="2";print(f"{I} -> {p.get(I)}")
<A:1|B:2> -> 0.26666666666666666
pyAgrum.Potential
include tensor operators (see for instance this notebook).
>>> c=gum.RangeVariable("C","variable C",1,5)
>>> q=gum.Potential().add(a).add(c).fillWith(1)
>>> print(p+q)
<A:1|C:1|B:1> :: 2 /<A:2|C:1|B:1> :: 3 /<A:3|C:1|B:1> :: 4 /<A:1|C:2|B:1> :: 2 /<A:2|C:2|B:1> :: 3 /<A:3|C:2|B:1> :: 4 /<A:1|C:3|B:1> :: 2 /<A:2|C:3|B:1> :: 3 /<A:3|C:3|B:1> :: 4 /<A:1|C:4|B:1> :: 2 /<A:2|C:4|B:1> :: 3 /<A:3|C:4|B:1> :: 4 /<A:1|C:5|B:1> :: 2 /<A:2|C:5|B:1> :: 3 /<A:3|C:5|B:1> :: 4 /<A:1|C:1|B:2> :: 5 /<A:2|C:1|B:2> :: 6 /<A:3|C:1|B:2> :: 7 /<A:1|C:2|B:2> :: 5 /<A:2|C:2|B:2> :: 6 /<A:3|C:2|B:2> :: 7 /<A:1|C:3|B:2> :: 5 /<A:2|C:3|B:2> :: 6 /<A:3|C:3|B:2> :: 7 /<A:1|C:4|B:2> :: 5 /<A:2|C:4|B:2> :: 6 /<A:3|C:4|B:2> :: 7 /<A:1|C:5|B:2> :: 5 /<A:2|C:5|B:2> :: 6 /<A:3|C:5|B:2> :: 7
>>> print((p*q).margSumOut(["B","C"])) # marginalize p*q over B and C(using sum)
<A:1> :: 25 /<A:2> :: 35 /<A:3> :: 45
Instantiation¶
- class pyAgrum.Instantiation(*args)¶
Class for assigning/browsing values to tuples of discrete variables.
Instantiation is designed to assign values to tuples of variables and to efficiently loop over values of subsets of variables.
- Instantiation() -> Instantiation
default constructor
- Instantiation(aI) -> Instantiation
- Parameters:
aI (pyAgrum.Instantiation) – the Instantiation we copy
- Returns
pyAgrum.Instantiation – An empty tuple or a copy of the one in parameters
Instantiation is subscriptable therefore values can be easily accessed/modified.
Examples
>>> ## Access the value of A in an instantiation aI >>> valueOfA = aI['A'] >>> ## Modify the value >>> aI['A'] = newValueOfA
- add(v)¶
Adds a new variable in the Instantiation.
- Parameters
v (pyAgrum.DiscreteVariable) – The new variable added to the Instantiation
- Raises
DuplicateElement – If the variable is already in this Instantiation
- Return type
None
- addVarsFromModel(model, names)¶
From a graphical model, add all the variable whose names are in the iterable
- Parameters
model (pyAgrum.GraphicalModel) –
network (Markov) –
network –
Diagram (Influence) –
etc. –
names (iterable of strings) –
string) (a list/set/etc of names of variables (as) –
- Returns
pyAgrum.Instantiation
the current instantiation (self) in order to chain methods.
- chgVal(*args)¶
Assign newval to v (or to the variable at position varPos) in the Instantiation.
- Parameters
v (pyAgrum.DiscreteVariable or string) – The variable whose value is assigned (or its name)
varPos (int) – The index of the variable whose value is assigned in the tuple of variables of the Instantiation
newval (int or string) – The index of the value assigned (or its name)
- Returns
The modified instantiation
- Return type
- Raises
NotFound – If variable v does not belong to the instantiation.
OutOfBound – If newval is not a possible value for the variable.
- clear()¶
Erase all variables from an Instantiation.
- Return type
None
- contains(*args)¶
Indicates whether a given variable belongs to the Instantiation.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable for which the test is made.
- Returns
True if the variable is in the Instantiation.
- Return type
bool
- dec()¶
Operator –.
- Return type
None
- decIn(i)¶
Operator – for the variables in i.
- Parameters
i (pyAgrum.Instantiation) – The set of variables to decrement in this Instantiation
- Return type
None
- decNotVar(v)¶
Operator – for vars which are not v.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable not to decrement in this Instantiation.
- Return type
None
- decOut(i)¶
Operator – for the variables not in i.
- Parameters
i (pyAgrum.Instantiation) – The set of variables to not decrement in this Instantiation.
- Return type
None
- decVar(v)¶
Operator – for variable v only.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable to decrement in this Instantiation.
- Raises
NotFound – If variable v does not belong to the Instantiation.
- Return type
None
- domainSize()¶
- Returns
The product of the variable’s domain size in the Instantiation.
- Return type
int
- empty()¶
- Returns
True if the instantiation is empty.
- Return type
bool
- end()¶
- Returns
True if the Instantiation reached the end.
- Return type
bool
- erase(*args)¶
- Parameters
v (pyAgrum.DiscreteVariable) – The variable to be removed from this Instantiation.
- Raises
NotFound – If v does not belong to this Instantiation.
- Return type
None
- fromdict(dict)¶
Change the values in an instantiation from a dictionary {variable_name:value} where value can be a position (int) or a label (string).
If a variable_name does not occur in the instantiation, nothing is done.
Warning
OutOfBounds raised if a value cannot be found.
- Parameters
dict (
object
) –- Return type
None
- hamming()¶
- Returns
the hamming distance of this instantiation.
- Return type
int
- inOverflow()¶
- Returns
True if the current value of the tuple is correct
- Return type
bool
- inc()¶
Operator ++.
- Return type
None
- incIn(i)¶
Operator ++ for the variables in i.
- Parameters
i (pyAgrum.Instantiation) – The set of variables to increment in this Instantiation.
- Return type
None
- incNotVar(v)¶
Operator ++ for vars which are not v.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable not to increment in this Instantiation.
- Return type
None
- incOut(i)¶
Operator ++ for the variables not in i.
- Parameters
i (Instantiation) – The set of variable to not increment in this Instantiation.
- Return type
None
- incVar(v)¶
Operator ++ for variable v only.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable to increment in this Instantiation.
- Raises
NotFound – If variable v does not belong to the Instantiation.
- Return type
None
- isMutable()¶
- Return type
bool
- nbrDim()¶
- Returns
The number of variables in the Instantiation.
- Return type
int
- pos(v)¶
- Returns
the position of the variable v.
- Return type
int
- Parameters
v (pyAgrum.DiscreteVariable) – the variable for which its position is return.
- Raises
NotFound – If v does not belong to the instantiation.
- rend()¶
- Returns
True if the Instantiation reached the rend.
- Return type
bool
- reorder(*args)¶
Reorder vars of this instantiation giving the order in v (or i).
- Parameters
i (pyAgrum.Instantiation) – The sequence of variables with which to reorder this Instantiation.
v (list) – The new order of variables for this Instantiation.
- Return type
None
- setFirst()¶
Assign the first values to the tuple of the Instantiation.
- Return type
None
- setFirstIn(i)¶
Assign the first values in the Instantiation for the variables in i.
- Parameters
i (pyAgrum.Instantiation) – The variables to which their first value is assigned in this Instantiation.
- Return type
None
- setFirstNotVar(v)¶
Assign the first values to variables different of v.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable that will not be set to its first value in this Instantiation.
- Return type
None
- setFirstOut(i)¶
Assign the first values in the Instantiation for the variables not in i.
- Parameters
i (pyAgrum.Instantiation) – The variable that will not be set to their first value in this Instantiation.
- Return type
None
- setFirstVar(v)¶
Assign the first value in the Instantiation for var v.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable that will be set to its first value in this Instantiation.
- Return type
None
- setLast()¶
Assign the last values in the Instantiation.
- Return type
None
- setLastIn(i)¶
Assign the last values in the Instantiation for the variables in i.
- Parameters
i (pyAgrum.Instantiation) – The variables to which their last value is assigned in this Instantiation.
- Return type
None
- setLastNotVar(v)¶
Assign the last values to variables different of v.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable that will not be set to its last value in this Instantiation.
- Return type
None
- setLastOut(i)¶
Assign the last values in the Instantiation for the variables not in i.
- Parameters
i (pyAgrum.Instantiation) – The variables that will not be set to their last value in this Instantiation.
- Return type
None
- setLastVar(v)¶
Assign the last value in the Instantiation for var v.
- Parameters
v (pyAgrum.DiscreteVariable) – The variable that will be set to its last value in this Instantiation.
- Return type
None
- setMutable()¶
- Return type
None
- setVals(i)¶
Assign the values from i in the Instantiation.
- Parameters
i (pyAgrum.Instantiation) – An Instantiation in which the new values are searched
- Returns
a reference to the instantiation
- Return type
- todict(withLabels=False)¶
Create a dictionary {variable_name:value} from an instantiation
- Parameters
withLabels (boolean) – The value will be a label (string) if True. It will be a position (int) if False.
- Returns
The dictionary
- Return type
Dict[str,int]
- unsetEnd()¶
Alias for unsetOverflow().
- Return type
None
- unsetOverflow()¶
Removes the flag overflow.
- Return type
None
- val(*args)¶
- Parameters
i (int) – The index of the variable.
var (pyAgrum.DiscreteVariable) – The variable the value of which we wish to know
- Returns
the current value of the variable.
- Return type
int
- Raises
NotFound – If the element cannot be found.
- variable(*args)¶
- Parameters
i (int) – The index of the variable
- Returns
the variable at position i in the tuple.
- Return type
- Raises
NotFound – If the element cannot be found.
- variablesSequence()¶
- Returns
the sequence of DiscreteVariable of this instantiation.
- Return type
List
Potential¶
- class pyAgrum.Potential(*args)¶
Class representing a potential.
- Potential() -> Potential
default constructor
- Potential(src) -> Potential
- Parameters:
src (pyAgrum.Potential) – the Potential to copy
- KL(p)¶
Check the compatibility and compute the Kullback-Leibler divergence between the potential and.
- Parameters
p (pyAgrum.Potential) – the potential from which we want to calculate the divergence.
- Returns
The value of the divergence
- Return type
float
- Raises
pyAgrum.InvalidArgument – If p is not compatible with the potential (dimension, variables)
pyAgrum.FatalError – If a zero is found in p or the potential and not in the other.
- abs()¶
Apply abs on every element of the container
- Returns
a reference to the modified potential.
- Return type
- add(v)¶
Add a discrete variable to the potential.
- Parameters
v (pyAgrum.DiscreteVariable) – the var to be added
- Raises
DuplicateElement – If the variable is already in this Potential.
InvalidArgument – If the variable is empty.
- Returns
a reference to the modified potential.
- Return type
- argmax()¶
- Return type
List
[Dict
[str
,int
]]
- argmin()¶
- Return type
List
[Dict
[str
,int
]]
- contains(v)¶
- Parameters
v (pyAgrum.Potential) – a DiscreteVariable.
- Returns
True if the var is in the potential
- Return type
bool
- domainSize()¶
- Return type
int
- draw()¶
draw a value using the potential as a probability table.
- Returns
the index of the drawn value
- Return type
int
- empty()¶
- Returns
Returns true if no variable is in the potential.
- Return type
bool
- entropy()¶
- Returns
the entropy of the potential
- Return type
float
- extract(*args)¶
create a new Potential extracted from self given a partial instantiation.
- Parameters
inst (pyAgrum.instantiation) – a partial instantiation
dict (Dict[str,str|int]) – a dictionnary containing values for some discrete variables.
- Returns
the new Potential
- Return type
- fillWith(*args)¶
Automatically fills the potential with v.
- Parameters
v (number or list or pyAgrum.Potential the number of parameters of the Potential) – a value or a list/pyAgrum.Potential containing the values to fill the Potential with.
Warning
if v is a list, the size of the list must be the if v is a pyAgrum.Potential. It must to contain variables with exactly the same names and labels but not necessarily the same variables.
- Returns
a reference to the modified potentia
- Return type
- Raises
pyAgrum.SizeError – If v size’s does not matches the domain size.
- fillWithFunction(s, noise=None)¶
Automatically fills the potential as a (quasi) deterministic CPT with the evaluation of the expression s.
The expression s gives a value for the first variable using the names of the last variables. The computed CPT is deterministic unless noise is used to add a ‘probabilistic’ noise around the exact value given by the expression.
Examples
>>> import pyAgrum as gum >>> bn=gum.fastBN("A[3]->B[3]<-C[3]") >>> bn.cpt("B").fillWithFunction("(A+C)/2")
- Parameters
s (str) – an expression using the name of the last variables of the Potential and giving a value to the first variable of the Potential
noise (list) – an (odd) list of numerics giving a pattern of ‘probabilistic noise’ around the value.
Warning
The expression may have any numerical values, but will be then transformed to the closest correct value for the range of the variable.
- Returns
a reference to the modified potential
- Return type
- Raises
gum.InvalidArgument – If the first variable is Labelized or Integer, or if the len of the noise is not odd.
- findAll(v)¶
- Parameters
v (
float
) –- Return type
List
[Dict
[str
,int
]]
- get(i)¶
- Parameters
i (pyAgrum.Instantiation) – an Instantiation
- Returns
the value in the Potential at the position given by the instantiation
- Return type
float
- inverse()¶
- Return type
- isNonZeroMap()¶
- Returns
a boolean-like potential using the predicate isNonZero
- Return type
- log2()¶
log2 all the values in the Potential
Warning
When the Potential contains 0 or negative values, no exception are raised but -inf or nan values are assigned.
- Return type
- loopIn()¶
Generator to iterate inside a Potential.
Yield an gum.Instantiation that iterates over all the possible values for the gum.Potential
Examples
>>> import pyAgrum as gum >>> bn=gum.fastBN("A[3]->B[3]<-C[3]") >>> for i in bn.cpt("B").loopIn(): print(i) print(bn.cpt("B").get(i)) bn.cpt("B").set(i,0.3)
- margMaxIn(varnames)¶
Projection using max as operation.
- Parameters
varnames (set) – the set of vars to keep
- Returns
the projected Potential
- Return type
- margMaxOut(varnames)¶
Projection using max as operation.
- Parameters
varnames (set) – the set of vars to eliminate
- Returns
the projected Potential
- Return type
- Raises
pyAgrum.InvalidArgument – If varnames contains only one variable that does not exist in the Potential
- margMinIn(varnames)¶
Projection using min as operation.
- Parameters
varnames (set) – the set of vars to keep
- Returns
the projected Potential
- Return type
- margMinOut(varnames)¶
Projection using min as operation.
- Parameters
varnames (set) – the set of vars to eliminate
- Returns
the projected Potential
- Return type
Warning
InvalidArgument raised if varnames contains only one variable that does not exist in the Potential
- margProdIn(varnames)¶
Projection using multiplication as operation.
- Parameters
varnames (set) – the set of vars to keep
- Returns
the projected Potential
- Return type
- margProdOut(varnames)¶
Projection using multiplication as operation.
- Parameters
varnames (set) – the set of vars to eliminate
- Returns
the projected Potential
- Return type
- Raises
pyAgrum.InvalidArgument – If varnames contains only one variable that does not exist in the Potential
- margSumIn(varnames)¶
Projection using sum as operation.
- Parameters
varnames (set) – the set of vars to keep
- Returns
the projected Potential
- Return type
- margSumOut(varnames)¶
Projection using sum as operation.
- Parameters
varnames (set) – the set of vars to eliminate
- Returns
the projected Potential
- Return type
- Raises
pyAgrum.InvalidArgument – If varnames contains only one variable that does not exist in the Potential
- max()¶
- Returns
the maximum of all elements in the Potential
- Return type
float
- maxNonOne()¶
- Returns
the maximum of non one elements in the Potential
- Return type
float
- Raises
pyAgrum.NotFound – If all value == 1.0
- min()¶
- Returns
the min of all elements in the Potential
- Return type
float
- minNonZero()¶
- Returns
the min of non zero elements in the Potential
- Return type
float
- Raises
pyAgrum.NotFound – If all value == 0.0
- nbrDim(*args)¶
- Returns
the number of vars in the multidimensional container.
- Return type
int
- newFactory()¶
Erase the Potential content and create a new empty one.
- Returns
a reference to the new Potential
- Return type
- new_abs()¶
- Return type
- new_log2()¶
- Return type
- new_sq()¶
- Return type
- noising(alpha)¶
- Parameters
alpha (
float
) –- Return type
- normalize()¶
Normalize the Potential (do nothing if sum is 0)
- Returns
a reference to the normalized Potential
- Return type
- normalizeAsCPT(varId=0)¶
Normalize the Potential as a CPT
- Returns
a reference to the normalized Potential
- Return type
- Raises
pyAgrum.FatalError – If some distribution sums to 0
- Parameters
varId (
int
) –
- pos(v)¶
- Parameters
v (pyAgrum.DiscreteVariable) – The variable for which the index is returned.
- Returns
- Return type
Returns the index of a variable.
- Raises
pyAgrum.NotFound – If v is not in this multidimensional matrix.
- product()¶
- Returns
the product of all elements in the Potential
- Return type
float
- putFirst(varname)¶
- Parameters
v (pyAgrum.DiscreteVariable) – The variable for which the index should be 0.
varname (
str
) –
- Returns
a reference to the modified potential
- Return type
- Raises
pyAgrum.InvalidArgument – If the var is not in the potential
- random()¶
- Return type
- randomCPT()¶
- Return type
- randomDistribution()¶
- Return type
- remove(var)¶
- Parameters
v (pyAgrum.DiscreteVariable) – The variable to be removed
- Returns
a reference to the modified potential
- Return type
Warning
IndexError raised if the var is not in the potential
- Parameters
var (pyAgrum.DiscreteVariable) –
- reorganize(*args)¶
Create a new Potential with another order.
- Returns
varnames – a list of the var names in the new order
- Return type
list
- Returns
a reference to the modified potential
- Return type
- scale(v)¶
Create a new potential multiplied by v.
- Parameters
v (float) – a multiplier
- Returns
- Return type
a reference to the modified potential
- set(i, value)¶
Change the value pointed by i
- Parameters
i (pyAgrum.Instantiation) – The Instantiation to be changed
value (float) – The new value of the Instantiation
- Return type
None
- sq()¶
Square all the values in the Potential
- Return type
- sum()¶
- Returns
the sum of all elements in the Potential
- Return type
float
- property thisown¶
The membership flag
- toarray()¶
- Returns
the potential as an array
- Return type
array
- toclipboard(**kwargs)¶
Write a text representation of object to the system clipboard. This can be pasted into spreadsheet, for instance.
- tolatex()¶
Render object to a LaTeX tabular.
Requires to include booktabs package in the LaTeX document.
- Returns
the potential as LaTeX string
- Return type
str
- tolist()¶
- Returns
the potential as a list
- Return type
list
- topandas()¶
- Returns
the potential as an pandas.DataFrame
- Return type
pandas.DataFrame
- translate(v)¶
Create a new potential added with v.
- Parameters
v (float) – The value to be added
- Returns
- Return type
a reference to the modified potential
- property var_dims¶
- Returns
a list containing the dimensions of each variables in the potential
- Return type
list
- property var_names¶
- Returns
a list containing the name of each variables in the potential
- Return type
list
Warning
listed in the reverse order of the enumeration order of the variables.
- variable(*args)¶
- Parameters
i (int) – An index of this multidimensional matrix.
- Returns
- Return type
the varible at the ith index
- Raises
pyAgrum.NotFound – If i does not reference a variable in this multidimensional matrix.
- variablesSequence()¶
- Returns
a list containing the sequence of variables
- Return type
list