Model for Decision in PGM

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(*args)

Add a 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 that will be a chance node.
  • descr (str) – the descr of the variable following fast syntax extended for pyagrum.fastID().
  • nbr_mod_or_id (int) – if the first argument is variable, this set an optional fixed id for the node. If the first argument is descr, this gives the default number of modalities for the variable. Note that if a utility node is described in descr, this value is overriden by 1.
• Returns: the id of the added variable.
• Return type: int
• Raises: pyagrum.DuplicateElement – If already used id or name.

addArc(*args)

Add an arc in the ID, and update diagram’s tensor nodes cpt if necessary.

• Parameters:
  • tail (int | str) – a variable’s id (int) or name
  • head (int | str) – a variable’s id (int) or name
• Raises:
  • pyagrum.InvalidEdge – If arc.tail and/or arc.head are not in the ID.
  • pyagrum.InvalidEdge – If tail is a utility node
• Return type: None

addArcs(listArcs)

add a list of arcs in te model.

• Parameters: listArcs (list *[*tuple *[*int *,*int ] ]) – the list of arcs

addChanceNode(*args)

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: pyagrum.DuplicateElement – If id(<>0) is already used

addDecisionNode(*args)

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: pyagrum.DuplicateElement – If id(<>0) is already used

addStructureListener(whenNodeAdded=None, whenNodeDeleted=None, whenArcAdded=None, whenArcDeleted=None)

Add the listeners in parameters to the list of existing ones.

• Parameters:
  • whenNodeAdded (lambda expression) – a function for when a node is added
  • whenNodeDeleted (lambda expression) – a function for when a node is removed
  • whenArcAdded (lambda expression) – a function for when an arc is added
  • whenArcDeleted (lambda expression) – a function for when an arc is removed

addUtilityNode(*args)

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:
  • pyagrum.InvalidArgument – If variable has more than one label
  • pyagrum.DuplicateElement – If id(<>0) is already used

addVariables(listFastVariables, default_nbr_mod=2)

Add a list of variable in the form of ‘fast’ syntax.

• Parameters:
  • listFastVariables (list *[*str ]) – the list of variables following fast syntax extended for pyagrum.fastID().
  • default_nbr_mod (int) – the number of modalities for the variable if not specified in the fast description. Note that default_nbr_mod=1 is mandatory to create variables with only one modality (for utility for instance).
• Returns: the list of created ids.
• Return type: list[int]

adjacencyMatrix()

adjacency matrix from a graph/graphical models

Compute the adjacency matrix of a pyAgrum’s graph or graphical models (more generally an object that has nodes, children/parents or neighbours methods)

• Returns: adjacency matrix (as numpy.ndarray) with nodeId as key.
• Return type: numpy.ndarray

ancestors(norid)

give the set of nodeid of ancestors of a node

• Parameters: norid (object) – the name or the id of the node
• Returns: the set of ids of the ancestors of node norid.
• Return type: set[int]

arcs()

• Returns: the list of all the arcs in the Influence Diagram.
• Return type: set[tuple[int, int]]

beginTopologyTransformation()

Begin a sequence of structural modifications to the influence diagram.

Structural changes are batched until endTopologyTransformation is called.

• Return type: None

chanceNodeSize()

• Returns: the number of chance nodes.
• Return type: int

changeVariableName(*args)

• Parameters:
  • var (int | str) – a variable’s id (int) or name
  • new_name (str) – the name of the variable
• Raises:
  • pyagrum.DuplicateLabel – If this name already exists
  • pyagrum.NotFound – If no nodes matches id.
• Return type: None

children(norid)

• Parameters:
  • var (int | str) – a variable’s id (int) or name
  • norid (object)
• Returns: the set of all the children
• Return type: set[int]

clear()

Clear the influence diagram, removing all nodes and arcs.

• Return type: None

completeInstantiation()

Give an instantiation over all the variables of the model

• Returns: a complete Instantiation for the model
• Return type: Instantiation

connectedComponents()

Return the weakly connected components of the graph.

Each node is mapped to the id of its component root (an arbitrarily chosen node from the same component).

