Reference Manual: DSL nodeDefinition

From DSL

There are several types of definitions, each corresponding to one of the node types supported by the library. Most of the following methods can be applied to every kind of definition. When that is not the case, the call will return DSL_WRONG_NODE_TYPE or signal the error by another mean (Ex: returning a NULL pointer in some occasions). In general, is not a good idea to call one of these methods with a node that doesn't support it (NOTE: this lack of support will be changed in future releases of the library). Each node type may behave slightly different so in the description of each method there is a table that lists these differences.

Each node type is associated with a definition type as indicated in the following table:

Node Type	Definition Type
DSL_LIST	DSL_list
DSL_TRUTHTABLE	DSL_truthTable
DSL_CPT	DSL_cpt
DSL_NOISY_MAX	DSL_noisyMAX
DSL_TABLE	DSL_table
DSL_MAU	DSL_mau

Methods

• int AfterDirectChange(int changeType = 0)

Call this function after changing the definition of a node directly if you want the affected nodes to be invalidated. See the description of the method BeforeDirectChange for a detailed explanation.

• int AddOutcome(char *thisName)

Adds an outcome with thisName. The new outcome will be the last one. See example below.

• int BeforeDirectChange(int changeType = 0)

Call this function before changing the definition of a node directly if you want the affected nodes to be invalidated. Changing directly means, for example, accessing the conditional probability table directly and change the distribution over the outcomes. Ignore the parameter changeType.

Example:

  // get the definition of a chance node (DSL_CPT)// (imagine it has two states and no parents, so the
  // corresponding matrix will have size 2)
  DSL_Dmatrix *theCpt;
  theNet.GetNode(aNode)->Definition()->GetDefinition(&theCpt);
  // tell the node that we are about to change its definition
  theNet.GetNode(aNode)->Definition()->BeforeDirectChange();
  // now change things directly
  (*theCpt)[0] = 0.3;
  (*theCpt)[1] = 0.7;
  // once we are done, we should finish the protocol
  theNet.GetNode(aNode)->Definition()->AfterDirectChange();

This way, relevance reasoning will have a chance of invalidating those nodes affected by the change in the distribution. We should not bother calling this function when we are building a network (model building phase) because at that point we are not really performing any inference. We should only call it when in the inference phase (the model is completely built) so the proper nodes are invalidated. On the other hand, once the model is completed and we are performing inference, the definition of the nodes will seldom change (except in specialized applications) so you may not have to call this function at all.

• DSL_network *Network(void)

Returns a pointer to the network that we are part of.

• int Handle(void)

Returns our handle in the network we are part of.

• int GetType(void)

Returns our type. The type of node is formed by OR-ing several flags from the following categories:

- Basic node type (DSL_DECISION, DSL_CHANCE, DSL_DETERMINISTIC, DSL_UTILITY): each node must have one (and only one) of these flags set.

- Node discreteness (DSL_DISCRETE): this flag must be set if the node represents a discrete variable.

- Probability representation type (DSL_NOISYMAX): if the node is of type chance, the conditional distribution can be represented as a Noisy-MAX interaction. The proper flag must be set if using one of these alternate representations.

By combining some of these flags we obtain the type of all the nodes currently supported by the library:

Node Type	Flags
DSL_LIST	DSL_DECISION, DSL_DISCRETE
DSL_TRUTHTABLE	DSL_DETERMINISTIC, DSL_DISCRETE
DSL_CPT	DSL_CHANCE, DSL_DISCRETE
DSL_NOISY_MAX	DSL_CHANCE, DSL_DISCRETE, DSL_NOISYMAX
DSL_TABLE	DSL_table
DSL_MAU	DSL_mau

• char *GetTypeName(void)

Returns a pointer to a string containing the "name" of the type of the node.

Node Type	GetTypeName() returns
DSL_LIST	"LIST"
DSL_TRUTHTABLE	"TRUTHTABLE"
DSL_CPT	"CPT"
DSL_NOISY_MAX	"NOISY_MAX"
DSL_TABLE	"TABLE"
DSL_MAU	"MAU"

