com.Bayesia.api
Class APIInference

java.lang.Object
  com.Bayesia.api.APIInference

public class APIInference
extends java.lang.Object

The class APIInference is used to perform exact or approximate inference on a bayesian network. The bayesian network is loaded from an xbl file. This format is generated by BayesiaLab from Bayesia.

The exact inference is performed with a junction tree algorithm. The approximate inference is performed with a likelihood weighting algorithm.

The class APIInference allows to use networks containing discrete, interval, constraint and utility nodes. It allows also the use of temporal networks.

All the methods of this class can throw an instance of IllegalOperationException which is a subclass of RuntimeException so you can avoid to catch them.

Version:

1.4 27/06/06

Author:

Bayesia S.A.

Field Summary

static int	APPROXIMATE_INFERENCE
static int	EXACT_INFERENCE

Constructor Summary

APIInference(BayesianNetworkTransferHandler networkHandler, java.lang.String licenceKey, int inferenceType)
Creates a new APIExactInference with the network stored in the specified BayesianNetworkTransferHandler.

APIInference(BayesianNetworkTransferHandler networkHandler, java.lang.String licenceServerHost, int licenseServerPort, java.lang.String userGroup, int inferenceType)
Creates a new APIExactInference with the network stored in the specified BayesianNetworkTransferHandler.

APIInference(java.lang.String fileName, java.lang.String licenceKey, int inferenceType)
Creates a new APIExactInference with the network stored in the specified file.

APIInference(java.lang.String fileName, java.lang.String licenceServerHost, int licenseServerPort, java.lang.String userGroup, int inferenceType)
Creates a new APIExactInference with the network stored in the specified file.

Method Summary

void	close() Method used to close the current instance of APIInference.
java.lang.String	getArcComment(java.lang.String nodeName1, java.lang.String nodeName2) Returns the comment associated to the arc between the nodes named nodeName1 and nodeName2.
java.lang.String	getComment() Returns the comment associated to the network.
int	getCurrentTime() Returns the current time of the network.
java.lang.String	getFormula(java.lang.String nodeName) Returns the formula associated to the node as String.
int	getInferenceType() Returns APPROXIMATE_INFERENCE if the inference type is approximate or EXACT_INFERENCE if the inference type is exact.
float[][]	getIntervals(java.lang.String nodeName) Returns an array containing the minimum and the maximum of each interval of the node as floats.
int[]	getIntValues(java.lang.String nodeName) Returns an array containing the values of the node as integers if the node is an integer node.
double	getLikelihood(java.lang.String nodeName, java.lang.String value) Returns the likelihood associated to a value of a node.
double[]	getLikelihoods(java.lang.String nodeName) Retrieves an array containing the likelihoods associated to the values of a node.
double	getMean(java.lang.String nodeName) Returns the mean of an interval or an integer node.
java.lang.String	getName() Returns the name of the loaded network.
java.lang.String	getNodeComment(java.lang.String nodeName) Returns the comment associated to the specified node
java.lang.String[]	getNodeNames() Returns an array containing the name of the nodes in the network
int	getNodeNumber() Returns the number of nodes in the network
java.lang.String	getObservedValue(java.lang.String nodeName) Returns the observed value of the specified node if the node is observed.
double[]	getProbabilities(java.lang.String nodeName) Return the posterior probabilities associated to the values of the specified node.
double	getProbability(java.lang.String nodeName, java.lang.String value) Returns the probability associated to a specific value of a node.
double[]	getQualities(java.lang.String nodeName) Returns an array containing the qualities of a decision node. it can be used only on a decision node.
int	getSampleSize() Returnss the sample size used to perform the approximate inference.
double	getStandardDeviation(java.lang.String nodeName) Returns the standard deviation of an interval or an integer node.
java.lang.String[]	getStringValues(java.lang.String nodeName) Returns an array containing the values of the node as String.
double[]	getUtility(java.lang.String nodeName) Returns an array containing the minimum utility, the current utility and the maximum utility of a utility node. it can be used only on a utility node.
int	getValueNumber(java.lang.String nodeName) Returns the number of values of the specified node.
void	increaseTime() Performs a step of temporal simulation : from getCurrentTime() to getCurrentTime()+1.
boolean	isBoolean(java.lang.String nodeName) Tests if the specified node is boolean, i.e. its values are equivalent to true and false.
boolean	isConstraint(java.lang.String nodeName) Tests if the node is a constraint node.
boolean	isDecision(java.lang.String nodeName) Tests if the node is a decision node.
boolean	isInteger(java.lang.String nodeName) Tests if all the values of the specified node are integers.
boolean	isInterval(java.lang.String nodeName) Tests if the node is described by a list of consecutives intervals.
boolean	isObservationValidityEnabled() Returns the state of the observation validity checking.
boolean	isObserved(java.lang.String nodeName) Tests if the specified node is observed.
boolean	isTemporal() Tests if the network is temporal.
boolean	isUtility(java.lang.String nodeName) Tests if the node is a utility node.
boolean	observe(java.lang.String nodeName, float value) Observes a float value for an interval node only.
boolean	observe(java.lang.String nodeName, short valueIndex) Observes a value through its index for a node.
boolean	observe(java.lang.String nodeName, java.lang.String value) Observes a value for a node.
void	resetTime() Resets the time to 0.
void	setInferenceType(int type) Sets the type of inference to use.
boolean	setLikelihood(java.lang.String nodeName, short valueIndex, double likelihood) Sets the likelihood for a value of a node (soft evidence).
boolean	setLikelihood(java.lang.String nodeName, java.lang.String value, double likelihood) Sets the likelihood for a value of a node (soft evidence).
void	setObservationValidityEnabled(boolean b) Sets the observation validity enabled or not.
void	setSampleSize(int sampleSize) Sets the sample size used by approximate inference.
void	setTime(int time) Performs a temporal simulation from the current time to the specified time.
void	unobserve(java.lang.String nodeName) Unobserves the specified node.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EXACT_INFERENCE

