The CTBN model

A CTBN is :

A bayesian network with pyAgrum.DiscreteVariable random variables.
A pyAgrum.DiGraph to represents dependency between random variables. The model allows cycles.
A pyAgrum.ctbn.CIM containing exponential distribution parameters for each variable describing its transition duration.

A CIM is :

A Conditional Intensity Matrix. The CIM of a variable \(X\) contains at least two variables \(X_i\) and \(X_j\), from/to states.
Diagonal coefficients \(q_{i,j}\).
\(D_{i,j}\) ~ \(exp(q_{i,j})\) and \(D_i\) ~ \(exp(\sum_jq_{i,j})\), waiting time before going from state i to state j (resp. before leaving state i).

Properties :

\(P_X(x_1\rightarrow x_2) = \frac{q_{i,j}}{q_i}\)
\(\mathbb{E}(D_{i,j}) = \frac{1}{q_{i,j}}\)
\(\forall i \sum_{j}q_{i,j} = 0\)

class pyAgrum.ctbn.CIM(pot=None)

This class is used to represent a CIM (random variables and parameters of transition time). A CIM is mainly a pyAgrum.Potential that contains the parameters of an exponential distribution. This class contains also contains the amalgamation operator, used for merging CIMs into one.

Notes

A static string DELIMITER is used to differentiate between the current state of the variable and its next state. <V_name><DELIMITER>i : starting node <V_name><DELIMITER>j : ending node

Parameters:: pot (pyAgrum.Potential | None) – Defines the new CIM using existing potential.

DELIMITER = '#'

add(v)

Add a new variable to the CIM.

Parameters:: v (pyAgrum.DiscreteVariable) – Variable to add.
Returns:: A reference to the CIM.
Return type:: CIM

amalgamate(cimY)

Amalgamation of 2 CIMs, i.e combine 2 CIMs into one. When manipulating CIMs * can be used instead.

Parameters:

cimY (CIM) – CIM to amalgamate self with.
self (CIM)

Returns:

Amalgamation of the CIMs.

Return type:

CIM

asPotential()

Returns:: a copy of the internal potential
Return type:: pyAgrum.Potential

extract(ctxt)

Creates a new CIM extracted from the current CIM using the instantiation ctxt.

Parameters:: ctxt (Optional[Dict[str, str]]) – Instantiation of variables.
Returns:: The extracted CIM.
Return type:: CIM

findVar(name)

Finds a variable in the CIM using its name.

Parameters:: name (str) – Name of the variable to find.
Returns:: The variable if it is in the CIM.
Return type:: pyAgrum.DiscreteVariable | None

fromMatrix(mat)

Fills the CIM with matrix mat.

Notes

Only works for square-shaped matrixes, if the CIM is not conditional.

Parameters:: mat (numpy.array) – Matrix to convert into a CIM.

getPotential()

Returns:: A copy of the CIM’s potential
Return type:: pyAgrum.Potential

instantiation()

Returns:: An Instantiation object using the CIM’s potential.
Return type:: pyAgrum.Instantiation

isIM()

Returns:: True if there is no conditioning variable (parent) in the CIM.
Return type:: bool

static isParent(v)

Uses the syntax convention to check if a variable’s name is the name of a parent in the CIM.

Parameters:: v (pyAgrum.DiscreteVariable) – Variable to check.
Returns:: True if v’s name corresponds to the name of a parent in the CIM.
Return type:: bool

nbrDim()

Returns:: The number of variables in the CIM (including v_i and v_j variables).
Return type:: int

remove(v)

Removes a variable from the CIM. Only for parent variables.

Parameters:

v (pyAgrum.DiscreteVariable) – Variable to remove.

Returns:

A reference to the CIM.

Return type:

CIM

Raises:

pyAgrum.NotFound – If the variable isn’t in the CIM.
pyAgrum.InvalidArgument – If the variable isn’t a parent in the CIM.

toMatrix(ctxt=None)

Converts a CIM to a numpy.array matrix.

Notes

Only works for CIMs with no conditioning variable, or CIMs obtained through amalgamation.

Parameters:: ctxt (Optional[Dict[str, str]] | None) – Instantiation of variables to use if given.
Returns:: The CIM as a numpy.array.
Return type:: numpy.array

static varI(name)

Parameters:: name (str) – Name of the variable to format.
Returns:: The name of the variable using {name}{DELIMITER}i format.
Return type:: str

static varJ(name)

Parameters:: name (str) – Name of the variable to format.
Returns:: The name of the variable using {name}{DELIMITER}j format.
Return type:: str

property varNames

Returns:: A list containing the name of each variable in the CIM.
Return type:: List[str]

static varRadical(v)

Parameters:: v (pyAgrum.DiscreteVariable) – Variable to get name from.
Returns:: The name of the variable (without DELIMITER formatting).
Return type:: str

variable(arg)

Parameters:: arg (int) – Index of the variable in the CIM (i.e its node id).
Returns:: The variable at index arg.
Return type:: pyAgrum.DiscreteVariable

variablesSequence()

Returns:: A list containing the sequence of variables of the CIM.
Return type:: List[pyAgrum.DiscreteVariable]

class pyAgrum.ctbn.CTBN

This class is used to represent a CTBN. A CTBN is : a set of random variables, a CIM for each one of them and a pyAgrum.DiGraph to represent dependency relations.

