Reference Manual: DSL network

From DSL
Jump to: navigation, search

This class holds most of the functionality of the library. A network contains nodes. Each node is assigned a unique handle that can be used to access it. A handle is an integer that is guaranteed to remain constant for the lifetime of the network. In the description of the methods of this class, we will use the node itself and the handle of the node as the same thing.


Methods

  • int AbsorbEvidenceNode(int theParent, int theChild)

This function "absorbs" the evidence of theParent into theChild removing the arc between them. If the node has a table indexed by theParent, the table will be "shrunk" by removing the dimension corresponding to theParent. The contents preserved correspond to the outcome observed of theParent. For this function to succeed theParent and theChild must be valid nodes, the arc must exist, and theParent must be observed. Affected nodes will be invalidated if relevance reasoning is active.

Error return values: DSL_OUT_OF_RANGE (if any of the conditions mentioned above is not true).


  • void ActivateRelevance(void)

Relevance reasoning will take place after every change that affects the network. These changes may be structural changes (Ex: adding an arc) or definition changes (Ex: the conditional distribution of a node is changed). This function works like a global switch. When activated, all the relevance levels set with the method SetRelevanceLevelFlag will become active.


  • int AddArc(int theParent, int theChild)

Adds an arc from theParent to theChild. For this function to succeed, all of the following conditions must be true: theParent and theChild are valid node handles, the arc will not create a cycle, there is not already an arc from theParent to theChild, and theChild can have theParent as a parent given their type (For example, a DSL_MAU node cannot have a DSL_CPT as a parent). Affected nodes will be invalidated if relevance reasoning is active.

Error return values: DSL_OUT_OF_RANGE (if any of the conditions mentioned above are not true).


  • int AddNode(int thisType, char *thisId)

Adds a node of thisType to the network. See the description of DSL_nodeDefinition class for information on the different node types and the possible values of thisType. thisId indicates the identifier of the new node. If thisId is NULL, a unique identifier will be generated. If the node is correctly created, the returning value will be the handle of the node. This handle is guaranteed to remain constant for the lifetime of the network.

Error return values: DSL_OUT_OF_MEMORY, DSL_OUT_OF_RANGE (thisId is already in use).


  • AnnealedMAP(

const std::vector<std::pair<int,int> > &evidNodes,

const std::vector<int> &mapNodes,

std::vector<int> &mapStates,

double &probM1E,

double &probE,

int randSeed

)

- evidNodes: This vector contains the evidence node ids and their corresponding state ids.

- mapNodes: This vector contains the ids of map nodes.

- mapStates: This vector returns the states of the most likely configuration of the MAP nodes. Each number in this vector corresponds to the state of the node that has the same index in vector mapNodes.

- probM1E: This number returns the probability of the map solution given the evidence, i.e., p(mapNodes = mapStates|evidNodes).

- probE: This number returns the probability of the given evidence set in evidNodes, i.e., p(evidNodes).

- randSeed: User can provide a random seed so that AnnealedMAP can repeart its results.


Return value: DSL_OKAY.

Description: The AnnealedMAP algorithm is described in (Yuan & Druzdzel 2004). It solves the problem of finding the most likely configuration (MAP) of a set of nodes given the evidence on another set of nodes by applying Gibbs sampling and simulated annealing technique powered by reheating as a function of cost. The result of this algorithm is an approximate solution. However, this algorithm drastically extends the class of MAP problems that can be solved.


  • int BecomesAcyclic(int theParent, int theChild)

Returns a non-zero value if a cycle would be created when adding an arc from theParent to theChild.


  • DSL_creation &Creation(void)

Returns the DSL_creation structure that contains information about the network.


  • int ChangeOrderOfParents(int ofThisNode, DSL_intArray &newOrder)

Changes the order of parents ofThisNode. The newOrder contains permutation vector, where i-th element with value x indicates, that after permutation, the i-th position will be occupied by element which was before on x-th position. Returns DSL_TRUE if operation was successful.


  • void ClearRelevanceLevelFlag(int thisFlag)