public static final int EXACT_INFERENCE

See Also:

Constant Field Values

APPROXIMATE_INFERENCE

public static final int APPROXIMATE_INFERENCE

See Also:

Constant Field Values

Constructor Detail

APIInference

public APIInference(java.lang.String fileName,
                    java.lang.String licenceKey,
                    int inferenceType)

Creates a new APIExactInference with the network stored in the specified file. You must provide a valid licence key for inference.

Parameters:

fileName - the name of the xbl file containing the network

licenceKey - the key of the licence.

inferenceType - one of EXACT_INFERENCE and APPROXIMATE_INFERENCE.

APIInference

public APIInference(java.lang.String fileName,
                    java.lang.String licenceServerHost,
                    int licenseServerPort,
                    java.lang.String userGroup,
                    int inferenceType)

Creates a new APIExactInference with the network stored in the specified file. You must provide the host and the port of the license server. The user group is optional, depending on the configuration of the license ont the license server. Use this constructor if you use a license server.

Parameters:

fileName - the name of the xbl file containing the network

licenceServerHost - the host of the license server.

licenseServerPort - the port of the license server.

userGroup - the user group corresponding to the license, maybe null if no user group is specified on the license server.

inferenceType - one of EXACT_INFERENCE and APPROXIMATE_INFERENCE.

APIInference

public APIInference(BayesianNetworkTransferHandler networkHandler,
                    java.lang.String licenceKey,
                    int inferenceType)

Creates a new APIExactInference with the network stored in the specified BayesianNetworkTransferHandler. You must provide a valid licence key for inference.

Parameters:

networkHandler - the transfer handler containing the network

licenceKey - the key of the licence.

inferenceType - one of EXACT_INFERENCE and APPROXIMATE_INFERENCE.

APIInference

public APIInference(BayesianNetworkTransferHandler networkHandler,
                    java.lang.String licenceServerHost,
                    int licenseServerPort,
                    java.lang.String userGroup,
                    int inferenceType)

Creates a new APIExactInference with the network stored in the specified BayesianNetworkTransferHandler. You must provide the host and the port of the license server. The user group is optional, depending on the configuration of the license ont the license server. Use this constructor if you use a license server.

Parameters:

networkHandler - the transfer handler containing the network.