• Returns: mapping node id → component root id
• Return type: dict[int, int]

SEE ALSO

connectedComponentsList : returns a dict[int, set[int]] grouping nodes by component

connectedComponentsCount : returns the number of components

connectedComponentsCount()

number of connected components

• Returns: the number of connected components in the graph.
• Return type: int

connectedComponentsList()

connected components as a dict of sets

• Returns: dict of connected components (as sets of nodeIds) keyed by an arbitrary root nodeId per component.
• Return type: dict(int, set[int])

cpt(*args)

Returns the CPT of a variable.

• Parameters: var (int | str) – a variable’s id (int) or name
• Returns: The variable’s CPT.
• Return type: Tensor
• Raises: pyagrum.NotFound – If no variable’s id matches varId.

dag()

• Returns: a constant reference to the dag of this BayesNet.
• Return type: DAG

decisionNodeSize()

• Returns: the number of decision nodes
• Return type: int

decisionOrder()

Return the sequence of decision nodes in a valid decision order.

• Returns: the ordered list of decision node ids
• Return type: list[int]
• Raises: pyagrum.NotFound – if no valid decision order exists

decisionOrderExists()

• Returns: True if a directed path exist with all decision node
• Return type: bool

descendants(norid)

give the set of nodeid of descendants of a node

• Parameters: norid (object) – the name or the id of the node
• Returns: the set of ids of the descendants of node norid.
• Return type: set[int]

empty()

Check if there are some variables in the model.

• Returns: True if there is no variable in the model.
• Return type: bool

endTopologyTransformation()

End a sequence of structural modifications and recompute internal structures.

Should be called after beginTopologyTransformation when all modifications are done.

• Return type: None

erase(*args)

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 (int | str | pyagrum.DiscreteVariable) – a variable’s id (int) or name or th reference on the variable to remove.
• Return type: None

eraseArc(*args)

Removes an arc in the ID, and update diagram’s tensor nodes cpt if necessary.

If (tail, head) doesn’t exist, the nothing happens.

• Parameters:
  • arc (pyagrum.Arc) – The arc to be removed whn calling eraseArc(arc)
  • tail (int | str) – a variable’s id (int) or name when calling eraseArc(tail,head)
  • head (int | str) – a variable’s id (int) or name when calling eraseArc(tail,head)
• Return type: None

exists(*args)

Check if a node with this name or id exists

• Parameters: norid (str *|*int) – name or id of the searched node
• Returns: True if there is a node with such a name or id
• Return type: bool

existsArc(*args)

Check if an arc exists

• Parameters:
  • tail (str *|*int) – the name or id of the tail of the arc
  • head (str *|*int) – the name or the id of the head of the arc
• Returns: True if tail->head is an arc.
• Return type: bool

existsPathBetween(*args)

• Returns: true if a path exists between two nodes.
• Return type: bool

existsProperty(name)

Check whether a property key exists in the model’s metadata.

• Parameters: name (str) – the property name
• Returns: True if the property exists
• Return type: bool

family(norid)

give the set of parents of a node and the node

• Parameters: norid (object) – the node
• Returns: the set of nodeId of the family of the node norid
• Return type: set[int]

static fastPrototype(*args)

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 pyagrum.RangeVariable using the default domain size (second argument)
  • with ‘a[10]’, the variable is a pyagrum.RangeVariable using 10 as domain size (from 0 to 9)
  • with ‘a[3,7]’, the variable is a pyagrum.RangeVariable using a domainSize from 3 to 7
  • with ‘a[1,3.14,5,6.2]’, the variable is a pyagrum.DiscretizedVariable using the given ticks (at least 3 values)
  • with ‘a{top|middle|bottom}’, the variable is a pyagrum.LabelizedVariable using the given labels.
  • with ‘a{-1|5|0|3}’, the variable is a pyagrum.IntegerVariable using the sorted given values.
  • with ‘a{-0.5|5.01|0|3.1415}’, the variable is a pyagrum.NumericalDiscreteVariable using the sorted given values.

Notes

