Author : Kevin Mathias
Date: 06-20-2005

External documentation to use the BNB tool:

The BNB tool helps in generating fragments of large Bayesian networks. All fragments
for a single project are stored under a single project directory. In case of the
Welfare to work project a network fragment represents an action.e.g. Taking_GED. This
tool helps in drawing the network fragments. One would draw nodes (random variables),
draw the dependencies between the nodes and then set the node properties. Setting the
node properties means that one specifies the name of the node and the domain of the
node by specifying the datatype for the node. The datatypes for different domains
(context/random variable) are defined using the Administration module.One can also 
define the situation-specific domain for network by associating context variables
and its possible values with a network fragment (node as well as the entire fragment). 
While drawing a situation-specific domain network, the user sets the local (node, fragment)
and global context domains (project).

The BNB tool can work as a stand alone as well as connect to the BNBserver for 
storing and retreiving the network and situation domain xml files.

Here is a step-wise explanation of different operations in the BNB tool:

1. Command to run the tool: ./startBNB 

2. The user needs to start a Project. The user can work with one project at a
time. The user can open a previously created project or can create a new project.
   
Within each project the user can perform the following steps:

3. For setting domains for datatypes:
   3.1 Click on Administration
   3.2 Click on random variable for setting datatypes for random variables
   3.3 Add new datatype by entering the new datatype and clicking on add domain datatype
   3.4 For defining the domain of the existing or new datatype :
       3.4.1 Click on the corresponding datatype
       3.4.2 enter the values in the textbox corresponding to new domain values 
       3.4.3 for each domain values click the add domain value button
   3.5 After you are have defined the domains , click on the done button, you will go
       back to the main window
Note: You can similarly set the domain of datatypes for context variables.
    
4. For drawing the general network:
   4.1 Click on draw network in the menu and select "general network"
   4.2 To draw the network:
   	4.2.1 add node - adds a node when the mouse is clicked
	4.2.2 move node - moves the node clicked on to the other clicked position
	4.2.3 add dependency - dependency is created when the parent node and then the child 
	node is clicked (the arrow direction would show the relationship)
	4.2.4 delete dependency - removes the link between two nodes by clicking on them
	4.2.5 delete node - deletes a node and its corresponding dependencies when clicked  
   
   4.3 For setting node properties, use the edit node properties option and click on the node
   whose properties you want to set. The properties window displays the following:
   	4.3.1 Name - enter the name of the node
	4.3.2 Datatype - enter the datatype for the node (the list is setup in the 
	      administration task)
	4.3.3 Values - list is displayed depending on the datatype selected
	4.3.4 Click on the done button when you have finished setting the properties 
              for a node.
Note: To set the properties for another node, click on another node with the node properties
option selected and continue the steps (4.3.1 - 4.3.4)

   4.4 You can save the file by clicking on the save option. The file should end with
   the .xml extension. It gets saved in the current project directory. 
   
   4.5 You can also store the file on the BNBServer by clicking on BNBoperations. The
   Store command will store a new file on the server. If the file already exists then
   the user should click on Modify. Remember to save the file locally before using
   the BNBoperations.
   
   4.6 To start a new network, kindly follow the previous steps, which will take you to
   another tab window and then you can start from step 4.1 to draw another network.
 
5. For drawing the situation-specific domain network:
   The local context domain for the network fragment comprise of the node context and fragment context.
   The global context domain for the network is set for the entire project.
   
   5.1 Click on Import network in the menu and select "General"
   5.2 Click on the menu "File" to get the submenus Open, Save and Save As. Click on 
   Open to see the list of general networks available
   	5.2.1 select the network by clicking on the item menu having the network name
	5.2.2 the network would be imported (without distribution)
	5.2.3 the properties for the nodes in the network can be viewed by selecting the 
              option "view node properties". The node would get colored and the properties of
              the node would be displayed in a pop-up screen
	5.2.4 to set the local context domain for a node, click on the menu item "operations"
	      that lists "Situation-specific domain". On selecting this option, a new tabbed
	      window is created with the copy of the network. One should select the option 
	      "edit node context" and click on the node inorder to set the context domain
	      for the node. The context frame would display the different context 
              variables available for different nodes (if set before). The domain for these variables 
	      is already defined depending on the domain chosen or can be set by the user.
	      5.2.4.1 User can add new context variable by entering it in the textbox 
                      besides "new context variable" button. After entering the new context 
                      variable , click on the "new context" button which adds it to the
                      list of context variables.
	      5.2.4.2 The newly added context variable can have a context datatype (admin module) 
	      	      associated with it or the user can enumerate the domain for the context variable by entering
		      the value in textbox besides the button "new context domain".
	      5.2.4.3 If the user selects a finite domain datatype, e.g. Times, then an 
                      enumerated list is presented. The user can modify this list for the context variable.
	      5.2.4.4 Click on the Done button when you have finished setting the context
                      for a node.
Note: To set the context for another node, click on another node with the context properties
option selected and continue the steps mentioned in 4.2.4. 
	      5.2.4.5 Click on the edit fragment context properties for setting the fragment context domain for the
	              network fragment. The interface is similar to node context domain.
   5.3 The save option is similar to step 3.4 with only one difference. If the user saves the file as
   testing.xml, the tool would save this file as situationdomaintesting.xml, i.e. it prepends the string "situationdomain"
   to the filename given by the user.
   
   5.4 You can also store the file on the BNBServer by clicking on BNBoperations. The
   Store command will store a new file on the server. If the file already exists then
   the user should click on Modify. Remember to save the file locally before using
   the BNBoperations.
   
   5.5 To start a new situation-specific domain network, click on the Import menu and select the option "General"  which 
       will take you to another tabbed window and then you can start from step 4.1 to draw another situation-specific domain network.
    
   5.6 The global context domain is set from the menu option that says Global context. You have options to import the global context domain,
   or load it from the BN server. It also gives you the option of storing it on the BN server.
       
6. One can also import the general and situation-specific domain file and make changes to it. For that one should click on the Import menu
which gives the user two options: General and Situation-specific. After selecting any one, the interface is similar to step 4 in case
of general network and step 5.2.4 for situation-specific domain network.
   
7. One can also Load the general and situation-specific domain file from the BNBserver and make changes to it. For that one should click on the Load menu
which will provide a list of files on the BNBserver. After selecting any one file and clicking on the Load button, the file is copied locally to
the machine and the interface is similar to the import module. Note that if there is a file with the same name locally, then the local copy is overwritten
during the Load operation.

8. Close option is available under Project menu. 

9. One can quit the application by selecting quit on the main menu.


Future work: 

The current tool should be able to create situation specific fragments from the situation-specfic domain fragments.
The tool should communicate with the Semi-structured probabilistic database management system (SPDBMS) to retrieve distributions
for the fragments created. Knowledge-based Model construction algorithms will also be implemented to be able to form probability 
tables of fragments (nodes) from the underlying data available in the SPDBMS.