cordexch

Coordinate-exchange D-optimal design

Syntax

dCE = cordexch(nfactors,nruns)

dCE = cordexch(nfactors,nruns,model)

dCE = cordexch(___,Name=Value)

[dCE,X] = cordexch(___)

Description

dCE = cordexch(nfactors,nruns) returns a numeric matrix dCE containing a D-optimal design with nruns runs for nfactors factors. The design is for a linear additive model with a constant term. By default, each factor has two levels. Each row (run) of dCE contains the settings for each factor in the design, which cordexch generates using a coordinate-exchange algorithm (see Algorithms).

dCE = cordexch(nfactors,nruns,model) returns a D-optimal design with the terms specified in model.

dCE = cordexch(___,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 lower and upper bounds for each factor, and the indices of categorical factors.

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

Examples

Coordinate-Exchange D-Optimal Design

Generate a five-run D-optimal design for a three-factor linear additive model.

dCE = cordexch(3,5)

dCE = 5×3

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

Each row of dCE contains the factor settings for a run. By default, each factor has two levels.

Coordinate-Exchange D-Optimal Design with Model Terms

Generate a nine-run D-optimal design for estimating the parameters of the following model, which has three factors and five terms:

$$y={\beta }_0+{\beta }_1{X}_1+{\beta }_2{X}_2+{\beta }_{13}{X}_1{X}_3+{\beta }_{23}{X}_2{X}_3^2+ϵ$$

dCE = cordexch(3,9,[0 0 0; 1 0 0; 0 1 0; 1 0 1; 0 1 2])

dCE = 9×3

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

Each row of dCE contains the factor settings for a run. The factors $$X_1$$ and $$X_2$$ have two levels, and the factor $$X_3$$ has three levels. By default, the software sets the number of levels for each factor as $$1+$$ its maximum exponent in the model terms.

Coordinate-Exchange D-Optimal Design with Custom Levels

Generate a 10-run D-optimal design for estimating the parameters of a two-factor pure quadratic model with levels 1, 2, and 3 for the first factor, and levels –1, 0, and 1 for the second factor.

dCE = cordexch(2,10,"purequadratic",Bounds={[1,2,3],[-1,0,1]})

dCE = 10×2

     2    -1
     1    -1
     1     1
     3    -1
     2     1
     1     0
     2     0
     3     0
     3     1
     3     0

Each row of dCE contains the factor settings for a run.

Coordinate-Exchange D-Optimal Design and Design Matrix

Generate a D-optimal design for estimating the parameters of the following three-factor, seven-term interaction model:

$$y={\beta }_0+{\beta }_1{X}_1+{\beta }_2{X}_2+{\beta }_3{X}_3+{\beta }_{12}{X}_1{X}_2+{\beta }_{13}{X}_1{X}_3+{\beta }_{23}{X}_2{X}_3+ϵ$$

Specify to find the best D-optimal design using 10 different initial starting points, and to return the design matrix.

[dCE,X] = cordexch(3,7,"interaction",NumTries=10)

dCE = 7×3

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

X = 7×7

     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

Each row of the design dCE contains the factor settings for a run. By default, each factor has two levels.

The columns of the design matrix X are the model terms evaluated at each row of dCE. The terms, in order from left to right, are the constant term ($${\beta }_0$$), linear terms (with coefficients $${\beta }_1$$, $${\beta }_2$$, $${\beta }_3$$), and interaction terms (with coefficients $${\beta }_{12}$$, $${\beta }_{13}$$, $${\beta }_{23}$$).

Input Arguments

nfactors — Number of factors

positive integer scalar

Number of factors in the design, specified as a positive integer scalar.

Example: 3

Data Types: single | double

nruns — Number of runs

nonnegative integer scalar

Number of runs in the design, specified as a nonnegative integer scalar.

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: cordexch(2,5,NumLevels=3) generates a five-run D-optimal design for a linear additive model with two factors, where each factor has three levels.

AvoidDuplicates — Flag to avoid duplicate rows

false or 0 (default) | true or 1

Flag to avoid duplicate rows in the D-optimal design, specified as a numeric or logical 0 (false) or 1 (true). If you set AvoidDuplicates=true and cordexch calculates nonduplicate points, the rows of the D-optimal design are unique. When AvoidDuplicates is false (the default), cordexch 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. 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, cordexch 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, cordexch sets two levels (1 and 2) for categorical factors.

Example: CategoricalVariables=[1 3]

Data Types: single | double

Covariates — Fixed covariate values

numeric matrix with nruns rows

Fixed covariate values, specified as a numeric matrix with nruns rows. Each column of Covariates contains the values of a fixed covariate factor in the design.

Note

You can also generate a D-optimal design with fixed covariate factors using the dcovary function.

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

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

FixedRows — Fixed design

[] (default) | numeric matrix with nfactors columns

Fixed design, specified as a numeric matrix with nfactors columns. cordexch D-optimally adds nruns rows to the rows of FixedRows.

Note

You can also use the daugment function to D-optimally add rows to a fixed design.

Example: FixedRows=[1 -1 1; -1 -1 1; 1 1 -1]

Data Types: single | double

InitialDesign — Initial design matrix

nruns-by-nfactors numeric matrix

Initial design matrix, specified as an nruns-by-nfactors numeric matrix. The default is a randomly selected set of points.

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

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. For more information, see Algorithms.

Example: MaxIterations=20

Data Types: single | double

NumLevels — Number of levels for each factor

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

Number of levels for each factor, specified as an integer scalar greater than 1, or a 1-by-nfactors numeric vector of integers greater than 1. cordexch 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 indices 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

NumTries — Number of trials

1 (default) | positive integer scalar

Number of trials for generating a D-optimal design starting from a new initial design matrix, specified as a positive integer scalar. If NumTries > 1 and you specify InitialDesign, then cordexch uses InitialDesign for the first trial, and a randomly selected set of points in subsequent trials.

Tip

If NumTries=1, cordexch might generate a locally D-optimal design. Specify a larger value of NumTries to return a globally D-optimal design. For more information, see Algorithms.

Example: NumTries=3

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

Output Arguments

dCE — D-optimal design

numeric matrix with p columns

D-optimal design for model, returned as a numeric matrix with p columns, where p is nfactors plus the number of columns in Covariates (if specified). dCE contains the rows of FixedRows (if specified), followed by nruns additional rows. Each row (run) of dCE contains the settings for each factor in the design, which cordexch generates using a coordinate-exchange algorithm.

X — Design matrix

numeric matrix

Design matrix, returned as a numeric matrix with nruns rows. 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

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.

Algorithms

Both cordexch and rowexch use iterative search algorithms that incrementally change an initial design matrix X to increase D = |X^TX| at each iteration. In both algorithms, randomness is built into the selection of the initial design and the choice of the incremental changes. As a result, both algorithms might return locally D-optimal designs instead of globally D-optimal designs. Run each algorithm multiple times and select the best result for your final design. To automate this repetition and comparison, set the NumTries name-value argument of either function.

Unlike the row-exchange algorithm used by rowexch, the coordinate-exchange algorithm used by cordexch does not use a candidate set. Instead, the candidate set is the entire design space. At each step, the coordinate-exchange algorithm exchanges a single element of X with a new element evaluated at a neighboring point in the design space. The absence of a candidate set reduces demands on memory, but the smaller scale of the search makes the coordinate-exchange algorithm more likely to become trapped in a local minimum.

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

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

• Bounds

• CategoricalVariables

• NumLevels