Deactivates particular cases in which relevance reasoning will take place. See the SetRelevanceLevelFlag method for details.


  • int ClearAllTargets(void)

Clears the target mark of all the nodes in the network.


  • int ClearAllEvidence(void)

Clears all the evidence in the network. Affected nodes will be invalidated if relevance reasoning is active.


  • int DeleteNode(int thisNode)

Deletes thisNode from the network. thisNode is the handle obtained when the node was created.


  • void DeactivateRelevance(void)

Prevents relevance reasoning from taking take place after every change that affects the network. This function works like a global switch. When deactivated, all the relevance levels set with the method SetRelevanceLevelFlag will be ignored.


  • void EnableNoisyMAXRelevance(bool enable=true)

This method enables/disables relevance for the noisy-MAX nodes. When enabled, nodes that are the noisy-MAX and they have evidence corresponding to the last state are decomposed. Such decomposition can lead to savings during inference.

Additionally, there is a 'magic' user property in DSL_network that has power to override this setting. If in UserProperties there is set DSL_NOISYMAXRELEVANCE with value 1 (or other non-zero value) the noisy-MAX relevance will be applied, if the value is 0, the relevance will be disabled. If the property DSL_NOISYMAXRELEVANCE is present in the network, the flag set by this method will be ignored.


  • DSL_errorStringHandler &ErrorHandler(void)

Grants access to the instance of the error handler class used to log/retrieve errors.


  • int FindNode(char *withThisID)

Returns the handle of the node withThisID.

Error return values: DSL_OUT_OF_RANGE (there is no node withThisID).


  • DSL_intArray &GetChildren(int ofThisNode)

Returns a list that contains the handles of the children ofThisNode.


  • DSL_node *GetNode(int theNode)

Returns a pointer to theNode. theNode is the handle obtained when the node was added to the network using the function AddNode. This pointer not guaranteed to remain constant so it should not be stored "for later use". Store the handle of the node instead.


  • DSL_intArray &GetParents(int ofThisNode)

Returns a list that contains the handles of the parents ofThisNode.


  • int GetNumberOfSamples(void)

Returns the number of samples that will be taken when a sampling algorithm is invoked.


  • int GetNumberOfTargets(void)

Returns the number of target nodes contained in the network. See the definition of target node in the relevance reasoning section for more information.


  • int GetDefaultIDAlgorithm(void)

Returns the default algorithm for solving influence diagrams. See the description of the function SetDefaultIDAlgorithm for the possible return values.


  • int GetNumberOfNodes(void)

Returns the number of nodes contained in the network.


  • int GetDefaultBNAlgorithm(void)

Returns the default algorithm for solving belief networks. See the description of the method SetDefaultBNAlgorithm for the possible return values.


  • int GetAncestors(int theNode, DSL_intArray &here)

Returns here the handles of the ancestors of theNode. See the definitions section to find out what are the ancestors of a node.


  • int GetDescendants(int theNode, DSL_intArray &here)

Returns here the handles of the descendants of theNode. See the definitions section to find out what are the descendants of a node.


  • int GetRelevanceLevelFlags(void)

Returns all the cases (in the form of flags) in which relevance reasoning will take place. See SetRelevanceLevelFlag function for details.


  • int GetNumOfAncestors(int theNode)

Returns the number of ancestors of theNode.


  • int GetNumOfDescendants(int theNode)

Returns the number of descendants of theNode.


  • int GetFirstNode(void)

Returns the handle of the first node of the network. You can use a combination of GetFirstNode and GetNextNode to traverse the whole network.


  • int GetNextNode(int ofThisNode)

Returns the handle of the next node ofThisNode(this is not necessarily ofThisNode+1). You can use a combination of GetFirstNode and GetNextNode to traverse the whole network.


  • int GetAllNodes(DSL_intArray &here)