• int GetSize(void)

Returns the size of the "important" part of the definition:

Node Type	GetSize() returns
DSL_LIST	Number of choices
DSL_TRUTHTABLE	Size of the conditional probability table
DSL_CPT	Size of the conditional probability table
DSL_NOISY_MAX	Size of the conditional probability table
DSL_TABLE	Size of the table of utilities
DSL_MAU	Size of the table of weights

• int GetNumberOfOutcomes(void)

Returns the number of possible outcomes for this node (definition).

• DSL_idArray *GetOutcomesNames(void)

Returns a pointer to the DSL_idArray that contains the names of the outcomes of the node.

• int GetDefinition(<several pointer types> here)

These functions will grant access to different parts of the definition depending on the node type and on the type of the parameter used. See table for details on what is returned for each node type.

Node Type	Type of [here] parameter passed to GetDefinition():
	Dmatrix *	doubleArray *	intArray *	stringArray *
LIST	Wrong type	Wrong type	Wrong type	Outcomes names
TRUTHTABLE	Conditional probability table	Array of probabilities	Wrong type	Outcomes names
CPT	Conditional probability table	Array of probabilities	Wrong type	Outcomes names
NOISY_MAX	Conditional probability table	Array of probabilities	Wrong type	Outcomes names
TABLE	Table of utilities	Array of utilities	Wrong type	Wrong type
DSL_MAU	Wrong type	Array of Weights	Wrong type	Wrong type

• DSL_Dmatrix* GetMatrix()

This function returns the pointer to numeric representation of node definition. It's implemented as a call to GetDefinition(DSL_Dmatrix **). Supported for CPT, TRUTHTABLE and NOISY_MAX nodes. See DSL_nodeValue for more information on this function.

• int InsertOutcome(int here, char *thisName)

Inserts here an outcome with thisName. See example below.

• int NodeTypeIs(int flags)

Will return a non-zero value if the node type has at least one the flags specified in flags set.

Example: For a node of type DSL_CPT, NodeTypeIs(DSL_CHANCE) will return a non-zero

value whereas NodeTypeIs(DSL_UTILITY) will return zero.

• int RemoveOutcome(int outcomeNumber)

Removes the outcome whose position is outcomeNumber. See example below.

Example:

  // assuming a node with two outcomes {"True","False"}
  AddOutcome("Undefined"); // outcomes = {"True","False","Undefined"}
  RemoveOutcome(1); // outcomes = {"True","Undefined"}
  InsertOutcome(0,"New"); // outcomes = {"New","True","Undefined"}

• int RenameOutcomes(DSL_stringArray &theOutcomeNames)

Renames the outcomes with the names included in theOutcomeNames. This method is intended just for renaming. The number of outcomes of the node doesn't change, even if theOutcomesNames contains more (or less) strings that the actual number of outcomes of the node.

• int SetDefinition(<several pointer types>)

These functions set the definition of the different types of nodes. They usually perform no checking so be careful when using them. To find what each of these functions will do to each of the node types, just look at the table given for GetDefinition. For example, if we call the SetDefinition method of a DSL_CPT node type with a pointer to a DSL_Dmatrix as a parameter, we will be setting the conditional probability table of the node. The only exception is NOISY_MAX, which as a parameter for SetDefinition requires DSL_Dmatrix with noisy-MAX parameters, which differs from one for DSL_CPT. For details see section about noisy-MAX.

• int SetNumberOfOutcomes(int aNumber)

This function sets the number of outcomes to be aNumber. It will recreate the definition so it can hold all the necessary information. The names of the outcomes will be set to a default value (Ex:"State0", "State1" (and so on) for nodes of type DSL_CPT).

• int SetNumberOfOutcomes(DSL_stringArray &theOutcomeNames)

This function behaves exactly like SetNumberOfOutcomes(aNumber) using the number of strings (value returned by NumItems) included in theOutcomesNames to recreate the definition. The names of the outcomes will be taken from theOutcomesNames.