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>i : starting node <V_name>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 (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

asTensor()

• Returns: a copy of the internal tensor
• Return type: pyagrum.Tensor

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.

getTensor()

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

instantiation()

• Returns: An Instantiation object using the CIM’s tensor.
• 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 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