Returns here the handles of all the nodes in the network.


  • DSL_header &Header(void)

Returns the DSL_header structure that contains information about the network.


  • bool IsNoisyMAXRelevanceEnabled(void)

It returns true if the relevance algorithm for the noisy-MAX nodes is enabled. By default it is disabled. See EnableNoisyMAXRelevance for more information.


  • int IsThisGuyMyParent(int Me, int He)

Returns a non-zero value if there is an arc from He to Me.


  • int IsThisIdentifierInUse(char *theId, int skipThisNode = -1)

Returns a non-zero value if theId is already being used by another node. Remember that identifiers of nodes should be unique in a given network. skipThisNode is the handle of a node that we may want to ignore (if we want all the nodes checked, just use the default value).


  • int IsThisGuyMyChild(int Me, int He)

Returns a non-zero value if there is an arc from Me to He.


  • int IsRelevanceLevelSet(int thisFlag)

Returns non-zero if relevance reasoning will take place for the case specified by thisFlag. See the SetRelevanceLevelFlag method for details.


  • int IsTarget(int thisNode)

Returns a non-zero value if thisNode is marked as target.


  • int IsPolyTree(void)

Returns a non-zero value if the network is a polytree. See the definitions section to find out what a polytree is.


  • int InDegree(void)

Returns the number of parents of the node with the most parents.


  • int IsAcyclic(void)

Returns a non-zero value if there are no cycles in the network.


  • int InvalidateAllBeliefs(void)

Invalidates the value of all the nodes of the network except those that are evidence.


  • int MarginalizeNode(int theParent, int theChild)

This function "marginalizes" theParent into theChild removing the arc between them. If the node has a table indexed by theParent, the table will be "shrunk" by removing the dimension corresponding to theParent and marginalize the conditional distribution using the prior beliefs of theParent (i.e., you obtain the distribution of theChild unconditioned on theParent). For this function to succeed theParent and theChild must be valid nodes and the arc must exist. Affected nodes will be invalidated if relevance reasoning is active.

Error return values: DSL_OUT_OF_RANGE (if any of the conditions mentioned above are not true).


  • void MinRelevant(void)

Removes from the network all those nodes that are not relevant to the target nodes. It also eliminates nuisance nodes and barren nodes and absorbs all the evidence into children nodes. See the section on relevance reasoning for more details.


  • int NumParents(int ofThisNode)

Returns the number of parents ofThisNode.


  • int NumChildren(int ofThisNode)

Returns the number of children ofThisNode.


  • int OrderPartially(DSL_intArray &theseNodes)

Orders thisNodes partially (i.e., after returning from this function, thisNodes will be ordered according to the partial order of the network). See the definitions section to see what is the partial order of a network.


  • int OrderTemporally(DSL_intArray &theseNodes)

Orders theseNodes temporally (i.e., after returning from this function, theseNodes will be ordered according to the temporal order of the network). See the definitions section to see what is the temporal order of a network.


  • int Ok(int aNode)

Returns a non-zero value if aNode is a valid handle for this network.


  • DSL_intArray &PartialOrdering(void)

Returns a list with the nodes ordered in partial order. Partial order guarantees that each node appears always after his parents.


  • int Related(int aNode, int anotherNode)

Returns a non-zero value if aNode and anotherNode are directly related (i.e., if there is an arc from any of them to the other).


  • int RemoveArc(int theParent, int theChild)

Removes the arc from theParent to theChild. For this function to succeed theParent and theChild must be valid nodes and the arc must exist. If the node has a table indexed by theParent, the table will be "shrunk" by removing the dimension corresponding to theParent. The contents preserved correspond to the outcome 0 (zero) of theParent. Affected nodes will be invalidated if relevance is active.

Error return values: DSL_OUT_OF_RANGE (if any of the conditions mentioned above are not true).


  • int ReadFile(char *thisFile, int fileType = 0)

