# 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).```

example

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

example

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

example

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

example

## Examples

collapse all

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.

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.

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 1 0 ```

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

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

collapse all

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

Example: `3`

Data Types: `single` | `double`

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

Example: `5`

Data Types: `single` | `double`

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

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

Flag to avoid duplicate rows for `dCE`, specified as logical `0` (`false`) or `1` (`true`). If you set `AvoidDuplicates=true` and `cordexch` calculates nonduplicate points, the rows of `dCE` are unique. When `AvoidDuplicates` is `false` (the default), `cordexch` does not avoid calculating duplicate rows.

Example: `AvoidDuplicates=true`

Data Types: `logical`

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

Example: `Bounds=[0 0; 2 1]`

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

Data Types: `single` | `double` | `cell array`

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`

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`

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 should be excluded.

Example: `ExcludeFcn=@excludefun`

Data Types: `function_handle`

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`

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 factors whose indices you specify in `CategoricalVariables` have two levels (`1` and `2`) by default.

Example: `NumLevels=[2 3]`

Data Types: `single` | `double`

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`

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 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 NameValueDefault
`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

collapse all

D-optimal design for the model specified in `model`, returned as an `nruns`-by-`nfactors` numeric matrix. Each row (run) of `dCE` contains the settings for each factor in the design, which `cordexch` generates using a coordinate-exchange algorithm.

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="quadratic"`, 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 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 = |XTX| 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.

## Version History

Introduced before R2006a

expand all