NORSYS SOFTWARE © 2012

NETICA API

JAVA VERSION 5.04

norsys.netica
Class Value

java.lang.Object
  |
  +--norsys.netica.Value

public class Value

extends java.lang.Object

The Value object is used to set a variable (node) to a certain value, or to provide uncertain information on the value. Currently the Value class is only used to represent the current findings (evidence) for a node's current value (see Node.finding). In future versions of Netica it may be used to represent the beliefs we hold regarding a Node's value, or it may be used to represent what we calculate to be the value of a Node.

A Value object thus holds the information (partial or exact) concerning the current value of a node's random variable. The Value class has methods allowing you to gather, set, transfer, or clear such information.

There is no public constructor for Value; obtain Values by calling Node.finding.

Since:

2.26

Version:

5.04 - January 21, 2012

Field Summary

static int	GAUSSIAN_VALUE This node's continuous random variable has a gaussian likelihood distribution.
static int	INTERVAL_VALUE This node's continuous random variable is within a range of possible values.
static int	LIKELIHOOD_VALUE This (discrete or discretized) node's random variable abides by a likelihood distribution.
static int	NO_VALUE There is no information on the range of values this node can adopt.
static int	REAL_VALUE This node's continuous random variable is precisely a single real number.
static int	STATE_NOT_VALUE This (discrete or discretized) node is not in one or more of its possible states, and could be in at least two states.
static int	STATE_VALUE This (discrete or discretized) node is in precisely a single one of its states.

Method Summary

void	clear() Removes all the information kept regarding this value.
void	enterCalibration(float[] probs) Currently, for internal use only.
void	enterGaussian(double mean, double stddev) Enters a likelihood finding for this Value object equivalent to a Gaussian distribution (normal distribution) with a mean of mean and a standard deviation of stddev.
void	enterInterval(double lo, double hi) Enters a likelihood finding for this Value object equivalent to an interval extending from low to high: [low, high].
void	enterLikelihood(float[] likelihood) Declares that this discrete or discretized node's random variable abides by the given likelihood distribution.
void	enterReal(double value) Declares that this continuous node has the exact value value.
void	enterState(int stateIndex) Declares that this discrete node is in the state whose index is stateIndex.
void	enterState(java.lang.String stateName) Declares that this discrete node is in the state named stateName.
void	enterStateNot(int stateIndex) Declares that this discrete or discretized node is not in the state with index stateIndex.
int	getKind() Returns the type of information we have on this node's value.
float[]	getLikelihood(float[] lkhds) Returns as a likelihood vector the accumulated (likelihood and other) values entered for this discrete or discretized node.
Node	getNode() Returns the Node that this Value object applies to.
double	getReal() Returns the real-valued finding entered for this node, or UNDEF_DBL if none has been entered since the last retraction (call to clear).
int	getState() Gets the state finding entered for this (discrete or discretized) node.
void	setReal(double value) Same as enterReal(double), only it first clears the node's value (by calling clear).
void	setState(int stateIndex) Same as enterState only it first clears the value (by calling clear).
void	setState(java.lang.String stateName) Same as enterState(String), only it first clears the node's value (by calling clear).

Methods inherited from class java.lang.Object

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

Field Detail

public static final int NO_VALUE

There is no information on the range of values this node can adopt. See getKind.

public static final int REAL_VALUE

This node's continuous random variable is precisely a single real number. See getKind.

public static final int STATE_VALUE

This (discrete or discretized) node is in precisely a single one of its states. See getKind.

public static final int STATE_NOT_VALUE

This (discrete or discretized) node is not in one or more of its possible states, and could be in at least two states. See getKind.

public static final int LIKELIHOOD_VALUE

This (discrete or discretized) node's random variable abides by a likelihood distribution. See getKind.

public static final int GAUSSIAN_VALUE

This node's continuous random variable has a gaussian likelihood distribution. See getKind.

public static final int INTERVAL_VALUE

This node's continuous random variable is within a range of possible values. See getKind.

Method Detail

public void clear ( ) throws NeticaException

Removes all the information kept regarding this value.

This includes definite information (state and real value), negative information, and likelihood information. It removes them from any kind of node, including "constant" nodes.

If this Value object does not have any information, calling this method will have no effect.

If the net is an auto-update net (see setAutoUpdate), and this Value object represents the findings of a node, then a belief updating will be done to reflect the removal of findings, before this method returns (otherwise it will just be done when needed). If you are going to be clearing the findings value for a node, and then entering new findings, sometimes very significant performance gains can be made by ensuring auto-updating is turned off prior to calling this method (see the example of enterState).