Fills the network with the contents of thisFile. thisFile must include the full path if needed. fileType specifies the format of the file according to the following values:

Value of [fileType] Format used by the program:
DSL_DSL_FORMAT Old native format of SMILE:. Discontinued.
DSL_ERGO_FORMAT Old ERGO format (Mac version)
DSL_NETICA_FORMAT Netica© version 1.06.
DSL_HUGIN_FORMAT Hugin© version 3.1.1 (API).
DSL_INTERCHANGE_FORMAT Microsoft© Bayes Networks version 1.0.1.7 (API).
DSL_XDSL_FORMAT New native format of SMILE:. Recommended.


If fileType is not specified or is not any of those values, an attempt to "guess" the type of the file will made based on its extension. (Ex: SMILE files usually have ".dsl" as extension).


  • int SetNumberOfSamples(int aNumber)

Sets the number of samples that will be taken when a sampling algorithm is invoked. Some of the samples taken may not be consistent with current evidence and will be discarded. See the algorithms reference to find out more about this.


  • void SetDefaultBNAlgorithm(int theAlgorithm)

Sets theAlgorithm as the algorithm to be used when updating a belief network. The possible values for theAlgorithm and their references are:

Value of [theAlgorithm] As described in:
DSL_ALG_BN_LAURITZEN Huang Cecil, and Darwiche, Adnan. (1996) Inference in Belief Networks: A Procedural Guide. International Journal of Approximate Reasoning, 15, 225-263. [1]
DSL_ALG_BN_HENRION Henrion, Max. (1988). Propagating Uncertainty in Bayesian Networks by Probabilistic Logic Sampling. In Lemmer, J.F. and Kanal, L.N. (Eds.) Uncertainty in Artificial Intelligence, 2. North Holland. 149-163.
DSL_ALG_BN_PEARL Judea Pearl. (1986). Fusion, Propagation, and Structuring in Belief Networks. Artificial Intelligence, 29(3), 241-288. [2]
DSL_ALG_BN_LSAMPLING Shachter, Ross D. and Peot, Mark A. (1990). Simulation Approaches to General Probabilistic Inference on Belief Networks. In M. Henrion and R.D. Shachter and L.N. Kanal and J.F. Lemmer (Eds.) Uncertainty in Artificial Intelligence, 5. North Holland. 221-231. [3] [4]
DSL_ALG_BN_SELFIMPORTANCE Shachter, Ross D. and Peot, Mark A. (1990). Simulation Approaches to General Probabilistic Inference on Belief Networks. In M. Henrion and R.D. Shachter and L.N. Kanal and J.F. Lemmer (Eds.) Uncertainty in Artificial Intelligence, 5. North Holland. 221-231. [5] [6]
DSL_ALG_BN_BACKSAMPLING Fung, Robert and Favero, Brendan Del. (1994). Backward Simulation in Bayesian Networks. Proceedings of the Tenth Conference on Uncertainty in Artificial Intelligence, 227-234. San Francisco, CA. [7]
DSL_ALG_BN_AISSAMPLING Cheng, Jian and Druzdzel, Marek J. (2000). AIS-BN: An Adaptive Importance Sampling Algorithm for Evidential Reasoning in Large Bayesian Networks. Journal of Artificial Intelligence Research 13(2000) 155-188. Pittsburgh, PA [8]
DSL_ALG_BN_EPISSAMPLING Yuan, Changhe and Druzdzel, Marek J. (2003). An Importance Sampling Algorithm Based on Evidence Pre-propagation. In Kjærulff, U. and Meek, C. (Eds.) Uncertainty in Artificial Intelligence, 19. Acapulco, Mexico. 624-631. [9]
DSL_ALG_BN_LBP Judea Pearl, (1982) "Reverend Bayes on inference engines: A distributed hierarchical approach". Proceedings of the Second National Conference on Artificial Intelligence. AAAI-82: Pittsburgh, PA. [10]
DSL_ALG_BN_LAURITZEN_OLD Old implementation of Lauritzen in SMILE. New implementation is much faster and uses less memory. Use this implementation only if you want to verify accuracy of new implementation


  • void SetDefaultIDAlgorithm(int theAlgorithm)