licenceServerHost - the host of the license server.

licenseServerPort - the port of the license server.

userGroup - the user group corresponding to the license, maybe null if no user group is specified on the license server.

inferenceType - one of EXACT_INFERENCE and APPROXIMATE_INFERENCE.

Method Detail

isObservationValidityEnabled

public final boolean isObservationValidityEnabled()

Returns the state of the observation validity checking.

Returns:

true is the observation validity is enabled, false otherwise

setObservationValidityEnabled

public final void setObservationValidityEnabled(boolean b)

Sets the observation validity enabled or not. Enabling observation validity prevent from observing impossible modality (its probability is 0). It may cause performance degradation if there are a lot of observation to do.

With this option enabled : observe("aNode", "aValue");

is equal to, with this option disabled : if (getProbability("aNode", "aValue")>0) { observe("aNode", "aValue"); }

Parameters:

b - the new state of the observation validity checking

See Also:

observe(String, String), observe(String, float)

getName

public final java.lang.String getName()

Returns the name of the loaded network.

Returns:

the name of the network

getNodeNames

public java.lang.String[] getNodeNames()

Returns an array containing the name of the nodes in the network

Returns:

the node names

getNodeNumber

public final int getNodeNumber()

Returns the number of nodes in the network

Returns:

the number of nodes

getComment

public final java.lang.String getComment()

Returns the comment associated to the network.

Returns:

the comment associated to the network.

getNodeComment

public final java.lang.String getNodeComment(java.lang.String nodeName)

Returns the comment associated to the specified node

Parameters:

nodeName - the name of the node we want the comment

Returns:

the comment of the node

getArcComment

public final java.lang.String getArcComment(java.lang.String nodeName1,
                                            java.lang.String nodeName2)

Returns the comment associated to the arc between the nodes named nodeName1 and nodeName2.

Parameters:

nodeName1 - the name of the first extremity node

nodeName2 - the name of the second extremity node

Returns:

the comment of the arc

isInteger

public final boolean isInteger(java.lang.String nodeName)

Tests if all the values of the specified node are integers.

Parameters:

nodeName - the name of the tested node

Returns:

true if the node values are integers, false otherwise

isBoolean

public final boolean isBoolean(java.lang.String nodeName)

Tests if the specified node is boolean, i.e. its values are equivalent to true and false.

Parameters:

nodeName - the name of the tested node

Returns:

true if the is boolean, false otherwise

isInterval

public final boolean isInterval(java.lang.String nodeName)

Tests if the node is described by a list of consecutives intervals.

Parameters:

nodeName - the name of the tested node

Returns:

true if the node is an interval node, false otherwise

isDecision

public final boolean isDecision(java.lang.String nodeName)

Tests if the node is a decision node.

Parameters:

nodeName - the name of the tested node

Returns:

true if the node is a decision node, false otherwise

isUtility

public final boolean isUtility(java.lang.String nodeName)

Tests if the node is a utility node.

Parameters:

nodeName - the name of the tested node

Returns:

true if the node is a utility node, false otherwise

isConstraint

public final boolean isConstraint(java.lang.String nodeName)

Tests if the node is a constraint node.

Parameters:

nodeName - the name of the tested node

Returns:

true if the node is a constraint node, false otherwise

getValueNumber

public final int getValueNumber(java.lang.String nodeName)

Returns the number of values of the specified node. It can't be used on constraint and utility nodes.

Returns:

the number of values of the node

getStringValues

public final java.lang.String[] getStringValues(java.lang.String nodeName)

Returns an array containing the values of the node as String. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

Returns:

an array containing the values of the node.

getIntValues

public final int[] getIntValues(java.lang.String nodeName)

Returns an array containing the values of the node as integers if the node is an integer node. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

Returns:

an array containing the values of the node.

getIntervals

public final float[][] getIntervals(java.lang.String nodeName)

Returns an array containing the minimum and the maximum of each interval of the node as floats. For each interval, the minimum is at index 0 and the maximum at index 1. It can be used only interval nodes.

Parameters:

nodeName - the name of the node

Returns:

an array containing the minimum and the maximum values of the intervals of the node.

