|
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||
java.lang.Object
|
+--norsys.netica.Generic
|
+--norsys.netica.Node
A node (object which represents a variable) in a Net (Bayesian belief network or decision network).
| Field Summary | |
static int |
CONSTANT_NODE
The value of this node is considered unchanging until the net is rebuilt. |
static int |
CONTINUOUS_TYPE
Node is for a continuous (analog) variable. |
static int |
DECISION_NODE
This node is for a variable that can be controlled by the agent (the "decision" node of an influence diagram). |
static int |
DISCONNECTED_NODE
This node is just a placeholder for a disconnected link, to indicate the type of parent it requires. |
static int |
DISCRETE_TYPE
Node is for a discrete (digital) variable. |
static int |
EVERY_STATE
A "wildcard" state that matches all states of a node. |
static int |
IMPOSS_STATE
Indicates that the state value is irrelevant, because it is for a condition that will never occur. |
static int |
LIKELIHOOD_FINDING
The Node has one or more likelihood findings entered. |
static int |
NATURE_NODE
The value of this node is determined by nature (also known as a "chance" or "deterministic" node). |
static int |
NEGATIVE_FINDING
The Node has one or more negative findings entered. |
static int |
NO_FINDING
The Node has no finding entered. |
static int |
TEXT_TYPE
A future type of Node, one used for holding or rendering text. |
static int |
UNDEF_STATE
Indicates that the state value is unknown or nonexistent. |
static int |
UTILITY_NODE
This node specifies the agent's desires; its expected value will be maximized. |
| Fields inherited from class norsys.netica.Generic |
NAME_MAX |
| Constructor Summary | |
Node()
Default constructor - do not call this constructor directly. |
|
Node(java.lang.String name,
int numStates,
Net net)
Creates and returns a new node for net. |
|
Node(java.lang.String name,
java.lang.String stateNames,
Net net)
Construct a node with the given name and state names, for the given Net. |
|
| Method Summary | |
int |
addLink(Node parentNode)
Adds a link from parentNode to this node, and returns the index of the added link. |
int |
calcState()
Returns the discrete finding entered for this node if one has been entered, or the state calculated from its neighbors if that can be done deterministically (e.g., by equation or function table), or else UNDEF_STATE. |
double |
calcValue()
Returns the real-valued finding entered for this node if one has been entered, or the real value calculated from its neighbors if that can be done deterministically (e.g., by equation or function table), or else UNDEF_DBL. |
void |
delete()
Removes this node from its net, and frees all resources (e.g., memory) it was using. |
void |
deleteLink(int parentLinkIndex)
Delete the link entering this node from the given parent node. |
void |
deleteTables()
Deletes this node's function table, its CPT table, and its experience table. |
Generic |
doc()
Deprecated. |
Generic |
docState(int stateIndex)
Deprecated. |
void |
enterFinding(int stateIndex)
Enters the discrete finding stateIndex for this node. |
void |
enterFinding(java.lang.String stateName)
Enters a finding for this node, that is, declare the node to be in the given state (referenced by state name). |
void |
enterFindingNot(int stateIndex)
Enter a negative finding for this this node, that is, declare that the node is in some state other than the given state. |
void |
enterLikelihood(float[] likelihood)
Enters a likelihood finding for this node, which is a finding that is not completely certain (it is sometimes called "virtual evidence"). |
void |
enterValue(double value)
Enters a real number finding for this node (which is normally a continuous variable node). |
void |
equationToTable(int numSamples,
boolean includeSamplingUncertainty,
boolean addExisting)
Builds the CPT for this node based on the equation that has been associated with it (see setEquation). |
void |
fadeCPTable(double degree)
Smoothes the conditional probabilities (CPT) of this node to indicate greater uncertainty, which accounts for the idea that the world may have changed a little since they were last learned. |
void |
finalize()
Called by the garbage collector, when this node can no longer be referenced. |
float |
getBelief(java.lang.String stateName)
Gets the belief that this node is in the given named state. |
float[] |
getBeliefs()
Returns a belief vector indicating the current probability for each state of this node. |
NodeList |
getChildren()
Returns a list of the children of this node. |
static java.lang.String |
getConstructorClass()
Retrieves the classname of the class that Netica-J uses when constructing a Node. |
static java.lang.String |
getConstructorClassName()
Deprecated. |
float[] |
getCPTable(int[] parentStates,
float[] cpTable)
Returns the conditional probabilities of this node, given that its parents are in the states indicated by the parentStates vector, by looking them up in the node's CPT table. |
float[] |
getCPTable(java.lang.String parentStatesStr,
float[] cpTable)
This does the same as getCPTable(int[], float[]) except that it takes the parent states as a string rather than as an integer array. |
java.lang.String |
getEquation()
Returns the equation associated with this node, or the empty string (rather than null), if this node does not have an equation. |
float[] |
getExpectedUtils()
Returns a vector providing the expected utility of each choice in a decision node, considering findings currently entered. |
double |
getExpectedValue(double[] moments)
Returns the expected real value of this node, based on the current beliefs for this node, and if moments is non-null, moments will be filled with the moments as well. |
double[] |
getExperTable(int[] parentStates,
double[] experTable)
Given parentStates, a vector of states for the parents of this node, this returns the "experience" of the node for the situation described by the parent states. |
int |
getFinding()
Gets the state finding entered for this node, or returns a 'SpecialFinding' code ( one of NO_FINDING, NEGATIVE_FINDING, or LIKELIHOOD_FINDING) if another kind of finding is entered. |
int |
getInputIndex(java.lang.String linkName)
Returns the link index number of the link whose name is linkName, or -1 if there isn't one with that name (case sensitive comparison). |
java.lang.String |
getInputName(int inputIndex)
Gets the name of this node's input (i.e., link) identified by the given index. |
int |
getKind()
Returns whether this node is a nature, decision, utility or constant node. |
double[] |
getLevels()
Returns the list of numbers used to enable a continuous node to act discrete, or enables a discrete node to provide real-valued numbers. |
float[] |
getLikelihood()
Returns the accumulated (likelihood and other) findings for this node as a likelihood vector. |
Net |
getNet()
Returns the net that this node is part of. |
int |
getNumStates()
Returns the number of states that this node can take on, or zero if this node is a continuous node that hasn't been discretized. |
NodeList |
getParents()
Returns a list of the parents of this node. |
double[] |
getRealFuncTable(int[] parentStates,
double[] realTable)
Gets the real value of this node as a function of its parent nodes. |
int[] |
getStateFuncTable(int[] parentStates,
int[] stateTable)
Gets the state value of this node as a function of its parent nodes. |
int |
getType()
Returns DISCRETE_TYPE if the variable corresponding to this node is discrete (digital), and CONTINUOUS_TYPE if it is continuous (analog). |
double |
getValueEntered()
Returns the real-valued finding entered for this node, or UNDEF_DBL if none has been entered since the last retraction. |
VisualNode |
getVisual()
Deprecated. |
boolean |
hasTable(boolean[] complete)
Returns true if this node has a function table or a CPT table, otherwise false. |
boolean |
isBeliefUpdated()
Whether the beliefs for this node have already been calculated (by belief propagation). |
boolean |
isDeterministic()
Whether the value of this node, given its parents, is deterministic (versus probabilistic). |
int[] |
parentStatesToIndexes(java.lang.String parentStateNamesStr)
Utility to convert a comma and/or space delimited string of parent state names for this node to an array of state indexes. |
void |
retractFindings()
Retracts all findings from this node. |
void |
reverseLink(Node parentNode)
Reverses the link from parentNode to this child node, so that instead it goes from this node to parentNode. |
static void |
setConstructorClass(java.lang.String nodeClassNm)
Sets the classname that Netica-J will use to independently construct Nodes. |
static void |
setConstructorClassName(java.lang.String netClassNm)
Deprecated. |
void |
setCPTable(int[] parentStates,
float[] cpTable)
Sets the probabilities for each state of this node, conditioned on its parent nodes. |
void |
setCPTable(java.lang.String parentStateNames,
float[] cpTable)
This does the same as setCPTable(int[], float[]) except that it takes the parent states as a string rather than as an integer array. |
void |
setEquation(java.lang.String eqn)
Sets the equation giving the probability of this node conditioned on its parent nodes, or the value of this node as a function of its parents. |
void |
setExperTable(int[] parentStates,
double experience)
Sets the experience of this node as a function of its parent nodes. |
void |
setInputName(int inputIndex,
java.lang.String inputName)
Sets the name of this node's input (i.e., link). |
void |
setKind(int kind)
Sets whether this node is a nature, decision, utility or constant node. |
void |
setLevels(double[] levels)
Sets the levels list of this node to levels. |
void |
setRealFuncTable(int[] parentStates,
double funcValue)
Sets the real value of this (continuous) deterministic node as a function of its parent nodes. |
void |
setStateFuncTable(int[] parentStates,
int funcState)
Sets the state value of this (discrete or discretized) deterministic node as a function of its parent nodes. |
void |
setStateNames(java.lang.String names)
Names the states of this node using the list of names names. |
State |
state(int stateIndex)
Returns a state of this node. |
State |
state(java.lang.String stateName)
Returns a state of this node. |
void |
switchParent(int linkIndex,
Node newParent)
Switches the parent of the identified link with newParent. |
VisualNode |
visual()
Return the VisualNode object which can be used to control the visual display of this node in Netica Application. |
| Methods inherited from class norsys.netica.Generic |
addListener, eventOccurred, getComment, getEnviron, getName, getNthUserField, getTitle, getUserData, getUserField, removeListener, setComment, setName, setTitle, setUserData, setUserField, toString, user |
| Methods inherited from class java.lang.Object |
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait |
| Field Detail |
public static final int CONTINUOUS_TYPE
public static final int DISCRETE_TYPE
public static final int TEXT_TYPE
public static final int NATURE_NODE
public static final int CONSTANT_NODE
public static final int DECISION_NODE
public static final int UTILITY_NODE
This is a "value" node of an influence diagram. See getKind.
public static final int DISCONNECTED_NODE
public static final int EVERY_STATE
public static final int IMPOSS_STATE
public static final int UNDEF_STATE
public static final int NEGATIVE_FINDING
public static final int LIKELIHOOD_FINDING
public static final int NO_FINDING
| Constructor Detail |
public Node(java.lang.String name,
int numStates,
Net net)
throws NeticaException
If the node is for a discrete variable, pass the number of states it has for numStates.
If the node is for a variable which is continuous in the real world, pass 0 for numStates, even if you plan to later discretize it to a certain number of states (see setLevels for more details).
name will be the name of the new node. It must be different from the names of all other nodes in net (by case-sensitive comparison), and it must be a legal IDname, which means it must have NAME_MAX or fewer characters, all of which are letters, digits or underscores, and it must start with a letter. If name is null, then Netica will pick a unique name for the node; you can discover what name was picked using Generic.getName after the node is formed.
The node will start off as a nature node (kind = NATURE_NODE), but it may be changed by calling setKind.
Parameters:
| String | name | The name of this node. | ||
| int | numStates | The number of states for this node, if this is a discrete node. If it is continuous, then supply 0, even if you plan to later discretize it to a certain number of states. See setLevels. | ||
| Net | net | The net in which the new node is placed. |
| delete | (reverse operation) Removes the node from its net and frees memory it uses | |
| duplicateNodes | Creates nodes by duplicating them, even from another net | |
| setKind | Set what kind of node it is (nature, decision, utility, etc.) | |
| setLevels | The way to set the number of states if the node is for a continuous variable being discretized | |
Generic.setName | Later change the name | |
Generic.setTitle | Label the node without the IDname restriction | |
| getType | Determine if it was created as a continuous variable node | |
| getNumStates | Retrieve numStates | |
Generic.getName | Retrieve name | |
| addLink | Link the new node with others | |
| Net | Create a net for adding nodes |
See setLevels for creating a discretized node for a continuous variable.// Here is how you might make a new node with the 2 states // "true" and "false" using this constructor. Node node = New Node ("n1", 2, net); node.setStateNames("true, false");
public Node(java.lang.String name,
java.lang.String stateNames,
Net net)
throws NeticaException
| String | name | The name of this node. | ||
| String | names | A string of unique stateNames, each separated by a comma and/or space. Each stateName can be no larger than NAME_MAX chararacters. | ||
| Net | parentNet | The net in which the new node will be placed. |
// Here is how you might make a new node with the 2 states "true" and "false".
Node node = New Node ("n1", "true, false", net);public Node()
throws NeticaException
| Method Detail |
public static java.lang.String getConstructorClass()
| setConstructorClass | Set the className to be used for this purpose. |
Node.setConstructorClass("com.myCompany.myProject.MyNode");
where ../com/myCompany/myProject/MyNode.java looks like:
/*
* MyNode.java
*
* Example of how to extend norsys.netica.Node.
*/
package com.myCompany.myProject;
import norsys.netica.*;
public class MyNode extends Node {
int i = 0; // your fields
//------------------------------------------------------------ constructors
public MyNode (String name, int num_states, Net parentNet) throws NeticaException {
super (name, num_states, parentNet);
i = 1;
}
public MyNode (String name, String stateNames, Net parentNet) throws NeticaException {
super (name, stateNames, parentNet);
i = 2;
}
public MyNode() throws NeticaException {
super ();
}
} public static void setConstructorClass(java.lang.String nodeClassNm)
throws NeticaException
If Netica-J has to construct a Node as a part of some operation (where you don't explicitly call a constructor), this is the class it will use. For example, this determines the type of Nodes returned by Net.getNode.
If you would like Netica to use a class other than norsys.netica.Net, say a class of your own that extends norsys.netica.Net, then use this method to tell Netica which class to use. The class must be available on the CLASSPATH, must extend norsys.netica.Node, and must have a default (parameterless) constructor; otherwise a NeticaException will be thrown.
Parameters:
| String | nodeClassNm | The name of a class, available on the CLASSPATH, that is an instance or extension of norsys.netica.Node |
| getConstructorClass | Retrieve the name of the current Class used for this purpose. | |
Net.setConstructorClass | Same for Nets. |
public Net getNet()
| getNodes | (inverse method) Get the list of nodes comprising a net | |
| duplicateNodes | Copy nodes from one net to another | |
| Net | Originally created the net |
public void setStateNames(java.lang.String names)
throws NeticaException
The names must be separated by commas and/or whitespace (i.e. spaces, tabs or newlines). It is okay if there is an extra separator at the end. The number of names must be the number that would be returned by getNumStates.
Each name must be a legal IDname, which means it must have NAME_MAX or fewer characters, all of which are letters, digits or underscores, and it must start with a letter. No two states of a node may have the same name. To avoid these restrictions, you can give the states titles instead; see Generic.setTitle.
It is not required that a node's states be named. If you pass null (not the empty string) for names, it will remove all the state names for this node.
Discretized continuous nodes may have their states named, as well as regular discrete nodes.
Parameters:
| String | names | A comma and/or space delimited set of state names, in index order. |
Generic.setName | Sets name of one state at a time | |
Generic.getName | Retrieves a single state name | |
Generic.setTitle | Doesn't have the restrictions of a name | |
| Node | Sets the number of states to start with | |
| Node(String, String, Net) | Sets the state names as well |
// Here is how you might make a new node with the 2 states
// "true" and "false".
Node node = New Node ("n1", 2, net); // make new node with 2 states
node.setStateNames ("true, false");
//
// Of course, you could do this more easily with the Node constructor
// that sets the state names at construction time
Node node = New Node ("n1", "true, false", net);public int addLink(Node parentNode)
throws NeticaException
This index will be one greater than that of the previously added link, and the existing links will maintain their same indexes.
If this node, the child node, has a table (CPT or function table), its entries are initially duplicated so its values are the same for each possible state of the new parent. In other words, they are independent of the new parent, so that the link from parent to child has no effect on probability computations until the table is changed.
parentNode must be in the same net as this node, or an exception will be thrown, and no action taken.
A warning will be generated (which can be detected by calling getWarnings) if there is already a link from parentNode to this node, or if the added link creates a cycle, but the link will be successfully added. If you don't remove one of the offending links, and later try to compile the net or do node absorption, an exception will be thrown.
Parameters:
| Node | parentNode | The node which will now be one of our parents, and we its child. |
| deleteLink | Removes the link between two nodes | |
| switchParent | Switches parents without changing conditional probabilities | |
| duplicateNodes | Also duplicates all the links between them |
See getWarnings.
public int getNumStates()
throws NeticaException
| Node | Sets the number of states for a discrete node | |
| setLevels | Sets the number and boundaries of discretization for a continuous node | |
Generic.getName |
See the NodeEx.java method nextStates() given in the example for setStateFuncTable.
Also, see the examples in setCPTable.
public void setCPTable(int[] parentStates,
float[] cpTable)
throws NeticaException
The purpose of this method is to build the conditional probability table (CPT) of this node, which provides a probability distribution over the states of this node for each possible configuration of parent states (i.e. parent condition). Each call sets the conditional probabilities of this node for the situation where its parents have the states indicated by the vector parentStates. The length of parentStates must be the number of parents of this node, and each of its entries provides a state for the corresponding parent. The length of the cpTable array must be the number of states of this node, and consist of the conditional probabilities:
P (this node = state0 | parents take on parentStates)
P (this node = state1 | parents take on parentStates)
...
P (this node = stateN | parents take on parentStates)
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
If any entry of parentStates is EVERY_STATE then it applies to all possible values of the corresponding parent. More than one entry of parentStates may be EVERY_STATE, in which case all the probabilities of their cartesian product will be set to cpTable, as you would expect (e.g. see the makeProbsUniform example below).
If this node has many parents (i.e., the product of their number of states is large) then the probability table will be large, and your system may run out of memory, in which case an exception will be thrown.
After changing a node's probabilities, its net must be (re)compiled before calling getBeliefs on any node in the net (although a full recompile isn't necessary, so it will proceed very quickly).
Parameters:
| int[] | parentStates | The indexes of the parent states. | ||
| float[] | cpTable | The probabilities in the same order as our states. |
| getCPTable | Retrieve values | |
| setStateFuncTable | Build the table for a deterministic node | |
| setExperTable | Associate a degree of experience with the probabilities | |
| reviseCPTsByFindings | Revise the probabilities using the case currently entered | |
| reviseCPTsByCaseFile | Revise the probabilities using a file of cases | |
| fadeCPTable | Adjust the probabilities for a changing world |
Example #2:The following method is available in NodeEx.java:/** * Gives the passed node a uniform conditional probability distribution * (i.e. all the probabilities the same). * @param node the node to modify */ static void makeProbsUniform (Node node) throws NeticaException { int numStates = node.getNumStates(); int numParents = node.getParents().size(); float[] uniform = new float[numStates]; int[] pstates = new int[numParents]; for (int st = 0; st < numStates; ++st) uniform[st] = 1.0F / numStates; for (int pn = 0; pn < numParents; ++pn) pstates[pn] = Node.EVERY_STATE; node.setCPTable (pstates, uniform); }
The following method is available in NodeEx.java:/** * Sets all the conditional probabilities of a given node based on an array of probabilities. * You could use this method in combination with getNodeAllProbs (see getCPTable * to temporarily save probability tables. * * @param node is the node whose CPT we are setting * @param probs is an array of probabilities, the first dimension being of size equal to * the size of cartesian product of the states of each parent of node. * The second dimension is the number of states of node. * i.e., double[] probs = new double[ NodeListEx.sizeCartesianProduct (node.getParents()) ] * [ node.getNumStates() ]; */ static void setNodeAllProbs (Node node, float[][] probs) throws NeticaException { NodeList parents = node.getParents(); int[] parentStates = new int[parents.size()]; //all initially zero int probSet = 0; while (true){ node.setCPTable (parentStates, probs[probSet++]); if (NodeListEx.nextStates (parentStates, parents)) break; } }
public void setCPTable(java.lang.String parentStateNames,
float[] cpTable)
throws NeticaException
| String | parentStateNames | A comma and/or space delimited set of parent states, one for each parent. | ||
| float[] | cpTable | The probabilities in the same order as our states. |
| getCPTable | Retrieves values |
public boolean isDeterministic()
throws NeticaException
If this returns true then this node is a deterministic node, which means that: given values for its parents, its value is determined with certainty.
There is no API method to directly set whether a node is deterministic, but setting all its conditional probabilities (i.e. CPT entries) to 0 or 1 will make a node deterministic. Building its table just with setStateFuncTable or setRealFuncTable also will. Note that a node with a deterministic equation can result in a non-deterministic CPT, due to uncertainties introduced in the discretization process.
Version:
| hasTable | Determine if node has any table | |
| setCPTable | To change whether a node is deterministic | |
| getType | To determine if a node is for a discrete or continuous variable | |
| getKind | To determine what kind of node it is |
public int getType()
throws NeticaException
It should be emphasized that the value returned only concerns the underlying physical variable that this node represents, not how this node acts within the net. For example, continuous variables may be discretized by subdividing them into ranges, and discrete variables may provide real values in continuous settings. See setLevels for more information.
In order to determine whether a node may act discrete, call getNumStates, and if the returned value is greater than 0 then the node can act as a discrete node.
There is no API method to change the type of a node; this can only be set when the node is first created by new Node(). A continuous node may be discretized anytime, by using setLevels.
WARNING: This method may return other types in the future, so check the return value completely and act appropriately if it has an unexpected value.
Version:
| getNumStates | To determine if a node can act discrete | |
| setLevels | To discretize a continuous variable, so it may act discrete | |
| Node | Originally sets the value that getType returns | |
| isDeterministic | Return whether a node is deterministically related to its parents | |
| getKind | Whether the node is a nature, decision, utility, constant, etc. |
public boolean hasTable(boolean[] complete)
throws NeticaException
It ignores experience tables.
If complete is non-null and has length > 0, then it's first element is set to indicate whether this node has a complete table (i.e. none of the entries are undefined).
Parameters:
| boolean[] | complete | array for retrieving whether this node has a complete table or not; leave null, if this information is not needed. |
| setCPTable | Create a probabilistic table (CPT) | |
| setStateFuncTable | Create a function table for a discrete node | |
| setRealFuncTable | Create a function table for a continuous node | |
| deleteTables | Remove all the tables of a node |
public int getKind()
throws NeticaException
The value returned will be one of:
| NATURE_NODE | Bayes nets are composed only of this type (and constant nodes). This is a "chance" or "deterministic" node of an influence diagram. | |
| DECISION_NODE | Indicates a variable that can be controlled. This is a "decision" node of an influence diagram. | |
| UTILITY_NODE | A variable to maximize the expected value of. This is a "value" node of an influence diagram. | |
| CONSTANT_NODE | A fixed parameter, useful as an equation constant. When its value changes, equations should be reconverted to CPT tables, and maybe the net recompiled. | |
| DISCONNECTED_NODE | The (virtual) parent node of a link which has been disconnected. |
| setKind | Sets it | |
| isDeterministic | To distinguish between "chance" and "deterministic" nodes | |
| getType | Indicates whether the node is for a discrete or continuous variable |
The following method is available in NodeEx.java:/** * Determines whether a link entering a node is disconnected. * @param linkIndex the index number of the link in question * @param node the node of interest * @returns true, iff the link is disconnected. */ static boolean isLinkDisconnected (int linkIndex, Node node) throws NeticaException { NodeList parents = node.getParents(); Node parent = (Node) parents.get (linkIndex); return (parent.getKind() == Node.DISCONNECTED_NODE); }
public void setKind(int kind)
throws NeticaException
kind must be one of:
| NATURE_NODE | Bayes nets are composed only of this type (and constant nodes) This is a "chance" or "deterministic" node of an influence diagram | |
| DECISION_NODE | Indicates a variable that can be controlled This is a "decision" node of an influence diagram | |
| UTILITY_NODE | A variable to maximize the expected value of This is a "value" node of an influence diagram | |
| CONSTANT_NODE | A fixed parameter, useful as an equation constant When its value changes, equations should be reconverted to CPT tables, and maybe the net recompiled |
You cannot use setKind to change a node to kind DISCONNECTED_NODE. Nodes of that kind are created automatically when switchParent is called with null for the new parent.
Parameters:
| int | kind | The new kind. |
| getKind | Retrieves value | |
| Node | Sets whether node is for a discrete or continuous variable | |
| switchParent | To change a node to kind DISCONNECTED_NODE |
public java.lang.String getInputName(int inputIndex)
throws NeticaException
Returns a string which is the name for input number inputIndex of this node, or the empty string (rather than null) if the link does not have a name. Numbering for inputIndex starts at 0 and proceeds in the same order as parents returned by getParents.
If the name is present, you can count on it to be a legal IDname, which means that it is NAME_MAX or fewer characters (not including terminating 0).
Input names are used to document what each link means, local to the node, which is especially important if the link is disconnected, or if its parents are continuously being switched. They are also useful as local parameters in equations, instead of using the names of parents' nodes, so the equation stays valid even if the parents change.
Parameters:
| int | inputIndex | The index of the input Node whose link name we seek. |
| setInputName | Sets it | |
| getParents | Gets the actual parents of the links | |
| getInputIndex | (inverse method) Returns input index given the name |
public void setInputName(int inputIndex,
java.lang.String inputName)
throws NeticaException
Names the link entering this node from its inputIndexth parent to be inputName.
inputIndex corresponds to the ordering of the parents obtained by getParents (with the first parent having inputIndex = 0). The reason that an index number is passed instead of the actual parent, is because the link may not have a parent node (i.e. it is "disconnected"), or there may be more than 1 link from the same parent to this node.
inputName must be a legal IDname, which means it must have NAME_MAX or fewer characters, all of which are letters, digits or underscores, and it must start with a letter.
To remove the name of a link, pass null (not the empty string) for inputName.
inputName must be different from the name of any other links entering this node (by case-sensitive comparison, and must be different from the names of any parents of this node which are connected to this node by an unnamed link.
Input names are used to document what each link means, local to the node, which is especially important if the link is disconnected, or if its parents are continuously being switched. They are also useful as local parameters in equations, instead of using the names of parent nodes, so the equation stays valid even if the parents change.
When links are first created, they are unnamed, and remain so until this method is called, or until they are disconnected from the parent node (in which case they take on the name of the parent). It is possible to name some of the links entering a node, and leave the rest unnamed. All disconnected links are named.
Parameters:
| int | inputIndex | The index of the desired input Node. | ||
| String | inputName | The the desired new name to assign this input link. |
| getInputName | Retrieves value | |
| getInputIndex | Retrieves the index given the name | |
| getParents | Gets the actual parents of the links (e.g. to find their names or determine their numbering) | |
| switchParent | Connects the "input" to a parent node |
public void finalize()
throws NeticaException
If in your application the native node associated with this node will no longer needed when this node is to be garbage collected, then you may wish to override this method and call delete in your finalize() method.
You may, however, wish to call it directly to ensure or hasten the freeing of native resources.
If you do override this method, be sure to call the base class method (super.finalize();).
See Also:
| delete | Frees the native resources used by this node |
finalize in class java.lang.Objectpublic void delete()
throws NeticaException
If this node has children, they will end up with disconnected links for parents, and the names of these links (if they weren't already named) will become the name of this node. If this node has parents, then links from them will simply be removed.
If a complete net is to be disposed of, use Net.finalize instead.
Version:
| Node | (Inverse operation) Creates a new node in a net | |
| absorb | Maintains joint distribution while removing | |
Net.finalize | Deletes all the nodes of a net |
The following method is available in NodeListEx.java:/** * Removes all the nodes in nodeList from their net, and deletes them. * @param nodeList the nodes to delete */ static void deleteNodes (NodeList nodeList) throws NeticaException { while (nodeList.size() > 0) { Node node = (Node) nodeList.remove (0); node.delete(); } }
public NodeList getParents()
throws NeticaException
The order of the list is significant. Numbering each node in the list (starting from 0) provides a numbering for the links entering this node, which is used by some other methods.
If there are several links from the same parent to this node, then in the list returned that parent will be repeated once for each link.
To obtain the number of links entering this node, use the length of the returned list.
Version:
| getChildren | Gets a list of the children | |
| java.util.Vector.length() | Use on returned list to find the number of parents | |
| getInputName | ||
| addLink | Add a parent | |
| deleteLink | Remove a parent | |
| switchParent | Switch one of the parents for a different one | |
| getKind | To determine if a link is disconnected (returns DISCONNECTED_NODE) | |
public NodeList getChildren()
throws NeticaException
If there are several links from this node to the same child, then that child will appear only once in the list returned, so the length of the returned list may be used to provide the number of unique children of this node.
Consecutive calls to this method may yield lists in different orders.
Version:
| getParents | Get a list of the parents | |
| addLink | Create a new child | |
| deleteLink | Remove a child |
public void deleteLink(int parentLinkIndex)
throws NeticaException
parentLinkIndex should be 0 for the first parent, and must be less than the number of links entering this child (the parent ordering is given by getParents).
It is often more useful to be able to delete a link by specifying the 2 nodes it connects. In order to do this use the method deleteLink defined in the example below.
If this child has a CPT or function table, it is collapsed as if the removed parent were taking on its first state (state = 0), unless there is a positive finding entered for the parent, in which case it is collapsed with the parent taking on the finding state.
WARNING: When a link is deleted, keep in mind that the numbering of subsequent links changes. For example, to delete all the links entering a node, use the method "DeleteLinksEntering" example below, not: for (pn = 0; pn < numParents; ++pn) DeleteLink (pn);
WARNING: Keep in mind that after deleting a link into node child, any list of parent nodes for child that was previously returned by getParents is no longer valid.
Parameters:
| int | parentLinkIndex | The index of the parent Node whose link we wish to remove. |
| addLink | Adds a link between two nodes | |
| switchParent | Switches parents without changing conditional probabilities (can be used to disconnect link instead of deleting) |
Example #2:The following method is available in NodeEx.java:/** * Removes the single link from node 'parent' to node 'child'. * If there is no link from 'parent' to 'child', or more than one, it generates an error. * @param parent the parent node * @param child the child node */ static void deleteLink (Node parent, Node child) throws NeticaException { NodeList parents = child.getParents(); int index = parents.indexOf (parent); child.deleteLink (index); }
// Removes all links entering node child
// See deleteLink comment for explanation
//The following method is available in NodeEx.java:
/**
* Removes all links entering node child
* See the deleteLink comment for explanation
* @param child the child node
*/
static void deleteLinksEntering (Node child) throws NeticaException {
NodeList parents = child.getParents();
int numParents = parents.size();
for (int pn = 0; pn < numParents; ++pn)
child.deleteLink (0);
} public double[] getLevels()
throws NeticaException
Returns null if this node does not have a levels list.
Since the usage of levels is a little different for each type of node, each is discussed separately:
this node is continuous: ( getType would return DISCRETE_TYPE)
The length of the list returned is one more than the number of states of this node. The node is discretized into states, and the list returned has the thresholds (monotonically increasing or decreasing). Each range is from levels[state] to levels[state+1]., where levels is the list returned. Normally each interval includes its lower endpoint, but not its upper.
this node is discrete: ( getType would return CONTINUOUS_TYPE)
The length of the list returned is the number of states of this node, with each element being the real number associated with the corresponding state.
Version:
| setLevels | Sets them | |
| getNumStates | Length of the vector returned (plus one if this node continuous) |
public void setLevels(double[] levels)
throws NeticaException
The levels list is a list of real numbers used by Netica to translate from a real value of a continuous node to a discrete state, or from a state of a discrete node to a real value. That way a continuous node can act discrete (called "discretization"), or a discrete node can provide real-valued numbers.
If the underlying variable is continuous, we may want to discretize it for some operations. For example, we may divide all possible masses of some object into 3 ranges: 0 to 0.1 kg, 0.1 to 10 kg, and greater than 10 kg. For that we would use the levels list: [0, 0.1, 10, INFINITY].
Conversely, if it is discrete, we may want a mapping from its state (represented as an integer), to a measurable value. For example, a drill may have 3 speeds (2.5 rps, 5 rps and 10 rps) as well as off. We could use a 4-state discrete node to represent the drill speed, with the levels list [0, 2.5, 5, 10]. Or milk may be available in containers of size 0.375, l, and 2 liters.
Since the usage of levels is a little different for each type of node, each is discussed separately:
this node is continuous: ( getType would return DISCRETE_TYPE)
For numStates pass the number of ranges to discretize the node into. It must be zero or greater (if it is zero, then levels must be null, and any current discretization will be removed).
levels must contain numStates + 1 entries, and must monotonically ascend or descend (it is okay to have adjacent entries equal to create point-valued "ranges").
The first and last entries of the levels list provide a bound on the lowest and highest values the node can take on, but they may be INFINITY or - INFINITY.
Once this node has been given the levels list, Netica can translate a continuous value val for the node to a discrete state st, by choosing st so that:
levels [st] <= val < levels [st + 1] (if levels ascends) or
levels [st] > val >= levels [st + 1] (if levels descend)
A discrete state st can also be translated to the range:
[levels[st], levels[st + 1]) (if levels ascends) or
[levels[st + 1], levels[st]) (if levels descend)
this node is discrete: ( getType would return CONTINUOUS_TYPE)
There must be one entry in levels for each state of this node. The value passed for numStates must be the number of states of the node (i.e. the value returned by getNumStates). There is no constraint on the ordering of levels.
Once this node has been given the levels list, Netica can convert a discrete state st to a real-valued number val, using:
val = levels [st]
A real-number value val can also be translated to a discrete state st by choosing st so that: val = levels [st]. If there is no such st, then a legal translation cannot be made, but sometimes you can request Netica to approximate by choosing st so that:
| val - levels [st] | is minimized.
Parameters:
| double[] | levels | The new levels to be assigned to all this node's states. |
| getLevels | Retrieves values | |
| Node | Must be called with numStates = 0 to make continuous node | |
| enterValue | Uses discretization to convert to state finding | |
| equationToTable | Uses discretization to handle continuous values in the table | |
| getExpectedValue | Uses discretization or real values to calculate mean and standard deviation |
// Here we make a continuous node and then discretize it into
// 3 states.
//
Node node = new Node ("n1", 0, net); // must pass 0 for num_states to create a node
for a continuous variable
double[] levels = new double[4]; // 1 more than the number of desired states
levels[0] = 0.0; // the first range is 0 to 0.1
levels[1] = 0.1;
levels[2] = 10.0;
levels[3] = Environ.INFINITY;
node.setLevels(levels); // discretizes to 3 states
node.setStateNames("low, medium, high"); // naming the states is optional
Example #2:
// Here we make a 3-state discrete node and then give it
// levels to provide real values to its children.
//
Node node = new Node ("voltSwitch", 3, net); // discrete, with 3 states
double[] levels = new double[3]; // 1 element for each state
levels[0] = 0.0;
levels[1] = -3.5; // state 1 gives -3.5
levels[2] = 5.5;
node.setLevels(levels); // set the levels
node.setStateNames("off, reverse, forward"); // naming the states is optionalpublic void switchParent(int linkIndex,
Node newParent)
throws NeticaException
Makes node newParent a parent of this node by replacing the existing parent at the linkIndexth position, without modifying this node's equation, or any of this node's tables (such as CPT table or function table).
The new parent must be compatible with the old (e.g. same number of states), or an explanatory exception will be thrown, and no action taken.
null can be passed for newParent, in which case the corresponding link will not be removed, but will become disconnected. If that link was not already named, then its name will become the name of the parent it was disconnected from. To determine whether a link is disconnected, see getKind.
If the link was disconnected, this method may be used to re-connect it, by passing non-null for newParent.
The parents of this node are numbered from 0 to one less than the number of parents, and the ordering can be obtained using getParents. Sometimes it is more useful to be able to pass a parent node instead of linkIndex, if you know there is exactly one link from the parent node to child. This can be accomplished with the SwitchNodeParent example below.
Parameters:
| int | linkIndex | The index of the parent Link we want to change. | ||
| Node | newParent | The new node to be assigned to that link index. |
| getParents | Can be used to determine a suitable value for linkIndex | |
| addLink | Adds a link between two nodes | |
| deleteLink | Removes a link between two nodes | |
| getKind | To determine if a link is disconnected (returns DISCONNECTED_NODE) |
// Switches the link from parent -> child to go from new_parent -> child.
// Assumes there is already exactly one link from parent to child.
//
static void switchNodeParent (Node parent, Node child, Node newParent) throws NeticaException {
NodeList parents = child.getParents();
int linkIndex = parents.indexOf (parent);
child.switchParent (linkIndex, newParent);
}public java.lang.String getEquation()
throws NeticaException
For information on Netica equations, see the "Equation" chapter of Netica Application's onscreen help.
Version:
| setEquation | Sets it | |
| equationToTable | If this hasn't been done, equation may not match CPT table |
public void setEquation(java.lang.String eqn)
throws NeticaException
The equation can be deterministic, so that it specifies a value for this node, given values for its parents (i.e. it expresses this node as a function of its parents). Or, it can be probabilistic, so that it provides a probability for each of this node's values (i.e. a probability distribution), as a function of its parents.
For information on Netica equations, see the "Equation" chapter of Netica Application's onscreen help.
WARNING: Setting a node's equation does not modify its CPT table (which is what is used for inference in a compiled net). To modify the CPT table so that it reflects the new equation, use equationToTable.
To remove a node's equation, pass null or the empty string for eqn.
There is no restriction on the length or complexity of the equation.
Parameters:
| String | eqn | The equation string to be assigned. |
| getEquation | Retrieves value | |
| equationToTable | Required to convert the equation to a CPT table for inference |
public void equationToTable(int numSamples,
boolean includeSamplingUncertainty,
boolean addExisting)
throws NeticaException
numSamples is the number of samples to make per parent condition. The higher the number, the more accurate the conversion will be, but the longer it will take. If this node and its parents are discrete, then it only takes one sample to generate an exact probability, and so in that case this argument is ignored.
includeSamplingUncertainty indicates whether to include in the generated probability table the uncertainty due to the sampling process or not. If the equations are simple (don't have narrow spikes), and the value passed for numSamples is high enough, it is better to make this argument false, so that the CPT entries for 'impossible' are zero, rather than close to zero. Otherwise make it true.
Normally you pass false for addExisting, but you can pass true if you wish the new sampling to be added to the table which already exists. If the equation conversion to table is nondeterministic (i.e. requires sampling), then calling this method twice with addExisting = true is equivalent to calling it once with a value of numSamples twice as large. So you can increase the accuracy of the conversion in small steps by repeatedly calling with addExisting = true. Or if you want to blend equations (say you want to indicate a 30% chance of equation 1 and a 70% chance of equation 2), you can call it twice, first setting equation 1 and using numSamples = 3, then setting equation 2 and using numSamples = 7. Similarly, you can blend equations with learned probabilities (see reviseCPTsByCaseFile), and those entered manually with setCPTable and setExperTable.
Parameters:
| int | numSamples | The number of samples to make per parent condition. | ||
| boolean | includeSamplingUncertainty | Whether to include in the generated probability table the uncertainty due to the sampling process or not | ||
| boolean | addExisting | Whether you wish the new sampling to be added to the table which already exists. Normally false. |
| setEquation | . | |
| getEquation | . | |
| getCPTable | Retrieve the table, if its probabilistic | |
| getStateFuncTable | Retrieve the table, if its deterministic discrete | |
| getRealFuncTable | Retrieve the table, if its deterministic continuous |
public float[] getCPTable(int[] parentStates,
float[] cpTable)
throws NeticaException
P (this node = state0 | parents take on parentStates)
P (this node = state1 | parents take on parentStates)
...
P (this node = stateN | parents take on parentStates)
Notice that it is not conditioned on any findings (evidence) entered into the net, so its value will not change as findings are added or belief updating is done.
null will be returned if no CPT table has been associated with this node (for example by setCPTable, setStateFuncTable, equationToTable, reviseCPTsByCaseFile or reviseCPTsByFindings), or if the table has been removed (for example by deleteTables), but no exception will be thrown. If you use only setEquation to indicate a node's relation with its parents, you must also call equationToTable before this will return non-null.
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
parentStates should not include EVERY_STATE or UNDEF_STATE.
If setStateFuncTable was used to provide this node with a function table, then getCPTable can be used to retrieve that table in the form of conditional probabilities, which will all be 0 or 1.
To get all the conditional probabilities of this node at once, see the GetNodeAllProbs example below.
If you will be regularly calling this method on this node, then you may wish to re-use the array to be filledbt supplying it as parameter cpTable, in order to avoid the continuous allocation of new memory. If cpTable is null or too small, then a new array will be allocated and returned.
Parameters:
| int[] | parentStates | An array of state indexes (one per parent) for which the Conditional Probabilities are desired. | ||
| float[] | cpTable | An array to be reused and filled with the probabilities. May be null, in which case a new array will be allocated and returned. Otherwise, it should have at least as many elements as the number of states of this node. If it does not, then a new array will be allocated and returned. |
| setCPTable | Sets them | |
| hasTable | Determine if getCPTable is going to return null | |
| getBeliefs | Conditioned on findings, but not parents | |
| absorb | Can be used to find probabilities conditioned on parents and findings | |
| getStateFuncTable | For deterministic nodes | |
| getExperTable | The confidence of the probabilities obtained | |
| getParents | Indicates the order of entries in parent_states | |
| getNumStates | Length of the array returned (plus one if node continuous) |
// To just get the probability that node is in state, given parentStates // double prob = node.getCPTable(parentStates) [state];Example #2:
// Puts all the conditional probabilities of node into the array probs. // You could allocate probs as follows // // double[] probs = new double[ NodeListEx.sizeCartesianProduct (node.getParents()) ] [ node.getNumStates() ]; // static void getNodeAllProbs (Node node, float[] probs) throws NeticaException { NodeList parents = node.getParents(); int numStates = node.getNumStates(); int[] parentStates = new int[parents.size()]; //initially all zero int probSet = 0; while (true){ float[] vecp = node.getCPTable (parentStates); if (vecp == null) break; for (int st = 0; st < numStates; ++st) probs[probSet][st] = vecp[st]; if (NodeListEx.nextStates (parentStates, parents)) break; ++probSet; } }
public int[] getStateFuncTable(int[] parentStates,
int[] stateTable)
throws NeticaException
If stateTable is not null it will be used to hold the returned value, rather than allocate a new array, and it will be the array reference returned.
This is for discrete or discretized nodes that are deterministic. Given a vector of states for the parents of this node, this returns the state of this node (which is functionally determined by the parent values) by looking it up in the nodes function table. If the function table between this node and its parents has not yet been created, or if it is probabilistic (i.e. a CPT) rather than deterministic, this returns UNDEF_STATE, without generating an error.
If this node is continuous, and not discretized, an exception will be thrown (use getRealFuncTable instead).
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
If the node has been given a deterministic equation with setEquation, you must call equationToTable before this can be used to retrieve values (if you needed to find values without generating the whole table you would enter findings for the parents, and use calcState).
If this node is a decision node in a decision net which has been compiled, and belief propagation has been done by calling getExpectedUtils on this node, then this method can be used to read out the table of optimal decisions under the different scenarios indicated by parentStates.
If setCPTable was used to provide this node with conditional probabilities that were all 0 or 1, getStateFuncTable can be used to retrieve the deterministic state of this node as a function of its parents.
This method ignores any findings entered in the net.
Parameters:
| int[] | parentStates | An array of state indexes (one per parent) with which to compute our function state. | ||
| int[] | stateTable | An array to be reused and filled with the state values. May be null, in which case a new array will be allocated and returned. Otherwise, it should have at least one element. If it does not, then a new array will be allocated and returned. |
| setStateFuncTable | Sets it | |
| getRealFuncTable | Same, but returns real value instead of state integer | |
| isDeterministic | To check if this method is applicable | |
| getCPTable | For nondeterministic discrete nodes |
//Here is a convenience method taking parentStates as a comma and/or space delimited string.
public int[] getStateFuncTable (String parentStatesStr) throws NeticaException {
return getStateFuncTable (parentStatesToIndexes (parentStatesStr), null);
}public void setStateFuncTable(int[] parentStates,
int funcState)
throws NeticaException
For deterministic nodes that are discrete or discretized. Deterministic nodes can be expressed as a function of their parent nodes, and that function can be in the form of a table. The purpose of setStateFuncTable is to build that table. It adds an entry to the table by telling Netica that when each parent has the state indicated in the vector parentStates, the state of this node is funcState.
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
If any entry of parentStates is EVERY_STATE then it applies to all possible values of the corresponding parent (see setCPTable).
If this node has many parents (i.e., the product of their number of states is large) then the function table will be large, and your system may run out of memory.
Parameters:
| int[] | parentStates | An array of state indexes (one per parent). | ||
| int | funcState | The state value to be assigned to this node when the parents are in the given states. |
| getStateFuncTable | Retrieves values | |
| setRealFuncTable | Same, but builds real-valued tables instead of discrete tables | |
| setCPTable | To use instead if this node isn't deterministic |
// This method is similar to setNodeProbs(); see the comment for it.
// int[] value = new int[ NodeListEx.sizeCartesianProduct (node.getParents()) ];
void setNodeFuncState (Node node, int[] value){
NodeList parents = node.getParents();
int[] parentStates = new int[parents().size()]; //all initially zero
int probSet = 0;
while (true){
node.setStateFuncTable(parentStates, value[probSet++]);
if (NodeListEx.nextStates (parentStates, parents)) break;
}
}
Example #2:
// This doesn't use setStateFuncTable, but it is useful for setting
// parentStates.The following method is defined in NodeListEx.java:
/**
* This cycles through all possible configurations (i.e. elements of the cartesian
* product) of states, odometer style, with the last state changing fastest.
* states is a list of node states, one for each node of nodeList.
* It returns 'true' when all the configurations have been examined (i.e., when it
* "rolls over" to all zeros again).
* Don't forget to initialize states before calling it the first time (usually
* to all zeros).
* @param states A set of state indices, one per node in nodeList, and in the same
* order as the nodes in nodeList.
* @param nodeList A set of nodes, whose states are to be cycled through.
*/
public static boolean nextStates (int[] states, NodeList nodeList) throws NeticaException {
int n;
for (n = nodeList.size() - 1; n >= 0; n--){
Node node = (Node) nodeList.get(n);
if (++states[n] < node.getNumStates())
return false;
states[n] = 0;
}
return true;
}
Example #3:
//Here is a convenience method taking parentStates as a comma and/or space delimited string.
public void setStateFuncTable (String parentStatesStr, int funcState) throws NeticaException {
setStateFuncTable (parentStatesToIndexes (parentStatesStr), funcState);
}public double[] getRealFuncTable(int[] parentStates,
double[] realTable)
throws NeticaException
If realTable is not null it will be used to hold the returned value, rather than allocate a new array, and it will be the array reference returned.
This is for deterministic nodes that are continuous or have been given real levels (e.g., by setLevels). Given a vector of states for the parents of this node, this returns the real value of this node (which is functionally determined by the parent values) by looking it up in the nodes function table. If the function table between this node and its parents has not yet been created, or if it is probabilistic (i.e. a CPT) rather than deterministic, this returns UNDEF_DBL, without generating an error.
If this node is discrete, with no real levels defined, an exception will be thrown (use getStateFuncTable instead).
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
If the node has been given a deterministic equation with setEquation, you must call equationToTable before this can be used to retrieve values (if you needed to find values without generating the whole table you would enter findings for the parents, and use calcValue).
This method ignores any findings entered in the net.
Parameters:
| int[] | parentStates | An array of state indexes (one per parent) with which to compute and return our real function value. | ||
| double[] | realTable | An array to be reused and filled with the real values. May be null, in which case a new array will be allocated and returned. Otherwise, it should have at least one element. If it does not, then a new array will be allocated and returned. |
| setRealFuncTable | Sets them | |
| getStateFuncTable | Same, but returns state integer instead of real value | |
| isDeterministic | To check if this method is applicable |
//Here is a convenience method taking parentStates as a comma and/or space delimited string.
public int[] getRealFuncTable (String parentStatesStr) throws NeticaException {
return getRealFuncTable (parentStatesToIndexes (parentStatesStr), null);
}public void setRealFuncTable(int[] parentStates,
double funcValue)
throws NeticaException
This is for deterministic nodes that are continuous or have been given real levels (e.g. by setLevels). Deterministic nodes can be expressed as a function of their parent nodes, and that function can be in the form of a table. The purpose of setRealFuncTable is to build that table. It adds an entry to the table by telling Netica that when each parent has the state indicated in the vector parentStates, the value of this node is funcValue.
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
If any entry of parentStates is EVERY_STATE then it applies to all possible values of the corresponding parent (see setCPTable).
If node has many parents (i.e., the product of their number of states is large) then the function table will be large, and your system may run out of memory.
Parameters:
| int[] | parentStates | An array of state indexes (one per parent). | ||
| double | funcValue | The value to be assigned to this node when the parents are in the given states. |
| getRealFuncTable | Retrieves values | |
| setStateFuncTable | Same, but builds state integer tables instead of real-valued tables | |
| setCPTable | To use instead if this node isn't deterministic |
// This method is similar to setNodeProbs(); see the comment for it.
// double[] value = new double[ NodeListEx.sizeCartesianProduct (node.getParents()) ];
void setNodeFuncState (Node node, double[] value){
NodeList parents = node.getParents();
int[] parentStates = new int[parents().size()]; //all initially zero
int probSet = 0;
while (true){
node.setRealFuncTable(parentStates, value[probSet++]);
if (NodeListEx.nextStates (parentStates, parents)) break;
}
}
Example #2:
//Here is a convenience method taking parentStates as a comma and/or space delimited string.
public void setRealFuncTable (String parentStatesStr, double funcValue) throws NeticaException {
setRealFuncTable (parentStatesToIndexes (parentStatesStr), funcValue);
}public double[] getExperTable(int[] parentStates,
double[] experTable)
throws NeticaException
If experTable is not null it will be used to hold the returned value, rather than allocate a new array, and it will be the array reference returned.
The experience is also known as the "number of cases", ess, or estimated sample size.
If no experience value has been assigned to this parent configuration (either by learning or setExperTable), then UNDEF_DBL is returned, without generating an error.
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
Parameters:
| int[] | parentStates | An array of state indexes (one per parent) with which to compute and return our experience value. | ||
| double[] | experTable | An array to be reused and filled with the experience values. May be null, in which case a new array will be allocated and returned. Otherwise, it should have at least one element. If it does not, then a new array will be allocated and returned. |
| setExperTable | Sets them | |
| getCPTable | Get the corresponding probability vector | |
| reviseCPTsByFindings | Increments experience | |
| reviseCPTsByCaseFile | Experience will measure the number of cases with each parent configuration |
//Here is a convenience method taking parentStates as a comma and/or space delimited string.
public int[] getExperTable (String parentStatesStr) throws NeticaException {
return getExperTable (parentStatesToIndexes (parentStatesStr), null);
}public void setExperTable(int[] parentStates,
double experience)
throws NeticaException
This is to associate a degree of experience with each belief vector of this node's conditional probability table. It sets the amount of experience for the condition described by parentStates (which provides a value for each parent) to experience.
The order of the states in parentStates should match the order of the nodes in the list returned by getParents (this will be the same order that parents were added using addLink). parentStates can be null if this node has no parents.
If any entry of parentStates is EVERY_STATE then it applies to all possible values of the corresponding parent (see setCPTable).
Parameters:
| int[] | parentStates | An array of state indexes (one per parent). | ||
| double | experience | The experience value to be assigned to this node when the parents are in the given states. |
| getExperTable | Retrieves values | |
| reviseCPTsByFindings | Increments experience | |
| reviseCPTsByCaseFile | Sets experience to measure the number of relevant cases | |
| fadeCPTable | Decreases experience, and smoothes the probabilities | |
| setCPTable | Sets corresponding CPT table entry |
//Here is a convenience method taking parentStates as a comma and/or space delimited string.
public void setExperTable (String parentStatesStr, double experience) throws NeticaException {
setExperTable (parentStatesToIndexes (parentStatesStr), experience);
}public void fadeCPTable(double degree)
throws NeticaException
degree must be between 0 and 1, with 0 having no effect and 1 creating uniform distributions with no experience. Calling fadeCPTable once with degree = 1-d, and again with degree = 1-f, is equivalent to a single call with degree = 1-df.
The global variable BaseExperience is used in the calculation as shown below. It's value should be the same as it was when the learning from cases was done (if it was). It must be greater than 0, and the most common value for it is 1 (1/2 is also commonly used). You will normally set it to one of these choices, depending on your philosophy, and leave it that way permanently.
Each of the probabilities in the node's conditional probability table is modified as follows (where prob and exper are the old values of probability and experience, and prob' and exper' are the new values):
prob' = normalize (prob * exper - (prob * exper - BaseExperience) * degree)
prob' = normalize (prob * exper * (1 - degree) + degree * BaseExperience)
exper' is obtained as the normalization factor from above. So:
prob' * exper' = prob * exper * (1 - degree) + degree * BaseExperience
When learning in a changing environment, you would normally call fadeCPTable every once in a while, so that what has been recently learned is more strongly weighted than what was learned long ago. If an occurrence time for each case is known, and the cases are learned sequentially through time, then the amount of fading to be done is:
degree = 1 - rDt where Dt is the amount of time since the last fading was done, and r is a number less than, but close to, 1 and depends on the units of time and how quickly the environment is changing. See the example below.
Parameters:
| double | degree | The amount by which to fade the probability tables; 0.0 <= degree <= 1.0 |
| reviseCPTsByFindings | This also contains a 'degree', which can be used to weight the impact of learning a case |
// The following does the same fading for a list of nodes:
//
static void fadeCPTsForNodes (NodeList nodes, double degree) throws NeticaException {
for (int n = 0; n < nodes.size(); ++n){
Node node = (Node) nodes.get(n);
node.fadeCPTable (degree);
}
}
Example #2:
// The following bit of code may be executed in a loop which is
// traversed as the cases are learned, in order to do the
// required fading:
// time - the occurrence time of the last case learned
// lastTime - a number initialized to the time of the 1st case
// minDelay - a number controlling how often fading is done
// rate - a number determining how much fading is done
// net - the net being learned
if ((time - lasttime) >= minDelay){
double degree = 1.0 - Math.pow (rate, (double) (time - lasttime));
fadeCPTsForNodes (net.getNodes(), degree);
lasttime = time;
}
public void deleteTables()
throws NeticaException
It does not modify this node's equation or its links.
Version:
| hasTable | Determine if a node currently has a table | |
| deleteLink | Reduce the number of parents of the node | |
| setStateFuncTable | Give a node a function table with its parents | |
| setCPTable | Give a node a probabilistic table (CPT) with its parents | |
| Node | Creates a new node without any tables |
public void reverseLink(Node parentNode)
throws NeticaException
This is a special method which maintains the joint probability represented by the net, which means any subsequent inference will yield the same results. To do so, Netica may have to add or remove links which go to parentNode from the parents of this node, or which go to this node from the parents of parentNode. If this is not desired then use deleteLink, followed by an addLink in the reverse direction. That will change the overall joint probability, and even change the independence information represented by the net.
If links are added, the CPT tables may become very large, possibly resulting in slow behavior or an out-of-memory condition.
If it is not possible to do the reversal, an exception will be thrown, and the net will not be changed. Reasons it might not be possible include: reversing the link would create a directed cycle, the child or parent node is not a nature node, the link is a time-delay link, the link is disconnected, or the child node has some other disconnected link.
Parameters:
| Node | parentNode | The parent whose link to us will be reversed. |
| getParents | See what links Netica has added or removed | |
| deleteLink | Followed by addLink the other way, will result in a reversed link and a net with different independence information | |
| deleteTables | Avoid overly large CPT tables caused by the reversal | |
| absorb | Removes nodes, also maintaining the overall joint probability | |
| setMaxMemoryUsage | In case this method is consuming too much memory |
public void enterFinding(int stateIndex)
throws NeticaException
stateIndex must be between 0 and n - 1 inclusive, where n is the node's number of states.
If this node could already have a finding that you wish to override with this new finding, retractFindings should be called first, otherwise an "inconsistent findings" error could result (see ChangeFinding in the examples below).
If you wish to pass the state by name, see the "EnterFinding" example below.
If this node is a continuous node that has been discretized, this method will work fine, but it is better to use enterValue if the real value is known, for possibly improved accuracy when equations are involved, the case is saved to file, or the discretization changes.
If 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:
| int | stateIndex | The index of a state of this node. |
| enterFindingNot | To indicate that node isn't in some state | |
| enterValue | To enter the real value of a continuous node | |
| enterLikelihood | To enter uncertain findings | |
| getFinding | To retrieve findings entered so far | |
| retractFindings | To remove the finding entered | |
| getNumStates | stateIndex must be between 0 and one less than this, inclusive |
// This method may be useful if we are not sure whether node
// already has a finding, but if it does we just want to override it.
// It is a method of NodeEx.java which extends Node.java
//
void changeFinding (int state) throws NeticaException {
int saved = getNet().getAutoUpdate();
getNet().setAutoUpdate (0); // turning it off can greatly aid efficiency
retractFindings();
enterFinding (state);
getNet().setAutoUpdate (saved); // if changing further findings, defer this step
// if possible, for efficiency
}
Example #2:
// This method is useful to enter a finding based on the names
// of the node and state.
// It is a method of NetEx.java which extends Net.java
//
void enterFinding (String nodeName, String stateName) throws NeticaException {
Node node = getNode (nodeName);
node.enterFinding (stateName);
}public void enterFindingNot(int stateIndex)
throws NeticaException
stateIndex must be between 0 and n - 1 inclusive, where n is the node's number of states.
This method may be called repeatedly to indicate all the states that you know this node isn't in. It also works in conjunction with enterLikelihood to accumulate further observations.
If 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:
| int | stateIndex | The index of a state of this node. |
| enterFinding | To enter the finding that a node is in a certain state | |
| enterLikelihood | The most general way to enter node findings | |
| getLikelihood | Retrieve negative findings that have been entered | |
| retractFindings | To remove the negative finding entered | |
| getNumStates | stateIndex must be between 0 and one less than this, inclusive |
public void enterValue(double value)
throws NeticaException
If the continuous node has been discretized, then the finding can also be entered as a state using enterFinding, but if the actual continuous value is known then it is recommended to use that, since it provides more detailed information for methods like writeCase, and it will automatically be converted to a discrete state when that is needed.
If this node is continuous discretized, and value is out of range (less than the low end of the first state, or more than the high end of the last state), then a suitable exception will be thrown.
If this node is discrete (i.e. not continuous), then it must have levels defined, and value must exactly match one of the levels.
If 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 | value | The new value to be assigned to this continuous variable node. |
| enterFinding | To enter a finding for a discrete or discretized node | |
| getValueEntered | To retrieve the value entered |
// This method is useful to enter a new value for node, whether or not it already has one.
//
// It is a method of NodeEx.java which extends Node.java
//
void changeValue (double value) throws NeticaException {
getNet().setAutoUpdate(0); // turning it off can greatly aid efficiency
retractFindings();
enterValue (value);
getNet().setAutoUpdate (Net.BELIEF_UPDATE); // if changing further findings, defer this step
// if possible, for efficiency
}public void enterLikelihood(float[] likelihood)
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 utility or decision node).
By calling it several times, you can combine the effects of several independent partial observations. If you don't want the likelihood findings to accumulate, call retractFindings between calls.
The likelihood finding is equivalent to the following scenario:
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 likelihood findings 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 index).
If 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:
| float[] | likelihood | a set of probabilites, one per state of this node. |
| enterFinding | To enter a certain finding that a node is in some state | |
| enterFindingNot | To indicate that node isn't in some state | |
| getLikelihood | To retrieve the likelihood finding entered | |
| retractFindings | To remove the findings entered |
See getFinding
public float[] getLikelihood()
throws NeticaException
Returns a likelihood vector with one entry for each state of this node, indicating the findings that have been entered for this node since the last retraction, including positive findings, negative findings, and likelihood findings.
If a positive finding has been entered, then the likelihood vector will consist of all zero entries, except a nonzero entry for the state corresponding to the finding (for more details on likelihood vectors, see enterLikelihood).
If a number of likelihood findings and/or negative findings have been entered for this node, they will be accumulated in the vector returned.
If no findings have been entered for this node since the last retraction, 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 setLevels).
Version:
| getFinding | Returns a scalar saying whether findings have been entered, and what kind | |
| getBeliefs | Current belief for a node (considers findings entered at other nodes) | |
| enterLikelihood | To enter a vector of uncertain findings (see example below) | |
| retractFindings | To clear away all findings entered so far for this node | |
| getNumStates | Determine the length of the vector returned |
// To temporarily remove all findings from a node and later restore them
//
float[] savedLikelihood = node.getLikelihood();
node.retractFindings();
... [stuff without the evidence] ...
node.retractFindings(); // in case any findings were introduced above
node.enterLikelihood (savedLikelihood); // restores to originalpublic void retractFindings()
throws NeticaException
This includes positive findings (state and real value), negative findings, and likelihood findings. It removes them from any kind of node, including "constant" nodes.
If this node does not have any findings, calling this will have no effect.
If the net is an auto-update net (see setAutoUpdate), 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 retracting a finding for a node, and then entering a new one, sometimes very significant performance gains can be made by ensuring auto-updating is turned off during the retraction (see example of enterFinding).
Version:
Net.retractFindings | To remove the findings from all nodes in the net | |
| enterFinding | To enter a finding for a node | |
| getFinding | To determine if a node has a finding |
public int getFinding()
throws NeticaException
If a positive finding has been entered for this node, this returns the finding. If no findings have been entered it returns NO_FINDING, and it can also return NEGATIVE_FINDING or LIKELIHOOD_FINDING.
The value returned will be one of:
| >= 0 | The positive (certain) finding which has been entered | |
| NO_FINDING | No findings have been entered, or likelihood findings exactly cancel | |
| NEGATIVE_FINDING | One or more negative findings have been entered | |
| LIKELIHOOD_FINDING | One or more likelihood findings have been entered |
Note that positive findings cannot cancel; if 2 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; for continuous nodes, use getValueEntered.
Version:
| getLikelihood | To get likelihood or negative findings | |
| getValueEntered | To get a real valued finding for a continuous node | |
| enterFinding | To enter a finding | |
| retractFindings | To clear away all findings entered so far for this node |
public double getValueEntered()
throws NeticaException
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 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:
| getFinding | For discrete findings, rather than continuous | |
| calcValue | Will compute from neighbors if deterministic | |
| enterValue | To enter a real-valued finding into a node | |
| retractFindings | To clear away all findings entered into a node |
public int calcState()
throws NeticaException
If this node is not a discrete or discretized node, then an exception is thrown (then use calcValue instead).
Version:
| calcValue | For real values (i.e. continuous) | |
| getFinding | Doesn't do deterministic propagation |
public double calcValue()
throws NeticaException
If this node is not a continuous node, and doesn't have a levels list defined (see setLevels), then an exception is thrown (then use calcState instead).
Version:
| calcState | For discrete nodes | |
| getValueEntered | Doesn't do deterministic propagation |
public float[] getExpectedUtils()
throws NeticaException
The vector will be indexed by states, with one utility for each state (i.e. choice).
The net containing this node must be a decision net (i.e. have decision and utility nodes), which has been compiled before calling this (with compile), or an exception will be thrown. If the net has been modified it must be recompiled, but just entering findings does not require a recompile.
Before calling this all preceding decision nodes must have positive findings entered.
this node must be a decision node.
If belief updating hasn't been done since the last findings were entered, it will be done before this method returns, which can be time consuming (you can call isBeliefUpdated before calling this to find out if belief updating will be done).
If you wish to retrieve a whole table of values, providing the optimal state to choose given the parent states, use getStateFuncTable.
Version:
| getStateFuncTable | Retrieve table of optimal choices as a function of parent values | |
| getNumStates | Determine the length of the vector returned | |
| getBeliefs | For the beliefs of a nature node | |
| getExpectedValue | Don't confuse it with this method, which gets the expected real value of a nature node |
public double getExpectedValue(double[] moments)
throws NeticaException
Returns UNDEF_DBL if the expected value couldn't be calculated.
This node must be continuous discretized, or must be discrete with a levels list defined to supply real values.
For continuous discretized nodes it assumes the belief for each state is distributed evenly over each discretized interval. Because of that, it can't handle infinite tails (returns UNDEF_DBL).
This method is not for expected utility; for that see getExpectedUtils.
Parameters:
| double[] | moments | an array, which if non-null, will have up to its 0th and 1st elements set to the 1st and 2nd moments, respectively. |
| getBeliefs | Returns beliefs for each state individually | |
| getExpectedUtils | For expected utility, rather than expected real value |
public boolean isBeliefUpdated()
throws NeticaException
Returns true if belief updating (i.e., computing the posterior probability of node) has been done so that the beliefs at this node are consistent with the current state of the net and current findings entered into the net, otherwise it returns false.
The main use of this method is to determine if Netica will do belief propagation (which may be time consuming) the next time getBeliefs or getExpectedUtils is called with this node.
Version:
| getBeliefs | Updates the beliefs (if they aren't already) |
public int[] parentStatesToIndexes(java.lang.String parentStateNamesStr)
throws NeticaException
| String | parentStateNamesStr | A comma and/or space delimited string of parent state names. |
public float[] getBeliefs()
throws NeticaException
The vector will be indexed by states, with one probability for each state (if required, the state indexes can be found from their names using state("stateName").getIndex()). It will be normalized, so that the sum of its entries is 1.
This provides the current beliefs (i.e. posterior probabilities) that the variable represented by this node is in each of its states, given the net model and all findings entered into all nodes of the net (positive findings, negative findings and likelihood findings).
The net containing this node must have been compiled before calling this (with compile), or an exception will be thrown. If the net has been modified it must be recompiled, but just entering findings does not require a recompile.
this node should be a discrete or discretized nature node.
If belief updating hasn't been done since the last findings were entered, it will be done before this method returns, which can be time consuming (you can call isBeliefUpdated before calling this to find out if belief updating will be done).
If you need the beliefs to persist, make a copy of the vector returned, since its contents may become invalid after further calls to Netica API. Do not try to directly modify or free the vector returned.
Version:
| isBeliefUpdated | Tells whether getBeliefs will trigger belief updating | |
| getNumStates | Determine length of vector returned | |
| getJointProbability | More than one node at a time | |
| compile | To do the initial compiling before entering findings | |
| getExpectedUtils | Get the resulting expected utility of a decision node |
// This method is useful to get the belief that a certain node is in
// a certain state, based on the names of the node and state.
//
static float getBelief (String nodeName, String stateName, Net net) throws NeticaException {
Node node = net.getNode (nodeName);
int stateIndex = node.state(stateName).getIndex();
return node.getBeliefs()[stateIndex];
}public int getInputIndex(java.lang.String linkName)
throws NeticaException
The value returned is particular to the node passed; another node may have a link with the same name, but a different link index.
Parameters:
| String | linkName | The name of a parent node. |
| getInputName | (inverse method) Returns the name of a link given its index |
public VisualNode getVisual()
throws NeticaException
public VisualNode visual()
throws NeticaException
node.getVisual().setPosition (200.0, 100.0);
public State state(int stateIndex)
throws NeticaException
| int | stateIndex | the index of the state desired |
| state(String) | Identical method, only uses stateName | |
| setLevels | To discretize a continuous variable, so it may act discrete |
node.state(0).setName("Heads");
node.state(1).setName("Tails");public State state(java.lang.String stateName)
throws NeticaException
| String | stateName | the name of the state desired |
| state(int) | Identical method, only uses stateIndex |
node.state(0).setName("Heads");
node.state("Heads").setTitle("Coin lands with face up");public void enterFinding(java.lang.String stateName)
throws NeticaException
This is a convenience method otherwise identical to Node.enterFinding(int). See that method for more detailed documentation.
Parameters:
| String | stateName | The name of one of our states. |
| enterFindingNot |
// This method is useful to enter a finding based on the names
// of the node and state.
static void enterFinding (String nodeName, String stateName, Net net) throws NeticaException {
Node node = net.getNode (nodeName);
node.enterFinding(stateName);
}public float getBelief(java.lang.String stateName)
throws NeticaException
| String | stateName | The name of the state whose belief value we seek. |
| getBeliefs | Retrieves beliefs for all states. |
public float[] getCPTable(java.lang.String parentStatesStr,
float[] cpTable)
throws NeticaException
| String | parentStatesStr | A comma and/or space delimited string of parent states, one per parent, in parent link index order. |
| setCPTable | Sets them |
public static void setConstructorClassName(java.lang.String netClassNm)
throws NeticaException
Node.setConstructorClass.public static java.lang.String getConstructorClassName()
Node.getConstructorClass.public Generic doc()
public Generic docState(int stateIndex)
throws NeticaException
|
||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||