Version:

In version 2.26 and later.

See Also:

Net.retractFindings		To remove the findings from all nodes in the net
Node.finding().getKind()		To determine if a node has a finding
Node.finding().enterState(stateIndex)		To enter a state finding for a node
Node.finding().enterStateNot(stateIndex)		To enter a negative finding for a node
Node.finding().enterLikelihood(likelihood)		To enter a likelihood finding for a node
Node.finding().enterReal(value)		To enter a real finding for a continuous node
Node.finding().enterInterval(lo,hi)		To enter an interval finding for a continuous node
Node.finding().enterGaussian(mean,stddev)		To enter a gaussian finding for a continuous node

public void enterCalibration (

float[ ]

probs

) throws NeticaException

Currently, for internal use only.

public void enterGaussian (

double	mean,
double	stddev

) throws NeticaException

Enters a likelihood finding for this Value object equivalent to a Gaussian distribution (normal distribution) with a mean of mean and a standard deviation of stddev.

This will not remove any findings already entered (they will accumulate), so you may want to call clear first.

The node associated with this Value object must be a continuous node (see Node), but discretized.

If this Value object represents the findings for this node, and the net has auto-updating (see setAutoUpdate), then a belief updating will be done to reflect the new finding before this method returns (otherwise it will just be done when needed).

To work with Gaussian distribution CPTs, see setEquation.

Parameters:

double		mean		The mean of the gaussian.
double		stddev		The standard deviation of the gaussian.

Version:

Versions 3.15 and later have this method.
In the C Version of the API, this function is named EnterGaussianFinding_bn.

See Also:

enterInterval		To enter a uniform distribution interval finding
enterState		To specify a specific state
enterReal		To specify a specific real value
enterLikelihood		The most general way to enter node findings
clear		To remove all information entered

Example:

  /**
   *  This method will clear previously entered finding information
   *  before entering new gaussian information.
   */
  public static void setGaussian (Value value, double mean, double stddev) throws NeticaException {
      Node node = value.getNode();
      int netAutoUpdateStateSaved = node.getNet().getAutoUpdate();
      node.getNet().setAutoUpdate (0); // turning it off can greatly aid efficiency
      value.clear();
      value.enterGaussian (mean, stddev);
      if ( netAutoUpdateStateSaved != 0 ) {
          node.getNet().setAutoUpdate (netAutoUpdateStateSaved);
      }
  }

public void enterInterval (

double	lo,
double	hi

) throws NeticaException

Enters a likelihood finding for this Value object equivalent to an interval extending from low to high: [low, high].

The likelihood outside the interval is zero, while inside the interval it is uniform (i.e., a "rectangular distribution").

This will not remove any findings already entered (they will accumulate), so you may want to call clear first.

If the node associated with this Value object is a continuous node (but discretized, see Node), then low and high refer to continuous values the node can take. Then high must be greater than low.

If it is a discrete node, then low and high are state numbers, and so must be integers. In that case, the interval includes both end states (so it is okay if low = high).

If this Value object represents the findings for this node, and the net has auto-updating (see setAutoUpdate), then a belief updating will be done to reflect the new finding before this method returns (otherwise it will just be done when needed).

Parameters:

double		low		The bottom of the range, inclusive.
double		high		The top of the range, inclusive.

Version:

Versions 3.15 and later have this method.
In the C Version of the API, this function is named EnterIntervalFinding_bn.

See Also:

enterState		To specify a specific state
enterReal		To specify a specific real value
enterGaussian		To specify a gaussian distribution finding instead
enterLikelihood		The most general way to enter node findings
clear		To remove all information entered

Example:

  /**
   *  This convenience method will clear previously entered value information
   *  before entering new interval information.
   */
  public static void setInterval (Value value, double lo, double hi ) throws NeticaException {
      Node node = value.getNode();
      int netAutoUpdateStateSaved = node.getNet().getAutoUpdate();
      node.getNet().setAutoUpdate (0); //
      value.clear();
      value.enterInterval (lo, hi);
      if ( netAutoUpdateStateSaved != 0 ) {
          node.getNet().setAutoUpdate (netAutoUpdateStateSaved);
      }
  }

public void enterLikelihood (

float[ ]

likelihood

) throws NeticaException

Declares that this discrete or discretized node's random variable abides by the given likelihood distribution. This means that we are uncertain about the value of the variable, but we have some partial expectation about it being in some of its states.

likelihood is a vector containing one probability for each state of this node.

This node must be a discrete or discretized nature node (i.e., not a constant, utility, or decision node). See Node.getKind().