_graph

Graph representing dependency relations between variables. Also used to link a variable with an id.

Type:: pyAgrum.DiGraph

_cim

Dict containing a CIM for each nodeId(the integer given to a variable).

Type:: Dict[NodeId, CIM]

_id2var

Dict containing the variable associated to a node id.

Type:: Dict[NodeId, pyAgrum.DiscreteVariable]

_name2id

Dict containing the nodeId associated to a variable’s name.

Type:: Dict[str, NodeId]

CIM(val)

Parameters:: val (NameOrId) – The variable’s name or id.
Returns:: The variable’s CIM.
Return type:: CIM
Raises:: pyAgrum.NotFound – If the variable isn’t in the CTBN.

add(var)

Add a new variable to the Ctbn.

Parameters:

var (pyAgrum.DiscreteVariable) – The variable to add to the CTBN.

Returns:

The id given to the variable.

Return type:

NodeId

Raises:

NameError – If a variable with the same name already exists.
ValueError – If the variable is None.

addArc(val1, val2)

Adds an arc val1 -> val2.

Parameters:

val1 (NameOrId) – The name or id of the first variable.
val2 (NameOrId) – The name or id of the second variable.

Returns:

The created arc (val1, val2).

Return type:

Tuple[NodeId, NodeId]

Raises:

pyAgrum.NotFound – If one the variables is not in the CTBN.

arcs()

Returns:: The set of arcs as a set of couple of NodeIds in the CTBN.
Return type:: Set[Tuple[NodeId, NodeId]]

children(val)

Parameters:: val (NameOrId) – The variable’s name or id.
Returns:: A set containing the ids of the variable’s children.
Return type:: Set[NodeId]
Raises:: pyAgrum.NotFound – If the variable isn’t in the CTBN.

childrenNames(val)

Parameters:: val (NameOrId) – The variable’s name or id.
Returns:: A list containing the names of a variable’s children.
Return type:: List[str]
Raises:: pyAgrum.NotFound – If the variable isn’t in the CTBN.

completeInstantiation()

Returns:: An instantiation of the variables in the CTBN.
Return type:: pyAgrum.Instantiation

equals(ctbn)

Tests the topologic equality with another CTBN.

Parameters:: ctbn (CTBN) – CTBN to test equality with.
Returns:: True if they are equal, False if not.
Return type:: bool

eraseArc(val1, val2)

Erases an arc from the graph.

Parameters:

val1 (NameOrId) – The name or id of the first variable.
val2 (NameOrId) – The name or id of the second variable.

Raises:

pyAgrum.NotFound – If a variable isn’t in the CIM.
pyAgrum.InvalidArgument – If a variable isn’t a parent in the CIM.

fullInstantiation()

Returns:: An instantiation of the variables in the CTBN including the corresponding starting and ending (i.e from/to variables) variables.
Return type:: pyAgrum.Instatiation

labels(val)

Parameters:: val (NameOrId) – The name or id of the variable.
Returns:: A tuple containing the labels of the variable.
Return type:: tuple
Raises:: pyAgrum.NotFound – If the variable is not found in the CTBN.

name(node)

Parameters:: node (NodeId) – The id of the variable.
Returns:: The variable’s name linked to the NodeId.
Return type:: str
Raises:: pyAgrum.NotFound – If the variable is not found in the CTBN.

names()

Returns:: The list of variables name in the CTBN.
Return type:: List[str]

node(name)

Parameters:: name (str) – The name of the variable.
Returns:: The id of the variable.
Return type:: NodeId
Raises:: pyAgrum.NotFound – If the variable is not found in the CTBN.

nodes()

Returns:: The list of variables id in the CTBN.
Return type:: List[NodeId]

parentNames(val)

Parameters:: val (NameOrId) – The variable’s name or id.
Returns:: A list containing the names of the variable’s parents.
Return type:: List[str]
Raises:: pyAgrum.NotFound – If the variable isn’t in the CTBN.

parents(val)

Parameters:: val (NameOrId) – The variable’s name or id.
Returns:: A set containing the id of the variable’s parents in the CTBN.
Return type:: Set[NodeId]
Raises:: pyAgrum.NotFound – If the variable isn’t found in the CTBN.

toDot()

Create a display of the graph representating the CTBN.

Returns:: A display of the graph.
Return type:: str

variable(val)

Parameters:: val (NameOrId) – The name or id of the variable.
Returns:: The corresponding variable.
Return type:: pyAgrum.DiscreteVariable
Raises:: pyAgrum.NotFound – If the variable is not found in the CTBN.

variables()

Returns:: The list of variables in the CTBN.
Return type:: List[pyAgrum.DiscreteVariable]

Other functions

pyAgrum.ctbn.randomCTBN(valueRange, n=1, parMax=1, modal=2)

Generates a random CTBN using Prufer’s sequence. Note : as diagonal coefficents are the negative sum of the coefficients one the line in a CIM, their value does not necessarily belong to valueRange.

Parameters:

valueRange (Tuple[float, float]) – Range to choose values from when filling the CIMs.
n (int) – Number of variables.
parMax (int) – Maximum number of parents a variable can have.
modal (int) – Number of states a variable has (domain size).

Returns:

A randomly generated ctbn.

Return type:

CTBN