The CTBN model
A CTBN is :
: - A bayesian network with pyagrum.DiscreteVariable random variables.
- A
pyagrum.DiGraphto represents dependency between random variables. The model allows cycles. - A
pyagrum.ctbn.CIMcontaining exponential distribution parameters for each variable describing its transition duration.
A CIM is : : - A Conditional Intensity Matrix. The CIM of a variable contains at least two variables and , from/to states.
- Diagonal coefficients .
- ~ and ~ , waiting time before going from state i to state j (resp. before leaving state i).
Properties : : -
class pyagrum.ctbn.CIM(pot=None)
Section titled “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>
- Parameters: pot (pyagrum.Tensor | None) – Defines the new CIM using existing tensor.
DELIMITER = ’#‘
Section titled “DELIMITER = ’#‘”Add a new variable to the CIM.
- Parameters:
v (
DiscreteVariable) – Variable to add. - Returns: A reference to the CIM.
- Return type:
CIM
amalgamate(cimY: CIM) → CIM
Section titled “amalgamate(cimY: CIM) → CIM”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
asTensor() → Tensor
Section titled “asTensor() → Tensor”- Returns: a copy of the internal tensor
- Return type:
Tensor
extract(ctxt: dict[str, str] | None) → CIM
Section titled “extract(ctxt: dict[str, str] | None) → CIM”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: str) → None | DiscreteVariable
Section titled “findVar(name: str) → None | DiscreteVariable”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) → None
Section titled “fromMatrix(mat) → None”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() → Tensor
Section titled “getTensor() → Tensor”- Returns: A copy of the CIM’s tensor
- Return type:
Tensor
instantiation() → Instantiation
Section titled “instantiation() → Instantiation”- Returns: An Instantiation object using the CIM’s tensor.
- Return type:
Instantiation
isIM() → bool
Section titled “isIM() → bool”- Returns: True if there is no conditioning variable (parent) in the CIM.
- Return type:
bool
static isParent(v: DiscreteVariable) → bool
Section titled “static isParent(v: DiscreteVariable) → bool”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() → int
Section titled “nbrDim() → int”- Returns: The number of variables in the CIM (including v_i and v_j variables).
- Return type:
int
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: dict[str, str] | None = None) → array
Section titled “toMatrix(ctxt: dict[str, str] | None = None) → array”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: str) → str
Section titled “static varI(name: str) → str”- 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: str) → str
Section titled “static varJ(name: str) → str”- 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
Section titled “property varNames”- Returns: A list containing the name of each variable in the CIM.
- Return type: list[str]
static varRadical(v: DiscreteVariable) → str
Section titled “static varRadical(v: DiscreteVariable) → str”- Parameters:
v (
DiscreteVariable) – Variable to get name from. - Returns:
The name of the variable (without
DELIMITERformatting). - Return type:
str
variable(arg: int) → DiscreteVariable
Section titled “variable(arg: int) → DiscreteVariable”- 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() → list[DiscreteVariable]
Section titled “variablesSequence() → list[DiscreteVariable]”- Returns: A list containing the sequence of variables of the CIM.
- Return type:
list[DiscreteVariable]
class pyagrum.ctbn.CTBN
Section titled “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
Section titled “_graph”Graph representing dependency relations between variables. Node names are registered via setName/idFromName.
- Type: pyagrum.DiGraph
Dict containing a CIM for each nodeId(the integer given to a variable).
- Type: dict[int, CIM]
_id2var
Section titled “_id2var”Dict containing the variable associated to a node id.
- Type: dict[int, pyagrum.DiscreteVariable]
CIM(val)
Section titled “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 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: str | int, val2: str | int) → tuple[int, int]
Section titled “addArc(val1: str | int, val2: str | int) → tuple[int, int]”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.
- val1 (
- Returns:
The created arc (
val1,val2). - Return type:
tuple[int,int] - Raises: pyagrum.NotFound – If one the variables is not in the CTBN.
arcs() → set[tuple[int, int]]
Section titled “arcs() → set[tuple[int, int]]”- Returns: The set of arcs as a set of couple of NodeIds in the CTBN.
- Return type:
set[tuple[int,int]]
children(val: str | int) → set[int]
Section titled “children(val: str | int) → set[int]”- 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: str | int) → list[str]
Section titled “childrenNames(val: str | int) → list[str]”- 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() → Instantiation
Section titled “completeInstantiation() → Instantiation”- Returns: An instantiation of the variables in the CTBN.
- Return type:
Instantiation
equals(ctbn: CTBN) → bool
Section titled “equals(ctbn: CTBN) → bool”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: str | int, val2: str | int) → None
Section titled “eraseArc(val1: str | int, val2: str | int) → None”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.
- val1 (
- 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() → Instantiation
Section titled “fullInstantiation() → Instantiation”- 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: str | int) → tuple
Section titled “labels(val: str | int) → tuple”- 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: int) → str
Section titled “name(node: int) → str”- 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() → list[str]
Section titled “names() → list[str]”- Returns: The list of variables name in the CTBN.
- Return type:
list[str]
node(name: str) → int
Section titled “node(name: str) → int”- 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() → list[int]
Section titled “nodes() → list[int]”- Returns: The list of variables id in the CTBN.
- Return type:
list[int]
parentNames(val: str | int) → list[str]
Section titled “parentNames(val: str | int) → list[str]”- 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: str | int) → set[int]
Section titled “parents(val: str | int) → set[int]”- 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() → str
Section titled “toDot() → str”Create a display of the graph representating the CTBN.
- Returns: A display of the graph.
- Return type:
str
variable(val: str | int) → DiscreteVariable
Section titled “variable(val: str | int) → DiscreteVariable”- 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() → list[DiscreteVariable]
Section titled “variables() → list[DiscreteVariable]”- Returns: The list of variables in the CTBN.
- Return type:
list[DiscreteVariable]
Other functions for CTBN model
Section titled “Other functions for CTBN model”pyagrum.ctbn.randomCTBN(valueRange, n=1, parMax=1, modal=2)
Section titled “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).
- valueRange (
- Returns: A randomly generated ctbn.
- Return type:
CTBN