By calling this method several times, you can combine the effects of several independent partial observations. If you don't want the likelihoods to accumulate, call clear between calls.

The likelihood is equivalent to the following scenario:

There are a number of possible observations you can make: A, B, ... N.

P(B|S_i) denotes the probability of making observation B if the true state of this node is S_i.

L_B is a vector composed of <P(B|S₁), P(B|S₂), ..., P(B|S_m)> where m is the number of states of this node.

You actually make observation B, so you enter the vector L_B as a likelihood finding for this node (or L_A if observation A was made, etc.). You pass it to enterLikelihood as the likelihood parameter.

Notice that each component of a likelihood vector is between 0 and 1 inclusive, they must not all be zero, and they aren't required to sum to 1.

If you enter several accumulating likelihoods for a node, they should correspond to observations that are independent given the value of the node (if not, look up "likelihood finding, not independent" in the manual index).

If this Value object represents the findings for this node, and the net has auto-updating (see setAutoUpdate) turned on, then a belief updating will be done to reflect the new finding before this method returns (otherwise it will just be done when needed).

Parameters:

float[]

likelihood

a set of probabilites, one per state of this node.

Version:

In version 2.26 and later.

See Also:

enterState		To enter a specific state value instead
enterStateNot		To enter a negative state value instead
clear		To remove all information entered

Example:

  /**
   *  This convenience method will clear previously entered likelihood information
   *  before entering new likelihood information.
   */
  public static void setLikelihood (Value value, float[] likelihood ) throws NeticaException {
      Node node = value.getNode();
      int netAutoUpdateStateSaved = node.getNet().getAutoUpdate();
      node.getNet().setAutoUpdate (0); // turning it off can greatly aid efficiency
      value.clear();
      value.enterLikelihood (likelihood);
      if ( netAutoUpdateStateSaved != 0 ) {
          node.getNet().setAutoUpdate (netAutoUpdateStateSaved);
      }
  }

public void enterReal (

double

value

) throws NeticaException

Declares that this continuous node has the exact value value.

If this node is discrete, but has been given a continuous range by calling setLevels, then this method will work; otherwise an exception is thrown.

If this Value object represents the findings for this node, and the net has auto-updating (see setAutoUpdate) turned on, then a belief updating will be done to reflect the new finding before this method returns (otherwise it will just be done when needed).

Parameters:

double

value

The value claimed for this node.

Version:

In version 2.26 and later.

See Also:

setReal		Same, except calls clear first
enterGaussian		To enter a gaussian likelihood distribution for the node
enterInterval		To enter an interval value for the node
clear		To remove all information entered

public void enterState (

int	stateIndex

) throws NeticaException

Declares that this discrete node is in the state whose index is stateIndex.

stateIndex must be between 0 and n - 1 inclusive, where n is the node's number of states.

If this Value object represents the findings for this node, and this node could already have a finding that you wish to override with this new finding, call setState(stateIndex) instead.

If you wish to pass the state by name, see enterState(String).

If this node is a continuous node that has been discretized, this method will work fine, but it is better to use enterReal if the real value is known, for possibly improved accuracywhen equations are involved, the case is saved to file, or the discretization changes.

If this Value object represents the findings for this node, and the net has auto-updating (see setAutoUpdate) turned on, then a belief updating will be done to reflect the new finding before this method returns (otherwise it will just be done when needed).

Parameters:

int

stateIndex

The index of a state of this node.

Version:

In version 2.26 and later.

See Also:

getState		To retrieve the information entered
setState		Same, except calls clear first
enterStateNot		To enter a negative claim about this stateIndex instead
clear		To remove all information entered
Node.getNumStates		stateIndex must be between 0 and one less than this, inclusive
enterLikelihood		To enter a likelihood distribution instead
enterReal		To enter a real value for a continuous node
enterInterval		To enter an interval value for a continuous node
enterGaussian		To enter a gaussian likelihood distribution for a continuous node

Example:

  int saved = node.getNet().getAutoUpdate();        
  node.getNet().setAutoUpdate (0);      // turning it off can greatly aid efficiency
  node.finding().enterState (1);        // claim a finding: node is in state 1.
  getNet().setAutoUpdate (saved);       // restore auto-updating

public void enterState (

String

stateName

) throws NeticaException

Declares that this discrete node is in the state named stateName.

This is a convenience method otherwise identical to enterState(int). See that method for more detailed documentation.

Parameters:

String

stateName

The name of a state of this node.

Version:

In version 2.26 and later.

See Also:

enterState(int)		same, only by state index
enterStateNot(int)		for when the node is not in the state

