Lma.design: Creating a choice experiment design using the L^MA method

Description Usage Arguments Details Value Author(s) See Also Examples

View source: R/Lma.design.R

Description

This function creates a choice experiment design according to the L^MA method.

Usage

1
2
3
4
5
6
Lma.design(candidate.array = NULL, attribute.names, 
           nalternatives, nblocks, row.renames = TRUE, 
           seed = NULL)

## S3 method for class 'cedes'
print(x, ...)

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 a 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 DoE.base package) via the function Lma.design, or those of an array assigned to the argument candidate.array by the user.

seed

Seed for a random number generator.

x

An object of S3 class "ceds."

...

Arguments passed to the function print.

Details

The L^MA method directly creates a choice experiment design from an orthogonal main-effect array (Johnson et al. 2007). In this method, an orthogonal main-effect array with M times A columns of L level factors is used to create each choice set that contains M alternatives of A attributes with L levels. Each row of the array corresponds to the alternatives of a choice set.

This method creates a labeled type choice experiment design that can contain both generic attributes and alternative-specific attributes: the generic attribute refers to that which is included in all the alternatives; the alternative-specific attribute is that which is included in only one alternative. The reader is referred to chapters 3 and 5 of Louviere et al. (2000) for details about the types of attribute—generic or alternative-specific—and the types of choice experiment design—labeled or unlabeled.

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, let's assume that 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.

When a large choice experiment design is created (that is, there are numerous choice experiment questions), the respondent may carry a heavy psychological burden in terms of answering the questions: in these cases, the choice experiment design is frequently divided into two or more blocks (subsets) of choice sets (questions), and each respondent is asked to answer one block of questions. The argument nblocks assigns the number of blocks. For example, when the argument nblocks is set to be 3 and the choice experiment design contains 27 individual choice sets (that is, there are 27 choice experiment questions), the choice experiment design is divided into 3 blocks, each of which has 9 individual choice sets (9 choice experiment questions). "Blocking" is performed on the basis of a factor with nblocks levels.

Under default settings, this function uses an orthogonal main-effect array that is automatically produced by the function oa.design in the package DoE.base 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.

The function Lma.design can also be used for creating a binary choice experiment design on the basis of an orthogonal main-effect array by setting the argument nalternatives as 1 for a binary choice experiment with an opt-out or common base option, and 2 for a forced-choice format binary choice experiment.

Value

This function returns an object of S3 class "cedes" 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 function oa.design in the package DoE.base 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).

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

rotation.design, syn.res2, oa.design

Examples

1
2
# See the second and third cases in "Example"
# for the function make.dataset.

Example output

Loading required package: DoE.base
Loading required package: grid
Loading required package: conf.design

Attaching package: 'DoE.base'

The following objects are masked from 'package:stats':

    aov, lm

The following object is masked from 'package:graphics':

    plot.design

The following object is masked from 'package:base':

    lengths

Loading required package: MASS
Loading required package: simex
Loading required package: RCurl
Loading required package: bitops
Loading required package: XML

support.CEs documentation built on Jan. 8, 2021, 5:35 p.m.