# Learning a CTBN

One of the main features of this library is the possibility to learn a CTBN.

More precisely what can be learned is :
• The dependency graph of a CTBN

• The CIMs of a CTBN

• (The variables and their labels from a sample)

Tools to extract data from samples are necessary. This is the role of class pyAgrum.ctbn.Trajectory and function pyAgrum.ctbn.CTBNFromData().

Before introducing the algorithms, here are the following definitions :
• $$M_{xx'|u}$$ is the number of time a variable X go from a state x to a state x’, conditioned by an instance of its parents u. It is filled using samples.

• $$M_{x|u}$$ is the number of time X goes to state x.

• $$T_{x|u}$$ is the time spent in state x, conditioned by an instance of its parents u.

• $$M_{xx'|y,u}$$ and $$T_{x|y,u}$$ are the same but with another conditioning variable Y in state y.

Those can be stored in pyAgrum.Potential.

Being conditioned by an instance means that the extracted data comes from time intervals where conditioning variables take specific values.

## Learning parameters : learning the CIMs

Goal : finding the $$q_{i,j|u}$$ (i.e $$q_{x|u}$$ and $$q_{x \rightarrow x'|u}$$) coefficients.

Idea : $$q_{x|u}$$ = $$\frac{M_{x|u}}{T_{x|u}}$$; $$P_X(x\rightarrow x') = \frac{M_{x \rightarrow x'|u}}{M_{x|u}} = \frac{q_{x \rightarrow x'|u}}{q_{x|u}}$$ Then $$q_{x \rightarrow x'|u} = \frac{M_{x \rightarrow x'|u}}{T_{x|u}}$$

## Learning the graph

To learn the graph of a CTBN (ie the dependence between variables) we use the CTPC algorithm from A. Bregoli, M. Scutari, F. Stella, Constraint-Based Learning for Continuous-Time Bayesian Networks, arXiv:2007.03248, 2020. The independence test used is based on Fisher and chi2 tests to compare exponential distributions.

class pyAgrum.ctbn.Learner(source)

Class used to learn a CTBN (independence between variables and CIMs) using samples.

Parameters:

source (str|Dict[int, List[Tuple[float, str, str]]]) – Path to the csv file containing the samples(trajectories). Or directly the trajectories in a python dict.

fitParameters(ctbn)

Learns the parameters of ctbn’s CIMs.

Parameters:

ctbn (CTBN) – CTBN containing the CIMs to learn.

learnCTBN(template=None)

Learns a CTBN, using the CTPC(continuous-time PC) algorithm. Reference : A. Bregoli, M. Scutari, F. Stella, Constraint-Based Learning for Continuous-Time Bayesian Networks, arXiv:2007.03248, 2020.

Parameters:

template (CTBN) – CTBN used to find variables. If not given, variables are searched inside the trajectories. (if the trajectory is very short, some variables can be missed).

Returns:

The learned ctbn.

Return type:

CTBN

Reads trajectories from a csv file. Storing format : {IdSample, time, var, state}

Parameters:

filename (str) – Path to the file.

Returns:

The trajectories, a trajectory for every index.

Return type:

Dict[int, List[Tuple[float, str, str]]]

pyAgrum.ctbn.CTBNFromData(data)

Constructs a CTBN and add the corresponding variables found in the trajectories.

Warning

If data is too short, some variables or state labels might be missed.

Parameters:

data (Dict[int, List[Tuple[float, str, str]]]) – The trajectories used to look for variables.

Returns:

The resulting CTBN.

Return type:

CTBN

pyAgrum.ctbn.computeCIMFromStats(X, M, T)

Computes a CIM (Conditional Intensity Matrix) using stats from a trajectory. Variables in the potential are not copied but directly used in the result to avoid memory issues.

Parameters:
• X (str) – Name of the variable to compute CIM for.

• M (pyAgrum.Potential) – Potential containing the number of transitions for each pair of X’s states.

• T (pyAgrum.Potential) – Potential containing the time spent to transition from every state of X.

Returns:

The resulting potential, X’s CIM.

Return type:

pyAgrum.Potential

class pyAgrum.ctbn.Trajectory(source, ctbn=None)

Tools to extract useful informations from a trajectory. It is used for parameters/graph learning. It can be created from a trajectory (a dict of trajectories) or from a file that contains one.

Parameters:
• source (str|Dict[int, List[Tuple[float, str, str]]]) – The path to a csv file containing the samples or the dict of trajectories itself.

• ctbn (CTBN) – To link the variables’s name in the trajectory to their pyAgrum variable. If not given, a new CTBN is created with the variables and labels found in the trajectory. (warning : if the trajectory is short, all of the variables may not be found correctly).

data

The samples.

Type:

Dict[int, List[Tuple[float, str, str]]]

ctbn

The CTBN used to link the names in the trajectory to pyAgrum variables.

Type:

CTBN

timeHorizon

The time length of the trajectory.

Type:

float

computeAllCIMs()

Computes the CIMs of the variables in self.ctbn. Conditioning is given by the graph of self.ctbn.

computeStats(X, U)

Computes time spent and number of transitions values of X and returns them as pyAgrum.Potential.

Parameters:
• X (str) – Name of the variable.

• U (List[str]) – List of conditioning variable’s name.

Returns:

The resulting potentials.

Return type:
computeStatsForTests(X, Y, U)

Computes time spent and number of transitions values of X when conditioned by Y and U and returns them as pyAgrum.Potential. Used for independence testing.

Parameters:
• X (str) – Name of the variable.

• Y (str) – Name of a conditioning variable not in U.

• U (List[str]) – List of conditioning variable’s name.

Returns:

The resulting potentials.

Return type:
setStatValues(X, inst_u, Txu, Mxu)

Fills the potentials given.

Parameters:
• X (str) – Name of the variable.

• inst_u (Dict[str, str]) – Instance of conditioning variables.

• Txu (pyAgrum.Potential) – Potential to fill. Contains the time spent in each state.

• Mxu (pyAgrum.Potential) – Potential to fill. Contains the number of transitions from any pair of states.

setStatsForTests(X, Y, inst_u, Txu, Txyu, Mxyu)

Fills the potentials given. They are used for independence testing.

Parameters:
• X (str) – Name of the variable.

• Y (str) – Name of a conditioning variable.

• inst_u (Dict[str, str]) – Instance of conditioning variables.

• Txu (pyAgrum.Potential) – Potential to fill. Contains the time spent in each state. Conditioned by variables in inst_u.

• Txyu (pyAgrum.Potential) – Potential to fill. Contains the time spent in each state. Conditioned by Y and variables in inst_u.

• Mxyu (pyAgrum.Potential) – Potential to fill. Contains the number of transitions from any pair of states. Conditioned by Y and variables in inst_u.

class pyAgrum.ctbn.Stats(trajectory, X, Y, par)

Stores all potentials used for learning.

Parameters:
• trajectory (Trajectory) – Samples used to find stats.

• X (str) – Name of the variable to study.

• Y (str) – Name of the variable used for conditioning variable X.

• par (List[str]) – List of conditioning variables of X.

Mxy

Potential containing the number of transitions the variable X does from any of its states for any instance of its parents and variableY.

Type:

pyAgrum.Potential

Mx

Potential containing the number of transitions the variable X does from any of its states for any instance of its parents.

Type:

pyAgrum.Potential

Tx

Potential containing the time spent by X to transition from a state to another for any instance of its parents.

Type:

pyAgrum.Potential

Txy

Potential containing the time spent by X to transition from a state to another for any instance of its parents and of Y.

Type:

pyAgrum.Potential

Qx

Conditional Intensity Matrix(CIM) of X.

Type:

pyAgrum.Potential

QxY

Conditional Intensity Matrix(CIM) of X that includes the conditioning variable Y.

Type:

pyAgrum.Potential

class pyAgrum.ctbn.StatsIndepTest.FChi2Test(tr)

Bases: IndepTest

This class use 2 independence tests : Fisher Test (F-test) and chi2 Test. To test independence between 2 variables, we first consider them independent. There is independence until one of the 2 tests (F and chi2) contradict the independence hypothesis. If the hyopothesis is not rejected, the variables are considered independent.

Parameters:

tr (Trajectory) – Samples used to extract stats.

Saves variables X and Y and the conditioning set U, and generates stats to be used in statistical tests.

Parameters:
• X (str) – Name of the variable.

• Y (str) – Name of the variable to test independence from, not in U.

• U (List[str]) – List of conditioning variables.

computeChi2()

Compute chi2-test value for every instance of the variables.

Returns:

chi2-test value.

Return type:

pyAgrum.Potential

computeF()

Compute F-test value for every instance of the variables.

Returns:

F-test value.

Return type:

pyAgrum.Potential

getMxxGivenU(M, Y)
Parameters:
• M (pyAgrum.Potential) – A matrix M_{x, x’ | y, U}, for some instantiation U of the conditioning set and y of a specific parent.

• Y (str) – A parent.

Returns:

The potential M_{x, x’ | U} by summing over all values of y.

Return type:

pyAgrum.Potential

nullStateToStateTransitionHypothesisChi2(X, Y, _)

Decides if the null state to state transition hypothesis is rejected using chi2-test.

Parameters:
• X (str) – A random variable.

• Y (str) – A parent of X.

• _ (List[str]) – A subset of the parents of X that does not contain Y.

• _

Returns:

False if X is not independent of Y given the conditioning set U.

Return type:

bool

nullTimeToTransitionHypothesisF(X, Y, _)

Decides if the null time to transition hypothesis is rejected using F-test.

Parameters:
• X (str) – A random variable.

• Y (str) – A parent of X.

• _ (List[str]) – A subset of the parents of X that does not contain Y.

• _

Returns:

False if X is not independent of Y given the conditioning set U.

Return type:

bool

testIndep(X, Y, U)
Parameters:
• X (str) – Name of the variable.

• Y (str) – Name of the variable to test independence from, not in U.

• U (List[str]) – List of conditioning variables.

Returns:

true if X is independent to Y given U, otherwise false.

Return type:

bool

class pyAgrum.ctbn.StatsIndepTest.IndepTest

Bases: object

Mother class used to test independance between 2 variables knowing some other parents.

abstract testIndep(X, Y, U)
Parameters:
• X (str) – Head of the arc we want to test.

• Y (str) – Tail of the arc we want to test.

• U (List[str]) – Known parents.

Return type:

bool

class pyAgrum.ctbn.StatsIndepTest.Oracle(ctbn)

Bases: IndepTest

Oracle’s testing tools.

Parameters:

ctbn (CTBN)

testIndep(X, Y, U)
Parameters:
• X (str) – Head of the arc we want to test.

• Y (str) – Tail of the arc we want to test.

• U (List[str]) – Known parents.

Returns:

False if there is an arc from Y to X knowing U, True otherwise.

Return type:

bool

pyAgrum.ctbn.StatsIndepTest.sqrtPotential(potential)

Applies sqrt function to all values inside the potential.

Parameters:

potential (pyAgrum.Potential) – potential to play sqrt to.

Returns:

sqrt of potential.

Return type:

pyAgrum.Potential