Example:

  // This method might be useful to enter a finding based on the names
  // of the node and state.
  //
  void enterFinding (Net net, String nodeName, String stateName) throws NeticaException {
      Node node = net.getNode (nodeName);
      node.finding().enterState (stateName);
  }

public void enterStateNot (

int	stateIndex

) throws NeticaException

Declares that this discrete or discretized node is not in the state with index stateIndex.

stateIndex must be between 0 and n - 1 inclusive, where n is the node's number of states.

If this Value object represents the findings for this node, and this node could already have a finding that you wish to override with this new finding, call clear prior to calling this.

If this Value object represents the findings for this node, and the net has auto-updating (see setAutoUpdate) turned on, then a belief updating will be done to reflect the new finding before this method returns (otherwise it will just be done when needed).

Parameters:

int

stateIndex

The index of a state of this node.

Version:

In version 2.26 and later.

See Also:

clear		To remove all information entered
Node.getNumStates		stateIndex must be between 0 and one less than this, inclusive
getLikelihood		To retrieve the information entered as a probability vector for all states
enterState		To enter a positive value instead
enterLikelihood		To enter a likelihood distribution instead

Example:

  // This method enters the negative information by stateName
  public static void enterStateNot (Value value, String stateName){
      int stateIndex = value.getNode().state(stateName).getIndex();
      value.enterStateNot (stateIndex); 
  }

public int getKind ( ) throws NeticaException

Returns the type of information we have on this node's value.

One of the following will be returned:

STATE_VALUE		this (discrete or discretized) node is in one of its states
STATE_NOT_VALUE		this (discrete or discretized) node is not in one or more states
LIKELIHOOD_VALUE		this (discrete or discretized) node can be in each of its states with a certain probability
REAL_VALUE		the continuous random variable is precisely a single real number
INTERVAL_VALUE		the continuous random variable is within an interval of values.
GAUSSIAN_VALUE		the continuous random variable has a gaussian likelihood distribution
NO_VALUE		There is no information on this node's value

Note that just because a value is of a certain kind, does not mean you cannot refer to it as another kind. Netica will attempt to convert between kinds, whereever it is sensible and possible to do so. Thus, even if you had entered a particular state as the finding value of a node, you could ask for the likelihood value and Netica would return a meaningful result, in this case, a distribution with a probability of 1.0 for the the given state, and 0.0 for all others. Or, if the node had been assigned a continuous representation (using Node.setLevels), you could also call getReal and the real value corresponding to that state would be returned.

Version:

In version 2.26 and later.

public float[ ] getLikelihood (

float[ ]

lkhds

) throws NeticaException

Returns as a likelihood vector the accumulated (likelihood and other) values entered for this discrete or discretized node.

Returns a likelihood vector with one entry for each state of this node, indicating the information that has been entered for this node since the last retraction (clear).

If lkhds is not null, it will be filled with the likelihood vector elemnts, and a reference to it will be returned. Otherwise a new array is allocated. If lkhds is not null, it must contain at least as many elements as there are states for this node (see Node.getNumStates).

If a positive state value has been entered, then the likelihood vector will consist of all zero entries, except a nonzero entry for the state corresponding to the one entered. (For more details on likelihood vectors, see enterLikelihood.)

If multiple likelihood and/or negative information has been entered for this node, they will be accumulated in the vector returned.

If no information have been entered for this node since the last retraction (clear), a uniform vector consisting of all 1's is returned. This is consistent with the concept of likelihood, since a likelihood finding which is a uniform vector is equivalent to no finding at all, and will not modify any beliefs.

This method cannot be used on a continuous node, unless the node has first been discretized (see Node.setLevels). If it hasn't, an exception will be thrown.

Parameters:

float[]

lkhds

if not null, this array will be filled with the likelihood vector and returned.

Version:

In version 2.26 and later.

See Also:

enterLikelihood		One way to enter likelihood information
enterState		Another way
enterStateNot		Yet another way
Node.getNumStates		The dimension of the array returned
clear		To remove all information entered

public Node getNode ( )

Returns the Node that this Value object applies to.

Version:

In version 2.26 and later.

public double getReal ( ) throws NeticaException

Returns the real-valued finding entered for this node, or UNDEF_DBL if none has been entered since the last retraction (call to clear).

Call getKind to determine the kind of value a node may have, or whether any has been entered.

Usually this method is for continuous nodes. If this node is not a continuous node, but has been given a levels list, and a discrete finding has been entered, then that finding will be converted to a real-value by the levels list, and the real-value returned (see Node.setLevels for an explanation of the levels list).

