norsys.netica
Class Sensitivity

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

public class Sensitivity

extends java.lang.Object

A sensitivity measurer, which determines to what degree a new finding at one node can affect another node.

Since:

2.08

Field Summary

static int	ENTROPY_SENSV Measure entropy or mutual information.
static int	REAL_SENSV Measure the effect on the real numeric value (rather than just the state).
static int	VARIANCE_SENSV Measure variance or mean squared change.

Constructor Summary

Sensitivity(Node qNode, NodeList fNodeList, int whatFind)
Creates a sensitivity measuring object, which measures how much the beliefs at one node (called the "query node") will change if a finding is entered at another node (called the "findings node").

Method Summary

void	finalize() Free all resources this norsys.netica.Sensitivity is using.
double	getMutualInfo(Node findingNode) Measures the mutual information between two nodes, which is how much a finding at one node (called the "findings node") is expected to alter the beliefs (measured as decrease in its entropy) at another node (called the "query node").
double	getVarianceOfReal(Node findingNode) Measures how much a finding at one node (called the "findings node") is expected to reduce the variance of another node (called the "query node").

Methods inherited from class java.lang.Object

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

Field Detail

ENTROPY_SENSV

public static final int ENTROPY_SENSV

Measure entropy or mutual information.

See Also:

Sensitivity

REAL_SENSV

public static final int REAL_SENSV

Measure the effect on the real numeric value (rather than just the state).

See Also:

Sensitivity

VARIANCE_SENSV

public static final int VARIANCE_SENSV

Measure variance or mean squared change.

See Also:

Sensitivity

Constructor Detail

Sensitivity

public Sensitivity(Node qNode,
                   NodeList fNodeList,
                   int whatFind)
            throws NeticaException

Creates a sensitivity measuring object, which measures how much the beliefs at one node (called the "query node") will change if a finding is entered at another node (called the "findings node"). This is sometimes called "utility-free value of information".

For qNode, pass the query node, and for fNodeList, pass a list of all nodes that might later be used as findings nodes.

There are two different measures available: variance reduction and entropy reduction (i.e. mutual information).

For whatFind, pass the bitwise-OR of which measures you want the created object capable of measuring. To measure variance reduction, pass REAL_SENSV + VARIANCE_SENSV, and to measure mutual information, pass ENTROPY_SENSV.

After the object is created, to measure variance reduction, pass the new object to getVarianceOfReal along with a particular findings node. To measure mutual information between two nodes, pass it to getMutualInfo.

When you are finished with the sensitivity object, free the resources it uses by calling finalize.

Netica uses an efficient algorithm that takes the current findings into account, and requires only a few belief updatings no matter how many nodes are contained in fNodeList. When you request the first sensitivity measure of the query node relative to one of the findings nodes (by calling getMutualInfo or getVarianceOfReal), the belief updatings are done and the results cached for subsequent calls involving other findings nodes.

These functions are available as "Network -> Sensitivity to Finding" in Netica Application. For more information on them, contact Norsys for the "Sensitivity" document.

Version:

Versions 2.03 and later have this function.
In the C Version of the API, this function is called NewSensvToFinding_bn.

See Also:

finalize		(reverse operation) Delete the norsys.netica.Sensitivity when finished with it
getVarianceOfReal		Use the norsys.netica.Sensitivity to find the variance reduction due to finding
getMutualInfo		Use the norsys.netica.Sensitivity to find the mutual info (entropy reduction)

Example:

  Net net = new Net ("Asia.dne");
  Sensitivity svCancer = new Sensitivity (net.getNode ("Cancer"), 
                                          net.geNodes(), 
                                          Sensitivity.ENTROPY_SENSV);
  double mutinfo = svCancer.getMutualInfo (net.getNode ("Dyspnea"));
  double entropy = svCancer.getMutualInfo (net.getNode ("Cancer"));
  svCancer.finalize(); // if memory is short, you may choose to force the early cleanup 
                       // of native Netica resources by explicitly calling the finalize
                       // before the Garbage Collector may get around to doing so.

Parameters:

qNode - query Node for this Sensitivity

fNodeList - finding Nodes for this Sensitivity

