Credal Network¶
Credal networks are probabilistic graphical models based on imprecise probability. Credal networks can be regarded as an extension of Bayesian networks, where credal sets replace probability mass functions in the specification of the local models for the network variables given their parents. As a Bayesian network defines a joint probability mass function over its variables, a credal network defines a joint credal set (from Wikipedia).
Tutorial
Reference
CN Model¶
- class pyAgrum.CredalNet(*args)¶
Constructor used to create a CredalNet (step by step or with two BayesNet)
- CredalNet() -> CredalNet
default constructor
CredalNet(src_min_num,src_max_den) -> CredalNet
- Parameters
src_min_num (str or pyAgrum.BayesNet) – The path to a BayesNet or the BN itself which contains lower probabilities.
src_max_den (str or pyAgrum.BayesNet) – The (optional) path to a BayesNet or the BN itself which contains upper probabilities.
- NodeType_Credal = 1¶
- NodeType_Indic = 3¶
- NodeType_Precise = 0¶
- NodeType_Vacuous = 2¶
- addArc(tail, head)¶
Adds an arc between two nodes
- Parameters
tail (
int
) – the id of the tail nodehead (int) – the id of the head node
- Raises
pyAgrum.InvalidDirectedCircle – If any (directed) cycle is created by this arc
pyAgrum.InvalidNode – If head or tail does not belong to the graph nodes
pyAgrum.DuplicateElement – If one of the arc already exists
- Return type
None
- addVariable(name, card)¶
- Parameters
name (str) – the name of the new variable
card (int) – the domainSize of the new variable
- Returns
the id of the new node
- Return type
int
- approximatedBinarization()¶
Approximate binarization.
Each bit has a lower and upper probability which is the lowest - resp. highest - over all vertices of the credal set. Enlarge the orignal credal sets and may induce huge imprecision.
Warning
Enlarge the orignal credal sets and therefor induce huge imprecision by propagation. Not recommended, use MCSampling or something else instead
- Return type
None
- bnToCredal(beta, oneNet, keepZeroes=False)¶
Perturbates the BayesNet provided as input for this CredalNet by generating intervals instead of point probabilities and then computes each vertex of each credal set.
- Parameters
beta (float) – The beta used to perturbate the network
oneNet (bool) – used as a flag. Set to True if one BayesNet if provided with counts, to False if two BayesNet are provided; one with probabilities (the lower net) and one with denominators over the first modalities (the upper net)
keepZeroes (bool) – used as a flag as whether or not - respectively True or False - we keep zeroes as zeroes. Default is False, i.e. zeroes are not kept
- Return type
None
- computeBinaryCPTMinMax()¶
- Return type
None
- credalNet_currentCpt()¶
Warning
Experimental function - Return type to be wrapped
- Returns
a constant reference to the (up-to-date) CredalNet CPTs.
- Return type
tbw
- credalNet_srcCpt()¶
Warning
Experimental function - Return type to be wrapped
- Returns
a constant reference to the (up-to-date) CredalNet CPTs.
- Return type
tbw
- currentNodeType(id)¶
- Parameters
id (int) – The constant reference to the choosen NodeId
- Returns
the type of the choosen node in the (up-to-date) CredalNet __current_bn if any, __src_bn otherwise.
- Return type
- current_bn()¶
- Returns
Returs a constant reference to the actual BayesNet (used as a DAG, it’s CPTs does not matter).
- Return type
- domainSize(id)¶
- Parameters
id (int) – The id of the node
- Returns
The cardinality of the node
- Return type
int
- epsilonMax()¶
- Returns
a constant reference to the highest perturbation of the BayesNet provided as input for this CredalNet.
- Return type
float
- epsilonMean()¶
- Returns
a constant reference to the average perturbation of the BayesNet provided as input for this CredalNet.
- Return type
float
- epsilonMin()¶
- Returns
a constant reference to the lowest perturbation of the BayesNet provided as input for this CredalNet.
- Return type
float
- fillConstraint(*args)¶
Set the interval constraints of a credal set of a given node (from an instantiation index)
- Parameters
id (int) – The id of the node
entry (int) – The index of the instantiation excluding the given node (only the parents are used to compute the index of the credal set)
ins (pyAgrum.Instantiation) – The Instantiation
lower (list) – The lower value for each probability in correct order
upper (list) – The upper value for each probability in correct order
Warning
You need to call intervalToCredal when done filling all constraints.
Warning
DOES change the BayesNet (s) associated to this credal net !
- Return type
None
- fillConstraints(id, lower, upper)¶
Set the interval constraints of the credal sets of a given node (all instantiations)
- Parameters
id (int) – The id of the node
lower (list) – The lower value for each probability in correct order
upper (list) – The upper value for each probability in correct order
Warning
You need to call intervalToCredal when done filling all constraints.
Warning
DOES change the BayesNet (s) associated to this credal net !
- Return type
None
- get_binaryCPT_max()¶
Warning
Experimental function - Return type to be wrapped
- Returns
a constant reference to the upper probabilities of each node X over the ‘True’ modality
- Return type
tbw
- get_binaryCPT_min()¶
Warning
Experimental function - Return type to be wrapped
- Returns
a constant reference to the lower probabilities of each node X over the ‘True’ modality
- Return type
tbw
- hasComputedBinaryCPTMinMax()¶
- Return type
bool
- idmLearning(s=0, keepZeroes=False)¶
Learns parameters from a BayesNet storing counts of events.
Use this method when using a single BayesNet storing counts of events. IDM model if s > 0, standard point probability if s = 0 (default value if none precised).
- Parameters
s (int) – the IDM parameter.
keepZeroes (bool) – used as a flag as whether or not - respectively True or False - we keep zeroes as zeroes. Default is False, i.e. zeroes are not kept.
- Return type
None
- instantiation(id)¶
Get an Instantiation from a node id, usefull to fill the constraints of the network.
bnet accessors / shortcuts.
- Parameters
id (int) – the id of the node we want an instantiation from
- Returns
the instantiation
- Return type
- intervalToCredal()¶
Computes the vertices of each credal set according to their interval definition (uses lrs).
Use this method when using two BayesNet, one with lower probabilities and one with upper probabilities.
- Return type
None
- intervalToCredalWithFiles()¶
Warning
Deprecated : use intervalToCredal (lrsWrapper with no input / output files needed).
Computes the vertices of each credal set according to their interval definition (uses lrs).
Use this method when using a single BayesNet storing counts of events.
- Return type
None
- isSeparatelySpecified()¶
- Returns
True if this CredalNet is separately and interval specified, False otherwise.
- Return type
bool
- lagrangeNormalization()¶
Normalize counts of a BayesNet storing counts of each events such that no probability is 0.
Use this method when using a single BayesNet storing counts of events. Lagrange normalization. This call is irreversible and modify counts stored by __src_bn.
Doest not performs computations of the parameters but keeps normalized counts of events only. Call idmLearning to compute the probabilities (with any parameter value).
- Return type
None
- nodeType(id)¶
- Parameters
id (int) – the constant reference to the choosen NodeId
- Returns
the type of the choosen node in the (up-to-date) CredalNet in __src_bn.
- Return type
- saveBNsMinMax(min_path, max_path)¶
If this CredalNet was built over a perturbed BayesNet, one can save the intervals as two BayesNet.
to call after bnToCredal(GUM_SCALAR beta) save a BN with lower probabilities and a BN with upper ones
- Parameters
min_path (str) – the path to save the BayesNet which contains the lower probabilities of each node X.
max_path (str) – the path to save the BayesNet which contains the upper probabilities of each node X.
- Return type
None
- setCPT(*args)¶
Warning
(experimental function) - Parameters to be wrapped
Set the vertices of one credal set of a given node (any instantiation index)
- Parameters
id (int) – the Id of the node
entry (int) – the index of the instantiation (from 0 to K - 1) excluding the given node (only the parents are used to compute the index of the credal set)
ins (pyAgrum.Instantiation) – the Instantiation (only the parents matter to find the credal set index)
cpt (tbw) – the vertices of every credal set (for each instantiation of the parents)
Warning
DOES not change the BayesNet(s) associated to this credal net !
- Return type
None
- setCPTs(id, cpt)¶
Warning
(experimental function) - Parameters to be wrapped
Set the vertices of the credal sets (all of the conditionals) of a given node
- Parameters
id (int) – the NodeId of the node
cpt (tbw) – the vertices of every credal set (for each instantiation of the parents)
Warning
DOES not change the BayesNet (s) associated to this credal net !
- src_bn()¶
- Returns
Returns a constant reference to the original BayesNet (used as a DAG, it’s CPTs does not matter).
- Return type
CN Inference¶
- class pyAgrum.CNMonteCarloSampling(credalNet)¶
Class used for inferences in credal networks with Monte Carlo sampling algorithm.
- CNMonteCarloSampling(cn) -> CNMonteCarloSampling
- Parameters:
cn (pyAgrum.CredalNet) – a credal network
- Parameters
credalNet (
CredalNet
) –
- currentTime()¶
- Returns
get the current running time in second (float)
- Return type
float
- dynamicExpMax(varName)¶
Get the upper dynamic expectation of a given variable prefix.
- Parameters
varName (str) – the variable name prefix which upper expectation we want.
- Returns
a constant reference to the variable upper expectation over all time steps.
- Return type
float
- dynamicExpMin(varName)¶
Get the lower dynamic expectation of a given variable prefix.
- Parameters
varName (str) – the variable name prefix which lower expectation we want.
- Returns
a constant reference to the variable lower expectation over all time steps.
- Return type
float
- epsilon()¶
- Returns
the value of epsilon
- Return type
float
- history()¶
- Returns
the scheme history
- Return type
tuple
- Raises
pyAgrum.OperationNotAllowed – If the scheme did not performed or if verbosity is set to false
- insertEvidenceFile(path)¶
Insert evidence from file.
- Parameters
path (str) – the path to the evidence file.
- Return type
None
- insertModalsFile(path)¶
Insert variables modalities from file to compute expectations.
- Parameters
path (str) – The path to the modalities file.
- Return type
None
- makeInference()¶
Starts the inference.
- Return type
None
- marginalMax(*args)¶
Get the upper marginals of a given node id.
- Parameters
id (int) – the node id which upper marginals we want.
varName (str) – the variable name which upper marginals we want.
- Returns
a constant reference to this node upper marginals.
- Return type
list
- Raises
pyAgrum.IndexError – If the node does not belong to the Credal network
- marginalMin(*args)¶
Get the lower marginals of a given node id.
- Parameters
id (int) – the node id which lower marginals we want.
varName (str) – the variable name which lower marginals we want.
- Returns
a constant reference to this node lower marginals.
- Return type
list
- Raises
pyAgrum.IndexError – If the node does not belong to the Credal network
- maxIter()¶
- Returns
the criterion on number of iterations
- Return type
int
- maxTime()¶
- Returns
the timeout(in seconds)
- Return type
float
- messageApproximationScheme()¶
- Returns
the approximation scheme message
- Return type
str
- minEpsilonRate()¶
- Returns
the value of the minimal epsilon rate
- Return type
float
- nbrIterations()¶
- Returns
the number of iterations
- Return type
int
- periodSize()¶
- Returns
the number of samples between 2 stopping
- Return type
int
- Raises
pyAgrum.OutOfBounds – If p<1
- setEpsilon(eps)¶
- Parameters
eps (float) – the epsilon we want to use
- Raises
pyAgrum.OutOfBounds – If eps<0
- Return type
None
- setMaxIter(max)¶
- Parameters
max (int) – the maximum number of iteration
- Raises
pyAgrum.OutOfBounds – If max <= 1
- Return type
None
- setMaxTime(timeout)¶
- Parameters
tiemout (float) – stopping criterion on timeout (in seconds)
timeout (
float
) –
- Raises
pyAgrum.OutOfBounds – If timeout<=0.0
- Return type
None
- setMinEpsilonRate(rate)¶
- Parameters
rate (float) – the minimal epsilon rate
- Return type
None
- setPeriodSize(p)¶
- Parameters
p (int) – number of samples between 2 stopping
- Raises
pyAgrum.OutOfBounds – If p<1
- Return type
None
- setRepetitiveInd(flag)¶
- Parameters
flag (bool) – True if repetitive independence is to be used, false otherwise. Only usefull with dynamic networks.
- Return type
None
- setVerbosity(v)¶
- Parameters
v (bool) – verbosity
- Return type
None
- verbosity()¶
- Returns
True if the verbosity is enabled
- Return type
bool
- class pyAgrum.CNLoopyPropagation(cnet)¶
Class used for inferences in credal networks with Loopy Propagation algorithm.
- CNLoopyPropagation(cn) -> CNLoopyPropagation
- Parameters:
cn (pyAgrum.CredalNet) – a Credal network
- Parameters
cnet (
CredalNet
) –
- InferenceType_nodeToNeighbours = 0¶
- InferenceType_ordered = 1¶
- InferenceType_randomOrder = 2¶
- currentTime()¶
- Returns
get the current running time in second (float)
- Return type
float
- dynamicExpMax(varName)¶
Get the upper dynamic expectation of a given variable prefix.
- Parameters
varName (str) – the variable name prefix which upper expectation we want.
- Returns
a constant reference to the variable upper expectation over all time steps.
- Return type
float
- dynamicExpMin(varName)¶
Get the lower dynamic expectation of a given variable prefix.
- Parameters
varName (str) – the variable name prefix which lower expectation we want.
- Returns
a constant reference to the variable lower expectation over all time steps.
- Return type
float
- epsilon()¶
- Returns
the value of epsilon
- Return type
float
- eraseAllEvidence()¶
Erase all inference related data to perform another one.
You need to insert evidence again if needed but modalities are kept. You can insert new ones by using the appropriate method which will delete the old ones.
- Return type
None
- history()¶
- Returns
the scheme history
- Return type
tuple
- Raises
pyAgrum.OperationNotAllowed – If the scheme did not performed or if verbosity is set to false
- inferenceType(*args)¶
- Returns
the inference type
- Return type
int
- insertEvidenceFile(path)¶
Insert evidence from file.
- Parameters
path (str) – the path to the evidence file.
- Return type
None
- insertModalsFile(path)¶
Insert variables modalities from file to compute expectations.
- Parameters
path (str) – The path to the modalities file.
- Return type
None
- makeInference()¶
Starts the inference.
- Return type
None
- marginalMax(*args)¶
Get the upper marginals of a given node id.
- Parameters
id (int) – the node id which upper marginals we want.
varName (str) – the variable name which upper marginals we want.
- Returns
a constant reference to this node upper marginals.
- Return type
list
- Raises
pyAgrum.IndexError – If the node does not belong to the Credal network
- marginalMin(*args)¶
Get the lower marginals of a given node id.
- Parameters
id (int) – the node id which lower marginals we want.
varName (str) – the variable name which lower marginals we want.
- Returns
a constant reference to this node lower marginals.
- Return type
list
- Raises
pyAgrum.IndexError – If the node does not belong to the Credal network
- maxIter()¶
- Returns
the criterion on number of iterations
- Return type
int
- maxTime()¶
- Returns
the timeout(in seconds)
- Return type
float
- messageApproximationScheme()¶
- Returns
the approximation scheme message
- Return type
str
- minEpsilonRate()¶
- Returns
the value of the minimal epsilon rate
- Return type
float
- nbrIterations()¶
- Returns
the number of iterations
- Return type
int
- periodSize()¶
- Returns
the number of samples between 2 stopping
- Return type
int
- Raises
pyAgrum.OutOfBounds – If p<1
- saveInference(path)¶
Saves marginals.
- Parameters
path (str) – The path to the file to save marginals.
- Return type
None
- setEpsilon(eps)¶
- Parameters
eps (float) – the epsilon we want to use
- Raises
pyAgrum.OutOfBounds – If eps<0
- Return type
None
- setMaxIter(max)¶
- Parameters
max (int) – the maximum number of iteration
- Raises
pyAgrum.OutOfBounds – If max <= 1
- Return type
None
- setMaxTime(timeout)¶
- Parameters
tiemout (float) – stopping criterion on timeout (in seconds)
timeout (
float
) –
- Raises
pyAgrum.OutOfBounds – If timeout<=0.0
- Return type
None
- setMinEpsilonRate(rate)¶
- Parameters
rate (float) – the minimal epsilon rate
- Return type
None
- setPeriodSize(p)¶
- Parameters
p (int) – number of samples between 2 stopping
- Raises
pyAgrum.OutOfBounds – If p<1
- Return type
None
- setRepetitiveInd(flag)¶
- Parameters
flag (bool) – True if repetitive independence is to be used, false otherwise. Only usefull with dynamic networks.
- Return type
None
- setVerbosity(v)¶
- Parameters
v (bool) – verbosity
- Return type
None
- property thisown¶
The membership flag
- verbosity()¶
- Returns
True if the verbosity is enabled
- Return type
bool