BeliefNet.h File Reference

---

Detailed Description

A Belief Net Structure with CPT local models.

This is the interface for creating, using, printing, & serializing Belief Nets (aka Bayesian Networks). This document will first describe the properties of BeliefNets and then of BeliefNetNodes. A belief net is a compact representation of a joint probability distribution of all of the variables in a domain. For each variable there is a local model (represented by a BeliefNetNode) that models the probability of the various values of that varable given the values of the variables that affect them. A BeliefNet is an acyclic graph of the nodes, where an edge represets (loosely) that the variable at the source affects the varable at the target. The exact semantics of an edge are a bit more complex. For a more detailed discussion see David Heckerman's Tutorial

Wish List:

A version of this that uses DecisionTree local models instead of full CPTs. This would also need a new structure learning tool (a modification of bnlearn).

Go to the source code of this file.

Data Structures
struct	_BeliefNet_
	Belief network ADT. More...
struct	_BeliefNetNode_
	Belief net node with full CPTs for local models. More...
BeliefNetNode
typedef _BeliefNetNode_	BeliefNetNodeStruct
	Belief net node with full CPTs for local models.
typedef _BeliefNetNode_ *	BeliefNetNode
	Belief net node with full CPTs for local models.
void	BNNodeAddParent (BeliefNetNode bnn, BeliefNetNode parent)
	Adds the specified node as a parent to bnn.
int	BNNodeLookupParentIndex (BeliefNetNode bnn, BeliefNetNode parent)
	Returns the index of parent in bnn's parent list.
int	BNNodeLookupParentIndexByID (BeliefNetNode bnn, int id)
	Looks through the parent list of bnn for a node with node id of 'id'.
void	BNNodeRemoveParent (BeliefNetNode bnn, int parentIndex)
	Removes the node with index 'parentIndex' from bnn's parent list.
BeliefNetNode	BNNodeGetParent (BeliefNetNode bnn, int parentIndex)
	Returns the parent at position 'index' in the node's parent list.
int	BNNodeGetParentID (BeliefNetNode bnn, int parentIndex)
	Returns the node id of the node at position 'index' in the node's parent list.
int	BNNodeGetNumParents (BeliefNetNode bnn)
	Returns the number of nodes in the target node's parent list.
int	BNNodeGetNumChildren (BeliefNetNode bnn)
	Returns the number of nodes in the target node's child list.
int	BNNodeHasParent (BeliefNetNode bnn, BeliefNetNode parent)
	Returns 1 if and only if parent is in the node's parent list.
int	BNNodeHasParentID (BeliefNetNode bnn, int parentID)
	Returns 1 if and only if one of the node's parents has the specified node id.
int	BNNodeGetNumValues (BeliefNetNode bnn)
	Returns the number of values that the variable represented by the node can take.
int	BNNodeGetNumParameters (BeliefNetNode bnn)
	Returns the number of parameters in the node's CPT.
char *	BNNodeGetName (BeliefNetNode bnn)
	Returns the name of the node.
int	BNNodeStructureEqual (BeliefNetNode bnn, BeliefNetNode otherNode)
	Returns 1 if and only if the two nodes have the same parents in the same order.
void	BNNodeInitCPT (BeliefNetNode bnn)
	Allocates memory for bnn's CPT and zeros the values.
void	BNNodeZeroCPT (BeliefNetNode bnn)
	Sets the value of all CPT entries to zero.
void	BNNodeFreeCPT (BeliefNetNode bnn)
	Frees any memory being used by the node's CPTs.
void	BNNodeAddSample (BeliefNetNode bnn, ExamplePtr e)
	Increments the count of the appropriate CPT element by 1.
void	BNNodeAddSamples (BeliefNetNode bnn, VoidListPtr samples)
	Calls BNNodeAddSample for each example in the list.
void	BNNodeAddFractionalSample (BeliefNetNode bnn, ExamplePtr e, float weight)
	Increments the count of the appropriate CPT element by weight.
void	BNNodeAddFractionalSamples (BeliefNetNode bnn, VoidListPtr samples, float weight)
	Calls BNNodeAddFractionalSample for each example in the list.
float	BNNodeGetCPTRowCount (BeliefNetNode bnn, ExamplePtr e)
	Returns the number of samples that have been added to the node with the same parent combination as in e.
float	BNNodeGetP (BeliefNetNode bnn, int value)
	Returns the marginal probability of the appropriate value of the variable.
float	BNNodeGetCP (BeliefNetNode bnn, ExamplePtr e)
	Get the probability of the value of the target variable given the values of the parent variables.