If this node is not a continuous node, and doesn't have a levels list defined, then an exception is thrown.

Version:

In version 2.26 and later.

See Also:

getKind		Return what kind of value was previously entered for the node
GetValueExpected		Returns moments of the expected likelihood distribution, if one is available
getInterval		Returns bounds of any interval value previously entered for the node
clear		To remove all information entered

public int getState ( ) throws NeticaException

Gets the state finding entered for this (discrete or discretized) node.

This can be the result of previously entering a definite state finding (with either enterState or setState), or of previously entering information that results in a single state value for this node (say, if repeated calls to enterStateNot or enterLikelihood result in only a single state remaining). If whatever information that has been entered is not consistent with a single positive state value, then an exception is thrown.

Use getKind to determine what kind of information has been entered.

Note that positive findings cannot cancel; if two differing positive findings are entered for a node, an exception is thrown.

If you wish to obtain the actual result of accumulated likelihood or negative findings, use getLikelihood.

This method is for discrete or discretized nodes; if you call it on a continuous node, an exception will be thrown. For continuous nodes, see getKind for how to read the value information.

Version:

In version 2.26 and later.

See Also:

clear		To remove (retract) all information entered for this node
Node.getNumStates		The number returned will be between 0 and one less than this, inclusive
enterLikelihood		To enter a likelihood distribution for a discrete or discretized node
enterReal		To enter a real value for a continuous node
enterState		To enter a state value for a discrete or discretized node
setState		Ditto, except calls clear first
enterStateNot		To enter a negative state value for a discrete or discretized node

public void setReal (

double

value

) throws NeticaException

Same as enterReal(double), only it first clears the node's value (by calling clear).

This is a convenience method that does as follows:

1. It disables auto-updating on this net, if it is set.

2. It calls clear();

3. It calls enterReal (value);

4. It restores auto-updating, if it was originally set.

WARNING: Use this method with caution, since it carries the inherent danger of never allowing you to discover when you have entered inconsistent findings for the node. This is because it always clears previously entered finding information, even when that information is valid. Use enterReal when it is important that you be made aware of such inconsistencies, should they occur.

Parameters:

double

value

The value claimed for this node.

Version:

In version 2.26 and later.

See Also:

enterReal		Enters value, without clearing first (generally to be preferred)
clear		To remove all information entered

Example:

  node.finding().setReal (2.63);  // claim a finding regardless of previous findings: node has value 2.63 
  

public void setState (

int	stateIndex

) throws NeticaException

Same as enterState only it first clears the value (by calling clear).

This is a convenience method that does as follows:

1. It disables auto-updating on this net, if it is set.

2. It calls clear();

3. It calls enterState (stateIndex);

4. It restores auto-updating, if it was originally set.

WARNING: Use this method with caution, since it carries the inherent danger of never allowing you to discover when you have entered inconsistent findings for the node. This is because it always clears previously entered finding information, even when that information is valid. Use enterState when it is important that you be made aware of such inconsistencies, should they occur.

Parameters:

int

stateIndex

The index of a state of this node.

Version:

In version 2.26 and later.

See Also:

getState		To retrieve the information entered
enterState		Same, except doesn't call clear first (generally to be preferred)
clear		To subsequently remove the information entered
Node.getNumStates		stateIndex must be between 0 and one less than this, inclusive
setReal		To set a real value for a continuous node

Example:

  node.finding().setState (1);  // claim a finding,regardless of previous findings: node is in state 1
  

public void setState (

String

stateName

) throws NeticaException

Same as enterState(String), only it first clears the node's value (by calling clear).

This is a convenience method that does as follows:

1. It disables auto-updating on this net, if it is set.

2. It calls clear();

3. It calls enterState (stateName);

4. It restores auto-updating, if it was originally set.

WARNING: Use this method with caution, since it carries the inherent danger of never allowing you to discover when you have entered inconsistent findings for the node. This is because it always clears previously entered finding information, even when that information is valid. Use enterState(stateName) when it is important that you be made aware of such inconsistencies, should they occur.

Parameters:

String

stateName

The name of a state of this node.

Version:

In version 2.26 and later.

See Also:

setState(int)		Same, only by state index
enterState(String)		Same, except doesn't call clear first (generally to be preferred)

Example:

  // This method might be useful to categorically enter a finding, regardless
  // of previous findings, based on the names of the node and state.
  //
  void setFinding (Net net, String nodeName, String stateName) throws NeticaException {
      Node node = ent.getNode (nodeName);
      node.finding().setState (stateName);
  }