Reference Manual: DSL noisyMAX

From DSL

The class DSL_noisyMAX provides implementation of very popular parametric gate Noisy-OR. Actually, noisy-MAX is a generalization of noisy-OR capable modeling multiple states. If you keep your nodes as binary, the DSL_noisyMAX will be simply a noisy-OR. The class DSL_noisyMAX is capable to express relationships modeled by noisy-AND/MIN, because by providing the mechanism for manipulating the order of outcomes in the node as well as assigning the strengths of parents' outcomes, noisy-AND/MIN can be expressed as OR/MAX only by means of changing orders of states and assigning causal strengths.

In literature one can find two different (but defining the same model) parameterizations of noisy-OR/MAX. They are often referred by names of the researchers, however this convention can be misleading. The two parameterizations are in forms and . The first one is used in DSL_noisyMAX as a 'native', while there is implemented interface to set or obtain parameters in the other form. We will refer to the first form as Diez parameters, while second Henrion parameters.

The implementation of noisy-MAX does not keep expanded full CPT by default. DSL_noisyMAX can work in two modes - KeepExpanded or DontKeepExpanded (by default).

KeepExpanded means, that DSL_noisyMAX will keep DSL_Dmatrix containing full CPT expanded and updated all the time. This produces extra overhead in calculations and memory allocations, but access to expanded CPT is immediate and without cost.

In the mode DontKeepExpanded, the full CPT is calculated only on explicit user request (like method GetCpt()). However each call to this method will be costly since, SMILE will update DSL_Dmatrix containing full CPT every time the method was called. In this mode there's an alternative method of accessing single probability distribution without expanding whole CPT - CalculateCptColumn(). This can be suggested, when noisy-MAX has multiple parents and storing whole CPT is too expensive or even impossible.

To switch between the modes there are two methods provided: SetKeepSynchronized() and SetDontKeepSynchronized().

The noisy-MAX parameters are stored in Dmatrix, which in noisy-MAX case always has two dimensions. The elements of the first dimension (number 0) correspond to parents states, and elements of the second dimension (number 1) correspond to states of noisy-MAX node.

The order of the outcomes is assumed to be descending, with the 'absent' state for noisy-MAX/OR always at the end.

The noisy-MAX parameters are stored in a following way: starting from the first parent of noisy-MAX, each parent node has assigned number of elements in dimension equal to its number of outcomes. For example, if noisy-MAX, with two states, has three parents with number of states: 2, 3, and 4, the corresponding Dmatrix will be as follows:

The regions marked as gray, denote constraints on noisy-MAX parameterization - the last state of each parent is assumed to have distribution {0.0,0.0,&ldots; ,1.0}. Implementation of noisy-MAX in SMILE, allows user to define order of parents states by assigning them 'strengths'. The details regarding assignments of the strengths are includes in further part of the documentation for noisy-MAX.

The class DSL_noisyMAX introduces the concept of outcome strengths. In DSL_noisyMAX class, user has possibility of control, in what is parent's outcomes order in causal relation. For each parent's outcome there's assigned outcome strength, which defines this order. The value of strength 0 indicates the strongest influence and the greatest value is assigned to distinguished state. The DSL_matrix containing parameters always follows order of strengths - this means, that the first column is aligned to the outcome of the greatest strength, the second column to the outcome of the second strength end so on. The distinguished state is always assigned to the last column.

It is important to note, that when obtaining full expanded CPT, the order of outcomes is preserved as was original in parents, and outcome strengths don't play any role. In other words, DSL_Dmatrix should be treated exactly in the same way as for DSL_cpt.

Methods

• int CiToCpt()

Enforces updating the full CPT using noisy-MAX parameters. Returns DSL_OKAY if the action was successful and error code otherwise.

• int CptToCi()

Enforces updating noisy-MAX parameters using the full CPT definition. It is using default SMILE algorithm. If the user wants to specify parameters of conversion, the particular method for conversion should be used (described below). Returns DSL_OKAY if the action was successful and error code otherwise.

• int CheckCiWeightsConsistency(DSL_Dmatrix &ciWeights, char * errorMsg, int errorMsgBufSize)

Allows the user to verify correctness of the noisy-MAX parameters in ciWeights. It returns DSL_OKAY, if the parameters are correct, otherwise returns an error code and the error message is copied in C-style string of the length errorMsgBufSize pointed by errorMsg.

• int CheckHenrionConsistency(DSL_Dmatrix &henrion, char * errorMsg, int errorMsgBufSize)

