# The CTBN model

A CTBN is :
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 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:
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:
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]

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

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

name(node)
Parameters:

node (NodeId) – The id of the variable.

Returns:

The variable’s name linked to the NodeId.

Return type:

str

Raises:

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:

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:

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