rotation.design {support.CEs}

Creating a choice experiment design using the rotation or mix-and-match method

Description

This function creates a choice experiment design according to the rotation or mix-and-match method.

Usage

rotation.design(candidate.array = NULL, attribute.names, 
                nalternatives, nblocks, row.renames = TRUE, 
                randomize = FALSE, seed = NULL)

Arguments

candidate.array

A data frame containing an array created by the user. Normally, when this function is used, this argument does not need to be set by the user.

attribute.names

A list of the names of attributes and levels.

nalternatives

An integer value describing the number of alternatives per choice set, excluding an opt-out alternative such as a "none of these" or common base alternative.

nblocks

An integer value describing the number of blocks into which a choice experiment design is divided.

row.renames

A logical variable describing whether or not the row names of a choice experiment design created by this function are changed. When its value is TRUE (default), integer values are assigned to the row names starting from 1. When its value is FALSE, the row names are the same as those of an array created by the function oa.design (included in the package DoE.base) via the function rotation.design, or those of an array assigned to the argument candidate.array by the user.

randomize

If this argument is TRUE (default), the function executes the mix-and-match method. If FALSE, the function executes the rotation method.

seed

Seed for a random number generator.

Details

This function creates an unlabeled (generic) choice experiment design according to the rotation or mix-and-match method (Johnson et al. 2007) (see "Details" for the function Lma.design about the types of choice experiment design). Each method depends on an orthogonal main-effect array generated by the function oa.design in the package DoE.base or an arbitrary array set by the user.

The rotation method uses an orthogonal main-effect array as the first alternative in each choice set; this method creates one or more additional alternative(s) by adding a constant to each attribute level of the first alternative; the kth(>= 2) alternative in the jth (= 1, 2, ..., J) choice set is created by adding one to each of the m attributes in the k - 1 th alternative in the jth choice set. If the level of the attribute in the k - 1 th alternative is maximum, then the level of the attribute in the k th alternative is assigned the minimum value.

The mix-and-match method modifies the rotation method by introducing the randomizing process. After placing a set of N alternatives created from the orthogonal main-effect array into an urn, one or more additional set(s) of N alternatives are created using the rotation method and placed into different urn(s). A choice set is generated by selecting one alternative from each urn at random. This selection process is repeated, without replacement, until all the alternatives are assigned to N choice sets. These N choice sets correspond to a choice experiment design.

When the mix-and-match method is implemented by this function, the argument randomize is set as TRUE (default). When the rotation method is implemented by this function, the argument is set as FALSE.

When this function is used, the combination of attributes and attribute levels, the number of alternatives per choice set excluding an opt-out or common base option, and the number of blocks are respectively assigned to the arguments.

The combination of attributes and attribute levels are assigned to the argument attribute.names in list format. For example, the alternative has three attributes, each of which has three levels: an attribute X with the three levels of x1, x2, and x3; an attribute Y with the three levels of y1, y2, and y3; and an attribute Z with the three levels of 10, 20, and 30. In this case, the argument is set as follows:

attribute.names = list(X = c("x1", "x2", "x3"),
Y = c("y1", "y2", "y3"), Z = c("10", "20", "30"))

The number of alternatives per choice set is defined by the argument nalternatives: the number of alternatives does not include an opt-out option such as a "none of these" or a common base option.

Similar to the function Lma.design, this function can divide a choice experiment design into two or more blocks based on the argument nblocks. A choice experiment design is randomly divided into nblocks blocks; therefore, nblocks must be divisors of the number of choice sets included in the choice experiment design.

Under default settings, this function uses an orthogonal main-effect array that is automatically produced by the function oa.design based on the argument attribute.names to create a choice experiment design. However, when there is no array corresponding to the argument attribute.names, the function oa.design returns a full factorial based on the argument attribute.names (See help for the function oa.design in the packge DoE.base). On the other hand, when this function does not create a choice experiment design matching the user's requirements, the user might achieve it by assigning an arbitrary (user-defined) array to the argument candidate.array: this function uses the array to create a choice experiment design. When the user-defined array is used, the last column of the array must contain a column for dividing the design based on the argument nblocks. The arguments attribute.names and nblocks must also be assigned according to the array.

Value

This function returns an object of S3 class "cedes" (see Lma.design) that is a list with the following components.

alternatives

A list of objects, alt.j: the jth alternative in each choice set created by this function. Each of alt.j includes a variable BLOCK describing the serial number of blocks, a variable QES describing the serial number of choice experiment questions for each value of the variable BLOCK, a variable ALT describing the serial number of alternatives for each value of the QES variable, and attribute variables corresponding to the argument attribute.names.

candidate

A candidate array used for creating a choice experiment design, which is generated using the oa.design function in the DoE.base package or which the user sets for the argument candidate.array. When nblocks >= 2, the last column in this value (candidate) shows a factor that is used for blocking.

design.information

Information related to the choice experiment design created by this function, which is used as arguments in post-processing functions, such as the functions questionnaire and make.design.matrix. This list includes objects such as the number of blocks into which the choice experiment design is divided (nblocks), the number of questions per block (nquestions), the number of alternatives per choice set excluding an opt-out or common base option (nalternatives), and the number of attributes per alternative (nattributes).

An error message is displayed when the argument nblocks does not match a choice experiment design. In such a case, the argument nblocks is set to be a divisior of the number of rows of the choice experiment design. Ohter messages are frequently shown immediately after executing this function when it works properly. These messages are taken from the function oa.design and may be valuable to a user who wishes to define the original array and assign it the argument candidate.array.

Author(s)

Hideo Aizaki

See Also

Lma.design, syn.res1, oa.design

Examples

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