whatFind - a bitwise OR of some of the constants: ENTROPY_SENSV, REAL_SENSV, or VARIANCE_SENSV.

Method Detail

getMutualInfo

public double getMutualInfo(Node findingNode)
                     throws NeticaException

Measures the mutual information between two nodes, which is how much a finding at one node (called the "findings node") is expected to alter the beliefs (measured as decrease in its entropy) at another node (called the "query node").

The query node is set by the particular norsys.netica.Sensitivity created (see Sensitivity). The findings node is passed as findingNode.

This function returns the mutual information between two nodes (measured in bits). It can be used with any discrete or discretized nodes. Mutual information is the expected reduction in entropy of one node (measured in bits) due to a finding at another.

The maximum possible decrease in entropy of the query node is when entropy goes to zero, i.e. all uncertainty is removed. That happens when a finding is obtained for the query node. So to find the entropy of a node, measure the mutual information between a node and itself (that is why "entropy" is sometimes called "self information").

To create a norsys.netica.Sensitivity that can measure mutual information, pass ENTROPY_SENSV for whatFind when calling Sensitivity. For its fNodeList argument, pass a list of all the nodes that might later be passed as findingNode to this function.

Mutual information is symmetric between nodes (i.e. has the same value when finding and query nodes are reversed). That makes this function useful to measure the degree to which one findings node can effect a number of different query nodes in an efficient way, by just passing the findings node to Sensitivity, and each of the query nodes to this function.

This function is available as "Network -> Sensitivity to Finding" in Netica Application. For more information on it, contact Norsys for the "Sensitivity" document.

Version:

Versions 2.03 and later have this function.
In the C Version of the API, this function is called MutualInfo_bn.

See Also:

getVarianceOfReal		Use a different measure of sensitivity: variance reduction
Sensitivity		Create a new norsys.netica.Sensitivity to measure mutual information

Example:

See  Sensitivity.

Parameters:

findingNode - The node we pretend to put a finding at.

getVarianceOfReal

public double getVarianceOfReal(Node findingNode)
                         throws NeticaException

Measures how much a finding at one node (called the "findings node") is expected to reduce the variance of another node (called the "query node").

The query node is set by the particular norsys.netica.Sensitivity created (see Sensitivity). The findings node is passed as findingNode.

getVarianceOfReal can only be used with query nodes that are discretized continuous nodes, or that have a real numeric value associated with each state. It measures the expected change squared in the expected real value of the query node, due to a finding at the findings node. This turns out to be the same as the expected decrease in variance of the expected real value of the query node, due to a finding at findings node. The findings nodes do not have to be continuous or have real numeric values attached to their states.

The maximum possible decrease in variance of the query node, is when variance goes to zero, i.e. all uncertainty is removed. That happens when a finding is obtained for the query node. So to find the variance of a node, measure the variance reduction between a node and itself.

To create a norsys.netica.Sensitivity that can measure variance reduction, pass REAL_SENSV + VARIANCE_SENSV for whatFind when calling Sensitivity. For its fNodeList argument, pass a list of all the nodes that might later be passed as findingNode to this function.

This function is available as "Network -> Sensitivity to Finding" in Netica Application. For more information on it, contact Norsys for the "Sensitivity" document.

Version:

Versions 2.03 and later have this function.
In the C Version of the API, this function is called VarianceOfReal_bn.

See Also:

Sensitivity		Create the norsys.netica.Sensitivity required to measure variance reduction due to finding
getMutualInfo		Use a different measure of sensitivity: mutual info (entropy reduction)

Parameters:

findingNode - The node we pretend to put a finding at.

finalize

public void finalize()
              throws NeticaException

Free all resources this norsys.netica.Sensitivity is using.

You must not try to use this norsys.netica.Sensitivity after calling this.

If you override this method, be sure to call the base class method (super.finalize();).

Version:

Versions 2.03 and later have this function.
In the C Version of the API, this function is called DeleteSensvToFinding_bn.

See Also:

Sensitivity

(reverse operation) Create a new norsys.netica.Sensitivity to do sensitivity analysis

Example:

See  Sensitivity.

Overrides:

finalize in class java.lang.Object