getFormula

public final java.lang.String getFormula(java.lang.String nodeName)

Returns the formula associated to the node as String. If the node doesn't have a formula it return an empty String.

Parameters:

nodeName - the name of the node

Returns:

a String representing the formula of the node

isObserved

public final boolean isObserved(java.lang.String nodeName)

Tests if the specified node is observed. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

Returns:

true if the node is observed or a its likelihood is set, false otherwise

getObservedValue

public final java.lang.String getObservedValue(java.lang.String nodeName)

Returns the observed value of the specified node if the node is observed. Return null if the node is not observed or if its likelihood is set. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

Returns:

the observer value if the node is observed, null if the node is not observed or its likelihood is set

observe

public final boolean observe(java.lang.String nodeName,
                             java.lang.String value)

Observes a value for a node. Return true if the observation succeed. If isObservationValidityEnabled() returns true, it can return false if the observation is not possible, i.e. the posterior probability of the observed value is 0. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node we want to observe

value - the value to observe

Returns:

true if the observation is possible or if the observation validity is disabled, false otherwise

See Also:

isObservationValidityEnabled(), setObservationValidityEnabled(boolean)

observe

public final boolean observe(java.lang.String nodeName,
                             short valueIndex)

Observes a value through its index for a node. Return true if the observation succeed. If isObservationValidityEnabled() returns true, it can return false if the observation is not possible, i.e. the posterior probability of the observed value is 0. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node we want to observe

valueIndex - the index of the value to observe

Returns:

true if the observation is possible or if the observation validity is disabled, false otherwise

See Also:

isObservationValidityEnabled(), setObservationValidityEnabled(boolean)

observe

public final boolean observe(java.lang.String nodeName,
                             float value)

Observes a float value for an interval node only. Return true if the observation succeed. If isObservationValidityEnabled() returns true, it can return false if the observation is not possible, i.e. the posterior probability of the observed value is 0. It can be used only on interval nodes.

Parameters:

nodeName - the name of the interval node we want to observe

value - the value to observe

Returns:

true if the observation is possible or if the observation validity is disabled, false otherwise

See Also:

isObservationValidityEnabled(), setObservationValidityEnabled(boolean)

setLikelihood

public final boolean setLikelihood(java.lang.String nodeName,
                                   java.lang.String value,
                                   double likelihood)

Sets the likelihood for a value of a node (soft evidence). The likelihood must be between 0 and 1. Return true if the operation succeed. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

value - the value of the node

likelihood - the likelihood associated to the given value

Returns:

true if the given likelihood is possible, false otherwise

setLikelihood

public final boolean setLikelihood(java.lang.String nodeName,
                                   short valueIndex,
                                   double likelihood)

Sets the likelihood for a value of a node (soft evidence). The likelihood must be between 0 and 1. Return true if the operation succeed. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

valueIndex - the index of the value of the node

likelihood - the likelihood associated to the given index value

Returns:

true if the given likelihood is possible, false otherwise

getLikelihoods

public final double[] getLikelihoods(java.lang.String nodeName)

Retrieves an array containing the likelihoods associated to the values of a node. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

Returns:

an array containing the likelihood for each value of the node

getLikelihood

public final double getLikelihood(java.lang.String nodeName,
                                  java.lang.String value)

Returns the likelihood associated to a value of a node. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node

value - the value of the node

Returns:

the likelihood of the specified value

unobserve

public final void unobserve(java.lang.String nodeName)

Unobserves the specified node. Resets also the likelihoods. It can't be used on constraint and utility nodes.

Parameters:

nodeName - the name of the node to unobserve

isTemporal

public final boolean isTemporal()

Tests if the network is temporal.

Returns:

true if the network is temporal, false otherwise.

See Also:

getCurrentTime(), resetTime(), increaseTime(), setTime(int)

getCurrentTime

public final int getCurrentTime()

Returns the current time of the network.

Warning: It must be used only if the network is temporal. Please see isTemporal().

Returns:

the current time of the network

See Also:

isTemporal()

resetTime

public final void resetTime()

Resets the time to 0. This method is equivalent to setTime(0).

