| NORSYS SOFTWARE © 2011 | NETICA API | JAVA VERSION 5.02

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.02 - April 8, 2011

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 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 enterCalibration ( |
float[ ] | probs
| ) throws NeticaException

  Currently, for internal use only.

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);
        }

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD