daugment

D-optimal augmentation

Syntax

dCE2 = daugment(dCE,mruns)

dCE2 = daugment(dCE,mruns,model)

dCE2 = daugment(___,Name=Value)

[dCE2,X] = daugment(___)

Description

dCE2 = daugment(dCE,mruns) D-optimally adds mruns runs to the D-optimal design dCE using a coordinate-exchange algorithm with a linear additive model. The model includes a constant term.

dCE2 = daugment(dCE,mruns,model) returns an augmented D-optimal design with the terms specified in model.

dCE2 = daugment(___,Name=Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in the previous syntaxes. For example, you can specify the indices of categorical variables, and whether to perform computations in parallel.

[dCE2,X] = daugment(___) additionally returns the design matrix X, whose columns are the model terms evaluated at each row of dCE2.

Examples

Augment D-Optimal Design

Create a six-run D-optimal design to estimate the main effects in a two-factor model.

dCE = cordexch(2,6)

dCE = 6×2

    -1    -1
     1    -1
    -1     1
     1     1
     1    -1
    -1    -1

Add three runs to the design.

dCE2 = daugment(dCE,3)

dCE2 = 9×2

    -1    -1
     1    -1
    -1     1
     1     1
     1    -1
    -1    -1
    -1     1
     1     1
    -1    -1

Augment D-Optimal Design Using Interaction Model

Create an eight-run D-optimal design to estimate the main effects in a four-factor model.

dCEmain = cordexch(4,8)

dCEmain = 8×4

     1    -1    -1     1
     1    -1    -1    -1
    -1    -1     1     1
     1     1     1    -1
    -1     1    -1     1
    -1     1    -1    -1
     1     1     1     1
    -1    -1     1    -1

To create a design that is suitable for estimating the six interaction terms in the model, augment the design with eight additional runs.

dCEinteraction = daugment(dCEmain,8,"interaction")

dCEinteraction = 16×4

     1    -1    -1     1
     1    -1    -1    -1
    -1    -1     1     1
     1     1     1    -1
    -1     1    -1     1
    -1     1    -1    -1
     1     1     1     1
    -1    -1     1    -1
    -1     1     1    -1
     1     1    -1    -1
     1    -1     1    -1
     1     1    -1     1
    -1     1     1     1
    -1    -1    -1     1
    -1    -1    -1    -1
      ⋮

Augment D-Optimal Design Using Initial Design

Create a six-run D-optimal design for a two-factor quadratic model where each factor has three levels.

dCE = cordexch(2,6,"quadratic",NumLevels=3)

dCE = 6×2

    -1    -1
    -1     0
     0     1
     1     1
     1    -1
    -1     1

Augment the design with three additional runs. Specify the initial design for the additional runs, and return the design matrix of the augmented design.

[dCE2,X] = daugment(dCE,3,InitialDesign=[-1 0; 0 1; -1 1])

dCE2 = 9×2

    -1    -1
    -1     0
     0     1
     1     1
     1    -1
    -1     1
     1    -1
    -1    -1
     1     1

X = 9×3

     1    -1    -1
     1    -1     0
     1     0     1
     1     1     1
     1     1    -1
     1    -1     1
     1     1    -1
     1    -1    -1
     1     1     1

Input Arguments

dCE — D-optimal design

numeric matrix

D-optimal design, specified as a numeric matrix with nruns rows and nfactors columns. Each row (run) of dCE contains the settings for each of the nfactors factors in the design. You can create a D-optimal design using cordexch, candexch, rowexch, or dcovary.

Data Types: single | double

mruns — Number of additional runs

nonnegative integer scalar

Number of additional runs, specified as a nonnegative integer scalar. daugment uses the coordinate-exchange algorithm to D-optimally add mruns runs to the input D-optimal design dCE.

Example: 5

Data Types: single | double

model — Model terms

"linear" or "additive" (default) | "interaction" | "quadratic" | "purequadratic" | numeric matrix

Model terms, specified as a value in the following table or as a numeric matrix.

Value	Model Contents
"linear" or "additive" (default)	Constant and linear terms
"interaction"	Constant, linear, and interaction terms
"quadratic"	Constant, linear, interaction, and squared terms
"purequadratic"	Constant, linear, and squared terms

If you specify model as a numeric matrix, it must contain one column for each factor and one row for each polynomial term in the model. The entries in each row are exponents for the factors in the columns. For example, if a model has factors X1, X2, and X3, then row [0 1 2] in model specifies the term X10X21X32. A row of all zeros in model specifies a constant term.

Example: "interaction"

Example: [0 1 2; 1 2 1]

Data Types: single | double | char | string

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: daugment(dCE,8,Display=false) adds eight rows to the D-optimal design dCE and does not display the iteration counter window.

AvoidDuplicates — Flag to avoid duplicates in the additional rows

false or 0 (default) | true or 1

Flag to avoid duplicates in the additional rows (runs), specified as a numeric or logical 1 (true) or 0 (false). If you set AvoidDuplicates=true, the additional rows are unique. However, some of the additional rows might be duplicates of rows in dCE. When AvoidDuplicates is false (the default), daugment does not avoid calculating duplicate rows.

Example: AvoidDuplicates=true

Data Types: logical

Bounds — Lower and upper bounds for each factor

2-by-nfactors numeric matrix | cell array of nfactors elements

Lower and upper bounds for each factor, specified as a 2-by-nfactors numeric matrix or a cell array of nfactors elements, where nfactors is the number of factors in dCE. For a matrix, the first row contains the lower bounds, and the second row contains the upper bounds. For a cell array, each element contains a vector of allowable values for the corresponding factor. If Bounds is a cell array, daugment ignores the value of NumLevels.

Example: Bounds=[0 0; 2 1]

Example: Bounds={[0 1 2],[0 1]}

Data Types: single | double | cell

CategoricalVariables — Indices of categorical factors

numeric vector of positive integers

Indices of categorical factors, specified as a numeric vector of positive integers. By default, daugment sets two levels (1 and 2) for categorical factors.

Example: CategoricalVariables=[1 3]

Data Types: single | double

Display — Flag to display iteration counter window

"on" (default) | "off"

Flag to display the iteration counter window, specified as "on" or "off". The window displays the trial number (see NumTries) and the iteration number during computation.

Example: Display="off"

Data Types: char | string

ExcludeFcn — Function to exclude unwanted runs

function handle

Function to exclude unwanted runs, specified as a function handle. If the function is f, it must support the syntax b = f(S), where S is a k-by-nfactors matrix, and nfactors is the number of factors in dCE. b is a vector of k Boolean values, where b(i) is true if the ith row of S is excluded.

Example: ExcludeFcn=@excludefun

Data Types: function_handle

InitialDesign — Initial design

mruns-by-nfactors numeric matrix

Initial design, specified as an mruns-by-nfactors numeric matrix, where nfactors is the number of factors in dCE. The default is a randomly selected set of points.

Example: InitialDesign=[-1 0 1; 0 1 1; 0 -1 1]

Data Types: single | double

NumLevels — Number of levels for each factor in the additional rows

integer scalar greater than 1 | 1-by-nfactors numeric vector of integers greater than 1

Number of levels for each factor in the additional rows (runs), specified as an integer scalar greater than 1, or a 1-by-nfactors numeric vector of integers greater than 1, where nfactors is the number of factors in dCE. daugment ignores the value of NumLevels when you specify Bounds as a cell array. The default value of NumLevels depends on the value of model.

Value of model	Default Value of NumLevels
"linear" or "additive" (default)	2
"interaction"	2
"quadratic"	3
"purequadratic"	3

If you specify model as a numeric matrix, then the default number of levels for each factor is 1 + the maximum exponent in model for that factor. Any factor whose index you specify in CategoricalVariables has two levels (1 and 2) by default.

Note

If you specify AvoidDuplicates=true, the software adds more levels for any noncategorical factors, as needed, to avoid duplicate rows in the design.

Example: NumLevels=[2 3]

Data Types: single | double

MaxIterations — Maximum number of iterations

10 (default) | positive integer scalar

Maximum number of iterations per trial in the coordinate-exchange algorithm, specified as a positive integer scalar. daugment uses an iterative search algorithm that incrementally changes the initial design matrix X to increase D = |X^TX| at each iteration.

Example: MaxIterations=20

Data Types: single | double

Options — Options for computing in parallel and setting random streams

structure

Options for computing in parallel and setting random streams, specified as a structure. Create the Options structure using statset. This table lists the option fields and their values.

Field Name	Value	Default
UseParallel	Set this value to true to run computations in parallel.	false
UseSubstreams	Set this value to true to run computations in a reproducible manner. To compute reproducibly, set Streams to a type that allows substreams: "mlfg6331_64" or "mrg32k3a".	false
Streams	Specify this value as a RandStream object or cell array of such objects. Use a single object except when the UseParallel value is true and the UseSubstreams value is false. In that case, use a cell array that has the same size as the parallel pool.	If you do not specify Streams, then daugment uses the default stream or streams.

Note

You need Parallel Computing Toolbox™ to run computations in parallel.

Example: Options=statset(UseParallel=true,UseSubstreams=true,Streams=RandStream("mlfg6331_64"))

Data Types: struct

NumTries — Number of trials

1 (default) | positive integer scalar

Number of trials for generating additional rows (runs) starting from a new initial design matrix, specified as a positive integer scalar. If NumTries > 1 and you specify InitialDesign, then daugment uses InitialDesign for the first trial, and a randomly selected set of points in subsequent trials.

Tip

If NumTries=1, daugment might generate a locally D-optimal design. Specify a larger value of NumTries to return a globally D-optimal design.

Example: NumTries=3

Data Types: single | double

Output Arguments

dCE2 — Augmented D-optimal design

p-by-nfactors numeric matrix

Augmented D-optimal design, returned as a p-by-nfactors numeric matrix, where p is the number of runs in dCE + mruns, and nfactors is the number of factors in dCE.

X — Design matrix

numeric matrix

Design matrix, returned as a numeric matrix with the same number of rows as dCE2. The number of columns in X depends on the value of model.

If you specify model as "quadratic" or a numeric matrix that includes constant, linear, interaction, and squared terms, the columns of X (in order) are:

1. Constant term

2. Linear terms in the order 1, 2, ..., nfactors, where nfactors is the number of factors in dCE

3. Interaction terms in the order (1, 2), (1, 3), ..., (1, nfactors), (2, 3), ..., (nfactors – 1, nfactors)

4. Squared terms in the order 1, 2, ..., nfactors

If you specify any other named value for model, X contains a subset of these terms, in the same order.

Alternative Functionality

daugment augments an existing D-optimal design using a coordinate-exchange algorithm. The FixedRows name-value argument of the candexch function provides the same functionality using a row-exchange algorithm.

Extended Capabilities

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run in parallel, specify the Options name-value argument in the call to this function and set the UseParallel field of the options structure to true using statset:

Options=statset(UseParallel=true)

For more information about parallel computing, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2024b: Avoid duplicates in D-optimal designs

You can specify whether to avoid duplicate rows when using daugment to augment a D-optimal design. Use the AvoidDuplicates name-value argument to avoid duplicate rows in the additional runs, when possible.

R2024b: Use updated names for name-value arguments

daugment has updated name-value argument names. These more intuitive names are now supported:

• Bounds

• CategoricalVariables

• NumLevels