Warning: It must be used only if the network is temporal. Please see isTemporal().

See Also:

isTemporal(), getCurrentTime(), setTime(int)

increaseTime

public final void increaseTime()

Performs a step of temporal simulation : from getCurrentTime() to getCurrentTime()+1. This method is equivalent to setTime(getCurrentTime()+1).

Warning: It must be used only if the network is temporal. Please see isTemporal().

See Also:

isTemporal(), getCurrentTime(), setTime(int)

setTime

public final void setTime(int time)

Performs a temporal simulation from the current time to the specified time. If the given time is less than the current time, it will restart the simulation from 0. The parameter time must be superior or equal to 0. If time is 0, the method is equivalent to resetTime(). If time equals getCurrentTime()+1, the method is equivalent to increaseTime().

Warning: It must be used only if the network is temporal. Please see isTemporal().

Parameters:

time - the time to reach.

See Also:

isTemporal(), getCurrentTime(), resetTime(), increaseTime()

setInferenceType

public final void setInferenceType(int type)

Sets the type of inference to use. If the parameter is EXACT_INFERENCE a junction tree algorithm will be used otherwise, if the parameter is APPROXIMATE_INFERENCE a likelihood weighting algorithm is used.

Parameters:

type - the type of inference to be used.

See Also:

getInferenceType()

getInferenceType

public final int getInferenceType()

Returns APPROXIMATE_INFERENCE if the inference type is approximate or EXACT_INFERENCE if the inference type is exact.

Returns:

the inference type used.

See Also:

setInferenceType(int)

setSampleSize

public final void setSampleSize(int sampleSize)

Sets the sample size used by approximate inference. It must be superior or equal to 1 and inferior or equal to 1E+8. By default its value is 1000.

Parameters:

sampleSize - the size of samples used by approximate inference.

See Also:

getSampleSize()

getSampleSize

public final int getSampleSize()

Returnss the sample size used to perform the approximate inference.

Returns:

the sample size of approximate inference.

See Also:

setSampleSize(int)

getProbabilities

public final double[] getProbabilities(java.lang.String nodeName)

Return the posterior probabilities associated to the values of the specified node. It can't be used on constraint and utility nodes.

Warning:If isObservationValidityEnabled() returns false and an observation on a node was illegal, the method will return an array with 0 as the probability of each modality.

Parameters:

nodeName - the name of the node

Returns:

an array containing the probabilities of the node

getProbability

public final double getProbability(java.lang.String nodeName,
                                   java.lang.String value)

Returns the probability associated to a specific value of a node. It can't be used on constraint and utility nodes.

Warning:If isObservationValidityEnabled() returns false and an observation on a node was illegal, the method will return 0 as the probability of the modality.

Parameters:

nodeName - the name of the node

value - the value of the node

Returns:

the posterior probability associated to the node

getUtility

public final double[] getUtility(java.lang.String nodeName)

Returns an array containing the minimum utility, the current utility and the maximum utility of a utility node. it can be used only on a utility node.

Warning:If isObservationValidityEnabled() returns false and an observation on a node was illegal, the method will return the minimum utility as the utility of the node.

Parameters:

nodeName - the name of the utility node

Returns:

an array containing the minimum, current and maximum utilities

getQualities

public final double[] getQualities(java.lang.String nodeName)

Returns an array containing the qualities of a decision node. it can be used only on a decision node.

Warning:If isObservationValidityEnabled() returns false and an observation on a node was illegal, the method will return 0 as the qualities of the node.

Parameters:

nodeName - the name of the decision node

Returns:

an array containing the qualities

getMean

public final double getMean(java.lang.String nodeName)

Returns the mean of an interval or an integer node.

Parameters:

nodeName - the name of the numeric node

Returns:

the mean of the node

getStandardDeviation

public final double getStandardDeviation(java.lang.String nodeName)

Returns the standard deviation of an interval or an integer node.

Parameters:

nodeName - the name of the numeric node

Returns:

the standard deviation of the node

close

public final void close()

Method used to close the current instance of APIInference.

WARNING: If you use a license server, this method must be called once you don't need the instance anymore. It allows to release the license on the license server.