COM.hugin.HAPI
Class Domain

java.lang.Object
  extended byCOM.hugin.HAPI.NetworkModel
      extended byCOM.hugin.HAPI.Domain
All Implemented Interfaces:
java.lang.Cloneable

public class Domain
extends NetworkModel
implements java.lang.Cloneable

Instances of the Domain class represent Bayesian networks and LIMIDs in which you can propagate evidence and calculate updated beliefs and expected utilities.


Nested Class Summary
static class Domain.Equilibrium
          The Equilibrium class represents the equilibrium state of this Domain.
static class Domain.EvidenceMode
          The EvidenceMode class represents the mode used for propagating evidence in this Domain.
static class Domain.TriangulationMethod
          The TriangulationMethod class represents the triangulation method used for this Domain.
 
Nested classes inherited from class COM.hugin.HAPI.NetworkModel
NetworkModel.Category, NetworkModel.Constraint, NetworkModel.Kind
 
Field Summary
static Domain.Equilibrium H_EQUILIBRIUM_MAX
          Represents max equilibrium.
static Domain.Equilibrium H_EQUILIBRIUM_SUM
          Represents sum equilibrium.
static Domain.EvidenceMode H_EVIDENCE_MODE_FAST_RETRACTION
          Represents the fast retraction evidence mode used for propagating evidence in this Domain.
static Domain.EvidenceMode H_EVIDENCE_MODE_NORMAL
          Represents the normal evidence mode used for propagating evidence in this Domain.
static Domain.TriangulationMethod H_TM_BEST_GREEDY
          Represents the best-greedy triangulation heuristic.
static Domain.TriangulationMethod H_TM_CLIQUE_SIZE
          Represents the clique-size triangulation heuristic.
static Domain.TriangulationMethod H_TM_CLIQUE_WEIGHT
          Represents the clique-weight triangulation heuristic.
static Domain.TriangulationMethod H_TM_FILL_IN_SIZE
          Represents the fill-in-size triangulation heuristic.
static Domain.TriangulationMethod H_TM_FILL_IN_WEIGHT
          Represents the fill-in-weight triangulation heuristic.
static Domain.TriangulationMethod H_TM_TOTAL_WEIGHT
          Represents the total clique-table size triangulation algorithm.
 
Fields inherited from class COM.hugin.HAPI.NetworkModel
H_CATEGORY_CHANCE, H_CATEGORY_DECISION, H_CATEGORY_FUNCTION, H_CATEGORY_INSTANCE, H_CATEGORY_UTILITY, H_CONSTRAINT_BACKWARD_EDGE_FORBIDDEN, H_CONSTRAINT_BACKWARD_EDGE_REQUIRED, H_CONSTRAINT_EDGE_FORBIDDEN, H_CONSTRAINT_EDGE_REQUIRED, H_CONSTRAINT_FORWARD_EDGE_FORBIDDEN, H_CONSTRAINT_FORWARD_EDGE_REQUIRED, H_CONSTRAINT_NONE, H_KIND_CONTINUOUS, H_KIND_DISCRETE, H_KIND_OTHER
 
Constructor Summary
Domain()
          Constructs a new empty Domain.
Domain(Class cls)
          Constructs a runtime domain from a Class object.
Domain(java.lang.String hkbFileName)
          Constructs a domain by loading the corresponding Hugin Knowledge Base (HKB) file.
Domain(java.lang.String netFileName, ParseListener parseListener)
          Constructs a domain from a NET file.
Domain(java.lang.String hkbFileName, java.lang.String password)
          Constructs a domain by loading the corresponding Hugin Knowledge Base (HKB) file.
 
