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|Si) denotes the probability of making observation B if the true state of this node is Si.

LB is a vector composed of <P(B|S1), P(B|S2), ..., P(B|Sm)> where m is the number of states of this node.

You actually make observation B, so you enter the vector LB as a likelihood finding for this node (or LA 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);
  }