Allows the user to verify correctness of Henrion's noisy-MAX parameters stored in henrion. It returns DSL_OKAY, if the parameters are correct, otherwise returns an error code and the error message is copied in C-style string of the length errorMsgBufSize pointed by errorMsg.

• int CalculateCptColumn (const DSL_intArray &coordinates, DSL_doubleArray &here)

Allows to calculate (without actual expanding) one distribution (column) in CPT. Input parameters coordinates are coordinates of requested distribution (indexed by order of outcomes in parents) and the output is a distribution provided in here. Returns the starting position (index in 0th dimension) corresponding to parent given parentPosition (index of parent in list of parents). If error occurs, returns DSL_OUT_OF_RANGE.

• int GetNumOfParentOutcomes(int parentPos)

Returns the number of parent outcomes for parent given parentPosition (index of parent in list of parents), if error occurs, returns DSL_OUT_OF_RANGE.

• int GetStrengthOfOutcome(int parentPos, int parentPosOutcome)

Returns the 'strength' of the parent's outcome on position parentPosOutcome in parent node. The parent is described by parentPosition (index of parent in list of parents), if error occurs, returns DSL_OUT_OF_RANGE.

• int GetOutcomeOfStrength(int parentPos, int outcomeStrength)

Returns the index in list of the outcomes of the parent given by parentPosition, corresponding to the outcome strength outcomeStrength. If error occurs, returns DSL_OUT_OF_RANGE.

• DSL_intArray &GetParentOutcomeStrengths(int parentPos)

Returns the array of indexes of outcomes in parent node given by parentPos, which is indexed by the 'strengths'. The value of the array at 0th position indicates the 'strongest' influence.

• int GetHenrionProbabilities(DSL_Dmatrix &henrion)

Allows the user to retrieve noisy-MAX parameters in form proposed by Henrion. Returns DSL_OKAY if the action was successful, otherwise an error code. The format Dmatrix with Henrion's parameters is exactly the same as native SMILE's noisy-MAX parameters. The method automatically reshapes Dmatrix henrion.

• DSL_Dmatrix &GetCpt()

Returns reference to the full CPT specified by noisy-MAX parameters.

• DSL_Dmatrix &GetCiWeights()

Returns reference to Dmatrix containing noisy-MAX parameters. See introduction to noisy-MAX for details.

• int IsExpanded()

Allows the user to verify if the content of CPT is valid. Returns 0, if the content of CPT is invalid and non zero value (constant DSL_CI_EXPANDED_CPT) if the content is valid. To validate content of the full CPT call CiToCpt().

• int KeepSynchronized()

Returns non-zero value (value of the DSL_CI_KEEP_IN_SYNC constant) if the flag DSL_CI_KEEP_IN_SYNC is set, otherwise returns 0.

• int KLCptToCi(DSL_Dmatrix& cpt, DSL_Dmatrix& ci, double step, double minStep)

The method allows the user to identify the 'closest' fit of noisy-MAX parameters for given CPT using Kullback-Leibler distance. The source CPT is in cpt, the approximation of noisy-MAX parameters is returned in ci, the initial step of algorithm should be provided in step and the precision defined by minStep.

• int SquareCptToCi(DSL_Dmatrix& cpt, DSL_Dmatrix& ci, double step, double minStep)

The method allows the user to identify the 'closest' fit of noisy-MAX parameters for given CPT using Euclidean distance. The source CPT is in cpt, the approximation of noisy-MAX parameters is returned in ci, the initial step of algorithm should be provided in step and the precision defined by minStep.

• int SetHenrionProbabilities(DSL_Dmatrix &henrion)

Similar to the one above, allows to set probabilities using Henion's definition of noisy-MAX parameters. Returns DSL_OKAY if the action was successful, otherwise an error code.

• int SetDefinition(DSL_Dmatrix &withThis)

Allows the user change noisy-MAX parameters, the content of withThis id described in the introduction to noisy-MAX.

• int SetDefinition(DSL_doubleArray &withThis)

Similar to the previous one, withThis is the DSL_doubleArray.

• void SetKeepSynchronized()

Sets the flag DSL_CI_KEEP_IN_SYNC, that indicates that after each operation on the noisy-MAX parameters, the Dmatrix containing full CPT is automatically updated.

• void SetDontKeepSynchronized()

Removes the flag DSL_CI_KEEP_IN_SYNC, that indicates that after each operation on the noisy-MAX parameters, the Dmatrix containing full CPT is automatically updated.