void	BNNodeSetCP (BeliefNetNode bnn, ExamplePtr e, float probability)
	Sets the probability without affecting the sum of the CPT row for the parent combination.
float	BNNodeGetNumSamples (BeliefNetNode bnn)
	Returns the number of samples that have been added to the belief net node.
int	BNNodeGetNumCPTRows (BeliefNetNode bnn)
	Returns the number rows in the node's CPT. This is the number of parent combinations.
BeliefNet
#define	BNGetUserData(bn)   (((BeliefNet)bn)->userData)
	Allows you to store an arbitrary pointer on the BeliefNet.
typedef _BeliefNet_	BeliefNetStruct
	Belief network ADT.
typedef _BeliefNet_ *	BeliefNet
	Belief network ADT.
BeliefNet	BNNew (void)
	Creates a new belief net with no nodes.
void	BNFree (BeliefNet bn)
	Frees the memory associated with the belief net and all nodes.
BeliefNet	BNClone (BeliefNet bn)
	Makes a copy of the belief net and all nodes.
BeliefNet	BNCloneNoCPTs (BeliefNet bn)
	Makes a copy of the belief net and all nodes, but does not copy the local models at the nodes.
BeliefNet	BNNewFromSpec (ExampleSpecPtr es)
	Makes a new belief net from the example spec.
int	BNGetSimStructureDifference (BeliefNet bn, BeliefNet otherNet)
	Returns the symetric difference in the structures.
void	BNSetName (BeliefNet bn, char *name)
	Set's the Belief net's name.
ExampleSpec *	BNGetExampleSpec (BeliefNet bn)
	Returns the ExampleSepc that is associated with the belief net.
BeliefNetNode	BNGetNodeByID (BeliefNet bn, int id)
	Gets the node with the associated index.
int	BNGetNumNodes (BeliefNet bn)
	Returns the number of nodes in the Belief Net.
BeliefNetNode	BNGetNodeByElimOrder (BeliefNet bn, int index)
	Returns nodes by their order in a topological sort.
int	BNHasCycle (BeliefNet bn)
	Returns 1 if and only if there is a cycle in the graphical structure of the belief net.
void	BNFlushStructureCache (BeliefNet bn)
	Needs to be called anytime you change network structure.
void	BNAddSample (BeliefNet bn, ExamplePtr e)
	Modifies all the CPTs in the network by adding a count to the approprite parameters.
void	BNAddSamples (BeliefNet bn, VoidListPtr samples)
	Calls BNAddSample for every example in the list.
void	BNAddFractionalSample (BeliefNet bn, ExamplePtr e, float weight)
	Modifies all the CPTs in the network by adding a weighted count to the approprite parameters.
void	BNAddFractionalSamples (BeliefNet bn, VoidListPtr samples, float weight)
	Calls BNAddFractionalSample for every example in the list.
long	BNGetNumIndependentParameters (BeliefNet bn)
	Returns the sum over all nodes of the number of independent parameters in the CPTs.
long	BNGetNumParameters (BeliefNet bn)
	Returns the sum over all nodes of the number of parameters in the CPTs.
long	BNGetMaxNodeParameters (BeliefNet bn)
	Returns the number of parameters in the node with the most parameters.
ExamplePtr	BNGenerateSample (BeliefNet bn)
	Samples from the distribution represented by bn.
void	BNSetPriorStrength (BeliefNet bn, double strength)
	Sets prior parameter strength as if some examples have been seen.
void	BNSmoothProbabilities (BeliefNet bn, double strength)
	Adds a number of samples equal to strength to each CPT entry in the network.
void	BNSetUserData (BeliefNet bn, void *data)
	Allows you to store an arbitrary pointer on the BeliefNet.
BeliefNet	BNReadBIF (char *fileName)
	Reads a Belief net from the named file.
BeliefNet	BNReadBIFFILEP (FILE *file)
	Reads a Belief net from a file pointer.
void	BNWriteBIF (BeliefNet bn, FILE *out)
	Writes the belief net to the file.
void	BNPrintStats (BeliefNet bn)
	Prints some information about the net to stdout.
Inference with Likelihood Sampling
The idea of likelihood sampling is that you have a set of query variables (specified by an example with some of the values unknown) and the system randomly generates samples for the query variables given the values of the non-query variables. After 'enough' samples the distribution of the samples generated for the query variables will be a good match to the 'true' distribution according to the net. The number of samples required can be very large, especially when dealing with events that don't occur often.
BeliefNet	BNInitLikelihoodSampling (BeliefNet bn, ExamplePtr e)
	Set up likelihood sampling and return place holder network.
