This function implements the Multi-Stratum Two-Phase Local
Search (MS-TPLS) algorithm described in Borrotti, Sambo, Mylona and Gilmour
(2016). This algorithm is useful to obtain exact optimal multi-stratum
designs through a multi-criteria approach. When using runTPLS the user must
establish the search problem (structure of the experiment, number of trials,
optimization criteria, etc.) and the total number of iterations of MS-TPLS.
The resulting experimental designs can minimize up to six criteria simultaneously
from the following: "I", "Id", "D", "Ds", "A" and "As". runTPLS is able
to provide the set of solutions building the approximate Pareto front for
the specified optimization problem.
runTPLS(facts, units, criteria, model, iters, ...)runTPLS returns a list, whose elements are:
ar: A list of length equal to iters. The \(i\)-th element
is a list whose elements are:
nsols: Number of designs produced during the \(i\)-th iteration.
dim: The criteria space dimension.
scores: A matrix of nsols rows and dim columns.
Every row contains the value of the criteria for each solution of the
\(i\)-th iteration.
solutions: A list of length equal to nsols containing the
design matrices produced during the \(i\)-th iteration. The values of the
criteria corresponding at the first element of solutions are placed
in the first row of the scores matrix and so on.
stats: A list of length equal to iters. Every element is a
vector of size \(r - (n * restInit) + 1\), where \(n\) is the number of the
considered criteria. The first element represents the number of function
evaluations during the first step of the MS-TPLS algorithm; the \(i\)-th
element (excluding the first one) is the sum of the number of evaluations for
the \(i\)-th scalarization and the maximum value in the stats.
megaAR: A list whose elements are:
nsols: The number of the Pareto front solutions.
dim: The criteria space dimension.
scores: A matrix of nsols rows and dim columns.
Every row contains the criteria values for each Pareto front design.
solutions: A list of length equal to nsols containing
the design matrices for the Pareto front designs. The values of the criteria
corresponding at the first element of solutions are placed in the
first row of the scores matrix and so on.
A list of vectors representing the distribution of factors across strata. Each item in the list represents a stratum and the first item is the highest stratum of the multi-stratum structure of the experiment. Within the vectors, experimental factors are indicated by progressive integer from 1 (the first factor of the highest stratum) to the total number of experimental factors (the last factor of the lowest stratum). Blocking factors are differently denoted by empty vectors.
A list whose \(i\)-th element, \(n_i\), is the number of experimental units within each unit at the previous stratum (\(i-1\)). The first item in the list, \(n_1\), represents the number of experimental units in the stratum \(0\). The latter is defined as the entire experiment, such that \(n_0 = 1\).
A list specifying the criteria to be optimized. It can contain any combination of:
``I" : I-optimality
``Id" : Id-optimality
``D" : D-optimality
``A" : Ds-optimality
``Ds" : A-optimality
``As" : As-optimality
More detailed information on the available criteria is given in
MSOpt.
A string which indicates the type of model, among ``main", ``interaction" and ``quadratic".
An integer indicating the number of iterations of the MS-TPLS algorithm.
optional arguments (see below).
Additional arguments can be specified as follows:
'Restarts', restarts: A string and an integer, used in pair. r
defines the number of times the MS-Opt procedure is altogether called within
each iteration of the MS-TPLS algorithm. The default value is r=100.
'Levels', levels: A string and a vector, used in pair. levels
is a vector containing the number of available levels for each experimental
factor in the argument facts (blocking factors are excluded). If all
experimental factors share the number of levels one integer is sufficient.
'Etas', etas: A string and a list, used in pair. In etas
the user must specify the ratios of error variance between subsequent strata,
starting from the highest strata. It follows that length(etas) must be
equal to length(facts)-1.
'RestInit', restInit: A string and an integer, used in pair. Through
these parameters, it is possible to determine how many of the r iterations
of MS-Opt should be used for each criterion in the first step of the MS-TPLS
algorithm (lines 3-6 of the pseudo-code of MS-TPLS, see Borrotti, Sambo, Mylona
and Gilmour (2017)). The default value is restInit=50. Let \(n\) be
the number of criteria under consideration. One can calculate accordingly as
\(r - (n * restInit)\) the number of times MS-Opt is called in the
second step (lines 7-11 of the pseudo-code of MS-TPLS) of each iteration of MS-TPLS.
'RngSeed', rngSeed: A number indicating the seed for reproducibility.
Default is to leave the random number generator alone.
M. Borrotti and F. Sambo and K. Mylona and S. Gilmour. A multi-objective coordinate-exchange two-phase local search algorithm for multi-stratum experiments. Statistics & Computing, 2017.