The raw data file input from the association data converter can be in one of two formats:

The format file specifies the format of the raw data file to the association data converter.

The format file follows one of the forms listed in Table F-1 or Table F-2, depending on the raw data file's format (single or multiple item).

Table F-4 lists the set of options for controlling the rule-generation process. A description of each option follows the table.

-tran %s
Specifies the path for the file. By default, the file is read from stdin.

-prev %f
Specifies the minimum prevalence threshold as a percentage of the total number of records. The default is 1.0%. If the prevalence threshold results in a minimum count less than 3, an error message is displayed, and no rules are generated.

-uniq %d
Specifies the number of unique or distinct items across all records (if known). Specifying this (or an upper bound) speeds processing.

-dir %s
Specifies the directory to store temporary files, including the message file (see -msg, below). The default is ./ .

-tprefix %s
Specifies the prefix to be used for temporary files, except the message file (see -msg, below). The default prefix is A_.

-msg %s
Specifies the message file. The default is assocgen.msg.

Table F-5 lists the set of options for restricting generated rules. Options in this set are used after those listed in Table F-4 and separated on the command line from the former options by -ropts. A description of each option follows the table.

-pred %f
Specifies the minimum predictability threshold for rules. Rules with a predictability below this value are not generated. The default is 50%.

-rnum
Output only the number of rules generated, not the rules themselves.

-rsort %d [%s]+
Specifies the sort order for rules. The first number denotes the number of sorting fields specified; the second field of the option specifies the fields to be sorted. The four keys for sorting rules are (in order):

-names %s
Specifies the name of the file which contains the descriptions of the items. This is typically the names file created during the assoccvt step.

-rout %s
Specifies the name of the file to which rules are to be written. If this is not specified, rules are written to stdout.

There are no hierarchical data options common to both assocgen and mapassocgen. See “Hierarchical Data Options for mapassocgen Only”.

In addition to the options provided by the assocgen program, the mapassocgen program provides two additional options (Table F-6). These options are rule-generation options and thus must be specified in the first set of options (the set before the -ropts string). A description of each option follows the table.

-agg %d
Specifies the level of the hierarchy at which the rules are desired. Level 0 is the lowest level of the hierarchy, level 1 is the next level up in the hierarchy, and so on.

-map %d [%d]+ %s
Specifies a file that allows the mapassocgen program to map the lowest level in the hierarchy (present in the data) to the level at which the rules are desired. The first number specifies the total number of levels of aggregation. Next, for each level, a number denotes the size in bytes for the mapping value for that level. Finally, the path is given for the map file.

The values at the lowest level are the integers 0, 1, 2, 3, and so on. The map file lists the values at the new level (or levels) in the same order. First list the value(s) corresponding to level 1, then the value(s) corresponding to value 2, and so on. The values at the lowest level (level 0) are omitted because the list of values is in the implicit order 0, 1, 2, 3, and so forth.

Table F-7 provides an example from the dataset used in the “Hierarchical Data Example” section. This example has two hierarchical levels:

The first line in the mapping file (/usr/lib/MineSet/assocgen/examples/synth.map) indicates that the value “0” at the lowest level is mapped to value “1” at the next level; the second line indicates that the value “1” at the lowest level is mapped to value “0” at the next level; and so forth.

There are no rule restriction options specific to mapassocgen only. See “Rule Restriction Options Common to assocgen and mapassocgen”.

The option used for hierarchical data is listed in Table F-8. A description follows the table.

-lvldesc %d %s
Specifies the hierarchical level and the corresponding string description file. Each string description file must be on a separate line. The strings are mapped, in order, to items 0, 1, 2, 3, and so forth, at the hierarchy level.

This option follows all other options and must be separated from them by -vopts.

Assume the minimum prevalence threshold is 30% (3 records out of 10 in the example below). With a default minimum predictability threshold of 50%, and given the input file described above, the assocgen program generates the set of rules shown in Table F-10.

The fields in each line correspond to

Using the example dataset in “Nonhierarchical Data Example”, Table F-11 shows the mapping of the values at the lowest level to the highest level. The first column represents data at the lowest hierarchical level, while the values Snack, Dairy, and Beverage in the second column represent a higher hierarchical level.

