Importing Conjoint Data from Text-Only Files
Top  Previous  Next


The Market Simulator can import conjoint part-worth utility data from any of the files generated by Sawtooth Software's current conjoint analysis systems. If you are importing data that you generated yourself, you should create a text-only file matching the ".HBU" format. If your utility file includes linear terms, you must also provide a .VAL file. The formats for these two files are described below.
 
The ".HBU" Import Format

This format gets its name from the CBC/HB system, which creates text-only files containing conjoint part-worth estimation with the extension ".HBU". It is the most flexible of the Sawtooth Software part-worth file formats, accommodating:

Part-worth or linear estimation of attribute effects  
Main effect and optional first-order interactions  
Individual-level records, with a measure of fit (e.g. correlation) that can be used as a filter for exclusion     

The .HBU file should be created as a text-only, space or tab-delimited format.

A Simple, Main Effects Example

Here is an example file for a simple study with 3 attributes (main effect part-worth estimation only) and a total of 2 respondents:

3 0 11 1 1  
3 4 4  
1 0 0  
0 1 0  
0 0 1  
1 1 Brand A  
1 2 Brand B  
1 3 Brand C  
2 1 Style A  
2 2 Style B  
2 3 Style C  
2 4 Style D  
3 1 $8  
3 2 $10  
3 3 $15  
3 4 $20  
  1001  778  0  11  0  
-1.323  0.667  0.656  -.520  0.836  0.310  -0.626  1.271  0.652 -.529   
-1.394  
  1003  540  0  11  0  
-1.042  0.235  0.807  -.239 -0.211  0.310   0.140  1.060  0.254 -.095  
-1.219  
 
The data structure consists of a header section (the first 16 lines in this example), followed by a respondent header (one per respondent) and preference values for each respondent.

The first line contains the number of attributes (3), whether a "None" utility is included (1 if yes, 0 if no), the total number of parameters estimated for each individual (11), and the numbers 1 and 1. (These last two values are just to conform to the file format for the Latent Class module, which uses the same header format.)

The second line contains the number of estimated terms for the main effects for each attribute (3, 4, 4).

Following is a line for each attribute, each with as many entries as there are attributes. This is an attribute-by-attribute matrix of ones and zeros (or minus ones) that indicates which effects were estimated. This example represents main effects only and is indicated by ones on the diagonal. If interactions were included (they weren't for this example), they would be indicated by a one in other positions. Linear variables (there weren't any for this example) are indicated by negative ones on the diagonal.

Following are labels, one for each parameter estimated. There are two leading space-delimited integers on each line, indexing the attributes and levels. These attribute/level labels are in the same order as the parameter estimates that follow in the file, and serve to identify them. If interaction parameters were estimated, then this list will include a label for each term.

The record for each respondent starts with a line that contains:

Respondent number (respondents 1001 and 1003 are found in this example). Respondent numbers are limited to 9 total characters.  
 
A measure of fit such as R-squared or RLH can be included and used as a filter in simulations. The range of acceptable values is from 0 to 1000. If no measure of fit is available, you can set this to an integer within that range such as "0".  
 
A value of zero (this is a carry-over from other Sawtooth Software formats)  
 
The total number of parameter estimates per respondent (in this case, 11 part-worths)  
 
A value of -1 if a "none" utility exists, or a zero otherwise.  

This respondent header is followed by the parameter values for that respondent, in the same order as the labels in the header.

Even though the example above uses utility values with just three decimal places of precision, up to 15 significant digits of precision may be used. The utility values can be formatted on a single or multiple lines (hard return characters within a respondent record are ignored). However, each respondent's record should begin a new line.

A Complex .HBU File Example

If your conjoint part-worths include linear terms (such as a single coefficient representing the main effect for Price), you must supply two files: .HBU and .VAL (format described below). The example below illustrates a linear term and the inclusion of a first-order interaction.

3 1 12 1 1  
3 4 1   
1  0  1   
0  1  0   
1  0 -1   
1 1 Brand A   
1 2 Brand B   
1 3 Brand C   
2 1 Style A   
2 2 Style B   
2 3 Style C   
2 4 Style D   
3 1 Price  
Brand A  x Price  
Brand B  x Price  
Brand C  x Price  
NONE  
1003    368  0  12  -1  
-0.099  1.082  -0.983  -0.070  2.106  -3.585   1.549  -1.463   0.391   0.537  
-0.928  1.004  
1004       708  0  12 -1  
7.197   4.854  -12.051  7.022  2.581  -4.098  -5.504  -0.735  -1.496  -2.280   
3.776   3.872   
1005   497    0 12 -1  
3.314   1.854  -5.169   3.656  1.736  -3.652  -1.740  -0.726  -0.114  -0.408  
0.522   2.709   

Note in this example that both linear effects and interactions have been specified. Because only one coefficient is estimated to represent the main effect for Price, note the "1" in the second line, third position. We've copied lines three through five below and added bolding and underlining for further illustration:

1  0  1   
0  1  0   
1  0 -1   
 
The elements along the diagonal (in bold) correspond to the main effects. All main effects are included, but attribute 3 is represented by a single coefficient (linear term). The linear terms are indicated by "-1" in the design matrix. Off-diagonal elements reflect interaction terms. There is one interaction (underlined) specified: attribute 1 x attribute 3 (note that it is indicated in both the lower and upper halves of the matrix).

The order of utility values must be as follows:  
 
Main effects  
 
Interactions, in the following order (assuming complete specification of interactions):  
   Attrib1 x Attrib2 . . . Attrib1 x Attribn, Attrib2 x Attrib3 . . .Attrib2 x Attribn, etc.  
 
None (only one value)  
 
Important Note: The Market Simulator assumes that the independent variables used for linear variables were zero-centered. If you used Sawtooth Software's CBC/HB or Latent Class systems, this happened automatically during utility estimation. If you are providing utility files from your own estimation procedure, you should make sure your linear codes are zero-centered.



The .VAL File

If your .HBU file includes linear terms, you must provide an accompanying .VAL file. Let's assume that you estimated a linear term for Price, and that the dollar values were $8, $10, $15 and $20. The Market Simulator assumes that you zero-centered the codes for linear variables for estimation. Therefore, you may have coded these prices as -5.25, -3.25, 1.75, 6.75 in your independent variable matrix. In that case, the accompanying .VAL file should be as follows:

Brand  
1 2 3  
Style  
1 2 3 4  
Price  
-5.25 -3.25  1.75  6.75  

There are two lines for each attribute: the first is a short attribute labels and the next contains blank-delimited values to be assigned to that attribute's levels for use in defining products in the simulator. There must be one value for each level. In this example the first two attributes have values of 1, 2 and 3, which are used as nominal level codes for these attributes. The third attribute has values of -5.25, -3.25, 1.75 and 6.75.

When you import the .HBU and .VAL file into the Market Simulator, these numeric codes will be assigned to the different levels of price. However, you can always add back the constant to change these values to 8, 10, 15 and 20 (the original prices in our example) for ease of use in the simulator by clicking Assign Level Values. Adding back the constant (that was subtracted for zero-centering) is appropriate as during simulations the Market Simulator always zero-centers level values for linear terms before applying them to the coefficients in the utility file.