Method Summary
 void adapt()
          Adapts this Domain according to the evidence entered.
 double approximate(double epsilon)
          Removes "near-zero" probabilities from the clique probability tables.
 boolean cgEvidenceIsPropagated()
          Returns true if evidence on CG nodes has been propagated; otherwise, returns false.
 java.lang.Object clone()
          Clones this Domain.
 void compile()
          Compiles this Domain.
 void compile(Domain.TriangulationMethod method)
          Compiles and triangulates this Domain using the specified triangulation method.
 void compile(NodeList eliminationOrder)
          Compiles and triangulates this Domain using the specified elimination order.
 double compress()
          Removes the zero entries from the clique and separator tables of the JunctionTrees in this Domain.
 void computeSensitivityData(NodeList nodes, int[] states)
          Computes the constants of the sensitivity functions for the specified output probabilities and all CPT parameters in the network.
 void delete()
          Deletes this Domain, including all Node and JunctionTree objects belonging to it.
 void enterCase(int c)
          Enters a case as evidence.
 boolean equilibriumIs(Domain.Equilibrium equilibrium)
          Tests for Equilibrium type.
 boolean evidenceIsPropagated()
          Tests if evidence has been propagated for this Domain.
 boolean evidenceModeIs(Domain.EvidenceMode evidenceMode)
          Tests for evidence mode.
 boolean evidenceToPropagate()
          Tests if evidence has been entered since the last propagation.
 void findMAPConfigurations(NodeList nodes, double minProbability)
          Finds all configurations of nodes with probability at least minProbability.
 double getAIC()
          Computes the AIC score (Akaike's Information Criterion) of the case data.
 double getApproximationConstant()
          Returns the approximation constant.
 double getBIC()
          Computes the BIC score (Bayesian Information Criterion) of the case data.
 double getCaseCount(int c)
          Returns case count for a case.
 int getConcurrencyLevel()
          Gets the current level of concurrency.
 double getConflict()
          Returns the conflict value.
 NodeList getDConnectedNodes(NodeList source, NodeList evidence)
          Performs a d-separation test and returns a list of d-connected nodes.
 NodeList getDConnectedNodes(NodeList source, NodeList hard, NodeList soft)
          Performs a d-separation test and returns a list of d-connected nodes.
 NodeList getDSeparatedNodes(NodeList source, NodeList evidence)
          Performs a d-separation test and returns a list of d-separated nodes.
 NodeList getDSeparatedNodes(NodeList source, NodeList hard, NodeList soft)
          Performs a d-separation test and returns a list of d-separated nodes.
 NodeList getEliminationOrder()
          Returns the triangulation order.
 double getExpectedUtility()
          Returns the total expected utility associated with this Domain.
 int getGrainSize()
          Returns the current value of the grain size parameter.
 JunctionTreeList getJunctionTrees()
          Returns the JunctionTrees of this Domain.
 double getLogLikelihood()
          Computes the log-likelihood of the case data.
 double getLogLikelihoodTolerance()
          Returns the log-likelihood tolerance for this Domain.
 double getLogNormalizationConstant()
          Returns the log of the normalization constant.
 int[] getMAPConfiguration(int index)
          Returns a MAP configuration.
 Table getMarginal(NodeList nodes)
          Computes the marginal distribution for the Nodes provided as argument with respect to the (imaginary) joint potential, determined by the current potentials on the JunctionTree(s) of this Domain.
 int getMaxNumberOfEMIterations()
          Returns the maximum number of iterations allowed for the EM algorithm.
 int getMaxNumberOfSeparators()
          Returns the maximum number of separators allowed when using the H_TM_TOTAL_WEIGHT TriangulationMethod.
 double getNormalDeviate(double mean, double variance)
          Use the pseudo-random number generator for this Domain to sample a real number from a normal (aka Gaussian) distribution.
 double getNormalizationConstant()
          Retrieves the normalization constant for the most recent propagation.
 int getNumberOfCases()
          Returns the number of data cases.
 int getNumberOfMAPConfigurations()
          Returns the number of MAP configurations.
 double getProbabilityOfMAPConfiguration(int index)
          Returns the probability of a MAP configuration.
 NodeList getSensitivitySet()
          Returns the sensitivity set computed by the most recent call to computeSensitivityData.
 NodeList getSensitivitySet(int output)
          Returns the sensitivity set computed by the most recent call to computeSensitivityData.
 double getSignificanceLevel()
          Returns the significance level of the dependency tests performed during structure learning using the PC-algorithm.
 double getUniformDeviate()
          Use the pseudo-random number generator for this Domain to sample a real number from the uniform distribution over the interval [0,1).
 void initialize()
          Establishes the initial values for all tables of this Domain (which must be compiled).
 boolean isCompiled()
          Tests whether this Domain is compiled.
 boolean isCompressed()
          Tests whether this Domain is compressed.
 boolean isTriangulated()
          Tests whether this Domain is triangulated.
 void learnClassTables()
          Learns the conditional probability tables of the class nodes, from which the domain is created, from data using the EM algorithm.
 void learnStructure()
          Learn the structure (graph) of the Bayesian network from data using the PC-algorithm.
 void learnTables()
          Learns the conditional probability tables from data using the EM algorithm.
 boolean likelihoodIsPropagated()
          Tests if likelihood evidence has been propagated for this Domain.
 int newCase()
          Creates a new case.
 void parseCase(java.lang.String fileName, ParseListener parseListener)
          Parses the case stored in file fileName and enters the associated findings into this Domain.
 void parseCases(java.lang.String fileName, ParseListener parseListener)
          Parses the cases stored in file fileName and enters the cases into this Domain.
 void propagate(Domain.Equilibrium equilibrium, Domain.EvidenceMode evidenceMode)
          Establishes the specified equilibrium using the evidence mode indicated for incorporation of evidence on all JunctionTrees of this Domain.
 void resetInferenceEngine()
          Establishes the initial state of the inference engine, which is sum-equilibrium with no evidence incorporated.
 void retractFindings()
          Retracts (all) evidence for all nodes in this Domain.
 void saveAsKB(java.lang.String fileName)
          Saves this Domain as a Hugin Knowledge Base (HKB) file.
 void saveAsKB(java.lang.String fileName, java.lang.String password)
          Saves this Domain as a password-protected Hugin Knowledge Base (HKB) file.
 void saveCase(java.lang.String fileName)
          Saves all evidence entered in this Domain in file fileName (if the file exists, it is overwritten).
 void saveCases(java.lang.String fileName, NodeList nodes, int[] cases, boolean caseCounts, java.lang.String separator, java.lang.String missingData)
          Saves all cases entered in this Domain in a file with the given fileName (if the file exists, it is overwritten).
 void saveToMemory()
          Creates a copy in memory of the belief and JunctionTree tables of this Domain.
 void seedRandom(int seed)
          Seeds the pseudo-random number generator for this Domain.
 void setCaseCount(int c, double count)
          Sets case count for a case.
 void setConcurrencyLevel(int level)
          Sets the level of concurrency.
 void setGrainSize(int size)
          Sets the grain size parameter.
 void setLogLikelihoodTolerance(double tolerance)
          Sets the log-likelihood tolerance for this Domain.
 void setMaxNumberOfEMIterations(int m)
          Sets the maximum number of iterations allowed for the EM algorithm.
 void setMaxNumberOfSeparators(int m)
          Sets the maximum number of separators allowed when using the H_TM_TOTAL_WEIGHT TriangulationMethod.
 void setNumberOfCases(int size)
          Sets the number of cases.
 void setSignificanceLevel(double alpha)
          Sets the significance level of the dependency tests performed during structure learning using the PC-algorithm.
 void simulate()
          Generates a sample configuration from the joint distribution represented by this Domain.
 boolean tablesToPropagate()
          Tests for new node tables.
 void triangulate()
          Triangulates the graph of this Domain using the default triangulation method.
 void triangulate(Domain.TriangulationMethod tm)
          Triangulates the graph of this Domain using the specified triangulation method.
 void triangulate(NodeList order)
          Triangulates the graph of this Domain using the specified elimination order.
 void uncompile()
          Uncompiles this Domain.
 void updatePolicies()
          Updates the policy tables of the domain.
 
Methods inherited from class COM.hugin.HAPI.NetworkModel
closeLogFile, generateTables, getAttribute, getAttributes, getFileName, getLogFile, getNodeByName, getNodes, getNodeSize, getUserData, INFINITY, isAlive, openLogFile, openLogFile, parseNodes, saveAsNet, setAttribute, setNodeSize, setUserData
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

H_EQUILIBRIUM_SUM

public static final Domain.Equilibrium H_EQUILIBRIUM_SUM
Represents sum equilibrium. Sum equilibrium is the state achieved by sum propagation in the JunctionTree of this Domain. See also propagate(Equilibrium, EvidenceMode).


H_EQUILIBRIUM_MAX

public static final Domain.Equilibrium H_EQUILIBRIUM_MAX
Represents max equilibrium. Max equilibrium is the state achieved by max propagation in the JunctionTree of this Domain. See also propagate(Equilibrium, EvidenceMode).


H_EVIDENCE_MODE_NORMAL

public static final Domain.EvidenceMode H_EVIDENCE_MODE_NORMAL
Represents the normal evidence mode used for propagating evidence in this Domain.


H_EVIDENCE_MODE_FAST_RETRACTION

public static final Domain.EvidenceMode H_EVIDENCE_MODE_FAST_RETRACTION
Represents the fast retraction evidence mode used for propagating evidence in this Domain.


H_TM_CLIQUE_SIZE

public static final Domain.TriangulationMethod H_TM_CLIQUE_SIZE
Represents the clique-size triangulation heuristic. Triangulation is the process of transforming the graph of this Domain to a triangulated graph, which forms the basis for constructing the JunctionTree of the Domain. As its score function, this heuristic uses the size of N(v), where N(v) is the set of neighbors of the target node v (i.e., the node to be eliminated next in the elimination order used for triangulating the graph).


H_TM_CLIQUE_WEIGHT

public static final Domain.TriangulationMethod H_TM_CLIQUE_WEIGHT
Represents the clique-weight triangulation heuristic. Triangulation is the process of transforming the graph of this Domain to a triangulated graph, which forms the basis for constructing the JunctionTree of the Domain. As its score function, this heuristic uses the product of the number of states of the discrete nodes in N(v) multiplied by a + bm(m + 3)/2, where m is the number of continuous nodes in N(v), a and b are the size of the types h_number_t and h_double_t, respectively, and N(v) is the set of neighbors of the target node v (i.e., the node to be eliminated next in the elimination order used for triangulating the graph).


H_TM_FILL_IN_SIZE

public static final Domain.TriangulationMethod H_TM_FILL_IN_SIZE
Represents the fill-in-size triangulation heuristic. Triangulation is the process of transforming the graph of this Domain to a triangulated graph, which forms the basis for constructing the JunctionTree of the Domain. As its score function, this heuristic uses the number of fill-in links required to complete the neighbors of a target node (i.e., the node to be eliminated next in the elimination order used for triangulating the graph).


H_TM_FILL_IN_WEIGHT

public static final Domain.TriangulationMethod H_TM_FILL_IN_WEIGHT
Represents the fill-in-weight triangulation heuristic. Triangulation is the process of transforming the graph of this Domain to a triangulated graph, which forms the basis for constructing the JunctionTree of the Domain. As its score function, this heuristic uses the sum of the weights of the fill-in links required to complete the neighbors of a target node (i.e., the node to be eliminated next in the elimination order used for triangulating the graph).


H_TM_BEST_GREEDY

public static final Domain.TriangulationMethod H_TM_BEST_GREEDY
Represents the best-greedy triangulation heuristic. Triangulation is the process of transforming the graph of this Domain to a triangulated graph, which forms the basis for constructing the JunctionTree of the Domain. This heuristic tries all the greedy elimination heuristics and uses the best result.


H_TM_TOTAL_WEIGHT

public static final Domain.TriangulationMethod H_TM_TOTAL_WEIGHT
Represents the total clique-table size triangulation algorithm. Triangulation is the process of transforming the graph of this Domain to a triangulated graph, which forms the basis for constructing the JunctionTree of the Domain. This algorithm is also sometimes referred to as the optimal triangulation algorithm. See also setMaxNumberOfSeparators.

Constructor Detail

Domain

public Domain()
       throws ExceptionHugin
Constructs a new empty Domain.


Domain

public Domain(java.lang.String hkbFileName,
              java.lang.String password)
       throws ExceptionHugin
Constructs a domain by loading the corresponding Hugin Knowledge Base (HKB) file.

Parameters:
hkbFileName - the name of the HKB file (a String).
password - a password needed to load the file.

Domain

public Domain(java.lang.String hkbFileName)
       throws ExceptionHugin
Constructs a domain by loading the corresponding Hugin Knowledge Base (HKB) file.

Parameters:
hkbFileName - the name of the HKB file (a String).

Domain

public Domain(java.lang.String netFileName,
              ParseListener parseListener)
       throws ExceptionHugin
Constructs a domain from a NET file.

Parameters:
netFileName - a string containing the name of the NET file
parseListener - the ParseListener used for handling parse errors.

Domain

public Domain(Class cls)
       throws ExceptionHugin
Constructs a runtime domain from a Class object.

Parameters:
cls - the Class object to instantiate.
Method Detail

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Clones this Domain.

Throws:
java.lang.CloneNotSupportedException

delete

public void delete()
            throws ExceptionHugin
Deletes this Domain, including all Node and JunctionTree objects belonging to it.

Specified by:
delete in class NetworkModel
Throws:
ExceptionHugin

approximate

public double approximate(double epsilon)
                   throws ExceptionHugin
Removes "near-zero" probabilities from the clique probability tables. For each Clique in this domain, a value delta is computed such that the sum of all elements less than delta in the (discrete part) of the clique table is less than epsilon. These elements (less than delta) are then set to 0.

Parameters:
epsilon - the threshold value. Maximal probability mass to eradicate from each clique.
Returns:
The probability mass remaining in the entire Domain, letting you know how much precision you have "lost". Note that this is not the same as 1 - e, as the e value is relative to each clique. Typically, the amount of probability mass removed will be somewhat larger than e.
Throws:
ExceptionHugin

cgEvidenceIsPropagated

public boolean cgEvidenceIsPropagated()
                               throws ExceptionHugin
Returns true if evidence on CG nodes has been propagated; otherwise, returns false.

Throws:
ExceptionHugin

compile

public void compile()
             throws ExceptionHugin
Compiles this Domain. The domain must not be compiled. The default triangulation method is used (unless the domain is already triangulated, in which case the existing triangulation is used).

Throws:
ExceptionHugin

compile

public void compile(NodeList eliminationOrder)
             throws ExceptionHugin
Compiles and triangulates this Domain using the specified elimination order. The domain must not be compiled or triangulated.

Parameters:
eliminationOrder - an ordered NodeList used as basis for constructing the triangulated graph (and in turn the JunctionTree).
Throws:
ExceptionHugin

compile

public void compile(Domain.TriangulationMethod method)
             throws ExceptionHugin
Compiles and triangulates this Domain using the specified triangulation method. The domain must not be compiled or triangulated.

Parameters:
method - the triangulation method used.
Throws:
ExceptionHugin

compress

public double compress()
                throws ExceptionHugin
Removes the zero entries from the clique and separator tables of the JunctionTrees in this Domain. Compression can only be applied to (compiled) ordinary Bayesian networks. Continuous nodes are allowed, but compression only applies to configurations of states of the discrete nodes.

Returns:
A double value which indicates a measure of compression achieved. The measure should be less than 1, indicating that the compressed Domain requires less space than the uncompressed Domain. An output greater than 1 means that the "compressed" Domain requires more space than the uncompressed Domain.
Throws:
ExceptionHugin

equilibriumIs

public boolean equilibriumIs(Domain.Equilibrium equilibrium)
                      throws ExceptionHugin
Tests for Equilibrium type. Returns true if the equilibrium states of all JunctionTrees of this Domain are identical to equilibrium.

Parameters:
equilibrium - the type of Equilibrium to test for.
Throws:
ExceptionHugin

evidenceIsPropagated

public boolean evidenceIsPropagated()
                             throws ExceptionHugin
Tests if evidence has been propagated for this Domain. Returns true if it has; otherwise, returns false.

Throws:
ExceptionHugin

evidenceModeIs

public boolean evidenceModeIs(Domain.EvidenceMode evidenceMode)
                       throws ExceptionHugin
Tests for evidence mode. Returns true if the equilibrium states of all JunctionTrees of this Domain could have been obtained through a propagation using evidenceMode as the evidence incorporation mode. Otherwise, returns false.

Parameters:
evidenceMode - the type of EvidenceMode to test for.
Throws:
ExceptionHugin

evidenceToPropagate

public boolean evidenceToPropagate()
                            throws ExceptionHugin
Tests if evidence has been entered since the last propagation. Returns true if it has; otherwise, returns false.

Throws:
ExceptionHugin

getApproximationConstant

public double getApproximationConstant()
                                throws ExceptionHugin
Returns the approximation constant. The number returned is based on the most recent (explicit or implicit) approximation operation. An implicit approximation takes place when you change some conditional probability tables of acompressed domain, and then perform a propagation operation. Since some (discrete) state configurations have been removed from a compressed domain, the probability mass of the remaining configurations will typically be less than 1. This probability mass is returned by getApproximationConstant().

Returns:
A real number expressing the probability mass remaining in the approximated domain.
Throws:
ExceptionHugin

getConflict

public double getConflict()
                   throws ExceptionHugin
Returns the conflict value. The conflict value is valid for this Domain computed during the most recent propagation. If no propagation has been performed, 1 is returned.

Returns:
A double-precision real value expressing the conflict measure in the domain.
Throws:
ExceptionHugin

getEliminationOrder

public NodeList getEliminationOrder()
                             throws ExceptionHugin
Returns the triangulation order. A NodeList containing the nodes in the order used to triangulate the network of this Domain is returned.

Returns:
NodeList containing Nodes representing the elimination order used.
Throws:
ExceptionHugin

getJunctionTrees

public JunctionTreeList getJunctionTrees()
                                  throws ExceptionHugin
Returns the JunctionTrees of this Domain.

Returns:
A JunctionTreeList.
Throws:
ExceptionHugin

getMarginal

public Table getMarginal(NodeList nodes)
                  throws ExceptionHugin
Computes the marginal distribution for the Nodes provided as argument with respect to the (imaginary) joint potential, determined by the current potentials on the JunctionTree(s) of this Domain. If nodes contains continuous nodes, they must be last in the list. This operation is not allowed on compressed Domains.

Parameters:
nodes - a NodeList containing the Nodes over which to compute the marginal.
Returns:
A Table containing the marginal distribution over the Nodes in nodes.
Throws:
ExceptionHugin

findMAPConfigurations

public void findMAPConfigurations(NodeList nodes,
                                  double minProbability)
                           throws ExceptionHugin
Finds all configurations of nodes with probability at least minProbability. This method uses a Monte Carlo algorithm to solve a generalized form of the maximum a posteriori (MAP) configuration problem: The MAP configuration problem is the problem of finding the most probable configuration of a set of nodes given evidence on some of the remaining nodes.

The results of this method are provided by getNumberOfMAPConfigurations, getMAPConfiguration, and getProbabilityOfMAPConfiguration.

Parameters:
nodes - a NodeList containing the DiscreteNodes for which to find configurations.
minProbability - configurations with a lower probability than minProbability are ignored.
Throws:
ExceptionHugin

getNumberOfMAPConfigurations

public int getNumberOfMAPConfigurations()
                                 throws ExceptionHugin
Returns the number of MAP configurations. This method returns the number of configurations found by the most recent successful call to findMAPConfigurations.

Throws:
ExceptionHugin

getMAPConfiguration

public int[] getMAPConfiguration(int index)
                          throws ExceptionHugin
Returns a MAP configuration. This method returns the configuration identified by index among the configurations with probability at least minProbability — as specified in the most recent successful call to findMAPConfigurations.

The index argument must be a nonnegative integer less than getNumberOfMAPConfigurations: 0 requests the most probable configuration, 1 the second-most probable configuration, etc.

Parameters:
index - identifies the configuration.
Returns:
an array of state indexes forming the configuration.
Throws:
ExceptionHugin

getProbabilityOfMAPConfiguration

public double getProbabilityOfMAPConfiguration(int index)
                                        throws ExceptionHugin
Returns the probability of a MAP configuration. This method returns the probability of the configuration returned by getMAPConfiguration(index)

Parameters:
index - identifies the configuration.
Returns:
the probability of the specified configuration.
Throws:
ExceptionHugin

getNormalizationConstant

public double getNormalizationConstant()
                                throws ExceptionHugin
Retrieves the normalization constant for the most recent propagation. For sum-propagation, the normalization constant is equal to the probability of the evidence propagated. For max-propagation, the normalization constant is the probability of the most probable configuration with the evidence incorporated.

Throws:
ExceptionHugin

getExpectedUtility

public double getExpectedUtility()
                          throws ExceptionHugin
Returns the total expected utility associated with this Domain.

Throws:
ExceptionHugin

initialize

public void initialize()
                throws ExceptionHugin
Establishes the initial values for all tables of this Domain (which must be compiled). This method erases all evidence previously entered.

Throws:
ExceptionHugin

isTriangulated

public boolean isTriangulated()
                       throws ExceptionHugin
Tests whether this Domain is triangulated. Being "triangulated" means that the junction forest has been created, but not the associated tables.

Throws:
ExceptionHugin

isCompiled

public boolean isCompiled()
                   throws ExceptionHugin
Tests whether this Domain is compiled. A domain is "compiled" if it is triangulated and junction tree tables are created.

Throws:
ExceptionHugin

isCompressed

public boolean isCompressed()
                     throws ExceptionHugin
Tests whether this Domain is compressed.

Throws:
ExceptionHugin

likelihoodIsPropagated

public boolean likelihoodIsPropagated()
                               throws ExceptionHugin
Tests if likelihood evidence has been propagated for this Domain. Returns true if it has; otherwise, returns false.

Throws:
ExceptionHugin

propagate

public void propagate(Domain.Equilibrium equilibrium,
                      Domain.EvidenceMode evidenceMode)
               throws ExceptionHugin
Establishes the specified equilibrium using the evidence mode indicated for incorporation of evidence on all JunctionTrees of this Domain. Also, revised beliefs will be computed for all nodes.

Parameters:
equilibrium - Equilibrium type. The normal Equilibrium type is Domain.H_EQUILIBRIUM_SUM.
evidenceMode - EvidenceMode type. The normal EvidenceMode type is Domain.H_EVIDENCE_MODE_NORMAL.
Throws:
ExceptionHugin

resetInferenceEngine

public void resetInferenceEngine()
                          throws ExceptionHugin
Establishes the initial state of the inference engine, which is sum-equilibrium with no evidence incorporated. Any propagated evidence will thus be removed from the JunctionTree potentials, but entered evidence will still be "registered" (i.e., they will be incorporated in the next propagation).

Throws:
ExceptionHugin

retractFindings

public void retractFindings()
                     throws ExceptionHugin
Retracts (all) evidence for all nodes in this Domain.

Throws:
ExceptionHugin

saveAsKB

public void saveAsKB(java.lang.String fileName,
                     java.lang.String password)
              throws ExceptionHugin
Saves this Domain as a password-protected Hugin Knowledge Base (HKB) file. If password is non-null, the file will be password protected. This password must be used in order to load the file.

Parameters:
fileName - the name of the file to which the HKB is saved.
password - if non-null, this must be used in order to load the file.
Throws:
ExceptionHugin

saveAsKB

public void saveAsKB(java.lang.String fileName)
              throws ExceptionHugin
Saves this Domain as a Hugin Knowledge Base (HKB) file. The HKB file will not be password protected.

Parameters:
fileName - the name of the HKB file.
Throws:
ExceptionHugin

saveToMemory

public void saveToMemory()
                  throws ExceptionHugin
Creates a copy in memory of the belief and JunctionTree tables of this Domain. This operation can only be performed if the domain is compiled, the current equilibrium equals Domain.H_EQUILIBRIUM_SUM, and no evidence has been incorporated.

Throws:
ExceptionHugin

simulate

public void simulate()
              throws ExceptionHugin
Generates a sample configuration from the joint distribution represented by this Domain. Given evidence, we may be interested in generating (sampling) configurations (i.e., vectors of values over the set of variables in the network) with respect to the conditional distribution for the evidence. If the Domain is compiled, a configuration is sampled with respect to the current distribution represented by the JunctionTree(s). This distribution must be in sum-equilibrium with evidence incorporated in normal mode.

Throws:
ExceptionHugin

seedRandom

public void seedRandom(int seed)
                throws ExceptionHugin
Seeds the pseudo-random number generator for this Domain. The configurations generated by simulate are not really random. They are generated using a pseudo-random number generator producing a sequence of numbers that although it appears random is actually completely deterministic. To change the starting point for the generator, use this method.

Parameters:
seed - the seed number.
Throws:
ExceptionHugin

getUniformDeviate

public double getUniformDeviate()
                         throws ExceptionHugin
Use the pseudo-random number generator for this Domain to sample a real number from the uniform distribution over the interval [0,1).

Throws:
ExceptionHugin

getNormalDeviate

public double getNormalDeviate(double mean,
                               double variance)
                        throws ExceptionHugin
Use the pseudo-random number generator for this Domain to sample a real number from a normal (aka Gaussian) distribution.

Parameters:
mean - the mean of the distribution
variance - the variance of the distribution
Throws:
ExceptionHugin

tablesToPropagate

public boolean tablesToPropagate()
                          throws ExceptionHugin
Tests for new node tables. Returns true if there is a node in this Domain having a (conditional probability, policy, or utility) table that has changed since the most recent compilation or propagation; otherwise, returns false.

Throws:
ExceptionHugin

triangulate

public void triangulate(Domain.TriangulationMethod tm)
                 throws ExceptionHugin
Triangulates the graph of this Domain using the specified triangulation method.

Parameters:
tm - the TriangulationMethod to use.
Throws:
ExceptionHugin

triangulate

public void triangulate()
                 throws ExceptionHugin
Triangulates the graph of this Domain using the default triangulation method.

Throws:
ExceptionHugin

triangulate

public void triangulate(NodeList order)
                 throws ExceptionHugin
Triangulates the graph of this Domain using the specified elimination order. The elimination order must contain each chance and decision node of this Domain exactly once, and continuous nodes must appear before discrete nodes.

Parameters:
order - a NodeList containing the Nodes of the network in the order of elimination
Throws:
ExceptionHugin

uncompile

public void uncompile()
               throws ExceptionHugin
Uncompiles this Domain. Removes the data structures of the Domain produced by a triangulation or a compilation. Note that any references to objects within the compiled structure (e.g., Cliques and JunctionTrees) are invalidated (that is, any attempt to access the objects will throw an object-not-alive exception). Also note that many of the editing functions automatically performs an uncompile() operation. When this happens, the domain must be compiled again before it can be used for inference.

Throws:
ExceptionHugin

setConcurrencyLevel

public void setConcurrencyLevel(int level)
                         throws ExceptionHugin
Sets the level of concurrency. The level of concurrency specifies the maximum number of threads to create when performing a specific table operation. Setting the level of concurrency to 1 will cause all table operations to be performed sequentially. The initial parameter value is 1.

Parameters:
level - the level of concurrency.
Throws:
ExceptionHugin

setGrainSize

public void setGrainSize(int size)
                  throws ExceptionHugin
Sets the grain size parameter. The grain size parameter specifies a lower limit of the tasks to be performed by each thread. The size of a task is approximately equal to the number of floating-point operations needed to perform the task (e.g. the number of elements to sum when performing a marginalization task).

The initial value of the grain size parameter is 10000.

Parameters:
size - the grain size.
Throws:
ExceptionHugin

getConcurrencyLevel

public int getConcurrencyLevel()
                        throws ExceptionHugin
Gets the current level of concurrency.

Returns:
A positive integer.

Throws:
ExceptionHugin
See Also:
setConcurrencyLevel

getGrainSize

public int getGrainSize()
                 throws ExceptionHugin
Returns the current value of the grain size parameter.

Returns:
A positive integer.
Throws:
ExceptionHugin

getLogNormalizationConstant

public double getLogNormalizationConstant()
                                   throws ExceptionHugin
Returns the log of the normalization constant.

Throws:
ExceptionHugin

setNumberOfCases

public void setNumberOfCases(int size)
                      throws ExceptionHugin
Sets the number of cases.

Throws:
ExceptionHugin

newCase

public int newCase()
            throws ExceptionHugin
Creates a new case.

Throws:
ExceptionHugin

getNumberOfCases

public int getNumberOfCases()
                     throws ExceptionHugin
Returns the number of data cases.

Throws:
ExceptionHugin

setCaseCount

public void setCaseCount(int c,
                         double count)
                  throws ExceptionHugin
Sets case count for a case.

Parameters:
c - the case for which to set the count.
count - the multiplicity of c.
Throws:
ExceptionHugin

getCaseCount

public double getCaseCount(int c)
                    throws ExceptionHugin
Returns case count for a case.

Parameters:
c - the case for which to get the count.
Returns:
The multiplicity of c.
Throws:
ExceptionHugin

enterCase

public void enterCase(int c)
               throws ExceptionHugin
Enters a case as evidence.

Parameters:
c - the case to enter.
Throws:
ExceptionHugin

learnTables

public void learnTables()
                 throws ExceptionHugin
Learns the conditional probability tables from data using the EM algorithm.

Throws:
ExceptionHugin

learnClassTables

public void learnClassTables()
                      throws ExceptionHugin
Learns the conditional probability tables of the class nodes, from which the domain is created, from data using the EM algorithm.

Throws:
ExceptionHugin

setLogLikelihoodTolerance

public void setLogLikelihoodTolerance(double tolerance)
                               throws ExceptionHugin
Sets the log-likelihood tolerance for this Domain.

Throws:
ExceptionHugin

getLogLikelihoodTolerance

public double getLogLikelihoodTolerance()
                                 throws ExceptionHugin
Returns the log-likelihood tolerance for this Domain.

Throws:
ExceptionHugin

setMaxNumberOfEMIterations

public void setMaxNumberOfEMIterations(int m)
                                throws ExceptionHugin
Sets the maximum number of iterations allowed for the EM algorithm. A value of 0 specifies an unbounded number of iterations.

Throws:
ExceptionHugin

getMaxNumberOfEMIterations

public int getMaxNumberOfEMIterations()
                               throws ExceptionHugin
Returns the maximum number of iterations allowed for the EM algorithm.

Throws:
ExceptionHugin

getLogLikelihood

public double getLogLikelihood()
                        throws ExceptionHugin
Computes the log-likelihood of the case data.

Throws:
ExceptionHugin

getAIC

public double getAIC()
              throws ExceptionHugin
Computes the AIC score (Akaike's Information Criterion) of the case data.

Throws:
ExceptionHugin

getBIC

public double getBIC()
              throws ExceptionHugin
Computes the BIC score (Bayesian Information Criterion) of the case data.

Throws:
ExceptionHugin

adapt

public void adapt()
           throws ExceptionHugin
Adapts this Domain according to the evidence entered.

Throws:
ExceptionHugin

learnStructure

public void learnStructure()
                    throws ExceptionHugin
Learn the structure (graph) of the Bayesian network from data using the PC-algorithm.

Throws:
ExceptionHugin

setSignificanceLevel

public void setSignificanceLevel(double alpha)
                          throws ExceptionHugin
Sets the significance level of the dependency tests performed during structure learning using the PC-algorithm. The default value is 0.05.

Parameters:
alpha - the significance level.
Throws:
ExceptionHugin

getSignificanceLevel

public double getSignificanceLevel()
                            throws ExceptionHugin
Returns the significance level of the dependency tests performed during structure learning using the PC-algorithm. The default value is 0.05.

Returns:
A positive double.
Throws:
ExceptionHugin

setMaxNumberOfSeparators

public void setMaxNumberOfSeparators(int m)
                              throws ExceptionHugin
Sets the maximum number of separators allowed when using the H_TM_TOTAL_WEIGHT TriangulationMethod. A value of 0 specifies an unbounded number of separators.

Throws:
ExceptionHugin

getMaxNumberOfSeparators

public int getMaxNumberOfSeparators()
                             throws ExceptionHugin
Returns the maximum number of separators allowed when using the H_TM_TOTAL_WEIGHT TriangulationMethod.

Throws:
ExceptionHugin

parseCase

public void parseCase(java.lang.String fileName,
                      ParseListener parseListener)
               throws ExceptionHugin
Parses the case stored in file fileName and enters the associated findings into this Domain. All existing evidence in the Domain is retracted before entering the case findings.

Parameters:
fileName - the name of the file containing the case.
parseListener - the ParseListener used for handling parse errors.
Throws:
ExceptionHugin

saveCase

public void saveCase(java.lang.String fileName)
              throws ExceptionHugin
Saves all evidence entered in this Domain in file fileName (if the file exists, it is overwritten).

Parameters:
fileName - the name of the file in which the case is going to be saved.
Throws:
ExceptionHugin

saveCases

public void saveCases(java.lang.String fileName,
                      NodeList nodes,
                      int[] cases,
                      boolean caseCounts,
                      java.lang.String separator,
                      java.lang.String missingData)
               throws ExceptionHugin
Saves all cases entered in this Domain in a file with the given fileName (if the file exists, it is overwritten).

Parameters:
fileName - the name of the file in which the case is going to be saved.
nodes - A list of all nodes which are to be included in the file
cases - An array of case indexes specifying the cases to be included in the file. Passing NULL for this argument will include all cases.
caseCounts - If true, include case counts in the data file. If false, only include case counts if they are present in the domain.
separator - The string used to seperate the items in the file
missingData - The string used to represent missing data
Throws:
ExceptionHugin

parseCases

public void parseCases(java.lang.String fileName,
                       ParseListener parseListener)
                throws ExceptionHugin
Parses the cases stored in file fileName and enters the cases into this Domain.

Parameters:
fileName - the name of the file containing the cases.
parseListener - the ParseListener used for handling parse errors.
Throws:
ExceptionHugin

getDConnectedNodes

public NodeList getDConnectedNodes(NodeList source,
                                   NodeList hard,
                                   NodeList soft)
                            throws ExceptionHugin
Performs a d-separation test and returns a list of d-connected nodes. Assuming evidence on the specified evidence nodes, this method returns the list of nodes that are d-connected to the specified list of source nodes.

Parameters:
source - list of source nodes
hard - list of nodes assumed to be instantiated
soft - list of nodes assumed to have multi-state or likelihood evidence.
Returns:
the list of d-connected nodes
Throws:
ExceptionHugin

getDConnectedNodes

public NodeList getDConnectedNodes(NodeList source,
                                   NodeList evidence)
                            throws ExceptionHugin
Performs a d-separation test and returns a list of d-connected nodes. Assuming evidence on the specified evidence nodes, this method returns the list of nodes that are d-connected to the specified list of source nodes.

Parameters:
source - list of source nodes
evidence - list of nodes assumed to be instantiated.
Returns:
the list of d-connected nodes
Throws:
ExceptionHugin

getDSeparatedNodes

public NodeList getDSeparatedNodes(NodeList source,
                                   NodeList hard,
                                   NodeList soft)
                            throws ExceptionHugin
Performs a d-separation test and returns a list of d-separated nodes. Assuming evidence on the specified evidence nodes, this method returns the list of nodes that are d-separated to the specified list of source nodes.

Parameters:
source - list of source nodes
hard - list of nodes assumed to be instantiated
soft - list of nodes assumed to have multi-state or likelihood evidence.
Returns:
the list of d-separated nodes
Throws:
ExceptionHugin

getDSeparatedNodes

public NodeList getDSeparatedNodes(NodeList source,
                                   NodeList evidence)
                            throws ExceptionHugin
Performs a d-separation test and returns a list of d-separated nodes. Assuming evidence on the specified evidence nodes, this method returns the list of nodes that are d-separated to the specified list of source nodes.

Parameters:
source - list of source nodes
evidence - list of nodes assumed to be instantiated.
Returns:
the list of d-separated nodes
Throws:
ExceptionHugin

computeSensitivityData

public void computeSensitivityData(NodeList nodes,
                                   int[] states)
                            throws ExceptionHugin
Computes the constants of the sensitivity functions for the specified output probabilities and all CPT parameters in the network. The output probabilities are specified using a list of nodes and a list of corresponding states.

Parameters:
nodes - the list of (output) nodes
states - a list of states of the nodes in the nodes list
Throws:
ExceptionHugin

getSensitivitySet

public NodeList getSensitivitySet()
                           throws ExceptionHugin
Returns the sensitivity set computed by the most recent call to computeSensitivityData. If the results produced by that call have been invalidated, a usage exception is thrown.

Throws:
ExceptionHugin

getSensitivitySet

public NodeList getSensitivitySet(int output)
                           throws ExceptionHugin
Returns the sensitivity set computed by the most recent call to computeSensitivityData. If the results produced by that call have been invalidated, a usage exception is thrown.

Parameters:
output - identifies one of the output probabilities specified in the call to computeSensitivityData.
Throws:
ExceptionHugin

updatePolicies

public void updatePolicies()
                    throws ExceptionHugin
Updates the policy tables of the domain. The policies of all unmade decisions are updated. The new policies maximize the overall expected utility.

Throws:
ExceptionHugin