• If the dot-like string contains such a specification more than once for a variable, the first specification will be used.
• the tensors (probabilities, utilities) are randomly generated.
• see also pyagrum.fastID.

Examples

>>> import pyagrum as gum
>>> bn=pyagrum.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 or str) – the default domain size or the default domain for variables
• Returns: the resulting Influence Diagram
• Return type: InfluenceDiagram

getDecisionGraph()

• Returns: the temporal Graph.
• Return type: DAG

hasSameStructure(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(name)

Return the node id of a variable given its name.

• Parameters: name (str) – the name of the variable
• Returns: the node id of the variable
• Return type: int
• Raises: pyagrum.NotFound – if no variable with this name exists in the model

ids(names)

List of ids for a list of names of variables in the model

• Parameters:
  • lov (list of str) – List of variable names
  • names (tuple[str, ...])
• Returns: The ids for the list of names of the graph variables
• Return type: list[int]

isChanceNode(*args)

• Parameters: varId (int) – the tested node id.
• Returns: true if node is a chance node
• Return type: bool

isDecisionNode(*args)

• Parameters: varId (int) – the tested node id.
• Returns: true if node is a decision node
• Return type: bool

isIndependent(*args)

check if nodes X and nodes Y are independent given nodes Z

• Parameters:
  • X (str *|*int *|*list of str *|*int) – a list of of nodeIds or names
  • Y (str *|*int *|*list of str *|*int) – a list of of nodeIds or names
  • Z (str *|*int *|*list of str *|*int) – a list of of nodeIds or names
• Raises: InvalidArgument – if X and Y share variables
• Returns: True if X and Y are independent given Z in the model
• Return type: bool

isUtilityNode(*args)

• Parameters: varId (int) – the tested node id.
• Returns: true if node is an utility node
• Return type: bool

loadBIFXML(*args)

Load a BIFXML file.

• Parameters: name (str) – the name’s file
• Raises:
  • pyagrum.IOError – If file not found
  • pyagrum.FatalError – If file is not valid
• Return type: bool

loadGUM(name, binary=False)

Load a jgum (JSON) or bgum (binary/msgpack) file.

• Parameters:
  • name (str) – the file’s path (extension: .jgum for JSON, .bgum for binary)
  • binary (bool) – if True, read as bgum (msgpack) regardless of extension (default: False)
• Raises:
  • pyagrum.IOError – If file not found
  • pyagrum.FatalError – If file content is not valid

SEE ALSO

JGUM / BGUM Format Reference : complete format reference

• Return type: None

loadGUMstring(content)

Deserialize an InfluenceDiagram from a jgum JSON string.

• Parameters: content (str) – a JSON string in jgum format
• Raises: pyagrum.FatalError – If the string is not valid jgum JSON or the type field does not match "ID"

SEE ALSO

JGUM / BGUM Format Reference : complete format reference

• Return type: None

log10DomainSize()

returns the log10 of the domain size of the model defined as the product of the domain sizes of the variables in the model.

• Returns: the log10 domain size.
• Return type: float

minimalCondSet(*args)

Return a minimal conditioning set of a target node (or set of nodes) given a set of source nodes in the DAG model.

A minimal conditioning set is a subset of the source nodes that d-separates the targets from the remaining sources.

• Parameters:
  • target (int | str | list *[*int *|*str ]) – the target node id(s) or name(s)
  • soids (list *[*int *|*str ]) – the list of source node ids or names
• Returns: the minimal conditioning set (as node ids)
• Return type: list[int]

moralGraph()

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: UndiGraph

moralizedAncestralGraph(nodes)

build a UndiGraph by moralizing the Ancestral Graph of a list of nodes

• Parameters: nodes (object) – the list of of nodeIds or names

Warning

pyagrum.UndiGraph only knows NodeId. Hence the moralized ancestral graph does not include the names of the variables.graph

• Returns: the moralized ancestral graph of the nodes
• Return type: UndiGraph

names()

• Returns: The names of the InfluenceDiagram variables
• Return type: set[str]

nodeId(var)

Return the node id of a variable.

• Parameters: var (DiscreteVariable) – the variable
• Returns: the node id of the variable
• Return type: int
• Raises: pyagrum.NotFound – if the variable does not exist in the model

nodes()

• Returns: the set of ids
• Return type: set[int]

nodeset(names)

Set of ids for a list of names of variables in the model

• Parameters:
  • lov (list of str) – List of variable names
  • names (tuple[str, ...])
• Returns: The set of ids for the list of names of the graph variables
• Return type: list[int]

parents(norid)

• Parameters:
  • var (int | str) – a variable’s id (int) or name
  • norid (object)
• Returns: the set of the parents ids.
• Return type: set[int]

properties()

Return the keys of all metadata properties of the model.

• Returns: tuple of property names (use property() to retrieve a value by key)
• Return type: tuple[str, ...]

saveBIFXML(name)

Save the BayesNet in a BIFXML file.

• Parameters: name (str) – the file’s name
• Return type: None

saveGUM(name, binary=False, indent=None)

Save the influence diagram as a .jgum (text) or .bgum (binary) file.

• Parameters:
  • name (str) – the name of the file
  • binary (bool) – if True, save in the msgpack-based .bgum binary format instead of the JSON-based .jgum text format
  • indent (int) – JSON indentation for the .jgum text format (ignored if binary=True): -1 for the most compact output, N>=0 to pretty-print with N spaces. Defaults to pyagrum.config["core","default_jgumIndent"].
• Return type: None

saveGUMstring(indent=None)

Save the influence diagram as a jgum string.

• Parameters: indent (int) – JSON indentation: -1 for the most compact output, N>=0 to pretty-print with N spaces. Defaults to pyagrum.config["core","default_jgumIndent"].
• Returns: the jgum string
• Return type: str

size()

• Returns: the number of nodes in the graph
• Return type: int

sizeArcs()

• Returns: the number of arcs in the graph
• Return type: int

static spaceCplxToString(dSize, dim, usedMem)

Return a human-readable string summarising the space complexity of a graphical model.

• Parameters:
  • dSize (float) – log10 of the joint domain size
  • dim (int) – number of independent parameters
  • usedMem (int) – memory footprint in bytes
• Returns: a string of the form 'domainSize: X, dim: Y, mem: Z'
• Return type: str

property thisown

The membership flag

toDot()

• Returns: a friendly display of the graph in DOT format
• Return type: str

toFast(filename=None)

Export the influence Diagram as fast syntax (in a string or in a python file)

• Parameters: filename (str) – the name of the file (including the prefix), if None , use sys.stdout
• Return type: str

topologicalOrder()

• Returns: the list of the nodes Ids in a topological order
• Return type: list[int]
• Raises: pyagrum.InvalidDirectedCycle – If this graph contains cycles

updateMetaData()

Update the model’s built-in metadata (version, creation date, last modification date).

This method is called automatically by writers before saving the model to a file.

• Return type: None

utility(*args)

• Parameters: var (int | str) – a variable’s id (int) or name
• Returns: the utility table of the node
• Return type: Tensor
• Raises: pyagrum.IndexError – If the InfluenceDiagram does not contain the variable

utilityNodeSize()

• Returns: the number of utility nodes
• Return type: int

variable(*args)

• Parameters: id (int) – the node id
• Returns: a constant reference over a variabe given it’s node id
• Return type: DiscreteVariable
• Raises: pyagrum.NotFound – If no variable’s id matches the parameter

variableFromName(name)

Return the variable with the given name.

• Parameters: name (str) – the name of the variable
• Returns: the variable
• Return type: DiscreteVariable
• Raises: pyagrum.NotFound – if no variable with this name exists in the model

variableNodeMap()

Return the variable-to-node mapping of the model.

• Returns: the internal variable-to-node bijection
• Return type: pyagrum.VariableNodeMap

variables(*args)

Return the set of variables corresponding to a list of names or a set of node ids.

• Parameters: args (list *[*str ] or set *[*int ]) – variable names or node ids
• Returns: the set of corresponding variables
• Return type: pyagrum.VariableSet