|
SYNTAX REFERENCE GUIDE
|
|
Quickly jump to ... |
|
Specifies what algorithm to use when generating efficient designs. |
|
|
Defines the alternatives in the choice set. |
|
|
Defines the type and number of draws for Bayesian priors. |
|
|
Defines the number of blocks in the design. |
|
|
Sets the random seed for drawing Bayesian priors. |
|
|
Specifies whether the design efficiency should also be optimised for estimating alternative-specific constants. |
|
|
Defines conditional constraints on attribute levels when generating an efficient design using the swapping algorithm. |
|
|
Indicates the generation of an efficient fractional factorial design and defines the optimisation criterion when generating an efficient design. |
|
|
Evaluates the efficiency of an existing experimental design. |
|
|
Indicates the generation of a full factorial design. |
|
|
Defines the Fisher information matrix when combining information from multiple models or population segments. |
|
|
Specifies whether a fold-over design will be generated. |
|
|
Defines the utility functions of the choice model. |
|
|
Indicates the generation of an orthogonal fractional factorial design and defines the type of orthogonal design. |
|
|
Defines the precision of all numbers reported in Ngene. |
|
|
Indicates the generation of a random fractional factorial design |
|
|
Defines the type and number of draws for random parameters. |
|
|
Defines check constraints to reject certain attribute level combinations when generating a design. |
|
|
Defines the size of the simulated sample to compute the efficiency of a design for a model type that accounts for panel effects. |
|
|
Defines check constraints to accept certain attribute level combinations when generating a design. |
|
|
Defines the design size, i.e., the number of choice tasks in the design. |
|
|
Sets the random seed for drawing random parameters. |
|
|
Defines a starting design when generating an efficient design. |
|
|
Defines willingness-to-pay (WTP) expressions that can be used to generate efficient designs for estimating WTP. |
|
General
All scripts have the following structure:
design ; <property> ; ... $
Each script starts with design and ends with $, while desired properties of the experimental design are defined in between. A semicolon (;) needs to be used as a separator when adding a new property. An example script is:
design ;alts = (laptop1, laptop2), neither ;rows = 12 ;eff = (mnl,d) ;model: U(laptop1, laptop2) = b1 * screensize[13,15,17] ? screensize in inch + b2 * storage[128,256,512] ? storage space in GB + b3 * price[800,1200,1600] ? price in dollars / U(neither) = b0 $
Syntax in the script is not case sensitive. Any text after a question mark (?) is considered a comment and is ignored by Ngene. In the example script above, four properties are defined, namely alts, rows, eff, and model.
In the remainder of this syntax reference, each possible property is listed (in alphabetical order) and is explained in detail. Some properties require the user to specify an integer value, a decimal value, or a string. A string can contain letters, numbers, and an underscore (_), but should not contain spaces or include other characters. A string should also not be identical to the name of a property. |
|
Property that specifies what algorithm to use when generating efficient designs.
|
|
|
Format
alg = <algorithm>(<option>, ...)
|
|
|
Explanation
<algorithm> can be |
|
|
all |
to consecutively assess all possible design combinations (only feasible for small design dimensions) |
|
mfedorov |
to use the row-based modified Fedorov algorithm, |
|
swap |
to use the column-based swapping algorithm, |
|
rsc (or: rs, rc, sc, r, s, c) |
to use the relabelling, swapping (s) & cycling (c) algorithm (or only some of these components). |
|
|
|
|
<option> for all algorithms can be: |
|
|
stop = total(number secs) |
to terminate the algorithm after number (integer) seconds, |
|
stop = total(number mins) |
to terminate the algorithm after number (integer) minutes, |
|
stop = total(number iterations) |
to terminate the algorithm after number (integer) iterations, |
|
stop = noimprov(number secs) |
to terminate the algorithm if no improvement after number (integer) seconds, |
|
stop = noimprov(number mins) |
to terminate the algorithm if no improvement after number (integer) minutes, |
|
stop = noimprov(number iterations) |
to terminate the algorithm if no improvement after number (integer) iterations. |
|
|
|
|
<option> for algorithm mfedorov can also be: |
|
|
candidates = number_of_rows |
to use a random candidate set of size number_of_rows (integer). |
|
candidates = experiment |
to use the design stored in experiment (string) as external candidate set. |
|
|
|
|
<option> for algorithm swap can also be: |
|
|
random = number |
to set number (integer) of seed iterations to perform during the initial phase of complete design randomisation, |
|
swap = number |
to set number (integer) of swaps to perform for each attribute, |
|
swapnoimprov = number |
to set number (integer) of swaps to perform for each attribute after an improvement has been found, |
|
reset = number |
to set number (integer) of iterations with no improvement that need to be elapsed before a new design randomisation, |
|
resetinc = number |
to set number (integer) of iterations with which to increase reset after each design randomisation. |
|
|
|
|
Comments
· If no algorithm property is specified, then swap is used by default. · If no options for the modified Fedorov algorithm are specified, then candidates=2000 is used by default. The maximum candidate set size is 10,000. · If no options for the swapping algorithm are specified, then random=10, swap=1, swaponimprov=50, reset=10000, resetinc=500 will be used for most model types. · If no termination criterion is specified, then by default stop=noimprov(5000 iterations), stop=total(1200 mins) is used. For the modified Fedorov algorithm with a candidate set larger than 2,500 rows, to avoid premature termination, 5000 is replaced with twice the candidate set size. · Property alg can only be used when generating an efficient design, there cannot be used in conjunction with properties, fact, rand, orth, or eval. · The modified Fedorov algorithm ignores attribute level balance. To guarantee a certain degree of attribute level balance, one may want to add minimum and maximum bounds on the number of times each attribute level should appear within the design, see property model.
|
|
|
Examples
alg = all alg = swap alg = mfedorov alg = rsc alg = rc alg = swap(random=20, swap=1, swaponimprov=40, reset=5000, resetinc=1000) alg = mfedorov(candidates=2000) alg = mfedorov(candidates=my_experiment) alg = swap(stop=total(200 secs)) alg = mfedorov(stop=noimprov(1000 iterations))
|
|
|
Property that defines the alternatives in the choice set.
|
|
Format
alts(model) = (alternative, ...), ...
|
|
Explanation
alternative (string) is the user-specified name of a choice option in a choice set. Alternatives that are of the same type with the same preference structure, also referred to as unlabelled or generic alternatives, should be grouped using parentheses around the alternative names.
model (string) is the user-specified model name in the model property. If only a single model is specified, then the model name can be omitted. If multiple models are specified, property alts should be defined for each model. Different models can have a different number of alternatives.
|
|
Comments
· This is a mandatory property to define.
|
|
Examples
alts = (laptopA, laptopB), neither alts = car, train, bus alts = (car1, car2), (train1, train2) alts = chemotherapy, immunotherapy, active_surveillance alts = (policy1, policy2, statusquo) alts(unforced) = Apple, Samsung, Huawei, optout ; alts(forced) = Apple, Samsung, Huawei alts(model1) = (hotel1, hotel2) ; alts(model2) = (hotel1, hotel2)
|
|
Property that defines the type and number of draws for Bayesian priors.
|
|
|
Format
bdraws = <drawtype>(number)
|
|
|
Explanation
<drawtype> can be |
|
|
gauss |
to use Gaussian quadrature, |
|
halton |
to use Halton draws, |
|
mlhs |
to use modified latin hypercube sampling, |
|
random |
to use pseudo-random draws, |
|
sobol |
to use Sobol draws. |
|
|
|
|
number (integer) is the total number of draws from the Bayesian distributions, except for gauss.
number (integer) for gauss refers to the number of abscissas (coordinates) for each individual prior, and the total number of draws depends on the number of Bayesian priors. For example, using gauss(3) in the presence of four Bayesian priors means that the total number of draws is 3*3*3*3 = 81. It is possible to use a different number of abscissas for each prior, for example gauss(3,4,2,5) uses three abscissas for the first Bayesian prior, four for the second, two for the third, and five for the fourth, such that the total number of draws equals 3*4*2*5 = 120.
|
|
|
Comments
· If Bayesian priors are specified but the bdraws is not defined, then by default halton(200) is used. · The more Bayesian priors are specified, the larger the number of draws needs to be. · The total number of draws cannot exceed 10,000. · Take care when using gauss; if the number of Bayesian priors is large, the total number of draws can become very large. · When the number of Bayesian priors is large, sobol and mlhs should be preferred over halton.
|
|
|
Examples
bdraws = sobol(500) bdraws = mlhs(1000) bdraws = gauss(5) bdraws = gauss(4,5,3,1,4)
|
|
|
Property that defines the number of blocks in the design.
|
|
|
Format
block = number, <option>, ...
|
|
|
Explanation
number (integer) divides the total number of choice tasks in a design, such that each decision maker can be given a subset of choice tasks. For example, when using rows=12 and block=3, then the design is blocked into three equal parts of four choice tasks each. Ngene aims to maximise attribute level balance within each block, although perfect attribute level balance within a block is only achievable with an orthogonal design. When adding this property, an additional column is added to the design that describes the block number that each choice task belongs to.
<option> can be |
|
|
minsum |
to determine blocks such that the sum of correlations between the blocking column and the attributes are minimised, |
|
minmax |
to determine blocks such that the maximum correlation between the blocking column and the attributes is minimised, |
|
total(number mins) |
to indicate the number (integer) of minutes to search for the best blocking column, |
|
noimprov(number secs) |
to indicate the number (integer) of seconds to keep searching after an improvement was found, |
|
noimprov(number mins) |
to indicate the number (integer) of minutes to keep searching after an improvement was found, |
|
newblocking |
to generate a new blocking column when evaluating an existing design using eval. |
|
|
|
|
Comments
· If no options are specified, the default options are set to minsum, total(3 secs)
|
|
|
Examples
block = 2 block = 4, minmax, noimprov(10 secs) block = 3, newblocking block = 3, minsum, total(1 mins), newblocking
|
|
|
Property that sets the random seed for bdraws.
|
|
Format
bseed = number
|
|
Explanation
number (integer) sets the seed for the random generator when taking draws for Bayesian priors using bdraws=random or bdraws=mlhs. Other types of draws than pseudo-random draws and latin hypercube sampling do not use a random generator and hence the random seed is redundant.
|
|
Comments
· If bseed is not specified, then the draws will be fully random each time the script is run.
|
|
Examples
bseed = 4 bseed = 12345
|
|
Property that specifies whether the design efficiency should also be optimised for estimating alternative-specific constants.
|
|
Format
con
|
|
Explanation
By default, Ngene does not aim to minimise the standard errors of the alternative-specific constants when generating an efficient design. Adding this property will force Ngene to also consider the efficiency of estimating alternative-specific constants.
|
|
Comments
· This property is only relevant for labelled experiments where alternative-specific constants exist.
|
|
Examples
con
|
|
Property that defines conditional constraints on attribute levels when generating an efficient design using the swapping algorithm.
|
|
|
Format
cond: if(<logical expression>, <logical expression>), ...
where <logical expression> can be |
|
|
<comparison> |
to specify a single comparison, |
|
<comparison> AND <comparison> ... |
to specify a compounded comparison using the AND operator, |
|
<comparison> OR <comparison> ... |
to specify a compounded comparison using the OR operator. |
|
|
|
|
where <comparison> can be |
|
|
<value> = <value> |
to specify an ‘equal to’ comparison, |
|
<value> > <value> |
to specify a ‘greater than’ comparison, |
|
<value> < <value> |
to specify a ‘smaller than’ comparison, |
|
<value> >= <value> |
to specify a ‘greater than’ or equal to comparison, |
|
<value> <= <value> |
to specify a ‘smaller than or equal to’ comparison, |
|
<value> <> <value> |
to specify an ‘unequal to’ comparison. |
|
|
|
|
<value> can be |
|
|
alternative.attribute |
to refer a specific attribute (string) belonging to a specific alternative (string), |
|
number |
to specify a specific number (decimal), |
|
[number, ...] |
to specify a set of numbers. |
|
|
|
|
Explanation
When selecting attribute levels for the design, if the first <logical expression> (related to IF) is true, then Ngene ensures that the second <logical expression> (related to the THEN) is also true.
Using a set of numbers is equivalent to using a compound comparison using the OR operator. For example, route1.fuelcost = [1,2] is equivalent to route1.fuelcost = 1 OR route1.fuelcost = 2.
A <value> can also be determined based on limited arithmetic, where only addition (+) and subtraction (–) are supported. For example, route1.fuelcost + route1.tollcost < 5 is an allowable comparison.
|
|
|
Comments
· Conditional constraints can only be defined when generating an efficient design using the column-based swapping algorithm. When using the modified Fedorov algorithm or when generating a full and random fractional factorial design, only check constraints using require and reject can be defined. Note that in most cases it is possible to rewrite cond constraints into reject constraints. · Since the swapping algorithm is a restrictive column-based algorithm, only a limited number of conditional constraints should be defined. If Ngene is unable to locate a design that satisfies all constraints, then please switch to the more flexible row-based modified Fedorov algorithm. · Adding too many, or too strict, conditional constraints may result in attributes becoming perfectly correlated. In this case, the model cannot be estimated due to multicollinearity and the D-error of the design would become very large or undefined. · Conditional constraints cannot be specified when generating designs using fisher.
|
|
|
Examples
cond: if(flight1.businessclass = 1, flight1.price = [2000,2500]), if(flight1.businesclass = 0, flight1.price = [800,1200]) cond: if(hotelA.stars < hotelB.stars, hotelA.price <= hotelB.price) cond: if(train.nr_transfers = 0, train.transfertime = 0), if(train.nr_transfers >= 2, train.transfertime = [20,30,40]) cond: if(laptop1.screensize > 15 and laptop1.harddisk > 512, laptop1.price > 2000)
|
|
|
Property that indicates the generation of an efficient fractional factorial design and defines the optimisation criterion when generating an efficient design.
|
|
|
Format
eff = <weight>*<objective> + ...
where <objective> can be |
|
|
<model>(<modeltype>,<criterion>,<statistic>,<decisionrule>) |
to optimise model efficiency, |
|
<fisher>(<modeltype>,<criterion>,<statistic>,<decisionrule>) |
to optimise model efficiency with a user-specified Fisher information, |
|
(imbalance) |
to optimise attribute level balance within the design. |
|
Explanation
<modeltype> can be |
|
|
mnl |
to optimise for estimating a multinomial logit model, |
|
rp |
to optimise for estimating a random parameter mixed logit model, |
|
rppanel |
to optimise for estimating a random parameter mixed logit model accounting for panel effects, |
|
ec |
to optimise for estimating an error component mixed logit model, |
|
ecpanel |
to optimise for estimating an error component mixed logit model accounting for panel effects, |
|
rpec |
to optimise for estimating a random parameter and error component mixed logit model, |
|
rpecpanel |
to optimise for estimating a random parameter and error component mixed logit model accounting for panel effects. |
|
|
|
|
<criterion> can be |
|
|
a |
to use the A-error as efficiency measure, |
|
d |
to use the D-error as efficiency measure, |
|
s(t_ratio) |
to use the sample size estimate as efficiency measure, based on a minimum desired t_ratio (decimal) with default 1.96 (5% significance), |
|
wtp(label) |
to use the C-error as efficiency measure, based on willingness-to-pay definition with optional label (string) in property wtp. |
|
|
|
|
<statistic> can be |
|
|
fixed |
to compute the local D-error using local priors or the means of the Bayesian priors, |
|
mean |
to compute the Bayesian D-error based on the average over all draws of the Bayesian distribution, |
|
median |
to compute the Bayesian D-error based on the median over all draws of the Bayesian distribution. |
|
|
|
|
<decisionrule> can be |
|
|
rum |
to assume a model based on random utility maximisation, |
|
rrm |
to assume a model based on random regret minimisation. |
|
|
|
|
weight (decimal) is an optional weight factor in case multiple objectives are considered. model (string) is the user-specified name of the model defined in the model property, which can be omitted if only a single model is specified. fisher (string) is the user-specified name for the Fisher information matrix defined in the fisher property.
|
|
|
Comments
· If only eff is specified, then by default the following objective is optimised: eff = 1*(mnl,d,fixed,rum). · It is strongly recommended to only optimise designs for the multinomial logit model, as optimising designs for other model types is very computationally intensive and can give unstable results. · When some Bayesian prior distributions are wide, it is recommended to use median instead of mean to avoid that outliers dominate the Bayesian D-error computation. · The use of median is not compatible with bdraws=gauss. · Using rrm as a decision rule is only meaningful for unlabelled experiments with three or more alternatives. · Adding (imbalance) as an optimisation criterion is mainly useful in conjunction with the row-based modified Fedorov algorithm; the swapping algorithm aims to achieve attribute level balance by definition.
|
|
|
Examples
eff eff = (mnl,d) eff = (mnl,a,mean) eff = (rppanel,d,median) eff = (mnl,s,fixed,rrm) eff = (mnl,wtp(wtp1)) eff = (mnl,d) + 2*(imbalance) eff = 2*(mnl,d) + 0.1*(mnl,s(2.576)) eff = model1(mnl,d) + 0.5*model2(rppanel,d) eff = fisher1(mnl,d)
|
|
|
Property that evaluates the efficiency of an existing experimental design.
|
|
Format
eval = design
|
|
Explanation
design (string) is the user-specified name of design in the same experiment folder that the user would like to evaluate. This design could have been imported as an NGD (Ngene Design file), Excel file, or CSV data file into the experiment.
|
|
Comments
· An efficiency criterion needs to be specified using the eff property.
|
|
Examples
eval = my_design
|
|
Property that indicates the generation of a full factorial design.
|
|
Format
fact
|
|
Explanation
Generates a design with all possible choice tasks, by default assuming rows = all. When generic alternatives are specified, it will omit choice tasks with identical profiles, and also omit choice tasks with a strictly dominant alternative if priors are specified.
|
|
Comments
· Full factorial designs can be very large; the design will not be generated if the design size exceeds 10,000 rows. · Check constraints can be added using the reject and require properties.
|
|
Examples
fact
|
|
Property that defines the Fisher information matrix when combining information from multiple models or population segments.
|
|
Format
fisher(fisher) = design(model[fraction], ...) + ...
|
|
Explanation
fisher (string) is the user-specified name of the Fisher information matrix. design (string) is the user-specified name of the resulting experimental design. model (string) is the user-specified name of the model defined in the model property, which can be omitted if only a single model is specified. fraction (decimal) is the expected fraction of the specific model in the data; fractions need to sum to one.
In case a homogeneous design is preferred, only a single design name should be specified, and all models should appear simultaneously between the brackets. For example fisher(fish1) = my_design(male[0.5],female[0.5]).
In contrast, if a heterogeneous design is preferred, multiple design names should be provided, and a subset of models should appear between brackets. For example, fisher(fish2) = design1(male[0.5]) + design2(female[0.5]).
Instead of specifying a fixed fraction, the user can choose to specify lower and upper bounds on the fractions, in which case Ngene will determine optimal fractions for each model in the data. For example, fisher(fish3) = design1(male[0.1:0.7]) + design2(female[0.1:0.7]), whereby the upper bounds of the fractions need to sum to one or more.
|
|
Comments
· The fisher property can be useful when generating designs for specific population segments with possibly different sets of attribute levels. · Each attribute needs to have a consistent number of levels across all specified models. · The fisher property cannot be used in combination with constraints (properties cond, reject or require).
|
|
Examples
fisher(fisher1) = des(small[0.33], medium[0.33], large[0.34]) fisher(f2) = design1(male[0.5]) + design2(female[0.5]) fisher(fish) = my_design(unforced[0.5], forced[0.5]) fisher{f1} = des1(small[0.33]) + des2(medium[0.33], large[0.34]) fisher{fish1} = d1(short[0.1:0.6]) + d2(medium[0.1:0.6], long[0.1:0.6])
|
|
Property that specifies whether a fold-over design will be generated. |
|
|
|
Format
foldover
|
|
Explanation
A fold-over design doubles the number of choice tasks in such a way that it removes all correlation between main effects and each two-way interaction effect (but not between two-way interaction effects).
|
|
Comments
· The fold-over design appends a new block to the design, such that it does not increase the number of choice tasks shown to a decision-maker.
|
|
Examples
foldover
|
|
Property that defines the utility functions of the choice model. |
|
|
|
|
|
Format
model(model): U(alternative, ...) = <utility component> + ... / ...
where <utility component> can be |
|
|
<parameter> |
to specify an alternative-specific constant, |
|
<parameter> * <attribute> |
to specify a main effect, |
|
<parameter> * <attribute> * <attribute> |
to specify a two-way interaction effect, |
|
<parameter> * <attribute> * <attribute> * <attribute> |
to specify a three-way interaction effect, |
|
<error component> |
to specify an error component. |
|
where <parameter> can be |
|
|
parameter[<prior>] |
to specify a fixed parameter of a numerical attribute, |
|
parameter.dummy[<prior>| ...] |
to specify a fixed parameter of a dummy coded categorical attribute |
|
parameter.effects[<prior>| ...] |
to specify a fixed parameter of an effects coded categorical attribute. |
|
parameter[n,<prior>,<prior>] |
to specify a random parameter following a normal distribution with priors for the mean and standard deviation, respectively, |
|
parameter[u,<prior>,<prior>] |
to specify a random parameter following a uniform distribution with priors for the lower and upper bound, respectively, |
|
parameter.dummy[n,<prior>,<prior>| ...] |
to specify a random parameter of a dummy coded categorical attribute following a normal distribution, |
|
parameter.effects[n,<prior>,<prior>| ...] |
to specify a random parameter of an effects coded categorical attribute following a normal distribution, |
|
parameter.dummy[u,<prior>,<prior>| ...] |
to specify a random parameter of a dummy coded categorical attribute following a uniform distribution, |
|
parameter.effects[u,<prior>,<prior>| ...] |
to specify a random parameter of an effects coded categorical attribute following a uniform distribution, |
|
|
|
|
where <error component> can be |
|
|
parameter[ec,<prior>] |
to specify a normally distributed parameter with mean 0 and an estimable standard deviation. |
|
|
|
|
where <prior> can be |
|
|
- |
to specify a noninformative prior that indicates a decreasing preference order with increasing attribute levels |
|
+ |
to specify a noninformative prior that indicates an increasing preference order with increasing attribute levels |
|
prior |
to specify a local prior, |
|
(n,mu,sigma) |
to specify a normally distributed Bayesian prior, |
|
(u,lower,upper) |
to specify a uniformly distributed Bayesian prior. |
|
|
|
|
where <attribute> can be |
|
|
attribute[level, ...] |
to specify an attribute and its levels, |
|
attribute.level[level] |
to refer to a specific level of a dummy or effects coded attribute, |
|
attribute.ref[level] |
to specify the reference level of an attribute, |
|
attribute.piv[level, ...] |
to specify the pivot levels of an attribute, |
|
attribute.covar[level] |
to define an attribute as a covariate (socio-demographic) with a fixed level, |
|
attribute[attribute2] |
to set the level of an attribute equal to the level of another attribute (only with swapping algorithm), |
|
attribute[fcn(<expression>)] |
to define the level of an attribute as a function of the levels of other attributes (only with swapping algorithm). |
|
|
|
|
Explanation
model (string) is the user-specified name of the model, which can be omitted if only a single model is specified. alternative (string) is the user-specified name of the alternative as defined in the alts property. parameter (string) is the user-specified name of the parameter associated with an attribute. attribute (string) is the user-specified name of an attribute associated with an alternative. level (decimal) is the user-specified value of a level associated with an attribute. prior (decimal) is the user-specified value associated with a parameter. mu (decimal) and sigma (decimal) are the mean and standard deviation of a normally distributed Bayesian prior. lower (decimal) and upper (decimal) are the lower and upper bounds of a uniformly distributed Bayesian prior.
Multiple alternatives that have the same utility function can be specified simultaneously using U(alternative1, alternative2, ...).
When the same parameter name is used across different alternatives, then it is considered a generic parameter and the prior values do not need to be repeated.
When the same attribute name is used across different alternatives, then it is considered generic attribute and the attribute levels do not need to be repeated. A different attribute name must be used if the levels are different for a similar attribute across alternatives.
When defining the levels of a categorical attribute, it is important to note that the last level is considered the base level. Further, the number of priors for a dummy of effects coded categorical attribute should be equal to the number levels of the attribute minus one. For example, b1.dummy[0.2|0.5]*symptoms[1,2,0] means that level 0 is the base level, and the priors 0.2 and 0.5 are associated with levels 1 and 2, respectively.
When using the modified Fedorov algorithm for generating an efficient design, attribute level balance is not guaranteed. In that case it is often useful, especially for numerical attributes, to impose constraints on the number of times each attribute level should appear within the design. This can be achieved by adding (min-max, ...) after the definition of the attribute and its levels, where min (decimal) and max (decimal) are the minimum and maximum number of times each level should appear. For example, toll[2,4,6](3-5,3-5,3-5) means that each toll level should appear between 3 and 5 times. It is important to make sure that these minimum and maximum numbers are consistent with the total number of rows as defined in the rows property. In this example, the values for min and max are appropriate when rows=12 but would be infeasible if rows=20. Note that toll[2,4,6](4,4,4) can be used instead of toll[2,4,6](4-4,4-4,4-4). If no design can be found, one may want to relax the minimum and maximum bounds. The widest bounds are set by using 0-inf where inf equals the total number of rows.
In case one would need to define a large number of equidistance attribute levels, one can use the following shortcut: attribute[lo:hi:step], where lo is the lowest level, hi is the highest level, and step is the step size between the lowest and highest level. For example, price[1:2:0.2] is the same as price[1,1.2,1.4,1.6,1.8,2].
Pivot levels of attributes can be absolute or relative differences from the reference level. For example, price.piv[-2,0,2] reflects absolute differences with the reference level, while price.piv[-25%,0%,25%] reflects relative differences.
When using fcn(<expression>) to define attribute levels, <expression> can only be a simple linear relationship containing numbers, references to other attributes, and plus (+) or minus (-). For example, trip.probLate[fcn(1-trip.probEarly-trip.ProbLate)].
|
|
|
Comments
· This is a mandatory property to define. · If a prior is omitted, it is set to zero. · If specified, the number of priors for a dummy of effects coded categorical attribute should be equal to the number levels of the attribute minus one. · If an alternative was specified in the alts property but no utility function is defined in the model property, then the utility of this alternative is set to zero. This may be useful for defining an optout alternative.
|
|
|
Examples
model: U(hotel1, hotel2) = b1.effects[0.2|0.5] * stars[3,5,1] + b2[-0.04] * price[80:200:20] + b3[-0.0001] * dist[500,2000,5000] / U(neither) = b0[-2.6]
model: U(policya, policyb) = pol[-]*pollution[20,40,60] + temp[-]*temprise[0,1,2] + cost[-]*annualtax[100,200,300] / U(statusquo) = pol *pollution_sq[80] + temp *temprise_sq[3] + cost *annualtax_sq[0]
model: U(car) = asc_car + t_car * cartime[10,15,20] + cost * carcost[2,3,4] + w.dummy[0] * weather[0,1] / U(train) = asc_train + e * egress[2,4,6,8] + t_train * traintime[20,30,40] + cost * fare[1,2,3] / U(bike) = t_bike * biketime[40,60] + w * weather[weather]
model: U(car) = eng.dummy * engine[0,1,2,3] + col.dummy * colour[0,1,2,3] + type.dummy * type[0,1,2,3] / U(no_car) = con_n
model: U(laptopa, laptopb) = proc.dummy[+] * processor[3,5,7,9] + stor[+] * storage[256,512,1024,2048] + cost[-] * price[1200,1500,1800]
model: U(laptop1) = b1*pr[1000,1500] + b2*scr[13,15,17] + b3.dummy[0|0]*brand[1,2,0] + i1*pr*brand.level[1] + i2*price*brand.level[2] / U(laptop2) = b1*pr + b2*scr + b3*brand + i1*pr*brand.level[1] + i2*price*brand.level[2]
model: U(chemo) = b1[(n,0.9,0.2)] * cure_chance[0.3,0.5,0.7,0.9] + b2.dummy[(u,-0.3,0)|u(-0.8,-0.5)] * side_effects[1,2,0] / U(immuno) = b1 * cure_chance + b3.dummy[(u,-0.4,-0.2)|u(-0.9,-0.7)] * side_effects / U(neither) = b0[(n,0.3,0.1)] + b1 * cure_chance_optout[0]
model(short): U(current) = time[-0.00001] * TIME.ref[20] + cost[-0.00001] * COST.ref[3] / U(routeA, routeB) = time * TIME.piv[-50%,-25%,0%,25%,50%] + cost * COST.piv[-2,-1,0,1,2] model(long): U(current) = time[-0.00001] * TIME.ref[40] + cost[-0.00001] * COST.ref[5] / U(routeA) = time * TIME.piv[-50%,-25%,0%,25%,50%] + cost * COST.piv[-2,-1,0,1,2] / U(routeB) = time * TIME.piv[-50%,-25%,0%,25%,50%] + cost * COST.piv[-2,-1,0,1,2]
|
|
|
Property that indicates the generation of an orthogonal fractional factorial design and defines the type of orthogonal design.
|
|
|
Format
orth = <type>
|
|
|
Explanation
<type> can be |
|
|
sim |
to generate a simultaneously orthogonal design |
|
seq |
to generate a random sequential orthogonal design |
|
seq2 |
to generate a random sequential orthogonal design in the presence of some alternative-specific attributes |
|
ood |
to generate an optimal sequential orthogonal design |
|
|
|
|
A simultaneously orthogonal design exhibits orthogonality across all attributes, both within an alternative as well as across alternatives. In contrast, a sequential orthogonal design exhibits orthogonality only across attributes within each alternative but not necessarily across alternatives, which is sufficient for unlabelled alternatives. An optimal sequential orthogonal design has minimum attribute level overlap across alternatives.
|
|
|
Comments
· If no type is specified, then the type defaults to sim. · If an orthogonal design with a specific number of rows (specified with the rows property) does not exist, then Ngene will increase the number of rows and try to find an orthogonal design with the smallest design size. It should be noted that an orthogonal design may not exist. · Property orth=sim can be used in conjunction with the eff property, in which case Ngene will evaluate all possible orthogonal designs and select the most efficient.
|
|
|
Examples
orth orth = sim orth = seq orth = seq2 orth = ood
|
|
|
Property that defines the precision of all numbers reported in Ngene. |
|
|
|
Format
prec = number
|
|
Explanation
number (integer) is the number of digits used in reporting results. Note that maximum precision is used for all calculations in Ngene.
|
|
Comments
· If no precision is specified, then the default is set to prec=6.
|
|
Examples
prec = 8
|
|
Property that indicates the generation of a random fractional factorial design.
|
|
Format
rand
|
|
Explanation
Generates a design with a random set of choice tasks. When generic alternatives are specified, it will omit choice tasks with identical profiles, and also omit choice tasks with a strictly dominant alternative if priors are specified.
|
|
Comments
· Check constraints can be added using the reject and require properties.
|
|
Examples
rand
|
|
Property that defines the type and number of draws for random parameters.
|
|
|
Format
rdraws = <drawtype>(number)
|
|
|
Explanation
<drawtype> can be |
|
|
gauss |
to use Gaussian quadrature, |
|
halton |
to use Halton draws, |
|
mlhs |
to use modified latin hypercube sampling, |
|
random |
to use pseudo-random draws, |
|
sobol |
to use Sobol draws. |
|
|
|
|
number (integer) is the total number of draws from the random distributions, except for gauss.
number (integer) for gauss refers to the number of abscissas (coordinates) for each individual parameter, and the total number of draws depends on the number of random parameters. For example, using gauss(3) in the presence of four random parameters means that the total number of draws is 3*3*3*3 = 81. It is possible to use a different number of abscissas for each parameter, for example gauss(3,4,2,5) uses three abscissas for the first random parameter, four for the second, two for the third, and five for the fourth, such that the total number of draws equals 3*4*2*5 = 120.
|
|
|
Comments
· If random parameters are specified but the rdraws is not defined, then by default halton(200) is used. · The more random parameters are specified, the larger the number of draws needs to be. · The total number of draws cannot exceed 10,000. · Take care when using gauss; if the number of random parameters is large, the total number of draws can become very large. · When the number of random parameters is large, sobol and mlhs should be preferred over halton.
|
|
|
Examples
rdraws = sobol(500) rdraws = mlhs(1000) rdraws = gauss(5) rdraws = gauss(4,5,3,1,4)
|
|
|
Property that defines check constraints to reject certain attribute level combinations when generating an efficient design using the modified Fedorov algorithm or when generating a full factorial or random fractional factorial design.
|
|
|
Format
reject: <logical expression>, ...
where <logical expression> can be |
|
|
<comparison> |
to specify a single comparison, |
|
<comparison> AND <comparison> ... |
to specify a compounded comparison using the AND operator, |
|
<comparison> OR <comparison> ... |
to specify a compounded comparison using the OR operator. |
|
|
|
|
where <comparison> can be |
|
|
<value> = <value> |
to specify an ‘equal to’ comparison, |
|
<value> > <value> |
to specify a ‘greater than’ comparison, |
|
<value> < <value> |
to specify a ‘smaller than’ comparison, |
|
<value> >= <value> |
to specify a ‘greater than’ or equal to comparison, |
|
<value> <= <value> |
to specify a ‘smaller than or equal to’ comparison, |
|
<value> <> <value> |
to specify an ‘unequal to’ comparison. |
|
|
|
|
<value> can be |
|
|
alternative.attribute |
to refer a specific attribute (string) belonging to a specific alternative (string), |
|
number |
to specify a specific number (decimal). |
|
|
|
|
Explanation
Each choice task in the experimental design is checked against each logical expression and if the outcome is TRUE then the choice task is discarded and replaced.
A <value> can also be determined based on limited arithmetic, where only addition (+) and subtraction (–) are supported. For example, route1.fuelcost + route1.tollcost < 5 is an allowable comparison.
|
|
|
Comments
· Reject constraints can only be defined when generating an efficient design using the modified Fedorov algorithm or when generating a full factorial or random fractional factorial design. · Adding too many, or too strict, reject constraints may result in attributes becoming perfectly correlated. In this case, the model cannot be estimated due to multicollinearity and the D-error of the design would become very large or undefined. · Property reject can be used in conjunction with property require. · Check constraints cannot be specified when generating designs using fisher.
|
|
|
Examples
reject: flight1.businessclass = 1 and flight.price = 500, flight1.businesclass = 0 and flight1.price = 1000 reject: hotelA.stars >= 4 and hotelA.price < 100, hotelB.stars >= 4 and hotelB.price < 100 reject: train.nr_transfers = 0 and train.transfertime > 0, train.nr_transfers > 0 and train.transfertime = 0 reject: laptop1.screensize > 15 and laptop1.harddisk > 512 and laptop1.price < 1500 reject: wineA.price – wineB.price < 10
|
|
|
Property that defines the size of the simulated sample to compute the efficiency of a design for a model type that accounts for panel effects. |
|
|
|
Format
rep = number
|
|
Explanation
number (integer) is a user-specified size of the simulated sample.
|
|
Comments
· If a design for a model type that accounts for panel effects is being generated or evaluated and this property is not defined, then by default rep=200 is used.
|
|
Examples
rep = 500
|
|
Property that defines check constraints to accept certain attribute level combinations when generating an efficient design using the modified Fedorov algorithm, or a full factorial or random fractional factorial design.
|
|
|
Format
reject: <logical expression>, ...
where <logical expression> can be |
|
|
<comparison> |
to specify a single comparison, |
|
<comparison> AND <comparison> ... |
to specify a compounded comparison using the AND operator, |
|
<comparison> OR <comparison> ... |
to specify a compounded comparison using the OR operator. |
|
|
|
|
where <comparison> can be |
|
|
<value> = <value> |
to specify an ‘equal to’ comparison, |
|
<value> > <value> |
to specify a ‘greater than’ comparison, |
|
<value> < <value> |
to specify a ‘smaller than’ comparison, |
|
<value> >= <value> |
to specify a ‘greater than’ or equal to comparison, |
|
<value> <= <value> |
to specify a ‘smaller than or equal to’ comparison, |
|
<value> <> <value> |
to specify an ‘unequal to’ comparison. |
|
|
|
|
<value> can be |
|
|
alternative.attribute |
to refer a specific attribute (string) belonging to a specific alternative (string), |
|
number |
to specify a specific number (decimal). |
|
|
|
|
Explanation
Each choice task in the experimental design is checked against each logical expression and if the outcome is TRUE then the choice task is accepted. Require constraints are often useful to set the attribute levels of a status quo alternative or to define scenario variables.
A <value> can also be determined based on limited arithmetic, where only addition (+) and subtraction (–) are supported. For example, route1.fuelcost + route1.tollcost < 5 is an allowable comparison.
|
|
|
Comments
· Require constraints can only be defined when generating an efficient design using the modified Fedorov algorithm, or when generating a full factorial or random fractional factorial design. · Adding too many, or too strict, require constraints may result in attributes becoming perfectly correlated. In this case, the model cannot be estimated due to multicollinearity and the D-error of the design would become very large or undefined. · Property require can be used in conjunction with property reject. · Check constraints cannot be specified when generating designs using fisher.
|
|
|
Examples
require: statusquo.traveltime = 30, statusquo.tollcost = 0 require: car.weather = bike.weather require: train.accesstime + train.invehicletime + train.waittime + train.egresstime < 60
|
|
|
Property that defines the design size, i.e., the number of choice tasks in the design. |
|
|
|
|
|
Format
rows = <designsize>
where <designsize> can be |
|
|
number |
to generate a design with a specified number of rows, |
|
all |
to generate a design with all possible combinations of attribute levels (full factorial). |
|
|
|
|
Explanation
number (integer) is a user-specified design size, which equals the number of rows in the design matrix. If property orth is used, then this number is used as a lower bound.
The use of rows = all is only available in combination with property fact.
|
|
|
Comments
· This is a mandatory property to define. · The maximum number of rows is 10,000.
|
|
|
Examples
rows = 60 rows = all
|
|
|
Property that sets the random seed for rdraws.
|
|
Format
rseed = number
|
|
Explanation
number (integer) sets the seed for the random generator when taking draws for random parameters using rdraws=random or rdraws=mlhs. Other types of draws than pseudo-random draws and latin hypercube sampling do not use a random generator and hence the random seed is redundant.
|
|
Comments
· If rseed is not specified, then the draws will be fully random each time the script is run.
|
|
Examples
rseed = 4 rseed = 12345
|
|
Property that defines a starting design when generating an efficient design. |
|
|
|
|
|
Format
start = design
|
|
|
Explanation
design (string) is the user-specified name of a design in the same experiment folder that the user would like to use as starting point in the search for an efficient design. |
|
|
|
|
|
Comments
· To only evaluate an existing design without continuing the search, please use property eval.
|
|
|
Examples
start = my_design |
|
|
|
|
|
Property that defines willingness-to-pay (WTP) expressions that can be used to generate efficient designs for estimating WTP. |
|
|
|
|
|
Format
wtp(model) = wtpname(<parameters> / costparameter), ...
where <parameters> can be |
|
|
parameter, ... |
to define WTP associated with one or more parameters, |
|
weight * parameter, ... |
to define weighted WTP associated with one or more parameters, |
|
* |
to define WTP associated with all non-cost parameters. |
|
|
|
|
Explanation
model (string) is the user-specified name of the model. The model name can be omitted if only a single model is specified. wtpname (string) is the user-specified name of the WTP definition. costparameter (string) is the user-specified name of the parameter for the monetary attribute in the utility function, which is used as the denominator for computing WTP, parameter (string) is the user-specified name of a parameter in the model that is used as the numerator for computing WTP. weight (decimal) is the user-specified weight attached to the WTP associated with that parameter.
|
|
|
Comments
· WTP definitions can be used in the eff property to optimise the design for C-error.
|
|
|
Examples
wtp = value_of_time(time / cost) wtp = wtp1(b1,b3,b3 / b1), wtp2(* / b1) wtp(model1) = wtp_all(* / bcost) wtp = weighted_wtp(0.4*b1, 0.6*b2 / b3)
|
|