void	BNAddLikelihoodSamples (BeliefNet bn, BeliefNet newNet, ExamplePtr e, int numSamples)
	Adds the requested number of samples to newNet.
BeliefNet	BNLikelihoodSampleNTimes (BeliefNet bn, ExamplePtr e, int numSamples)
	Combines a call to BNInitiLikelihoodSampling with a call to BNAddLikelihoodSamples.

---

Define Documentation

#define BNGetUserData (  bn   )     (((BeliefNet)bn)->userData)

Allows you to store an arbitrary pointer on the BeliefNet. You are responsible for managing any memory that it points to.

---

Typedef Documentation

typedef struct _BeliefNet_ * BeliefNet

Belief network ADT. See BeliefNet.h for more detail.

typedef struct _BeliefNetNode_ * BeliefNetNode

Belief net node with full CPTs for local models. See BeliefNet.h for more detail.

typedef struct _BeliefNetNode_ BeliefNetNodeStruct

Belief net node with full CPTs for local models. See BeliefNet.h for more detail.

typedef struct _BeliefNet_ BeliefNetStruct

Belief network ADT. See BeliefNet.h for more detail.

---

Function Documentation

void BNAddFractionalSample (  BeliefNet  bn, ExamplePtr  e, float  weight )

Modifies all the CPTs in the network by adding a weighted count to the approprite parameters. See the BeliefNetNode functions for a more detailed description of how the CPTs are represented and handled.

void BNAddFractionalSamples (  BeliefNet  bn, VoidListPtr  samples, float  weight )

Calls BNAddFractionalSample for every example in the list.

void BNAddLikelihoodSamples (  BeliefNet  bn, BeliefNet  newNet, ExamplePtr  e, int  numSamples )

Adds the requested number of samples to newNet. newNet should have been created by a call to BNInitiLikelihoodSampling. Adds the requested number of samples for the unknown variables in e using the distributions in bn.

void BNAddSample (  BeliefNet  bn, ExamplePtr  e )

Modifies all the CPTs in the network by adding a count to the approprite parameters. See the BeliefNetNode functions for a more detailed description of how the CPTs are represented and handled.

void BNAddSamples (  BeliefNet  bn, VoidListPtr  samples )

Calls BNAddSample for every example in the list.

BeliefNet BNClone (  BeliefNet  bn  )

Makes a copy of the belief net and all nodes.

BeliefNet BNCloneNoCPTs (  BeliefNet  bn  )

Makes a copy of the belief net and all nodes, but does not copy the local models at the nodes.

void BNFlushStructureCache (  BeliefNet  bn  )

