make.design.matrix: Converting a choice experiment design into a design matrix

In support.CEs: Basic Functions for Supporting an Implementation of Choice Experiments

Converting a choice experiment design into a design matrix

Description

This function converts a choice experiment design created by the function Lma.design or rotation.design into a design matrix suitable for a conditional logit model analysis with the function clogit in the package survival, or for a binary choice model analysis with the function glm in the package stats.

Usage

make.design.matrix(choice.experiment.design,
                   optout = TRUE,
                   categorical.attributes = NULL, 
                   continuous.attributes = NULL,
                   unlabeled = TRUE,
                   common = NULL,
                   binary = FALSE)

Arguments

choice.experiment.design	A data frame containing a choice experiment design created by the function Lma.design or rotation.design.
optout	A logical variable describing whether or not the opt-out alternative is included in the design matrix created by this function. If TRUE (default), the opt-out alternative is included; otherwise it is not.
categorical.attributes	A vector containing the names of attributes treated as categorical independent variables in the analysis.
continuous.attributes	A vector containing the names of attributes treated as continuous independent variables in the analysis.
unlabeled	A logical variable describing the types of a choice experiment design assigned by the argument choice.experiment.design. If the type is unlabeled, the argument is set as TRUE (default). If the type is labeled, it is set as FALSE.
common	A vector containing a fixed combination of attribute-levels corresponding to a common base option in each question. If there is no common base option, the argument is set as NULL (default).
binary	When the function is applied to the conditional logit model, the argument is set as FALSE (default). When the function is applied to the binary choice model, it is set as TRUE.

Details

This function converts a choice experiment design created by the function Lma.design or rotation.design into a design matrix that is suitable for conditional logit model analysis with the function clogit in the package survival or binary choice model analysis with the function glm in the package stats.

A choice experiment design created by the function Lma.design or rotation.design is assigned to the argument choice.experiment.design.

Attributes included in the choice experiment design assigned to the argument choice.experiment.design are classified into categorical and continuous attributes that are assigned to the arguments categorical.attributes and continuous.attributes, respectively. For example, an alternative may have three attributes such as X, Y, and Z. In the conditional logit model analysis, when attributes X and Y are treated as categorical variables and attribute Z is treated as continuous variable, the arguments are set as follows:

categorical.attributes = c("X", "Y")
continuous.attributes = c("Z")

The categorical variables are created in dummy-variable format. In other words, the minimum value in a categorical attribute is normalized; as a result, each dummy variable is assigned a value of 1 when the categorical attribute takes on a value other than the minimum value. The dummy variables are referred to by their levels. For example, in a categorical attribute X with the three levels of "x1," "x2," and "x3," the dummy variables are created as follows: (1) When the choice experiment design is unlabeled, two dummy variables are created: a dummy variable x2 that assumes a value of 1 when attribute X takes "x2," and 0 otherwise; and a dummy variable x3 that assumes a value of 1 when attribute X takes "x3," and 0 otherwise. (2) When the choice experiment design is labeled and the design contains two alternatives ("alternative 1" and "alternative 2"), excluding an opt-out alternative, four dummy variables are created: a dummy variable x21 that assumes a value of 1 when attribute X in alternative 1 takes "x2," and 0 otherwise; a dummy variable x22 that assumes a value of 1 when attribute X in alternative 2 takes "x2," and 0 otherwise; a dummy variable x31 that assumes a value of 1 when attribute X in alternative 1 takes "x3," and 0 otherwise; and a dummy variable x32 that assumes a value of 1 when attribute X in alternative 2 takes "x3," and 0 otherwise.

Two points should be noted with regard to continuous and categorical variables in the function make.design.matrix. First, the level of the argument continuous.attributes must take on numerical values: that is, the level must not contain a unit of the attribute, such as "USD," "kg," or "km." For example, when the argument continuous.attributes is set as c("Z") and it shows the price attribute of a product alternative, the variable Z must not contain the levels USD10, USD20, and USD30 but must have the levels of 10, 20, and 30, respectively. Second, categorical variables created by the function are not in factor format. R usually treats categorical variables as factors. However, values of attribute variables in each row corresponding to an opt-out option must be set as zero (0) because the systematic component of the utility for the opt-out option is normalized to zero. Therefore, the function make.design.matrix converts categorical attributes into dummy variables (the same treatment is applied to the function make.dataset).

The argument unlabeled is set as TRUE when the choice experiment design assigned to the argument choice.experiment.design is unlabeled; it is FALSE otherwise (when the choice experiment design is labeled).

The argument optout is set as TRUE when an opt-out alternative such as the option "none of these" is included in the choice experiment questions. It is set as FALSE when the opt-out alternative is not included.

When a common base option, which is also known as the constant comparator, is included in each choice set, a combination of attribute-levels corresponding to the common base is assigned to the argument common. For example, when the common base is an alternative in which attribute X takes "x1," attribute Y takes "y2" and attriute Z "10," the argument is set as follows:

common = c(X = "x1", Y = "y2", Z = "10")

The argument common is set as NULL when the common base option is not included. It is noted that levels of categorical attributes in the common base option are limited to those that are used in the design assigned to the argument choice.experiment.design.

When this function is used for constructing a design matrix for the function clogit, the argument binary is set as FALSE (default); the argument is set as TRUE when the function is applied to binary choice models with the function glm.

Value

This function provides a design matrix that can be directly assigned to an argument design.matrix in the function make.dataset. The design matrix contains categorical and/or continuous variables created by this function as well as the following four kinds of variables.

BLOCK	An integer variable describing the serial number of blocks.
QES	An integer variable describing the serial number of questions according to the value of the variable BLOCK.
ALT	An integer variable describing the serial number of alternatives according to the value of the variable QES.
ASC	Alternative specific constant(s). When the choice experiment design is labeled, the serial number of alternatives (ALT) is automatically appended to the tail of ASC (such as ASC1, ASC2, and ASC3)

Author(s)

Hideo Aizaki

See Also

Lma.design, rotation.design, make.dataset, syn.res1, syn.res2, syn.res3, clogit, glm

Examples

# See "Examples" for the function make.dataset.

support.CEs documentation built on Nov. 3, 2023, 9:07 a.m.