In this example, value “Milk” is mapped to “Dairy”, value “Chips” is mapped to “Snack”, and so on. “Snack”, “Dairy”, and “Beverage” can be represented as integers 0, 1, and 2 in the mapping file. Then, the -map option can be specified as

-map 2 4 synth.map

where 2 indicates two levels in the hierarchy, 4 indicates a 4-byte integer for each value in the map file, and synth.map is the name of the map file. The binary file synth.map for our running example can be found in /usr/lib/MineSet/assocgen/examples and contains the following values (for purposes of illustration, numbers are provided in decimal rather than binary form):

1 0 2 1 2 0 1 1

To obtain rules at the lowest hierarchical level, specify -agg 0. The program output for this is shown in Table F-12.

When listing each item, the program shows the complete hierarchical description. For example, 0|1 indicates that item 1 (“Chips”) is mapped to value 0 (“Snack”) at the next higher level in the hierarchy. If you specify -agg 1, you get the rules at the next higher level of the hierarchy (which, for this example, is the top level):

1       1       80.0000   80.00    80.00  1     0

1       1       80.0000  100.00   100.00  0     1

To see the strings “Snack,” “Beverage,” and “Dairy” instead of values 0, 1, and 2 at the top-level hierarchy, specify a third set of options (described in the “Example of Applying Description Files”).

Using the example in “Hierarchical Data Example”, you can specify a description file for the top-level hierarchy (level 1) as follows:

mapassocgen -tran <dataFileName> -agg 1 -map 2 4  
        <hierarchyMappingFileName> -ropts -vopts  
        -lvldesc 1 <level1descriptionFileName>  
        -rout <rulesFileName>

The description file level1descriptionFileName now looks like this:

Snack

Dairy
Beverage

The rules at level 1 of the hierarchy then appear like this:

1       1       80.0000   80.00    80.00  Dairy    Snack

1       1       80.0000  100.00   100.00  Snack    Dairy

Similarly, you can specify a description file for the items at the lowest level. If the description file, synth0.names, looks like this:

Milk

Chips
Coffee
Eggs
Tea
Soda
Cheese
Butter

then item 0 is mapped to “Milk,” item 1 is mapped to “Chips,” and so on. Then if you specify the options string

-lvldesc 1 synth1.names -lvldesc 0 synth0.names

after -vopts, the rules generated at the lowest hierarchical level are shown in Table F-13.

The rules file is generated by the association rules generator (See “Association Rules Generator”).

The configuration file describes how the data from the rules file is to be displayed. This file consists of three sections:

An example configuration file, group.ruleviz, is

input {
   file “group.rules”;
}

expressions {
   float ratio = expected / predictability;
}

view {
   height predictability, max 10, legend on;
   disk height expected, legend on;
   color prevalence, scale 0 10, colors “white” “purple”,
   legend on;
   options grid size 6;
   message “LHS: %s\nRHS: %s\npredictability: %.2f  
   expected: %.2f  prevalence: %.2f”,
   LHS, RHS, predictability, expected, prevalence;
}

The input section has the form:

input { file “rulesFilename”; }

The file statement specifies the rules file. It is the only statement in the input section.

The expressions section of the configuration file defines field names to be used subsequently in both this section itself and in the view section. This section specifies new fields in terms of the fields in the rules file. For example, the following line specifies the ratio between predictability and expected predictability:

expressions { float ratio = predictability / expected; }

The expression section uses field names defined in the rules file. These field names and their types are listed in Table F-14.

Expressions are defined with a combination of field names and operators. The operations and their symbols are listed in Table F-15.

Also, the following functions are available:

The following sample code illustrates some of the possible expressions:

float variable0 = expected / predictability;
float variable1 = prevalence +1;
float variable2 = variable1 - 1;
float variable3 = variable1 * 3;
float variable5 = 10 % 4;
float variable6 = variable1;
float variable7 = variable1 || 87;
float variable8 = variable1 && 34;
float variable9 = (7 < 5 ? 4 : 3);
float variable10 = divide(15,8,9);
float variable11 = modulus(15,0,9);
float variable12 = (“abc” < “def” ? 1 : 2);
int variable 13 = (int) variable 12;

