addruns

Add runs to D-optimal design

Since R2024b

Syntax

doptAdd = addruns(dopt,nruns)

doptAdd = addruns(dopt,nruns,Name=Value)

Description

doptAdd = addruns(dopt,nruns) adds nruns design points, also called runs, to the optimalDOE design object dopt and returns the result in a new design object doptAdd.

doptAdd = addruns(dopt,nruns,Name=Value) specifies additional options using one or more name-value arguments. For example, you can specify the experiment model for the design points and the maximum number of iterations for the algorithm that generates the design points.

Examples

Add Design Points

Generate a D-optimal design that has four factors and 10 points.

dopt = optimalDOE(4,10)

dopt = 
  optimalDOE with properties:

                Design: [10×4 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3 + Factor4"
       OptimalityValue: 8.6016e+04
                Levels: {[-1 1]  [-1 1]  [-1 1]  [-1 1]}
    CategoricalFactors: []
          FixedFactors: []
        ExchangeMethod: "coordinate"

dopt is an optimalDOE object that contains information about the generated D-optimal design. The output shows that the design contains 10 points.

Generate a second D-optimal design by adding 5 more design points to dopt.

doptAdd = addruns(dopt,5)

doptAdd = 
  optimalDOE with properties:

                Design: [15×4 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3 + Factor4"
       OptimalityValue: 7.2090e+05
                Levels: {[-1 1]  [-1 1]  [-1 1]  [-1 1]}
    CategoricalFactors: []
          FixedFactors: []
        ExchangeMethod: "coordinate"

The output for doptAdd shows that the model, factor levels, and algorithm for generating the design points are the same as those for dopt. However, doptAdd has 15 design points and a different optimal value.

Add Design Points for Different Model

Generate a D-optimal design that has four factors, one of them fixed, and six points.

dopt = optimalDOE(3,6,FixedFactors=[ones(3,1);zeros(3,1)])

dopt = 
  optimalDOE with properties:

                Design: [6×4 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3 + Factor4"
       OptimalityValue: 1.2800e+03
                Levels: {[-1 1]  [-1 1]  [-1 1]  [0 1]}
    CategoricalFactors: []
          FixedFactors: 4
        ExchangeMethod: "coordinate"

dopt is an optimalDOE object that contains information about the generated D-optimal design. The output shows that the design contains 6 points, the experiment model is linear, and the fourth factor is fixed.

Generate a second D-optimal design by adding six more design points to dopt. Use an interactions experiment model to generate the additional points.

doptAdd = addruns(dopt,6,ModelSpecification="interactions",FixedFactors=[ones(3,1);zeros(3,1)])

doptAdd = 
  optimalDOE with properties:

                Design: [12×4 table]
    ModelSpecification: "1 + Factor1*Factor2 + Factor1*Factor3 + Factor1*Factor4 + Factor2*Factor3 + Factor2*Factor4 + Factor3*Factor4"
       OptimalityValue: 5.3687e+08
                Levels: {[-1 1]  [-1 1]  [-1 1]  [0 1]}
    CategoricalFactors: []
          FixedFactors: 4
        ExchangeMethod: "coordinate"

The output shows that doptAdd has 12 design points. Also, the optimal value and experiment model are different from those for dopt.

Input Arguments

dopt — D-optimal design

optimalDOE object

D-optimal design, specified as an optimalDOE object. You can create an optimalDOE object using the function of the same name.

nruns — Number of design points to add

positive integer

Number of design points to add to dopt, specified as a positive integer.

Example: 100

Data Types: single | double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: addruns(dopt,6,ModelSpecification="interactions",IterationLimit=20) specifies an interactions experiment model and a maximum of 20 iterations for the iterative algorithm.

FixedFactors — Fixed factor values

numeric matrix | table

Fixed factor values, specified as a numeric matrix or a table.

Fixed factors are held constant while the function varies other factors, which can be useful when you create a blocked design. A blocked design orders design points by the values of a factor.

addruns uses all factors, including fixed factors, to calculate design points. The last columns of the design contain the values specified in FixedFactors. FixedFactors must have nruns rows.

Example: FixedFactors=[zeros(100,1);ones(100,1)]

Data Types: single | double | table

IterationLimit — Maximum number of iterations

10 (default) | positive integer

Maximum number of iterations for the algorithm that generates the design points, specified as a positive integer. To specify the algorithm, use the ExchangeMethod name-value argument of optimalDOE when you create dopt.

Example: IterationLimit=20

Data Types: single | double

ModelSpecification — Experiment model

string scalar | character vector | terms matrix

Experiment model for the additional design points, specified as one of the following values.

• A character vector or string scalar with the model name.

  Value	Model Description
  "linear"	The model contains an intercept and linear term for each factor.
  "constant"	The model contains only a constant (intercept) term.
  "interactions"	The model contains an intercept, a linear term for each factor, and all products of pairs of distinct factors (no squared terms).
  "purequadratic"	The model contains an intercept term, and linear and squared terms for each factor.
  "quadratic"	The model contains an intercept term, linear and squared terms for each factor, and all products of pairs of distinct factors.
  "scheffe-linear"	The model contains a linear term for each factor and does not include an intercept term.
  "scheffe-quad"	The model is given by the formula: $${\displaystyle \sum _{i=1}^n{b}_i{x}_i}+{\displaystyle \sum _{i=1}^n{\displaystyle \sum _{j<i}^{n-1}{b}_{ij}{x}_i{x}_j}}$$
  "scheffe-special-cubic"	The model is given by the formula: $${\displaystyle \sum _{i=1}^n{b}_i{x}_i}+{\displaystyle \sum _{i=1}^n{\displaystyle \sum _{j<i}^{n-1}{b}_{ij}{x}_i{x}_j}}+{\displaystyle \sum _{i=1}^n{\displaystyle \sum _{j<i}^{n-1}{\displaystyle \sum _{k<j}^{n-2}{b}_{ijk}{x}_i{x}_j{x}_k}}}$$
  "polyijk"	The model is a polynomial with all terms up to degree i in the first factor, degree j in the second factor, and so on. Specify the maximum degree for each factor by using numerals 0 though 9. The model contains interaction terms, but the degree of each interaction term does not exceed the maximum value of the specified degrees. For example, "poly13" has an intercept and x1, x2, x22, x23, x1*x2, and x1*x22 terms, where x1 and x2 are the first and second factors, respectively.

  In the above table, each x_i corresponds to the ith factor in the D-optimal design, and b_i, b_ij, b_ijk, and d_ij are coefficients for the model terms.

• A character vector or string scalar formula in Wilkinson Notation. The factor names in the formula must be factor names specified by the FactorNames name-value argument when you create dopt.

• A t-by-n terms matrix, where t is the number of terms and n is the number of factors in the design. A terms matrix is convenient when the number of factors is large and you want to generate the terms programmatically. For more information about terms matrices, see Terms Matrix

ModelSpecification does not include the response variable. addruns generates a design that minimizes the covariance between the estimated coefficients for ModelSpecification.

Example: ModelSpecification="Factor1+Factor2*Factor3"

Data Types: single | double | char | string

NumTries — Maximum number of start points

1 (default) | positive integer

Maximum number of start points for generating the additional design points, specified as a positive integer. If NumTries > 1, then addruns generates NumTries designs from different starting points. The function returns the design with the least amount of covariance between the coefficient estimates for the experiment model.

Example: NumTries=5

Data Types: single | double

Options — Options for controlling iterative algorithm

[] (default) | structure array

Options for controlling the iterative algorithm to minimize the fitting criteria, specified as a structure array returned by statset. Supported fields of the structure array specify options for controlling the iterative algorithm.

This table summarizes the supported fields, which require Parallel Computing Toolbox™.

Field	Description
Streams	A RandStream object or cell array of such objects. If you do not specify Streams, addruns uses the default stream or streams. If you specify Streams, use a single object except when all of the following apply: You have an open parallel pool. UseParallel is true. UseSubstreams is false. In this case, use a cell array the same size as the parallel pool. If a parallel pool is not open, then Streams must supply a single random number stream.
UseParallel	If true and NumTries > 1, then addruns generates the design points in parallel. If Parallel Computing Toolbox is not installed, then computation occurs in serial mode. The default is false, indicating serial computation.
UseSubstreams	Set to true to compute in a reproducible fashion. The default is false. To compute reproducibly, set Streams to a type allowing substreams: "mlfg6331_64" or "mrg32k3a".

To ensure more predictable results, use parpool (Parallel Computing Toolbox) and explicitly create a parallel pool before calling addruns with Options=statset(UseParallel=1).

Example: Options=statset(UseParallel=1)

Data Types: struct

Output Arguments

doptAdd — D-optimal design

optimalDOE object

D-optimal design, returned as an optimalDOE object. The design for doptAdd includes the design points for dopt plus the design points you specify using addruns.

More About

Terms Matrix

A terms matrix T is a t-by-n matrix specifying the terms in a model, where t is the number of terms, and n is the number of factors in the design. The value of T(i,j) is the exponent of variable j in term i.

For example, suppose that a design includes three factors x1, x2, and x3. Each row of T represents one term:

• [0 0 0] — Constant term or intercept

• [0 1 0] — x2; equivalently, x1^0 * x2^1 * x3^0

• [1 0 1] — x1*x3

• [2 0 0] — x1^2

• [0 1 2] — x2*(x3^2)

Wilkinson Notation

Wilkinson notation describes the terms in a model. The notation relates to the terms included in the model, not to the multipliers (coefficients) of those terms.

Wilkinson notation uses these symbols:

• + means include the next variable.

• – means do not include the next variable.

• : defines an interaction, which is a product of the terms.

• * defines an interaction and all lower order terms.

• ^ raises the predictor to a power, exactly as in * repeated, so ^ includes lower order terms as well.

• () groups the terms.

This table shows typical examples of Wilkinson notation.

Wilkinson Notation	Terms in Standard Notation
1	Constant (intercept) term
x1^k, where k is a positive integer	x1, x12, ..., x1k
x1 + x2	x1, x2
x1*x2	x1, x2, x1*x2
x1:x2	x1*x2 only
–x2	Do not include x2
x1*x2 + x3	x1, x2, x3, x1*x2
x1 + x2 + x3 + x1:x2	x1, x2, x3, x1*x2
x1*x2*x3 – x1:x2:x3	x1, x2, x3, x1*x2, x1*x3, x2*x3
x1*(x2 + x3)	x1, x2, x3, x1*x2, x1*x3

For more details, see Wilkinson Notation.

Version History

Introduced in R2024b