Needs to be called anytime you change network structure. That is, any time you add nodes, add or remove edges after calling BNHasCycle, or any ElimOrder stuff. The reason is that these two classes of functions cache topological sorts of the network and changing the structure invalidates these caches. In prinicipal, all of the functions that modify structure could be modified to automatically call this. I think things were done this way for efficiency (but I am not sure it actually helps efficiency...

void BNFree (  BeliefNet  bn  )

Frees the memory associated with the belief net and all nodes.

ExamplePtr BNGenerateSample (  BeliefNet  bn  )

Samples from the distribution represented by bn. You are responsible for freeing the returned example (using ExampleFree when you are done with it.

ExampleSpec* BNGetExampleSpec (  BeliefNet  bn  )

Returns the ExampleSepc that is associated with the belief net. The spec will be automatically created when you read the network from disk or as you add nodes to the net and values to the nodes.

long BNGetMaxNodeParameters (  BeliefNet  bn  )

Returns the number of parameters in the node with the most parameters.

BeliefNetNode BNGetNodeByElimOrder (  BeliefNet  bn, int  index )

Returns nodes by their order in a topological sort. If the nodes can not be topologically sorted (perhaps because there is a cycle) this function returns 0. Note that this function caches (and uses a cache) of the topological sort and that you might want to call BNFlushStructureCache before calling this if you've changed the structure of the net since the cache was filled.

BeliefNetNode BNGetNodeByID (  BeliefNet  bn, int  id )

Gets the node with the associated index. This is 0 based (like a C array).

long BNGetNumIndependentParameters (  BeliefNet  bn  )

Returns the sum over all nodes of the number of independent parameters in the CPTs. This is different from the total number of parameters because one of the parameters in each row can be determined from the values of the others, and so is not independent.

int BNGetNumNodes (  BeliefNet  bn  )

Returns the number of nodes in the Belief Net.

long BNGetNumParameters (  BeliefNet  bn  )

Returns the sum over all nodes of the number of parameters in the CPTs.

int BNGetSimStructureDifference (  BeliefNet  bn, BeliefNet  otherNet )

Returns the symetric difference in the structures. This is defined as the sum for i in nodes of the number of parents that node i of bn has but node i of otherBN does not have plus the number of parents that node i of otherBN has that node i of bn does not have.

int BNHasCycle (  BeliefNet  bn  )

Returns 1 if and only if there is a cycle in the graphical structure of the belief net. Note that this function caches (and uses a cache) of the topological sort and that you might want to call BNFlushStructureCache before calling this if you've changed the structure of the net since the cache was filled.

BeliefNet BNInitLikelihoodSampling (  BeliefNet  bn, ExamplePtr  e )

Set up likelihood sampling and return place holder network. Returns a new belief net with CPT set to start to acumulate samples for the unknown variables in e, you should free this net when you are done with it. Once the net is created you should add as many samples to it as you like using BNAddLikelihoodSamples and then check the CPTs at the appropriate nodes for the generated distributions.

BeliefNet BNLikelihoodSampleNTimes (  BeliefNet  bn, ExamplePtr  e, int  numSamples )

Combines a call to BNInitiLikelihoodSampling with a call to BNAddLikelihoodSamples.

BeliefNet BNNew (  void   )

Creates a new belief net with no nodes.

BeliefNet BNNewFromSpec (  ExampleSpecPtr  es  )

Makes a new belief net from the example spec. All attributes in the spec should be discrete. This adds a node, with the appropriate values, to the net for each variable in the spec. The resulting network has no edges and zeroed CPTs

void BNNodeAddFractionalSample (  BeliefNetNode  bnn, ExamplePtr  e, float  weight )

Increments the count of the appropriate CPT element by weight. Looks in example to get the values for the parents and the value for the variable. If any of these are unknown changes nothing, prints a low priority warning message, and returns -1 where applicable.

void BNNodeAddFractionalSamples (  BeliefNetNode  bnn, VoidListPtr  samples, float  weight )

Calls BNNodeAddFractionalSample for each example in the list.

void BNNodeAddParent (  BeliefNetNode  bnn, BeliefNetNode  parent )

Adds the specified node as a parent to bnn. Both nodes should be from the same BeliefNet structure.

void BNNodeAddSample (  BeliefNetNode  bnn, ExamplePtr  e )

Increments the count of the appropriate CPT element by 1. Looks in example to get the values for the parents and the value for the variable. If any of these are unknown changes nothing, prints a low priority warning message, and returns -1 where applicable.

void BNNodeAddSamples (  BeliefNetNode  bnn, VoidListPtr  samples )

Calls BNNodeAddSample for each example in the list.

void BNNodeFreeCPT (  BeliefNetNode  bnn  )

Frees any memory being used by the node's CPTs. This should be called before changing the node's parents. After a call to this function, you should call BNNodeInitCPT for the node before making any calls that might try to access the CPT (adding samples, doing inference, smoothing probability, comparin networks, etc).

float BNNodeGetCP (  BeliefNetNode  bnn, ExamplePtr  e )

Get the probability of the value of the target variable given the values of the parent variables. Looks in example to get the values for the parents and the value for the variable. If any of these are unknown changes nothing, prints a low priority warning message, and returns -1 where applicable.

float BNNodeGetCPTRowCount (  BeliefNetNode  bnn, ExamplePtr  e )

Returns the number of samples that have been added to the node with the same parent combination as in e. Looks in example to get the values for the parents and the value for the variable. If any of these are unknown changes nothing, prints a low priority warning message, and returns -1 where applicable.

char* BNNodeGetName (  BeliefNetNode  bnn  )

Returns the name of the node.

int BNNodeGetNumChildren (  BeliefNetNode  bnn  )

Returns the number of nodes in the target node's child list.

int BNNodeGetNumCPTRows (  BeliefNetNode  bnn  )

Returns the number rows in the node's CPT. This is the number of parent combinations.

int BNNodeGetNumParameters (  BeliefNetNode  bnn  )

Returns the number of parameters in the node's CPT.

int BNNodeGetNumParents (  BeliefNetNode  bnn  )

Returns the number of nodes in the target node's parent list.

float BNNodeGetNumSamples (  BeliefNetNode  bnn  )

Returns the number of samples that have been added to the belief net node.

int BNNodeGetNumValues (  BeliefNetNode  bnn  )

Returns the number of values that the variable represented by the node can take.

float BNNodeGetP (  BeliefNetNode  bnn, int  value )

Returns the marginal probability of the appropriate value of the variable. That is, the sum over all rows of the number of counts for that value divided by the sum over all rows of the number of counts in the row. Looks in example to get the values for the parents and the value for the variable. If any of these are unknown changes nothing, prints a low priority warning message, and returns -1 where applicable.

BeliefNetNode BNNodeGetParent (  BeliefNetNode  bnn, int  parentIndex )

Returns the parent at position 'index' in the node's parent list.

int BNNodeGetParentID (  BeliefNetNode  bnn, int  parentIndex )

Returns the node id of the node at position 'index' in the node's parent list.

int BNNodeHasParent (  BeliefNetNode  bnn, BeliefNetNode  parent )

Returns 1 if and only if parent is in the node's parent list.

int BNNodeHasParentID (  BeliefNetNode  bnn, int  parentID )

Returns 1 if and only if one of the node's parents has the specified node id.

void BNNodeInitCPT (  BeliefNetNode  bnn  )

Allocates memory for bnn's CPT and zeros the values. This allocates enough memory to hold one float for each value of the variable associated with the node for each parent combination (an amount of memory that is exponential in the number of parents). This should be called once all parents are in place.

int BNNodeLookupParentIndex (  BeliefNetNode  bnn, BeliefNetNode  parent )

Returns the index of parent in bnn's parent list. Returns -1 if parent is not one of node's parents.

int BNNodeLookupParentIndexByID (  BeliefNetNode  bnn, int  id )

Looks through the parent list of bnn for a node with node id of 'id'. See BNNodeGetID for more info.

void BNNodeRemoveParent (  BeliefNetNode  bnn, int  parentIndex )

Removes the node with index 'parentIndex' from bnn's parent list. To remove the node 'parent' call BNNodeRemoveParent(bnn, BNNodeLookupParentIndex(bnn, parent)).

void BNNodeSetCP (  BeliefNetNode  bnn, ExamplePtr  e, float  probability )

Sets the probability without affecting the sum of the CPT row for the parent combination. This means that the probability has the same prior weight before and after a call to this. Put another way, the set probability is equivilant to having seen the same number of samples at the new probability as at the old. Looks in example to get the values for the parents and the value for the variable. If any of these are unknown changes nothing, prints a low priority warning message, and returns -1 where applicable.

int BNNodeStructureEqual (  BeliefNetNode  bnn, BeliefNetNode  otherNode )

Returns 1 if and only if the two nodes have the same parents in the same order. Bug: Only returns 1 if the parents are in the same order, but the order probably shouldn't matter.

void BNNodeZeroCPT (  BeliefNetNode  bnn  )

Sets the value of all CPT entries to zero. Can be called after InitCPT to reset all the table's values to 0.

void BNPrintStats (  BeliefNet  bn  )

Prints some information about the net to stdout. The information includes num nodes, min max avg num parents, etc.

BeliefNet BNReadBIF (  char *  fileName  )

Reads a Belief net from the named file. The file should contain a net in Bayesian Interchange Format (BIF).

BeliefNet BNReadBIFFILEP (  FILE *  file  )

Reads a Belief net from a file pointer. The file pointer should be opened for reading and should contain a net in Bayesian Interchange Format (BIF).

void BNSetName (  BeliefNet  bn, char *  name )

Set's the Belief net's name. This doesn't really affect anything (except it is recorded if you write out the belief net), but using it may make you feel better.

void BNSetPriorStrength (  BeliefNet  bn, double  strength )

Sets prior parameter strength as if some examples have been seen. Multiplies all the counts in all of the network's CPTs so that each parent combination has the equivilant of strength samples, divided acording to that combination's distribution in the network. Hrm, does that confuse you too?

void BNSetUserData (  BeliefNet  bn, void *  data )

Allows you to store an arbitrary pointer on the BeliefNet. You are responsible for managing any memory that it points to.

void BNSmoothProbabilities (  BeliefNet  bn, double  strength )

Adds a number of samples equal to strength to each CPT entry in the network. This effectivly smooths the probabilities towards uniform.

void BNWriteBIF (  BeliefNet  bn, FILE *  out )

Writes the belief net to the file. Out should be a file open for writing, pass stdout to write to the console. The net it written in Bayesian Interchange Format (BIF).

---

Generated for VFML by hosted by