Expressions using int and float promote both sides to float. Expressions using int and double, or float and double, promote both sides to double. The result of a relational expression (for example, ==, <) is always an int. Type casting is also supported.

Strings can be compared using relational expressions; the strings are compared lexicographically.

The view section describes how data is presented. A rule is displayed at the junction of its left-hand-side and right-hand-side items. The view section lets you specify what is shown at the junctions.

The view section has the form:

view { viewStatement; ... }

You can view bars, disks, and labels at the junctions. The bars and disks have heights and colors.

The height statement describes how the rules are mapped to the heights of bars and disks. The height statement consists of a series of clauses, separated by commas. Alternatively, it can be specified as multiple height statements.

height sales, max 2.0;

or

height sales; 
max 2.0;

The first clause normally contains the name of a column that is to be mapped to bar height (sales, in the example). The column must be of a number type (int, float, or double); float is the most efficient. If no height column is specified, all bars are flat, and the remaining height clauses have no effect.

The max clause specifies the height of the tallest bars. If no max clause is specified, the height is 1.0 in arbitrary units. If, after looking at the view, you see that the heights are too low or too high, use the max clause to adjust them. The syntax of the max clause is

max float

where float is a floating point number (the decimal point is optional). For example, to specify the maximum height as 2, enter:

max 2

The scale clause scales the arbitrary height values; all values are multiplied by the scale. The syntax of the scale clause is

scale float

Do not use the scale clause with the max clause.

The legend clause specifies whether mapping information is displayed in the lower window pane. This information is about mapping between display entities and data values (for example, bar height corresponds to predictability values). The legend clause has the following syntaxes:

By default, the height statement affects bars. To specify disks, begin the statement with disk height:

disk height sales, max 2.0;

If no max or scale clause is specified for disk heights, the disks inherit the clause specified for bars.

The color statement describes how values are mapped to colors. The format is similar to the height statement, consisting of several clauses that can be separated by commas, or entered as multiple statements.

Color names must be in quotation marks. Examples of valid colors are “green,” “Hot Pink,” and “#77ff42.” The last one is in the form “#rrggbb”, in which the red, green, and blue components of the color are specified as hexadecimal values. Pure saturation is represented by ff, a lack of color by 00. For example, “#000000” is black, “#ffffff” is white, “#ff0000” is red, and “#00ffff” is cyan. You can use the colorview program to determine the names of the colors available on your workstation.

The color variable lets you map a column to a color. The column must be a number type. There is no normalization of colors.

The colors clause specifies the colors to be used. The colors clause syntax is:

colors "colorname" "colorname"...

The format for colorname has been described above. Note that there are no commas between the colors. This is because commas are used to separate clauses in the color statement. A sample colors clause is

colors "red" "gray" "blue"

Colors in the list are subsequently referred to by their index, starting at zero. In the above example, red is color 0, gray is color 1, and blue is color 2.

If there is no colors statement, all bars have the same color.

The scale clause allows assignment of values to a continuous range of colors. For example, when displaying a percentage, red can be assigned to 0%, gray to 50%, and blue to 100%. Intermediate values are interpolated; for example, 25% is pinkish, and 55% is a slightly bluish gray.

The syntax for the scale clause is

scale float float ...

The first value is mapped to color 0, the second to color 1, and so forth. The colors statement must contain at least as many colors as are to be mapped to the largest index.

Values in the scale clause must be in increasing order. Any value less than the first color is assigned the value of the first color. Any value greater than the last value is assigned the last color. Intermediate values are interpolated.

For example, assume the pctFemale column indicates what percentage of the group is female, and you want to map a group that is 100% female to red, 100% male to blue, and 50% each to gray. The colors statement for this is:

colors pctFemale, colors "blue" "gray" "red", scale 0 50 100;

The buckets clause is similar to the scale clause without interpolation. All values are rounded down to the highest value in the clause, and that exact color is used. Values less than the first value use the first color.

The syntax for the buckets clause is

buckets float float ...

The syntax and assignment of colors is the same as for the scale clause.

If, in the above example, you use the buckets clause instead of the scale clause, the statement is:

