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.Tensor 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.Tensor | None) – Defines the new CIM using existing tensor.

DELIMITER = '#'

add(v)

Add a new variable to the CIM.

Parameters:: v (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

asTensor()

Returns:: a copy of the internal tensor
Return type:: Tensor

extract(ctxt)

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

Parameters:: ctxt (dict[str, str] | None) – 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:: None | DiscreteVariable

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.
Return type:: None

getTensor()

Returns:: A copy of the CIM’s tensor
Return type:: Tensor

instantiation()

Returns:: An Instantiation object using the CIM’s tensor.
Return type:: 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 (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 (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 (dict[str, str] | None) – Instantiation of variables to use if given.
Returns:: The CIM as a numpy.array.
Return type:: 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 (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:: DiscreteVariable

variablesSequence()

Returns:: A list containing the sequence of variables of the CIM.
Return type:: list[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. Node names are registered via setName/idFromName.

Type:: pyagrum.DiGraph

_cim

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

Type:: dict[int, CIM]

_id2var

Dict containing the variable associated to a node id.

Type:: dict[int, pyagrum.DiscreteVariable]

CIM(val)

Parameters:: val (str | int) – 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 (DiscreteVariable) – The variable to add to the CTBN.

Returns:

The id given to the variable.

Return type:

int

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 (str | int) – The name or id of the first variable.
val2 (str | int) – The name or id of the second variable.

Returns:

The created arc (val1, val2).

Return type:

tuple[int, int]

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[int, int]]

children(val)

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

childrenNames(val)

Parameters:: val (str | int) – 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:: 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 (str | int) – The name or id of the first variable.
val2 (str | int) – 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.

Return type:

None

fullInstantiation()

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

labels(val)

Parameters:: val (str | int) – 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 (int) – The id of the variable.
Returns:: The variable’s name linked to the int.
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:: int
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[int]

parentNames(val)

Parameters:: val (str | int) – 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 (str | int) – The variable’s name or id.
Returns:: A set containing the id of the variable’s parents in the CTBN.
Return type:: set[int]
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 (str | int) – The name or id of the variable.
Returns:: The corresponding variable.
Return type:: 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[DiscreteVariable]

Other functions for CTBN model

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