Treeviz does support one option not found in the standard input section of a .schema file. All options statements begin with the word options and have one or more comma-separated options.

The levels statement defines how the table is converted into a hierarchy. The format is:

levels name, name...;

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).

If the column is an array, you can specify only a single column 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).

You can use a variable-length array 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 cannot be performed 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]};

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 to which the enumeration refers. If, however, the key is an enumerated array, the sorting occurs 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: Because the arrays are fixed, the use of a colon separator for the arrays is not required; however, it might make it easier for the user to read the input.

---

In this example, the hierarchy section appears as follows:

hierarchy 
{
   levels region, state, city, storeId; 
   key sales; 
   ... 
}

Because 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 arrays.

Arrays other than enumerated arrays cannot 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.

IF 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.

An aggregate statement can take either of the following two forms:

agg name;
name1 = agg name2;

In both cases, the aggregate (agg) is one of sum, average, min, max, count, and any. The first form is illustrated in the preceding paragraphs; 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 names the result name1. This second form is useful if the same value is being aggregated multiple times. Because 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 previously, 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, and 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).

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 possible values for this option are as follows:

If you do not specify an organization, the Tree Visualizer determines the organization as follows:

If the organization specified does not match the data, the results are unspecified. For example, you should not specify same unless all nodes have the same entries.

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, you can specify multiple height statements. The following three examples are equivalent:

The first clause normally contains the name of a column 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 you do not specify a height column, 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. Therefore, if the maximum value is 30.0, and that bar was given a height of 1.0 (in arbitrary units), a value of 15.0 would be mapped to a value of 0.5.

The syntax of the normalize clause can be any of the following:

normalize

This normalizes all values against one another, throughout the hierarchy.

normalize levels

This performs independent normalization at each level of the hierarchy.

normalize none

This performs no normalization, and is the default.

The second form is particularly useful if 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 salespeople to salespeople, 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 scale clause scales the height of all objects; all values are multiplied by the scale. The syntax of the scale clause is:

scale float 

float is a floating point number (the decimal point is optional). For example, to double the heights, specify:

scale 2

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%

You must type in the > and % characters. 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. If a chart contains just one bar that meets this criterion, the entire chart is shown.

You can also change the filter value interactively through the Filter panel.

You can use the filter clause 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:

You can 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 you omit the base height statement, 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. You cannot use the filter clause with the base height statement.

base height off

base height on 

With the disk height statement, you can place a disk on each bar to indicate an additional item of data. The syntax of the disk height statement 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 you omit these, 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;

In this case, 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. You can use this, for example, if the bars represent dollars and the disks represent head count.

You cannot use the filter clause with 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 you can separate by commas or enter as multiple statements.

colors "colorname" "colorname"...

colors "red" "gray" "blue"

scale float float ...

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

buckets float float ...

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

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

legend "string" "string. 

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 you include the base color statement, 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 you omit the disk color statement, the disk has the same color as the bars. If you include the statement, any omitted clauses default to the values of the color statement.

Because 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, you can omit these statements. By default, each bar is labeled with its key; each base is labeled with its position in the hierarchy. The types of syntax for the label statements are:

label name 
base label name 
line label name 
back label name 

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 when 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:

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 U.S. 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:

message "%s: $%,f, %,.0f%% of target, %,.0f%% of last year”,
      product, sales, pctTarget, pctLastYear;

In this case, it would produce the following 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. Therefore, 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. You can 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 statement; however, because 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.

The following 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 on 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 following 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.

This sample execute statement will work on Windows as well as UNIX, because a simple xconfirm utility is provided with the installation on Windows.

The view section has many options. Like other options statements, the options can be separated by commas, or they can appear on separate lines.

options sky color colorname 
options sky color colorname colorname 
options ground color colorname 
options ground color colorname colorname

options sky color "black", ground color "black";

options rows number 
options columns number 

options overview on 
options overview off

options shrinkage auto 
options shrinkage float 
options shrinkage off

Root Label

By default, the root node of the hierarchy receives 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 hierarchy() function.

---

Note: 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).

---

options font "fontname"

options base label color "color"

options bar label color "color"

options line color "color"

options zero solid
options zero outline
options zero hidden

options null solid
options null outline
options null hidden