The first part of this appendix describes the types and formats of data supported by the Tree Visualizer. Data input to the Tree Visualizer must be provided as a single file containing raw data, usually in a tab-separated ASCII text form.
The second part discusses the configuration file, which describes how the Tree Visualizer reads in, and graphically displays, the data file.
Note that both the data and configuration files can be generated automatically by the Tool Manager (see Chapter 3).
In its simplest form, the data file consists of a list of lines, each containing a set of fields separated by one tab. (Other separators are also allowed—see “Input Options”—but only one can separate each field). All lines must contain the same fields. (The interpretation of the fields is specified by the configuration file, described in the next section.) For example, using the retail store data (store.treeviz file) provided as part of the Tree Visualizer package, the first few lines of the input file look like this:
In this example, the first five columns are strings: region, state, city, store ID, and product. These are followed by three numbers, representing current sales, last year's sales, and the sales target. (The specific mapping to those values is defined in the configuration file, described in the section “The Configuration File.”)
The data file cannot contain blank lines or comments. Missing or extra data on a line causes an error.
Eastern:Maryland:Baltimore:1816:appliances:72:115:138 |
The order of the columns must match the format of the configuration file. The order of the rows affects the layout of the final graphic, unless the configuration file specifies sorting. Generally, objects appearing earlier in the file appear to the left of objects appearing later in the file.
Any field in the data can also be a “?”, indicating that the data is null (unknown). See Appendix G, “Nulls in MineSet.”
The Tree Visualizer supports integer, floating-point number, and string data types, as well as arrays of these types. The following five data types are supported:
float represents a single-precision floating point number. The decimal point is optional. Numbers in exponential “e” notation are also accepted.
double represents a double-precision floating point number. The decimal point is optional when representing a floating point number. Numbers in exponential “e” notation are also accepted. The superior precision of double can be useful for accurately representing large numbers, since float can represent only seven or eight significant digits accurately. This superior accuracy, however, consumes twice the memory space of float.
dataString represents a string that is unlikely to appear multiple times. If it appears multiple times, several copies are made. A dataString can be used to store an address. Addresses are unlikely to be compared, and each record can have a different address.
string represents a string of characters that can appear multiple times in the data file. Unlike a dataString, only a single copy of a given string is stored in memory, no matter how many times it appears in the data. This saves memory for strings appearing many times.
Comparing strings is also much quicker than comparing dataStrings. Reading in strings can be slower than reading in dataStrings because it is necessary to look for duplications. An example of string use is a division name that appears once for each department in the division. If you are unsure whether to use a string or a dataString, use a string.
You can create a special data type that maps consecutive integers to strings. These types are referred to as enumerations, or enums. For example, you can create a state enum that maps 0 to Alabama, 1 to Alaska, and so on. Often, enums are created by the Tool Manager to represent bins. For example, 0 might map to a bin representing <10, 1 to the bin 10-20, and so on.
With the Tree Visualizer, you can use one-dimensional arrays of fixed or variable size.
In a fixed-sized array, all entries of the given type have the same number of values. For example, the budgets of the 50 United States, can be represented by a separate float column for each state, or by a single array with 50 floats.
A special form of a fixed array is an “enumerated array.” Like the normal fixed array, there are a fixed number of values in the array; however, the values are associated with an enumeration. For each value in the enumeration, there is a single entry in the array. For example, if there is an enumeration representing the 50 states, an enumerated array based on this enumeration has 50 values. (Note that in MineSet release 1.0, the enumerated array was referred to as a “keyed fixed array.”)
A variant of the “enumerated array” is the “null enumerated array.” This is a variant of the enumerated array with an additional entry at the beginning for null (represented as a “?” ). For example, with the enumeration of the 50 states, the null enumerated array has 51 values, one for NULL, and the remaining 50 for the 50 states. The null array element could be used for entries where the state is unknown.
A variable-length array can have a different number of entries in each instance of the array. Often this is useful for representing organizations in which different parts have different depths. For example, one department could be represented by Gomez:Shapiro:Lacy (three entries), while another is Gomez:Wong:McMartin:Singe (four entries).
A variable-length entry with zero values can also be declared by passing an empty string. This can be used to specify data for the top level of a hierarchy.
When representing an organization with variable-length arrays, be careful. The Tree Visualizer computes the height for each level of the hierarchy separately, giving the highest bar on each level a user-specified height and normalizing the other bars accordingly. For example: Imagine a U.S.-based organization with a domestic and an international sales force. Domestic sales are divided up into states, which are divided into cities. International sales are divided into continents, which are divided into countries and cities. You can have locations such as domestic:California:Mountain View, and international:Europe:Italy:Rome. When displaying organizational hierarchies of this type, it is best to normalize heights at each level. If this is not done, small parts of the organization (for example, Mountain View) would be dwarfed by large parts of the organization (for example, domestic).
When the system tries to match up the levels, the normalization process might introduce anomalies. Usually, this is not the case at the highest level (domestic is matched with international); however, at lower levels this correspondence is no longer valid. Domestic cities (for example, Mountain View) are at the third level, but the third level for international is a country (for example, Italy). Comparing domestic cities against foreign countries usually has little validity. In this case, it is recommended that you introduce artificial levels to balance the hierarchies (for example, domestic:USA:California:Mountain View), thus matching cities.
Variable-length arrays might also be useful when some of the regions being compared are subdivided further than others. For example, an organization might have USA:California:San Francisco and USA:California:Los Angeles, but only USA:Wyoming. There is no need to construct an artificial third level just to keep the arrays balanced, as long as each level in the array matches the same level in other arrays.
Starting up the Tree Visualizer takes longer when variable-length arrays are read in than when fixed-length arrays or individual columns are read in. Unless the data is variable length, it is best not to use variable-length arrays.
As with the columns, arrays are represented as values separated by tabs or other separators. For a fixed-sized array, the same separator can be used for columns and for individual array elements (in which case, array elements are not visually distinguished from separate columns). You can also define a different separator. In the sales example (on page 315), for example, you can treat the location as a four-element array, rather than as four columns. It then could be represented like this:
Eastern:Maryland:Baltimore:1816 appliances 72 115 138
Here, the array is separated by colons, and the columns are separated by tabs. (For clarity, the rest of this document uses tabs to separate columns, and colons to separate array elements.)
For a variable-length array, you must use different separators for the array and for the columns; otherwise, it is impossible to determine where the variable-length array ends and the other columns begin.
The configuration file format is flexible. Words in it must be separated by spaces, and it is case-sensitive. Except for the include statement and text within quoted strings, spacing and line breaks are irrelevant.
Comments begin with a pound (#) symbol at the beginning of a line; anything after this symbol to the end of the line (80 characters) is ignored.
The configuration file consists of a series of sections, each of which has this syntax:
sectionKeyword
{
statements...
}
|
where sectionKeyword names the section. A semicolon (;) can follow the closing brace (}) but is not required. The order of the sections is significant, since sections can refer to variables defined in previous sections.
As each section is encountered, a special configuration file (referred to as a “options file”) is also read in. Options files have names in the form:
sectionName.treeviz.options |
Options files normally contain options statements. These files are searched in the following order:
Files with the same name can appear in more than one of the above-named directories; in this case, the order given is the one in which the directories are read. If the same option is found in multiple files, the last option read is used. Note that the appropriate section in the configuration file is read after all the options files have been read in; thus, options in the configuration file override those in the options files.
A statement has the following syntax:
statementKeyword info ; |
where statementKeyword defines the statement, and info varies according to the keyword. A statement can be another section (using the brace format defined under “Sections”).
A variable name can appear in two formats:
In the first format, it is a letter followed by a number of letters, digits, or underscores. It cannot be a keyword, and should not be placed in quotation marks.
In the alternate form, the variable name should be surrounded by back quotes (`). In this form, the variable name can match a keyword, and can contain even non-alphanumeric characters. The primary purpose of this second form is for configuration files generated automatically by the Tool Manager.
There is no scoping of variable names; a given variable name can be declared only once in the configuration file.
Many sections have options statements, which have this syntax:
options key info, key info... ; |
where key defines the specific option, and info depends on the key. In some cases, the key can be more than one word. To maximize the number of allowable variable names, most option keys are meaningful only within the appropriate option statement; keys do not conflict with variable names. You can declare several options on the same line, separating them by commas or placing them in several options statements. For example, the following two examples are equivalent:
options home angle 30, shrinkage 10.0; |
and
options home angle 30; options shrinkage 10.0; |
If two conflicting values for the same option appear, the last value is taken.
The configuration file can contain lines of the form:
include "filename" |
These lines can appear anywhere in the configuration file, but each must be on its own line. The filename must be in quotation marks; anything after the closing quotation mark is ignored. Include statements can be nested. If a relative pathname (one not beginning with a slash) is specified, the file is first sought relative to the directory containing the current configuration file. (If include statements are present, this might not be the same as the initially loaded configuration file.) If it is not found in the current configuration file, the include is sought in the current directory. If the file is not found, an error message appears.
The currently recognized keywords are listed in Table A-1. Variables cannot have these names unless they are surrounded by back quotes (`). Tokens appearing only in option statements are not keywords, and can be used for variable names.
Table A-1. Keywords for the Tree Visualizer
aggregate | disk | int | normalize |
any | divide | isSummary | off |
ascending | double | key | on |
average | enum | label | options |
back | execute | landscape | scale |
base | expressions | legend | separator |
buckets | file | levels | sort |
color | filter | max | string |
colors | float | message | sum |
count | height | min | view |
dataString | hierarchy | modulus |
|
descending | input | none |
|
Expressions are accepted in several places in the input. Expressions follow standard C syntax. The following operations are supported:
+ - * / % == != > < >= <= && || ! & | ^ ?:
Also, the following functions are available:
divide(x, y, z) divides x by y, unless y is zero. If y is zero, the result is z; this is equivalent to the C construct y==0 ? z : x/y.
hierarchy(string) is valid only within a hierarchy. It produces a string describing the components of the hierarchy, separated by string. For example:
hierarchy(":")might produce
Western:California:Mountain View
The hierarchy function is most useful in the execute statement, passing the hierarchy information to the command being executed.
isSummary() returns 1 if the expression is being applied to base information; otherwise, it returns zero. Often, this is useful with the ?: operator, particularly in message and execute statements.
Type handling is similar to that in C. 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.
Unlike in C, strings can be compared using relational expressions; the strings are compared alphabetically.
The first section of a data file is normally the input section. It defines the name and format of the file. A typical input section might look like this:
input {
file "store";
string region;
string state;
string city;
string storeId;
string product;
float sales;
float lastYear;
float target;
options separator `:';
}
|
This example states that the input file is called store, and that there are eight fields: five of type string, three of type float.
When the input section is entered, the options file, input.treeviz.options, is read in.
The file statement names the data file to be read. This statement is required. Its syntax is:
file "filename"; |
Filename must be in double quote marks. If it is a relative pathname (no leading slash), it is first sought in the directory containing the current configuration file. If include statements are present, this might not be the same as the initially loaded configuration file. If it is not found in the current configuration file's directory, the file is sought in the current directory.
The data statements declare the columns in the data file. The columns must be declared in the order they appear in the data file. The format of most data statements is
type name; |
where type is int, float, double string, or dataString; name is the variable name. Unlike in C, only one variable can be declared per statement.
The syntax for declaring an enumeration is:
enum type name { value, value...};
|
For example:
enum string state {
"Alabama",
"Alaska",
...
“Wyoming"
};
|
The word “string” indicates that the enumeration maps integers to strings; they can also be mapped to other types.
Note that for compatibility with MineSet 1.0, “enum” can be replaced with “key.”
Once an enumeration is declared, a column can be declared to be of that enumeration using the following syntax:
enum enumname columnname; |
For example:
enum state st; |
declares st to be a variable of state enumeration. The input file corresponding to this column must contain values from 0-49 (or “?” representing null); however, the output shows the state name.
Enumerations also can be used to declare enumerated arrays (see “Enumerated Arrays”).
Arrays are also declared using data declarations. The simplest form is the fixed array. The declaration syntax is
type name [ number ] ; |
For example:
float revenue [50]; |
You can also override the separator by declaring it as
type name [ number ] separator `char'; |
For example:
float revenue [50] separator `:'; |
If no separator is specified, the default column separator (usually a tab) is used.
To declare an enumerated array, first declare the enumeration (see the “Enumerations” subsection). Then declare the array using the following syntax:
type name [ enum keyname ]; |
or
type name [enum keyname ] separator `char'; |
For example:
float revenue [enum state]; |
As with the normal fixed array, you can also specify a separator. Note that for compatibility with MineSet 1.0, the word "enum" can be omitted from within the brackets. To declare a null enumerated array, use the syntax:
type name [ null enum keyname ]; |
or
type name [ null enum keyname ] separator `char'; |
For example:
float revenue [null enum state]; |
indicates that the array contains one additional value at the beginning, corresponding to null.
To declare a variable-length array, do not include a number in the brackets ( [ ] ). With a variable-length array, you must include a separator that is different from the one specified as a column separator. The syntax is:
type name [] separator `char'; |
For example:
string category [] separator `:'; |
The input section of a data file has several options. All options statements begin with the word options and have one or more comma-separated options.
The separator option defines the separator between columns in the data file. The default separator is a tab. The syntax is:
options separator `char';
For example:
options separator `:';
Note: Arrays can override the separator. The monitor option allows a dynamic update of the data displayed. When the specified file is changed (for example, through the touch command), the data file (not the configuration file) is reread. The data file should not be used to trigger the updates. This prevents the data file being read at the same time it is being updated. The syntax of the monitor option is
options monitor "filename"; options monitor "filename" timeout;
where filename is the file to watch, and the optional timeout specifies the number of seconds to wait after the file changes. If the user interacts with the application in any way during this timeout (via the mouse or keyboard), the timeout restarts. Updating the file can take a few seconds. By specifying a timeout, the chances of an update occurring while the user is interacting with the tool are minimized (but the update is delayed). If no timeout is specified, the update occurs immediately.
The file being monitored must exist at the start of the program. When this file is being updated, it must not be removed and re-created; instead, only its modify time should be updated (for example, through the touch command). If the file is deleted, subsequent updates are not shown.
Suppose a program extractor extracts data from a database into a data file. If you want the program to update the data file every 10 minutes, the script might look like this:
extractor > dataFile; # create first data file touch trigger; # create the trigger file while (sleep 600) # sleep 10 minutes do extractor > dataFile; # create new data file touch trigger; # force a reread done & # this loop goes in the # background treeviz configFile; # run treeviz kill $! # when treeviz exits, kill the # update loopThe monitor option can be used only if the file alteration monitor /usr/etc/fam is installed (this can be found in the subsystem desktop_eoe.sw.fam).
The input section of a configuration file might look like this:
input { file "dataFile" #data declarations here options monitor "trigger" 15; }The backslash option controls whether backslashes in the input data are treated specially or like other characters. The syntax is:
options backslash off; options backslash on;The default is off. If backslash processing is on, separators in the input data preceded by backslashes are treated as regular characters rather than separators. Also, within strings standard C-style backslash processing is done.
The expression section of a data file lets you define additional columns that are expressions of existing columns. For example, one column can be defined as the sum of two other columns. The expressions are calculated before the definition of the hierarchy. In many cases, it is more appropriate to apply the expressions after creating the hierarchy; the expressions then should be defined within the hierarchy section (described later), and the expressions section can be omitted.
The following is a sample expression section. This section assumes two existing columns of type float, “male” and “female”; these represent spending by males and females on various goods. Two columns are added: “total” represents the total dollars spent, and “pctFemale” represents the percentage of dollars spent by females.
expressions
{
float total = male+female;
float pctFemale = divide (female*100, total, 50.0);
}
|
The format of the expressions section is:
expressions
{
expressionDeclaration;
...
}
|
where expressionDeclaration has the following syntax:
type name = expression ; |
Since the expressions section has no options, no options file is read in for it.
The hierarchy section of a data file describes how the previously read table is converted into a hierarchy. Here is a sample hierarchy section:
hierarchy
{
levels region, state, city, storeId;
key product;
aggregate
{
sum sales;
sum lastYear;
sum target;
}
expressions
{
float pctLastYear = divide(sales*100, lastYear, 100.0);
float pctTarget = divide(sales*100, target, 100.0);
}
}
|
The parts of the hierarchy section are described below.
When entering the hierarchy section, the hierarchy.treeviz.options options file is read in.
The levels statement defines how the table is converted into a hierarchy. The format is:
levels name, name...; |
where name represents a column previously defined in the input or the expressions section. How the hierarchy is created depends on the types of the columns defined.
If the columns represent simple types (for example, strings or numbers), each column is converted into a single level of the hierarchy. The top level of the hierarchy is a single, all-inclusive node. The next level contains one node for each unique value in the first column. The third level contains one node for each unique value in the second column, and so on. Hierarchies created in this way are always balanced: All branches in the hierarchy go to the same depth (namely one greater than the number of columns specified in the levels statement).
In the case where the column is an array, there can be only a single column specified in the levels statement. Each value in the array is mapped to one level in the hierarchy. The top level is a single node representing the total aggregation. The next level contains one node for each unique value of the first value in the array; the third level contains one node for each unique value of the first two values of the array, and so on.
If the array is of fixed type, this hierarchy is balanced. If a variable array is used, the hierarchy is not necessarily balanced (some branches can go deeper than others).
A variable-length array can be used to specify the hierarchy, even if the hierarchy is balanced to a fixed depth. When using columns or fixed arrays to specify the levels, you can specify data associated only with those levels at the bottom (or leaf) nodes. In this case, all higher nodes in the hierarchy must be aggregated. However, rather than relying on automatic aggregation, you might want to supply your own data for each level of the hierarchy (if, for example, the calculation can not be done automatically by the Tree Visualizer). In that case, use variable-length arrays to specify levels and provide separate data for each level. For example, the data file might contain lines such as:
Domestic:Western 43 Domestic:Eastern 57 Domestic 85 Intl:Europe 52 Intl:Asia 39 Intl 94 133 |
| Note: The last line has an empty value for the location; the number 133 is translated to the top of the hierarchy. |
The key statement specifies those keys that are used to select the bars at each node in the hierarchy. The key corresponds to the bars displayed in the final view. The syntax of the key statement is:
key name [sort [ascending|descending]}; |
where name is the name of one of the previously defined columns. It cannot be the name of a column used in the levels statement. Only a single key statement can be made.
By default, the bars generated by the key statement appear in the order first encountered. If the key is an enumerated array, the bars appear in the order of the enumeration; otherwise they appear in the order in which values are first encountered in the data file. Adding the word sort at the end of the key statement sorts the bars. Sorting depends on the type: Strings are sorted alphabetically, and numbers are sorted numerically. Enumerations are sorted on the index of the enumeration, not the string that the enumeration refers to. If, however, the key is an enumerated array, the sorting takes place according to the enumeration string (to sort based on the enumeration index, leave it unsorted). Optionally, the word sort can be followed by ascending or descending to specify the sort order; the default is ascending.
If the key column is a simple type (for example, a string), the unique values of that key are looked up in the original table. The order of the values is the same as the one in which the key values appear in the original input table. Although it is not required, the same keys are often repeated in the same order. For example, in the following table, the fifth column is the key, and has the values “appliances,” “clothing,” “electronics,” and “furniture.”
Eastern Maryland Baltimore 1816 appliances 72 115 138 Eastern Maryland Baltimore 1816 clothing 355 344 395 Eastern Maryland Baltimore 1816 electronics 156 182 209 Eastern Maryland Baltimore 1816 furniture 78 75 82 Eastern Massachusetts Boston 1331 appliances 48 68 81 Eastern Massachusetts Boston 1331 clothing 307 258 296 Eastern Massachusetts Boston 1331 electronics 38 183 210 Eastern Massachusetts Boston 1331 furniture 52 69 75 Eastern Massachusetts Boston 1220 appliances 37 63 75 Eastern Massachusetts Boston 1220 clothing 233 240 276 Eastern Massachusetts Boston 1220 electronics 175 208 239 Eastern Massachusetts Boston 1220 furniture 35 53 58 |
The key can also be any column of the enumerated array type. In this case, the enumeration is used as the key for specifying the bars. Other columns in the input can also be enumerated array types, as long as they use the same enumeration. For example, this table can also be input as
Eastern Maryland Baltimore 1816
72:355:156:78 115:344:182:75 138:395:209:82
Eastern Massachusetts Boston 1331
48:307:38:52 68:258:183:69 81:296:210:75
Eastern Massachusetts Boston 1200
837:233:175:35 63:240:208:53 75:276:239:58
|
For clarity, each line has been wrapped onto two lines; however, in the file these should be on single lines. The input section for this data appears as
input
{
file "...";
key string product {
"appliances", "clothing", "electronics", "furniture"
}
string region;
string state;
string city;
string storeId;
float sales [ enum product ] separator `:' ;
float lastYear [ enum product ] separator `:' ;
float target [ enum product ] separator `:' ;
}
|
| Note: Since the arrays are fixed, the use of a colon separator for the arrays is not required; however, it might make it easier for a human to read the input. |
In this example, the hierarchy section appears as follows:
hierarchy
{
levels region, state, city, storeId;
key sales;
...
}
|
Since sales is an enumerated array, it used its key type (product) as the key to generating the bars; thus, each graph in the final view has four bars. Note that lastYear and target must use the same key type for their array.
Arrays other than enumerated arrays can not be specified as the key.
The aggregate subsection of the hierarchy section describes how values are aggregated at higher levels of the hierarchy. An example is:
aggregate
{
sum sales;
sum lastYear;
sum target;
}
|
This indicates that sales, lastYear, and target are to be summed at higher levels of the hierarchy (each level summing the values in the level below it). In addition to the sum aggregation, the aggregations average, min, max, count, and any are allowed. All are self-explanatory, except for any, which indicates that any of the values can be used. This aggregation is used if you expect the same value (for example, a string) to appear everywhere in the hierarchy and if you just want it to populate the entire hierarchy.
A special case is when the key is an enumerated array. Here, the key is normally also aggregated.
In the case where a variable-length array specifies data for all levels of the hierarchy simultaneously (as opposed to merely specifying the data at the leaf nodes), the aggregate section cannot be used.
The two forms an aggregate statement can take are
agg name; name1 = agg name2; |
In both cases, the aggregate (agg) is one of sum, average, min, max, count, and any. The first form was illustrated above; it aggregates a column, and the result is given the same name as the original column being aggregated. The second form aggregates the column name2, but gives the result the name name1. This second form is useful if the same value is being aggregated multiple times. Since using the first form creates two aggregations with the same name, the second form can be used to differentiate the aggregations.
For example, if you have a column named expenses and want to aggregate it to show the maximum and minimum expenses, you can use
aggregate
{
maxExpenses = max expenses;
minExpenses = min expenses;
}
|
This subsection specifies how values in the base are aggregated. It can be used only if the aggregate subsection is not present. (If the aggregate section is present, the base is aggregated using the aggregations specified in it).
A sample aggregate base subsection is:
aggregate base
{
sum sales;
sum lastYear;
}
|
An aggregate statement takes the form
agg name; |
where the aggregate (agg) is one of sum, average, min, max, count, and any, (similar to the aggregate section). The aggregation is applied to all the bars on that base to give the appropriate value for the base. After the base is aggregated, its values correspond to all of the columns used in specifying the bars. Any column not specified in the aggregate base section has a value of zero. Because the base values correspond to the bar values, the second form of the aggregate statement (using the =), cannot be used in the aggregate base section.
An expressions subsection of the hierarchy section is similar to the expressions section described earlier, except that it is applied after the hierarchy is created and aggregated. The syntax is identical, but it is declared within the hierarchy section, not external to it.
To give an example of the difference between calculating the expressions before and after creating the hierarchy, take the example of male and female dollars spent. Assume you want to calculate the percentage of dollars spent by women. The expressions might be:
expressions
{
float total = male+female;
float pctFemale = divide (female*100, total, 50.0);
}
|
Assume you calculated these variables before creating the hierarchy. Then, when aggregating the data up the hierarchy, summing the percentages is not useful. Averaging the percentages results in a believable number; however, it averages percentages of large dollars with percentages of small dollars, and produces incorrect results. (To make this clearer, suppose that on one product, males spent $99, and females spent $0. On another product, males spent $0, and females spent $1. On the first product females spent 0%, and on the second they spent 100%. Averaging these gives 50%, but in reality, females spent only 1% of the dollars spent on the two products combined.)
The base data should be aggregated first, then the expressions should be applied. (In the example, after aggregating, the result is a combined spending of $99 for males, and $1 for females; if the percentage is calculated after the aggregation, the correct value of 1% results.)
By default, the order of the nodes within each level of the hierarchy is based on the order of the data in the input file. However, sometimes it is desirable to sort the hierarchy. The sort statement can appear in one of two forms:
sort name [, ascending|descending]; sort key [, ascending|descending]; |
In the first form, one column name (not used in the level statement) is used for sorting. The column can be the result of an aggregation or an expression. In the second form, the value used in the level statement is the one used in laying out the hierarchy.
The hierarchy can be sorted in ascending or descending order. If neither option is specified, the default is descending order if the first form of the sort is used (this places the largest columns on the left); the default is ascending order if the second form is used (this typically sorts alphabetically).
Note that sort statements affect the sorting of only the branches of the hierarchy; they do not affect the bars within each node of the hierarchy.
There are two options in the hierarchy section: skipMissing and organization. The format for the skipMissing option is
options skipMissing; |
If this option is off (the default) and some values of the key are not present for a given hierarchy node, dummy entries are created with values of 0. This guarantees that all graphs in the hierarchy have the same number of bars, and the same layout. If this option is on, no such entries are generated. This results in variable-length tables in the hierarchy, and bars exist only for items in the input. The position of these bars, however, is not meaningful. This option is not useful if the key is an enumerated array (for which all values are supplied).
The skipMissing option increases memory usage and should be avoided, if possible.
The format for the organization option is
options organization same; options organization contains; options organization unknown; |
The organization option provides hints about the hierarchy organization that allow for more efficient algorithms. This option is most useful if no hierarchy aggregation is done. The same value specifies that all nodes in the hierarchy contain entries for the same item (for example, all nodes could contain “appliances,” “clothing,” “electronics,” and “furniture”). The contains value indicates that a parent node contains entries for all values that its children contain. For example, if a node contains “appliances,” its parent node must also contain “appliances,” although not all of its child nodes must contain appliances. The unknown value means that no assumptions are to be made regarding the contents of individual nodes.
If no organization is specified, the Tree Visualizer determines the organization as follows.
If there is no aggregate subsection, unknown is used.
If there is an aggregate section, but the skipMissing option is provided, contains is used; otherwise, same is used. Since this is normally correct when an aggregate subsection is provided (unless skipMissing is used but nothing is missing), there normally is no need to provide an organization if the aggregate subsection is present.
If the organization specified does not match the data, the results are unspecified. For example, same should not be specified, unless all nodes have the same entries.
The view section of a data file describes how the hierarchy is displayed, including the mapping of heights, colors, labels, and so forth. A sample view section is:
view hierarchy landscape
{
height sales, normalize levels, max 2.0;
height legend label "Height: Total sales";
base height max 1.0;
disk height target, legend label "Disk height: Target
sales";
color pctTarget, scale 0 100 200 500;
color colors "red" "gray" "green" "blue";
color legend label "Color: % of target" "0%" "100%"
"200%" "500%";
options columns 4;
message "$%,.2f, %.0f%% of target, %.0f%% of last year",
sales, pctTarget, pctLastYear;
}
|
The first words of the view section (before the opening brace) describe the type of view. The only view type supported is view hierarchy landscape; thus, these words must introduce the view section.
When entering the view section, the viewHierarchyLandscape.treeviz.options options file is read in. Note that there is not a simple view.treeviz.options options file, the full name viewHierarchyLandscape must be used.
The height statement describes how the columns are mapped to the height of objects. It consists of a series of clauses separated by commas. Alternatively, it can be specified as multiple height statements. Thus: the following three examples are equivalent:
height sales, normalize levels, max 2.0;
height sales;
height normalize levels;
height max 2.0;height sales, normalize levels;
height max 2.0;
The first clause normally contains the name of a column that is to be mapped to 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 normalize clause determines the maximum value of the height variable; it normalizes all values relative to that height. Thus, if the maximum value is 30.0, and that bar was given a height of 1.0 (in arbitrary units, as discussed in “The max Clause”), a value of 15.0 would be mapped to a value of 0.5.
The syntax of the normalize clause can be
| normalize | This normalizes all values against one another, throughout the hierarchy. | |
| normalize levels |
| |
| normalize none |
|
The second form is particularly useful in cases where the data is aggregated up the hierarchy. For example, assume the sales data is aggregated up the company. Comparing the sales of the company as a whole to the sales of a single individual has little meaning; in a large company, the heights of the bars for the individuals are so small as to be indistinguishable from zero. It makes more sense to compare sales people to sales people, offices to offices, regions to regions, and so on. Normalizing levels does this.
Regardless of which form of normalization is used, the base (if shown) is always normalized independently of the bars. By default, the same normalization mechanism for the bars is used for the base.
The max clause is used with the normalize clause to specify 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 double the heights, specify
max 2 |
The max clause must be used with the normalize clause.
If normalization is not used, the height variable is mapped directly to the height (in the arbitrary height units). The scale clause can scale these 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 normalize or max clauses.
Large datasets can contain many graphics. This results in poor performance. In many cases, the data values are small and of little informative value. The filter clause prefilters the data based on the height variable, so that only the nodes with the highest bars are shown. The syntax of the filter clause is:
filter > float%
|
The > and % characters must be typed literally. For example:
filter > 5% |
This example filters out all charts containing no bars greater than 5% of the maximum bar height, except for those containing descendants in the hierarchy containing such bars. Note that if a chart contains just one bar that meets this criterion, the entire chart is shown.
The filter value can be changed interactively through the filter panel (see “The Filter Panel” in Chapter 4).
The filter clause is permitted only on the height statement.
The legend clause defines the meaning of the height mappings. Any string can be placed in the height legend. The legend clause has the following syntaxes:
| legend off | This turns off the height legend (this is the default). | |
| legend on | This turns on the height legend. | |
| legend label string |
|
By default, the legend has the following syntax:
height:varname |
where varname is the name of the variable that is mapped to height.
It is possible to declare separate legends for the height, the base height, and the disk height.
The base height statement specifies how the height of the base is calculated. The format is similar to the height statement, except that it is preceded by the word “base.” If the base height statement is omitted, the height of the base is calculated using the same values as in the height statement (the same variable, normalization mechanism, max value, and so on). You also can specify only some of the clauses for the base, in which case everything else is the same as the height statement. For example:
height sales, normalize levels, max 2.0; base height max 1.0; |
In this case, the base height is based on sales, and it is normalized by levels. The maximum height, however, is only 1.0 instead of 2.0. Usually, the visual effect is better if the base height max is less than the max for the bars.
The filter clause is not permitted on the base height statement.
The initial value of the base height can be turned on and off via the on and off clauses. To turn it off, use
base height off |
To turn it on, use the default:
base height on |
The base height can be changed interactively using the Base Height option in the Display menu. The on and off clauses are valid only with base height. Do not use them with the height or disk height statements.
You can place a disk on each bar to indicate an additional item of data. This is done with the disk height statement. The disk height statement's syntax is similar to that of the height statement, but it is preceded by the word “disk.” For a disk to be displayed, there must be a clause specifying the column to be mapped to the disk. Other clauses are optional; if these are omitted, the height statement's defaults are used.
If the height statement has a normalize clause, and the disk height statement has no normalize or max clause, then the disks are normalized with the bars (they are drawn to the same scale). If the disk height statement has either a normalize clause or a max clause, the disks are normalized independently of the bars. For example:
height sales, normalize levels, max 2.0; disk height target; |
In this case, the bars are mapped to the variable “sales,” and the disks are mapped to “target.” Both are normalized, with the maximum value of sales or target on each level mapped to a value of 2.0. If instead this example is written as
height sales, normalize levels, max 2.0; disk height target, normalize levels; |
the bars are mapped so the highest bar at each level is 2.0, and the highest disk on each level is 2.0, but the bars and disks are not mapped to the same scale. This can be used, for example, if the bars represent dollars and the disks represent head count.
The filter clause is not permitted on the disk height statement.
The color statement describes how values are mapped to colors. The format is similar to that of the height statement, consisting of several clauses that can be separated by commas or entered as multiple statements.
Color names follow the conventions of the X Window System™, except that the 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. (A list of available colors is found in the file /usr/lib/X11/rgb.txt.)
As with height, you also can specify a single column to be mapped to a color. The column must be a number type. Unlike for height, there is no normalization of colors.
Instead of specifying a variable, the word key can be specified. This assigns a different color based on each key, normally for each bar. For example, if the 50 states were the keys, key assigns a different color to the bar for each state. Since the base is not keyed, when the key clause is used, the base is always gray.
The colors clause specifies the colors to be used. The colors clause syntax is:
colors "colorname" "colorname"... |
The format for colorname is described “Color Naming.” 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, colors are chosen randomly; however, if there is a colors statement, at least as many colors must be specified as are to be mapped. If a key is used, there must be one color for each key value.
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 this statement 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 pctFemale example, you used the buckets clause instead of the scale clause, the statement would be
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 other values are blue.
The legend clause creates a legend of the colors. By default, a legend is on for the bar colors, and off for base and disk colors, although separate legends are permitted for each. The legend clause syntax can be any of the following:
legend off legend on legend "string" "string" ... legend label "string" legend "string" "string" ... 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 column that is mapped to color), and a list of colored labels on the right (with values obtained from the scale clause, the buckets clause, or from the keys). To override the strings in the colored labels, specify the strings as: 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 "" |
The base color statement controls the color of the base. Its syntax is similar to the color statement, except that it is preceded by the word “base.” If this word is omitted, the base has the same color as the bars. If the base color statement is present, any omitted clauses default to the values of the color statement.
The disk color statement controls the color of the disk. The syntax is similar to the color statement, except that it is preceded by the word “disks.” If the disk color statement is omitted, the disk has the same color as the bars. If the statement is present, any omitted clauses default to the values of the color statement.
Since disks are drawn only if a disk height statement is present, a disk color statement has no effect without a disk height statement.
Label statements specify the labels used when labeling objects in the scene. Normally, these statements can be omitted. By default, each bar is labeled with its key; each base is labeled with its position in the hierarchy. The syntaxes of the label statements are:
label name base label name line label name back label name |
where name is the name of the column to be used as the label. The first form is used as the label on the bars. The second form is the label on the bases. The third form labels the lines connecting the bases. The fourth places labels behind the bases. (Note that bases often obscure the back labels, so this form is less useful; however, there might be occasions where it is appropriate.)
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 "%s: $%f, %.0f%% of target, %.0f%% of last year",
product, sales, pctTarget, pctLastYear;
|
This could produce the following message:
furniture: $2425.37, 23% of target, 87% of last year |
The formats must match the type of data being used:
Strings must use %s.
Ints must use integer formats (such as %d).
Floats and doubles must use floating point formats (such as %f).
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 "%s: $%,f, %,.0f%% of target, %,.0f%% of last year”,
product, sales, pctTarget, pctLastYear;
|
it would produce the message:
furniture: $2,425.37, 23% of target, 87% of last year |
The $, *, h, l, ll, L, and n printf format options are not supported.
All values, including the format string, are expressions. Thus, if you had a pctFemale column, but wanted a more gender-neutral message, you could use
message pctFemale>50?"%f%% females":"%f%% males",
pctFemale>50?pctFemale:100-pctFemale;
|
If pctFemale is 70, the message “70% females” is displayed; if pctFemale is 30, the message “70% males” is displayed. In this case, you can also achieve the same result with a single format string:
message "%f%% %s", pctFemale>50?pctFemale:100-pctFemale,
pctFemale>50?"females":"males";
|
By default, the same message is used for the base as for the bars. It is possible to specify a different message by using a base message statement, which has the same syntax.
If no message is specified, a default message containing the names and values of all the columns is used.
The execute statement lets you execute a shell command by double-clicking an object. The syntax is similar to that of the message command; however, since hierarchy information is not displayed on a separate line, it is useful to include the hierarchy information and to pass the key information as arguments.
Here is a sample execute statement that uses xconfirm to show a window with information about the item. (The first line, the string, is broken into multiple lines to fit into a single page. In an actual file, it should be on a single line. Multi-line strings are not supported.
execute "xconfirm -t `%s' -t `sales of %s' -t `$%,.0f'
-t `target $%,.0f (%.0f%% of target)'
-t 'last year $%,.0f, %.0f%% of last year'>/dev/null",
hierarchy(" "), isSummary()?"everything":product,
sales, target, pctTarget, lastYear, pctLastYear;
|
This might produce a dialog with the message
Eastern Connecticut Milford sales of clothing $348 target $427 (81% of target) last year $372 (94% of target) |
Note the use of hierarchy(" ") to produce a blank-separated description of the hierarchy. Also note the isSummary()?”everything”:product; this produces the word “everything” if the base was selected, but otherwise produces the product. An alternative to this is using separate execute and base execute statements.
If there is no execute statement, double-clicking an object has the same effect as single-clicking it.
The view section has many options. Like other options statements, the options can be separated by commas, or they can appear in separate lines.
The sky and ground color can be specified using the following syntax:
options sky color colorname options sky color colorname colorname options ground color colorname options ground color colorname colorname |
The syntax for color names is the same as that for color naming.
For both the sky and the ground it is possible to specify either one or two colors. If only one color is specified, the sky or ground is solid. If two colors are specified, the sky or ground is shaded between the colors. For the sky, the first color is for the top of the sky, the second for the bottom. For the ground, the first color is for the far horizon, the second for the near ground.
For example, to have a solid black background, specify:
options sky color "black", ground color "black"; |
By default, bars in each chart are laid out as close to a square as possible. You can override this using either the rows or the columns option:
options rows number options columns number |
Only one of these can be specified.
Although the overview can be brought up using the Show menu, it can also be configured to come up automatically at startup. The overview syntax is:
options overview on options overview off |
The first form causes the overview to be displayed at startup. The second form (the default) turns the overview off. Regardless of the setting, the overview can be invoked from the Show menu.
Hierarchies normally have a large aspect ratio, having greater width than depth. In their unaltered form, it is impossible to view the entire hierarchy, except from such a far distance that no detail would be visible. To see the hierarchy more clearly, distant objects can be shrunk more than perspective normally dictates. The shrinkage option lets you control the shrinkage for a given graph. The shrinkage option syntax is any of the following:
options shrinkage auto options shrinkage float options shrinkage off |
The first form (the default) automatically calculates a shrinkage value. Its results are usually reasonable, but not necessarily optimal in unusual hierarchical layouts. Thus, you might want to explicitly set the shrinkage using the second form. For hierarchies in which some parts are deeper than others, automatic calculation does not work well. The best shrinkage value depends on the graph being displayed, as well as various layout options such as margins. You should experiment with each graph. Start with a value of 10.0, then make adjustments. Smaller values result in a narrower hierarchy and increased distortion. The shrinkage value must be positive; avoid values smaller than 5.0.
Shrinkage can be turned off. This is recommended only for very small hierarchies, as it produces hierarchies with very large aspect ratios.
By default, the root node of the hierarchy gets a label based on the name of the configuration file. You can override this by using the root label option. The format is
options root label string |
This option also affects the string displayed when an object is selected, as well as the result of the of hierarchy() function.
Note that the root label option has no effect if the base label statement was used (that statement defines the base label for the root as well as for all other bases).
The font option controls the font used for drawing the labels. The syntax is
options font "fontname" |
where fontname can be any font in the directory /usr/lib/DPS/outline/base.
It also can be the string default. This attempts to use Helvetica (if available), or the default Inventor font (if Helvetica is not available). Note that different systems can have different fonts installed.
The base label color option controls the color of the labels in front of the bases. The syntax is
options base label color "color" |
The bar label color option controls the color of the labels in front of the bars. The syntax is
options bar label color "color" |
The line color option controls the color of the lines connecting the nodes in the hierarchy. The syntax is
options line color "color" |
The zero option lets you determine whether bars, disks, and bases of height zero are drawn solid, as an outline, or hidden completely. In the last case, space is left for the object, but it is not drawn. The default value is solid. This option can be changed at run time using the Display menu (see “The Display Menu” in Chapter 4).
The syntax for the zero option is
options zero solid options zero outline options zero hidden |
The null option lets you determine whether bars, disks, and bases of height null (see Appendix G, “Nulls in MineSet”) are drawn solid, outline, or hidden completely. In the last case, space is left for the object, but it is not drawn. The default value is outline. This option can be changed at run time using the Display menu (see “The Display Menu” in Chapter 4). The syntax is
options null solid options null outline options null hidden |
There are 10 other options to control the layout of the display, level of detail, and other parameters. Generally, it is not necessary to adjust these parameters. The values of many of the options are in arbitrary units. Adjust the options by increasing or decreasing the value. For the default values of these parameters, see the file /usr/lib/MineSet/treeviz/viewHierarchyLandscape.
options speed float
Controls the speed during free-form (middle-mouse) horizontal navigation (forward, backward, and side to side). The larger the value, the faster the motion.
options climb speed float
Controls the speed when moving up and down using Shift + middle mouse. The larger the value, the faster the motion.
options leaf leaf margin float
Controls the distance between adjacent nodes in the hierarchy. Larger values move the nodes farther away.
options root leaf margin float
Controls the distance between a node and its children. Larger values move the nodes farther away.
options leaf edge margin float
Adds margin space next to nodes at the edge of a subhierarchy.
options initial position float float float
Provides the initial x, y, and z position from which the scene is viewed. A value of 0 0 0 positions the viewer at the root of the hierarchy; since the user is looking forward, the root probably is not visible. Increasing x, y, and z moves the camera to the right, up, and back, respectively. A typical position has a zero x, positive y, and positive z. If unspecified, the initial position depends on the layout of the hierarchy.
options initial angle float
Provides the initial angle, measured in degrees, from which the hierarchy is viewed. The value must be between 0 and 90. A value of 0 looks at the scene horizontally; a value of 90 looks straight down.
options bar label size float
Specifies the size of the labels in front of the bars. Larger values result in larger labels.
options base label size float
Specifies the size of the labels in front of the bases. Larger values result in larger labels.
options lod [bar float float] [bar label float [float]]
[base float float] [base label float [float]] [disk float]
[motion float]Controls the level of detail. The parameters can appear in any order, be omitted, or placed in multiple lod options. These options control the changing form, or disappearance of, objects, thus providing better system performance.
Except for the motion parameter, all float values represent the size of the object when the form change or disappearance takes place. The smaller the value specified, the smaller and farther away the object is when the change takes place. Smaller values provide nicer graphics but slower system performance. The numbers of the different parameters cannot be compared directly because the size of the object also determines when the change takes place. A value of 0.0 means no level of detail changes for that parameter. This setting can significantly slow the rendering process.
bar controls when a bar is drawn with less detail. The first value specifies when the object is drawn as a pair of planes; the second value specifies when the object is drawn as a single line.
bar label controls when the labels on the bars disappear. If two values are specified, the first value specifies when the label is drawn in a lower-quality, fast font; the second value controls when it disappears.
base controls when the bases, and the bar charts in front on top of them, disappear. The first number is based on the width of the base; the second on the height of the base plus the tallest bar on it.
base label controls when the label in front of the base disappears. If two values are specified, the first value specifies when the label is drawn in a lower-quality, fast font; the second value controls when it disappears.
initial depth controls the initial depth to which the hierarchy is viewed. When you are at the top of the hierarchy, you see only the number of hierarchical levels specified by the slider. The nodes in the rows are arranged to optimize their visibility. When navigating to nodes lower in the hierarchy, additional rows are made visible automatically. The nodes above them automatically adjust their locations to accommodate the newly added nodes; thus, some nodes might seem to move. Note that the overview shows all nodes in the hierarchy, not just the top nodes, so the layout of the overview might not match the layout of the main view. The X in the overview approximates the corresponding location in the main view; there is no exact mapping between the two layouts.
An initial depth of zero, or one greater than the depth of the hierarchy, shows the entire hierarchy.
Once the Tree Visualizer is running, the depth can be changed through the filter panel.
disk controls when the disk disappears.
motion controls changes in some of the level of detail calculations when the scene is animated. A value greater than 1.0 defaults to 1.0. A value of 1.0 specifies that motion has no effect on the level of detail. Smaller values change the level of detail at a proportional distance. For example, a value of 0.5 means that during animation, level of detail changes occur at half the normal distance.