Influence Diagram¶
An influence diagram is a compact graphical and mathematical representation of a decision situation. It is a generalization of a Bayesian network, in which not only probabilistic inference problems but also decision making problems (following the maximum expected utility criterion) can be modeled and solved. It includes 3 types of nodes : action, decision and utility nodes (from wikipedia).
PyAgrum’s so-called influence diagram represents both influence diagrams and LIMIDs. The way to enforce that such a model represent an influence diagram and not a LIMID belongs to the inference engine.
Tutorial
Reference
Model¶
-
class
pyAgrum.
InfluenceDiagram
(*args)¶ InfluenceDiagram represents an Influence Diagram.
- InfluenceDiagram() -> InfluenceDiagram
- default constructor
- InfluenceDiagram(source) -> InfluenceDiagram
- Parameters:
- source (pyAgrum.InfluenceDiagram) – the InfluenceDiagram to copy
-
add
(InfluenceDiagram self, DiscreteVariable variable, int id=0)¶ Add a chance variable, it’s associate node and it’s CPT.
The id of the new variable is automatically generated.
Parameters: - variable (pyAgrum.DiscreteVariable) – The variable added by copy.
- id (int) – The chosen id. If 0, the NodeGraphPart will choose.
Warning
give an id (not 0) should be reserved for rare and specific situations !!!
Returns: the id of the added variable. Return type: int Raises: gum.DuplicateElement
– If id(<>0) is already used
-
addArc
(InfluenceDiagram self, int tail, int head)¶ addArc(InfluenceDiagram self, str tail, str head)
Add an arc in the ID, and update diagram’s potential nodes cpt if necessary.
Parameters: - tail (int) – the id of the tail node
- head (int) – the id of the head node
Raises: gum.InvalidEdge
– If arc.tail and/or arc.head are not in the ID.gum.InvalidEdge
– If tail is a utility node
-
addChanceNode
(InfluenceDiagram self, DiscreteVariable variable, int id=0)¶ addChanceNode(InfluenceDiagram self, DiscreteVariable variable, pyAgrum.MultiDimImplementation aContent, int id=0) -> int
Add a chance variable, it’s associate node and it’s CPT.
The id of the new variable is automatically generated.
Parameters: - variable (pyAgrum.DiscreteVariable) – the variable added by copy.
- id (int) – the chosen id. If 0, the NodeGraphPart will choose.
Warning
give an id (not 0) should be reserved for rare and specific situations !!!
Returns: the id of the added variable. Return type: int Raises: gum.DuplicateElement
– If id(<>0) is already used
-
addDecisionNode
(InfluenceDiagram self, DiscreteVariable variable, int id=0)¶ Add a decision variable.
The id of the new variable is automatically generated.
Parameters: - variable (pyAgrum.DiscreteVariable) – the variable added by copy.
- id (int) – the chosen id. If 0, the NodeGraphPart will choose.
Warning
give an id (not 0) should be reserved for rare and specific situations !!!
Returns: the id of the added variable. Return type: int Raises: gum.DuplicateElement
– If id(<>0) is already used
-
addUtilityNode
(InfluenceDiagram self, DiscreteVariable variable, int id=0)¶ addUtilityNode(InfluenceDiagram self, DiscreteVariable variable, pyAgrum.MultiDimImplementation aContent, int id=0) -> int
Add a utility variable, it’s associate node and it’s UT.
The id of the new variable is automatically generated.
Parameters: - variable (pyAgrum.DiscreteVariable) – the variable added by copy
- id (int) – the chosen id. If 0, the NodeGraphPart will choose
Warning
give an id (not 0) should be reserved for rare and specific situations !!!
Returns: the id of the added variable.
Return type: int
Raises: gum.InvalidArgument
– If variable has more than one labelgum.DuplicateElement
– If id(<>0) is already used
-
ancestors
(DAGmodel self, int id)¶ ancestors(DAGmodel self, str name) -> Set
-
arcs
(InfluenceDiagram self)¶ Returns: the list of all the arcs in the Influence Diagram. Return type: list
-
chanceNodeSize
(InfluenceDiagram self)¶ Returns: the number of chance nodes. Return type: int
-
changeVariableName
(InfluenceDiagram self, int id, str new_name)¶ changeVariableName(InfluenceDiagram self, str name, str new_name)
Parameters: - id (int) – the node Id
- new_name (str) – the name of the variable
Raises: gum.DuplicateLabel
– If this name already existsgum.NotFound
– If no nodes matches id.
-
children
(InfluenceDiagram self, int id)¶ Parameters: id (int) – the id of the parent Returns: the set of all the children Return type: Set
-
clear
(InfluenceDiagram self)¶
-
completeInstantiation
(GraphicalModel self)¶
-
cpt
(InfluenceDiagram self, int varId)¶ cpt(InfluenceDiagram self, str name) -> Potential
Returns the CPT of a variable.
Parameters: VarId (int) – A variable’s id in the pyAgrum.BayesNet. Returns: The variable’s CPT. Return type: pyAgrum.Potential Raises: gum.NotFound
– If no variable’s id matches varId.
-
dag
(DAGmodel self)¶ Returns: a constant reference to the dag of this BayesNet. Return type: pyAgrum.DAG
-
decisionNodeSize
(InfluenceDiagram self)¶ Returns: the number of decision nodes Return type: int
-
decisionOrder
(InfluenceDiagram self)¶
-
decisionOrderExists
(InfluenceDiagram self)¶ Returns: True if a directed path exist with all decision node Return type: bool
-
descendants
(DAGmodel self, int id)¶ descendants(DAGmodel self, str name) -> Set
-
empty
(GraphicalModel self)¶
-
erase
(InfluenceDiagram self, int id)¶ erase(InfluenceDiagram self, str name) erase(InfluenceDiagram self, DiscreteVariable var)
Erase a Variable from the network and remove the variable from all his childs.
If no variable matches the id, then nothing is done.
Parameters: - id (int) – The id of the variable to erase.
- var (pyAgrum.DiscreteVariable) – The reference on the variable to remove.
-
eraseArc
(InfluenceDiagram self, Arc arc)¶ eraseArc(InfluenceDiagram self, int tail, int head) eraseArc(InfluenceDiagram self, str tail, str head)
Removes an arc in the ID, and update diagram’s potential nodes cpt if necessary.
If (tail, head) doesn’t exist, the nothing happens.
Parameters: - arc (pyAgrum.Arc) – The arc to be removed.
- tail (int) – the id of the tail node
- head (int) – the id of the head node
-
exists
(DAGmodel self, int node)¶
-
existsArc
(DAGmodel self, int tail, int head)¶ existsArc(DAGmodel self, str nametail, str namehead) -> bool
-
existsPathBetween
(InfluenceDiagram self, int src, int dest)¶ existsPathBetween(InfluenceDiagram self, str src, str dest) -> bool
Returns: true if a path exists between two nodes. Return type: bool
-
family
(DAGmodel self, int id)¶ family(DAGmodel self, str name) -> Set
-
static
fastPrototype
(str dotlike, int domainSize=2)¶ - Create an Influence Diagram with a dot-like syntax which specifies:
- the structure ‘a->b<-c;b->d;c<-e;’.
- a prefix for the type of node (chance/decision/utiliy nodes):
- a : a chance node named ‘a’ (by default)
- $a : a utility node named ‘a’
- *a : a decision node named ‘a’
- the type of the variables with different syntax as postfix:
- by default, a variable is a gum.RangeVariable using the default domain size (second argument)
- with ‘a[10]’, the variable is a gum.RangeVariable using 10 as domain size (from 0 to 9)
- with ‘a[3,7]’, the variable is a gum.RangeVariable using a domainSize from 3 to 7
- with ‘a[1,3.14,5,6.2]’, the variable is a gum.DiscretizedVariable using the given ticks (at least 3 values)
- with ‘a{top|middle|bottom}’, the variable is a gum.LabelizedVariable using the given labels.
Note
- If the dot-like string contains such a specification more than once for a variable, the first specification will be used.
- the potentials (probabilities, utilities) are randomly generated.
- see also pyAgrum.fastID.
Examples
>>> import pyAgrum as gum >>> bn=gum.fastID('A->B[1,3]<-*C{yes|No}->$D<-E[1,2.5,3.9]',6)
Parameters: - dotlike (str) – the string containing the specification
- domainSize (int) – the default domain size for variables
Returns: the resulting Influence Diagram
Return type:
-
getDecisionGraph
(InfluenceDiagram self)¶ Returns: the temporal Graph. Return type: pyAgrum.DAG
-
hasSameStructure
(DAGmodel self, DAGmodel other)¶ Parameters: pyAgrum.DAGmodel – a direct acyclic model Returns: True if all the named node are the same and all the named arcs are the same Return type: bool
-
idFromName
(InfluenceDiagram self, str name)¶ Returns a variable’s id given its name.
Parameters: name (str) – the variable’s name from which the id is returned. Returns: the variable’s node id. Return type: int Raises: gum.NotFound
– If no such name exists in the graph.
-
ids
(GraphicalModel self, Vector_string names)¶
-
isChanceNode
(InfluenceDiagram self, int varId)¶ isChanceNode(InfluenceDiagram self, str name) -> bool
Parameters: varId (int) – the tested node id. Returns: true if node is a chance node Return type: bool
-
isDecisionNode
(InfluenceDiagram self, int varId)¶ isDecisionNode(InfluenceDiagram self, str name) -> bool
Parameters: varId (int) – the tested node id. Returns: true if node is a decision node Return type: bool
-
isIndependent
(DAGmodel self, int X, int Y, Set Z)¶ isIndependent(DAGmodel self, str Xname, str Yname, Vector_string Zanmes) -> bool isIndependent(DAGmodel self, Set X, Set Y, Set Z) -> bool isIndependent(DAGmodel self, Vector_string Xname, Vector_string Yname, Vector_string Zanmes) -> bool
-
isUtilityNode
(InfluenceDiagram self, int varId)¶ isUtilityNode(InfluenceDiagram self, str name) -> bool
Parameters: varId (int) – the tested node id. Returns: true if node is an utility node Return type: bool
-
loadBIFXML
(InfluenceDiagram self, str name, PyObject * l=(PyObject *) 0)¶ Load a BIFXML file.
Parameters: name (str) – the name’s file
Raises: gum.IOError
– If file not foundgum.FatalError
– If file is not valid
-
log10DomainSize
(GraphicalModel self)¶
-
moralGraph
(DAGmodel self, bool clear=True)¶ Returns the moral graph of the BayesNet, formed by adding edges between all pairs of nodes that have a common child, and then making all edges in the graph undirected.
Returns: The moral graph Return type: pyAgrum.UndiGraph
-
moralizedAncestralGraph
(DAGmodel self, Set nodes)¶ moralizedAncestralGraph(DAGmodel self, Vector_string nodenames) -> UndiGraph
-
names
(InfluenceDiagram self)¶ Returns: The names of the InfluenceDiagram variables Return type: list
-
nodeId
(InfluenceDiagram self, DiscreteVariable var)¶ Parameters: var (pyAgrum.DiscreteVariable) – a variable Returns: the id of the variable Return type: int Raises: gum.IndexError
– If the InfluenceDiagram does not contain the variable
-
nodes
(InfluenceDiagram self)¶ Returns: the set of ids Return type: set
-
nodeset
(GraphicalModel self, Vector_string names)¶
-
parents
(InfluenceDiagram self, int id)¶ Parameters: id – The id of the child node Returns: the set of the parents ids. Return type: set
-
property
(GraphicalModel self, str name)¶
-
propertyWithDefault
(GraphicalModel self, str name, str byDefault)¶
-
saveBIFXML
(InfluenceDiagram self, str name)¶ Save the BayesNet in a BIFXML file.
Parameters: name (str) – the file’s name
-
setProperty
(GraphicalModel self, str name, str value)¶
-
size
(DAGmodel self)¶ Returns: the number of nodes in the graph Return type: int
-
sizeArcs
(DAGmodel self)¶ Returns: the number of arcs in the graph Return type: int
-
toDot
(InfluenceDiagram self)¶ Returns: a friendly display of the graph in DOT format Return type: str
-
topologicalOrder
(DAGmodel self, bool clear=True)¶ Returns: the list of the nodes Ids in a topological order Return type: List Raises: gum.InvalidDirectedCycle
– If this graph contains cycles
-
utility
(InfluenceDiagram self, int varId)¶ utility(InfluenceDiagram self, str name) -> Potential
Parameters: varId (int) – the tested node id. Returns: the utility table of the node Return type: pyAgrum.Potential Raises: gum.IndexError
– If the InfluenceDiagram does not contain the variable
-
utilityNodeSize
(InfluenceDiagram self)¶ Returns: the number of utility nodes Return type: int
-
variable
(InfluenceDiagram self, int id)¶ Parameters: id (int) – the node id Returns: a constant reference over a variabe given it’s node id Return type: pyAgrum.DiscreteVariable Raises: gum.NotFound
– If no variable’s id matches the parameter
-
variableFromName
(InfluenceDiagram self, str name)¶ Parameters: name (str) – a variable’s name Returns: the variable Return type: pyAgrum.DiscreteVariable Raises: gum.IndexError
– If the InfluenceDiagram does not contain the variable
-
variableNodeMap
(GraphicalModel self)¶
Inference¶
-
class
pyAgrum.
ShaferShenoyLIMIDInference
(infDiag: pyAgrum.InfluenceDiagram)¶ This inference considers the provided model as a LIMID rather than an influence diagram. It is an optimized implementation of the LIMID resolution algorithm. However an inference on a classical influence diagram can be performed by adding a assumption of the existence of the sequence of decision nodes to be solved, which also implies that the decision choices can have an impact on the rest of the sequence (Non Forgetting Assumption, cf. pyAgrum.ShaferShenoyLIMIDInference.addNoForgettingAssumption).
-
MEU
(ShaferShenoyLIMIDInference self)¶ MEU(ShaferShenoyLIMIDInference self) -> PyObject *
Returns maximum expected utility obtained from inference.
Raises: gum.OperationNotAllowed
– If no inference have yet been made
-
addEvidence
(ShaferShenoyLIMIDInference self, int id, int val)¶ addEvidence(ShaferShenoyLIMIDInference self, str nodeName, int val) addEvidence(ShaferShenoyLIMIDInference self, int id, str val) addEvidence(ShaferShenoyLIMIDInference self, str nodeName, str val) addEvidence(ShaferShenoyLIMIDInference self, int id, Vector vals) addEvidence(ShaferShenoyLIMIDInference self, str nodeName, Vector vals)
-
addNoForgettingAssumption
(ShaferShenoyLIMIDInference self, vector< int, allocator< int > > ids)¶ addNoForgettingAssumption(ShaferShenoyLIMIDInference self, Vector_string names)
-
chgEvidence
(ShaferShenoyLIMIDInference self, int id, int val)¶ chgEvidence(ShaferShenoyLIMIDInference self, str nodeName, int val) chgEvidence(ShaferShenoyLIMIDInference self, int id, str val) chgEvidence(ShaferShenoyLIMIDInference self, str nodeName, str val) chgEvidence(ShaferShenoyLIMIDInference self, int id, Vector vals) chgEvidence(ShaferShenoyLIMIDInference self, str nodeName, Vector vals)
-
clear
(ShaferShenoyLIMIDInference self)¶
-
eraseAllEvidence
(ShaferShenoyLIMIDInference self)¶ Removes all the evidence entered into the diagram.
-
eraseEvidence
(ShaferShenoyLIMIDInference self, int id)¶ eraseEvidence(ShaferShenoyLIMIDInference self, str nodeName)
Parameters: evidence (pyAgrum.Potential) – the evidence to remove Raises: gum.IndexError
– If the evidence does not belong to the influence diagram
-
hardEvidenceNodes
(ShaferShenoyLIMIDInference self)¶
-
hasEvidence
(ShaferShenoyLIMIDInference self, int id)¶ hasEvidence(ShaferShenoyLIMIDInference self, str nodeName) -> bool
-
hasHardEvidence
(ShaferShenoyLIMIDInference self, str nodeName)¶
-
hasNoForgettingAssumption
(ShaferShenoyLIMIDInference self)¶
-
hasSoftEvidence
(ShaferShenoyLIMIDInference self, int id)¶ hasSoftEvidence(ShaferShenoyLIMIDInference self, str nodeName) -> bool
-
influenceDiagram
(ShaferShenoyLIMIDInference self)¶ Returns a constant reference over the InfluenceDiagram on which this class work.
Returns: the InfluenceDiagram on which this class work Return type: pyAgrum.InfluenceDiagram
-
isSolvable
(ShaferShenoyLIMIDInference self)¶
-
junctionTree
(ShaferShenoyLIMIDInference self)¶
-
makeInference
(ShaferShenoyLIMIDInference self)¶ Makes the inference.
-
meanVar
(ShaferShenoyLIMIDInference self, int node)¶ meanVar(ShaferShenoyLIMIDInference self, str name) -> pair< double,double > meanVar(ShaferShenoyLIMIDInference self, int node) -> PyObject *
-
nbrEvidence
(ShaferShenoyLIMIDInference self)¶
-
nbrHardEvidence
(ShaferShenoyLIMIDInference self)¶
-
nbrSoftEvidence
(ShaferShenoyLIMIDInference self)¶
-
optimalDecision
(ShaferShenoyLIMIDInference self, int decisionId)¶ optimalDecision(ShaferShenoyLIMIDInference self, str decisionName) -> Potential
Returns best choice for decision variable given in parameter ( based upon MEU criteria )
Parameters: decisionId (int,str) – the id or name of the decision variable
Raises: gum.OperationNotAllowed
– If no inference have yet been madegum.InvalidNode
– If node given in parmaeter is not a decision node
-
posterior
(ShaferShenoyLIMIDInference self, int node)¶ posterior(ShaferShenoyLIMIDInference self, str name) -> Potential posterior(ShaferShenoyLIMIDInference self, int var) -> Potential posterior(ShaferShenoyLIMIDInference self, str nodeName) -> Potential
-
posteriorUtility
(ShaferShenoyLIMIDInference self, int node)¶ posteriorUtility(ShaferShenoyLIMIDInference self, str name) -> Potential
-
reducedGraph
(ShaferShenoyLIMIDInference self)¶
-
reducedLIMID
(ShaferShenoyLIMIDInference self)¶
-
reversePartialOrder
(ShaferShenoyLIMIDInference self)¶
-
setEvidence
(evidces)¶ Erase all the evidences and apply addEvidence(key,value) for every pairs in evidces.
Parameters: evidces (dict) – a dict of evidences
Raises: gum.InvalidArgument
– If one value is not a value for the nodegum.InvalidArgument
– If the size of a value is different from the domain side of the nodegum.FatalError
– If one value is a vector of 0sgum.UndefinedElement
– If one node does not belong to the influence diagram
-
softEvidenceNodes
(ShaferShenoyLIMIDInference self)¶
-
updateEvidence
(evidces)¶ Apply chgEvidence(key,value) for every pairs in evidces (or addEvidence).
Parameters: evidces (dict) – a dict of evidences
Raises: gum.InvalidArgument
– If one value is not a value for the nodegum.InvalidArgument
– If the size of a value is different from the domain side of the nodegum.FatalError
– If one value is a vector of 0sgum.UndefinedElement
– If one node does not belong to the Bayesian network
-