Documentation: Programming guide

Variables

This chapter explains how to declare and use variables in SPIRIT.

Variable Indexing

Each KBase must contain at least one variable to be able to make something of sense. You can fetch the number of variables actually in the KBase by calling 

int varCount = kb.getVarCount();

After its declaration, each variable is accessible through a unique index. The indices start at zero and increase with each variable added. Thus the indices are taken from the interval [0..kb.getVarCount() - 1]. Keep in mind, that some indices might have changed when you delete a variable.

Declaring Variables

There are two ways of adding a variable to a KBase:

You have to label a variable with a suitable name and assign a type to it. Depending on the selected type, you will have to supply some initial values for the variable. Here are some typical declarations: 

»Add a boolean variable...«
kb.addVar("pregnant", KBase.VT_BOOLEAN, null);
»Add a nominal variable...«
Vector colors = new Vector();
colors.addElement("red");
colors.addElement("green"); ťAt least two values are required!«
colors.addElement("blue");
kb.addVar("color", KBase.VT_NOMINAL, colors);
»Add a number variable...«
Vector amounts = new Vector();
amounts.addElement(new Double(-3.14));
amounts.addElement(new Double(0)); ťAt least two values!«
kb.addVar("amount", KBase.VT_NUMBER, amounts);
»Add an interval variable...«
amounts.addElement(new Double(42));
amounts.addElement(new Double(10000));
kb.addVar("ranges", KBase.VT_INTERVAL, amounts);
»Var contains 3 states«

Illegal calls of addVar (e.g. if you chose a name twice) are rejected. You can get the type of each variable using the KBase.getVarType method.

Deleting Variables

To remove variables from the KBase use the KBase.deleteVar method. All rules that the variable appears in are deleted too. For example, use the following command to delete the second variable of the KBase: 

kb.deleteVar(1);

Variable Values (States)

Variables of non-boolean type have a specified number of values (sometimes called states, booleans have exactly two values). Nominal and Number variables must possess of at least two values. The values of interval variables are its intervals: Declaring an interval variable with the boundaries 0, 2, 3 and 5 means that it can take 3 different states ([0..2], [2..3], [3..5]). The number of states a variable can take is called its arity. To get the number of values of the first variable use: 

int arity = kb.getVarArity(0);

The values of a variable must be unique and are accessed by an index ranging from zero to its arity minus one. You can request the name of a specified value using KBase.getValueName, as in 

String name = kb.getValueName(0,1);

Editing Variables

You can rename a variable using the KBase.renameVar method. Renaming a variable doesn't have any effect on the rules (i.e. the appearances in a rule are renamed too). You are able to change the set of values of any non-boolean variables: Use KBase.addValue to increase a variable's number of states 

»For a nominal variable«
kb.addValue(1, "yellow");
»For a number or interval variable«
kb.addValue(2, new Double(74));

Number and interval variables always sort their values in an ascending order. Adding a value to an interval variable means to split an existing interval into two parts or adding a new interval.

Utilities

Each value has a certain utility, i.e. a double value connected to some semantical information. These utilities can be fetched using the KBase.getUtility method.

The utility is used to compute the expected value (see ~ for further details).

Assigning User Infos to a Variable

You can assign arbitrary user infos to each variable (compareable to those infos that might be assigned to knowlegde bases). Examples for such information are screen coordinates in a graph, long names or additional comments on the variable. Use the twin methods KBase.getVarUserInfo and KBase.setVarUserInfo to get and set those infos.