NORSYS SOFTWARE © 2012  NETICA API  JAVA VERSION 5.04 


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: INNER  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object  +norsys.netica.Value
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
.
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 realvalued 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 
public static final int REAL_VALUE 
public static final int STATE_VALUE 
public static final int STATE_NOT_VALUE 
public static final int LIKELIHOOD_VALUE 
public static final int GAUSSIAN_VALUE 
public static final int INTERVAL_VALUE 
Method Detail 
public void clear ( ) throws NeticaException 
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 autoupdate 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 autoupdating is turned off prior to calling this method (see the example of enterState).
Version:
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 ( 
 ) throws NeticaException 
public void enterGaussian ( 
 ) throws NeticaException 
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 autoupdating (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. 
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 
/** * 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 ( 
 ) throws NeticaException 
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 autoupdating (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. 
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 
/** * 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 ( 
 ) throws NeticaException 
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:
P(BS_{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(BS_{1}), P(BS_{2}), ..., P(BS_{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 autoupdating (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. 
enterState  To enter a specific state value instead  
enterStateNot  To enter a negative state value instead  
clear  To remove all information entered 
/** * 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 ( 
 ) throws NeticaException 
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 autoupdating (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. 
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 ( 
 ) throws NeticaException 
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 autoupdating (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. 
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 
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 autoupdating
public void enterState ( 
 ) throws NeticaException 
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. 
enterState(int)  same, only by state index  
enterStateNot(int)  for when the node is not in the state 
// 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 ( 
 ) throws NeticaException 
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 autoupdating (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. 
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 
// 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 
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:
public float[ ] getLikelihood ( 
 ) throws NeticaException 
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. 
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 ( ) 
public double getReal ( ) throws NeticaException 
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 realvalue by the levels list, and the realvalue 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:
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 
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:
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 ( 
 ) throws NeticaException 
This is a convenience method that does as follows:
1. It disables autoupdating on this net, if it is set.
2. It calls clear();
3. It calls enterReal (value);
4. It restores autoupdating, 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. 
enterReal  Enters value, without clearing first (generally to be preferred)  
clear  To remove all information entered 
node.finding().setReal (2.63); // claim a finding regardless of previous findings: node has value 2.63
public void setState ( 
 ) throws NeticaException 
This is a convenience method that does as follows:
1. It disables autoupdating on this net, if it is set.
2. It calls clear();
3. It calls enterState (stateIndex);
4. It restores autoupdating, 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. 
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 
node.finding().setState (1); // claim a finding,regardless of previous findings: node is in state 1
public void setState ( 
 ) throws NeticaException 
This is a convenience method that does as follows:
1. It disables autoupdating on this net, if it is set.
2. It calls clear();
3. It calls enterState (stateName);
4. It restores autoupdating, 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. 
setState(int)  Same, only by state index  
enterState(String)  Same, except doesn't call clear first (generally to be preferred) 
// 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); }


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: INNER  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 