2.4.2 Variable Elements

A “variable” in detail XML is a 1-dimensional array of data. Each element of the array may, independently, have string or numeric content. All of the variables in a given detail XML member either have the same number of elements or have zero elements.

Two different elements define variables and their content:

sourceVariable

These variables’ data comes from the associated tableData.bin member.

derivedVariable

These variables are defined in terms of a mapping function from a source variable, or they are empty.

A variable named cell always exists. This variable holds the data displayed in the table.

Variables in detail XML roughly correspond to the dimensions in a light detail member. Each dimension has the following variables with stylized names, where n is a number for the dimension starting from 0:

dimensionncategories

The dimension’s leaf categories (see Categories).

dimensionngroup0

Present only if the dimension’s categories are grouped, this variable holds the group labels for the categories. Grouping is inferred through adjacent identical labels. Categories that are not part of a group have empty-string data in this variable.

dimensionngroup1

Present only if the first-level groups are further grouped, this variable holds the labels for the second-level groups. There can be additional variables with further levels of grouping.

dimensionn

An empty variable.

Determining the data for a (non-empty) variable is a multi-step process:

  1. Draw initial data from its source, for a sourceVariable, or from another named variable, for a derivedVariable.
  2. Apply mappings from valueMapEntry elements within the derivedVariable element, if any.
  3. Apply mappings from relabel elements within a format or stringFormat element in the sourceVariable or derivedVariable element, if any.
  4. If the variable is a sourceVariable with a labelVariable attribute, and there were no mappings to apply in previous steps, then replace each element of the variable by the corresponding value in the label variable.

A single variable’s data can be modified in two of the steps, if both valueMapEntry and relabel are used. The following example from the corpus maps several integers to 2, then maps 2 in turn to the string “Input”:

<derivedVariable categorical="true" dependsOn="dimension0categories"
                 id="dimension0group0map" value="map(dimension0group0)">
  <stringFormat>
    <relabel from="2" to="Input"/>
    <relabel from="10" to="Missing Value Handling"/>
    <relabel from="14" to="Resources"/>
    <relabel from="0" to=""/>
    <relabel from="1" to=""/>
    <relabel from="13" to=""/>
  </stringFormat>
  <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
  <valueMapEntry from="10;11" to="10"/>
  <valueMapEntry from="14;15" to="14"/>
  <valueMapEntry from="0" to="0"/>
  <valueMapEntry from="1" to="1"/>
  <valueMapEntry from="13" to="13"/>
</derivedVariable>