SYNTAX REFERENCE GUIDE

Overview

algSpecifies what algorithm to use when generating efficient designs.
altsDefines the alternatives in the choice set.
bdrawsDefines the type and number of draws for Bayesian priors.
blockDefines the number of blocks in the design.
bseedSets the random seed for drawing Bayesian priors.
conSpecifies whether the design efficiency should also be optimised for estimating alternative-specific constants.
condDefines conditional constraints on attribute levels when generating an efficient design using the swapping algorithm.
effIndicates the generation of an efficient fractional factorial design and defines the optimisation criterion when generating an efficient design.
evalEvaluates the efficiency of an existing experimental design.
factIndicates the generation of a full factorial design.
fisherDefines the Fisher information matrix when combining information from multiple models or population segments.
foldoverSpecifies whether a fold-over design will be generated.
modelDefines the utility functions of the choice model.
orthIndicates the generation of an orthogonal fractional factorial design and defines the type of orthogonal design.
precDefines the precision of all numbers reported in Ngene.
randIndicates the generation of a random fractional factorial design.
rdrawsDefines the type and number of draws for random parameters.
rejectDefines check constraints to reject certain attribute level combinations when generating a design.
repDefines the size of the simulated sample to compute the efficiency of a design for a model type that accounts for panel effects.
requireDefines check constraints to accept certain attribute level combinations when generating a design.
rowsDefines the design size, i.e., the number of choice tasks in the design.
rseedSets the random seed for drawing random parameters.
startDefines a starting design when generating an efficient design.
wtpDefines 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 other characters. A string should also not be identical to the name of a property.

ALG

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 (r), 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 elapse 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, swapnoimprov=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(600 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, and 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, swapnoimprov=40, reset=5000, resetinc=1000)
alg = mfedorov(candidates=2000)
alg = mfedorov(candidates=my_experiment)
alg = mfedorov(candidates=500, stop=total(15 mins))
alg = swap(stop=total(200 secs))
alg = mfedorov(stop=noimprov(1000 iterations))

ALTS

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)

BDRAWS

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 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)

BLOCK

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 is minimised,

minmax

to determine blocks such that the maximum correlation between the blocking column and the attributes is minimised,

total(number secs)

to indicate the number (integer) of seconds to search for the best blocking column,

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

BSEED

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: bdraws=random or bdraws=mlhs. Draw types other than pseudo-random and Latin hypercube 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

CON

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

COND

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 compound comparison using the AND operator,

<comparison> or <comparison> ...

to specify a compound 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 to 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 factorial or 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 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.
  • Compound comparisons are evaluated strictly from left to right; and does not take precedence over or.

Examples#

cond: if(flight1.businessclass = 1, flight1.price = [2000,2500]), if(flight1.businessclass = 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)

EFF

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 efficiency measure using local priors or the means of the Bayesian priors,

mean

to compute the Bayesian efficiency measure based on the average over all draws of the Bayesian distribution,

median

to compute the Bayesian efficiency measure 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 efficiency measure 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)

EVAL

Property that evaluates the efficiency of an existing experimental design.

Format#

eval = design

Explanation#

design (string) is the user-specified name of a 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

FACT

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

FISHER

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 parentheses. 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 the parentheses. 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])

FOLDOVER

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

MODEL

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 a 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 or effects coded categorical attribute should be equal to the number of 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 (integer) and max (integer) 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 is typed as written and equals the total number of rows.

In case one would need to define a large number of equidistant 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.probOnTime)].

Comments#

  • This is a mandatory property to define.
  • If a prior is omitted, it is set to zero.
  • 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 opt-out 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*pr*brand.level[2] /
U(laptop2) = b1*pr + b2*scr + b3*brand + i1*pr*brand.level[1] + i2*pr*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]

ORTH

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

PREC

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

RAND

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

RDRAWS

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 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)

REJECT

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 compound comparison using the AND operator,

<comparison> or <comparison> ...

to specify a compound 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 to 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, when generating an efficient design, 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.
  • Compound comparisons are evaluated strictly from left to right; and does not take precedence over or.

Examples#

reject: flight1.businessclass = 1 and flight1.price = 500, flight1.businessclass = 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

REP

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

REQUIRE

Property that defines check constraints to accept 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#

require: <logical expression>, ...

where <logical expression> can be

<comparison>

to specify a single comparison,

<comparison> and <comparison> ...

to specify a compound comparison using the AND operator,

<comparison> or <comparison> ...

to specify a compound 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 to 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.
  • Compound comparisons are evaluated strictly from left to right; and does not take precedence over or.

Examples#

require: statusquo.traveltime = 30, statusquo.tollcost = 0
require: car.weather = bike.weather
require: train.accesstime + train.invehicletime + train.waittime + train.egresstime < 60

ROWS

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, unless property fact is used.
  • The maximum number of rows is 10,000.

Examples#

rows = 60
rows = all

RSEED

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: rdraws=random or rdraws=mlhs. Draw types other than pseudo-random and Latin hypercube 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

START

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

WTP

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(b2,b3 / b1), wtp2(* / b1)
wtp(model1) = wtp_all(* / bcost)
wtp = weighted_wtp(0.4*b1, 0.6*b2 / b3)