colors pctFemale, colors "blue" "gray" "red", buckets 0 50 100;

All values greater or equal to 100 are colored red. Values greater than or equal to 50, but less than 100, are gray. All remaining values is blue.

If a color variable is specified, but neither a scale clause nor a buckets clause is given, a default scale clause is used. The values are generated automatically, ranging from the minimum value to the maximum value in the data.

The legend clause creates a legend of the colors. The legend clause syntax can be any of the following:

legend off
legend on
legend "string" "string" ...
legend label "string"

The legend off clause turns the legend off. The legend on clause turns the legend on. It can be omitted if other legend statements are included. Specifying only legend on generates the default legend.

The default legend includes a single label to the left (with the name of the field that is mapped to color), and a list of colored labels on the right (with values obtained from the scale clause or the buckets clause). To override the strings in the colored labels, specify the strings as shown:

legend "string" "string"

To override the label on the left, specify it following the word label. To eliminate this label, specify an empty string; that is:

legend label ""

By default, the color statement affects bars. To affect disks, begin the statement with disk color:

disk color pctFemale;

If no colors, scale, or buckets clause is given for disk colors, the disks inherit the clauses given for bars.

You can specify a variable name and a color for labels to appear in front of the bars, at the base. By default, no labels appear. The color is a single color (unlike the bars and disks). For example, the following line displays the numeric predictability value in red at the base of each bar:

label predictability, color “red”;

The message statement specifies the message displayed when the pointer is moved over an object or when an object is selected. The syntax is similar to that of the C printf statement. A sample message statement is

message "LHS: %s\NRHS: %s\npredictability/expected: %.2f",
LHS, RHS, predictability/expected;

This could produce the following message:

LHS: milk
RHS: bread
predictability/expected: 2.00

The formats must match the type of data being used:

For details of the printf format, see the printf (1) reference (man) page (type man printf at the shell prompt).

A special format type has been added to printf. If the percent sign is followed by a comma (for example, %,f), commas are inserted in the number for clarity. Currently, only the United States convention of d,ddd,ddd.dddd is supported, with the decimal point represented by a period, and commas separating every three places to the left of the decimal point. For example, if the above format were:

message "LHS: %s\nRHS: %s\npredictability/expected: %.2f",
      LHS, RHS, predictability/expected;

it would produce the message:

LHS: milk
RHS: bread
predictability/expected: 1,000.00

The $, *, h, l, ll, L, and n printf format options are not supported.

All values, including the format string, are expressions. Thus, if want to distinguish rules with predictability greater than twice the expected, you can use

message predictability > expected*2 ? "LHS: %s\nRHS:
      %s\npredictability/expected: HIGH" : "LHS: %s\nRHS:
      %s\npredictability/expected: LOW" , LHS, RHS;

This could produce the message

LHS: milk
RHS: bread
predictability/expected: LOW

or:

LHS: milk
RHS: cake
predictability/expected: HIGH

You could also achieve the same result with a single format string:

message "LHS: %s\nRHS: %s\npredictability/expected: %s",
   LHS, RHS, predictability > expected*2 ? "HIGH" : "LOW";

If no message is specified, a default message is used.

An item statement describes the item names displayed along the LHS and RHS axes. An item statement has the form

item colors <colorLeft> <colorRight>;

The colors are absolute colors, like the label color. There is also a statement to turn on/off the item names:

item <off|on>;

Display axes may be customized using the syntax:

item labels <leftLabel> <rightLabel;

For example

item labels “LHS” “RHS”;

produces the same as the default found in the examples file /usr/lib/MineSet/ruleviz/examples/category.ruleviz.

The grid statement describes the grid on which the rules are displayed. A grid statement has the form

grid color <color>;

or

grid <off|on>;

The color is a single color.

The options statement lets you fine-tune certain parameters of the display. When the view section is first entered, options are loaded from the defaults file /usr/lib/MineSet/ruleviz/view.ruleviz.options. This file is searched for in the following directories, in the order listed:

The file is not required to be present.

Options specified directly in the configuration file override those in the defaults files. The syntax of the options statement is

options option, option, ...

The following options are available:

The following is a description of each option.