Sets theAlgorithm as the algorithm to use when updating an influence diagram. The possible values for theAlgorithm and their references are:

Value of [theAlgorithm] As described in:
DSL_ALG_ID_COOPERSOLVING Cooper, G.F. (1988). A method for using belief networks as influence diagrams. Proceedings of the Workshop on Uncertainty in Artificial Intelligence, 56-63. Minneapolis, Minnesota. [11]
DSL_ALG_ID_SHACHTER R.D. Shachter and M.A. Peot (1992), Decision Making Using Probabilistic Inference Methods. Proceedings of the Eighth Annual Conference on Uncertainty in Artificial Intelligence, 227-234. Stanford University, California. [12]


The belief network algorithm used when solving an influence diagram will be the one set using the function SetDefaultBNAlgorithm.


  • int SetTarget(int thisNode)

Marks thisNode as target node. When updating the network, only those nodes that are relevant to the target nodes will be taken into account. See the section on relevance reasoning for more details.


  • void SetRelevanceLevelFlag(int thisFlag)

Activates particular cases in which relevance reasoning will take place. The possible cases and the event that will trigger them are:

Value for [thisFlag] Event that invokes relevance reasoning
DSL_RELEVANCE_ARC_ADDED Event that invokes relevance reasoning
DSL_RELEVANCE_ARC_REMOVED An arc was removed.
DSL_RELEVANCE_EVIDENCE_SET The value of a node has been observed .
DSL_RELEVANCE_EVIDENCE_CLEARED The observation of a node is no longer valid.
DSL_RELEVANCE_PROPAGATED_EVIDENCE_SET The value of a node was deduced from other evidence.
DSL_RELEVANCE_PROPAGATED_EVIDENCE_CLEARED The deduced value of a node is no longer "deducible" from other evidence.
DSL_RELEVANCE_NUMBER_OF_OUTCOMES_CHANGED The number of outcomes of a node has changed.
DSL_RELEVANCE_DISTRIBUTION_CHANGED The conditional distribution of a node has changed.
DSL_RELEVANCE_GENERAL_CHANGE A non-specific general change that requires relevance reasoning to take place has happened.


Remember that, for this to work, relevance reasoning should be activated globally by means of the ActivateRelevance method.


  • void SetRelevanceLevelFlags(int thisFlags)

Sets all the cases (specified in thisFlags) in which relevance reasoning will take place. See the SetRelevanceLevelFlag method for details.


  • int TemporalOrder(DSL_intArray &here)

Returns a list with the nodes ordered in temporal order. Temporal order guarantees that decision nodes and informational predecessors of decision nodes are ordered according to the semantics of influence diagrams. When in the same temporal "slot", nodes will be partial-ordered. See the definitions section for more details.


  • int UnSetTarget(int thisNode)

Clears the target mark of thisNode.


  • int UpdateBeliefs(void)

This function will update the network using the default algorithm set by the SetDefaultBNAlgorithm and SetDefaultBNAlgorithm functions. Only those nodes that are relevant to the nodes that are marked as targets will be updated. If no nodes are marked as targets, all the nodes of the network will be updated. See the tutorials to find out more about updating a network.


  • int ValueOfInformation(DSL_valueOfInformation &here)

Calculates the value of information for the parameters specified here. The result will also be stored here. See DSL_valueOfInformation class documentation and the tutorials for more details.


  • int WriteFile(char *thisFile, int fileType = 0)

Writes the contents of the network in thisFile in the specified format. See ReadFile method

for more details.

Retrieved from "http://genie.sis.pitt.edu/w/index.php?title=Reference_Manual:_DSL_network&oldid=13181"
Personal tools