# cordexch

Coordinate exchange

## Syntax

```dCE = cordexch(nfactors,nruns) [dCE,X] = cordexch(nfactors,nruns) [dCE,X] = cordexch(nfactors,nruns,'model') [dCE,X] = cordexch(...,'name',value) ```

## Description

`dCE = cordexch(nfactors,nruns)` uses a coordinate-exchange algorithm to generate a D-optimal design `dCE` with `nruns` runs (the rows of `dCE`) for a linear additive model with `nfactors` factors (the columns of `dCE`). The model includes a constant term.

`[dCE,X] = cordexch(nfactors,nruns)` also returns the associated design matrix `X`, whose columns are the model terms evaluated at each treatment (row) of `dCE`.

`[dCE,X] = cordexch(nfactors,nruns,'model')` uses the linear regression model specified in `model`. `model` is one of the following:

• `'linear'` — Constant and linear terms. This is the default.

• `'interaction'` — Constant, linear, and interaction terms

• `'quadratic'` — Constant, linear, interaction, and squared terms

• `'purequadratic'` — Constant, linear, and squared terms

The order of the columns of `X` for a full quadratic model with n terms is:

1. The constant term

2. The linear terms in order 1, 2, ..., n

3. The interaction terms in order (1, 2), (1, 3), ..., (1, n), (2, 3), ..., (n – 1, n)

4. The squared terms in order 1, 2, ..., n

Other models use a subset of these terms, in the same order.

Alternatively, `model` can be a matrix specifying polynomial terms of arbitrary order. In this case, `model` should have one column for each factor and one row for each term in the model. The entries in any row of `model` are powers for the factors in the columns. For example, if a model has factors `X1`, `X2`, and `X3`, then a row `[0 1 2]` in `model` specifies the term `(X1.^0).*(X2.^1).*(X3.^2)`. A row of all zeros in `model` specifies a constant term, which can be omitted.

`[dCE,X] = cordexch(...,'name',value)` specifies one or more optional name/value pairs for the design. Valid parameters and their values are listed in the following table. Specify `name` inside single quotes.

nameValue
`bounds`

Lower and upper bounds for each factor, specified as a `2`-by-`nfactors` matrix. Alternatively, this value can be a cell array containing `nfactors` elements, each element specifying the vector of allowable values for the corresponding factor.

`categorical`

Indices of categorical predictors.

`display`

Either `'on'` or `'off'` to control display of the iteration counter. The default is `'on'`.

`excludefun`

Handle to a function that excludes undesirable runs. If the function is f, it must support the syntax b = f(S), where S is a matrix of treatments with `nfactors` columns and b is a vector of Boolean values with the same number of rows as S. b(i) is true if the method should exclude ith row S.

`init`

Initial design as a `nruns`-by-`nfactors` matrix. The default is a randomly selected set of points.

`levels`

Vector of number of levels for each factor. Not used when `bounds` is specified as a cell array.

`maxiter`

Maximum number of iterations. The default is `10`.

`tries`

Number of times to try to generate a design from a new starting point. The algorithm uses random points for each try, except possibly the first. The default is `1`.

`options`

Options for computing in parallel and setting random numbers, specified as a structure. You need Parallel Computing Toolbox™ to run computations in parallel.

Create the `options` structure with `statset`. Structure fields:

• `UseParallel` — Set to `true` to compute in parallel. Default is `false`.

• `UseSubstreams` — Set to `true` to compute in a reproducible fashion. Default is `false`. To compute reproducibly, set `Streams` to a type allowing substreams: `'mlfg6331_64'` or `'mrg32k3a'`.

• `Streams` — A `RandStream` object or cell array of such objects. If you do not specify `Streams`, `cordexch` uses the default stream or streams. If you choose to specify `Streams`, use a single object except in the case

• `UseParallel` is `true`

• `UseSubstreams` is `false`

In that case, use a cell array the same size as the Parallel pool.

## Examples

Suppose you want a design to estimate the parameters in 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}+\epsilon$`

Use `cordexch` to generate a D-optimal design with seven runs:

```nfactors = 3; nruns = 7; [dCE,X] = cordexch(nfactors,nruns,'interaction','tries',10) dCE = -1 1 1 -1 -1 -1 1 1 1 -1 1 -1 1 -1 1 1 -1 -1 -1 -1 1 X = 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```

Columns of the design matrix `X` are the model terms evaluated at each row of the design `dCE`. The terms appear in order from left to right: constant term, linear terms (1, 2, 3), interaction terms (12, 13, 23). Use `X` to fit the model, as described in Linear Regression, to response data measured at the design points in `dCE`.

## Algorithms

Both `cordexch` and `rowexch` use iterative search algorithms. They operate by incrementally changing an initial design matrix X to increase D = |XTX| at each step. In both algorithms, there is randomness built into the selection of the initial design and into the choice of the incremental changes. As a result, both algorithms may return locally, but not globally, D-optimal designs. Run each algorithm multiple times and select the best result for your final design. Both functions have a `'tries'` parameter that automates this repetition and comparison.

Unlike the row-exchange algorithm used by `rowexch`, `cordexch` does not use a candidate set. (Or rather, 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 design space. The absence of a candidate set reduces demands on memory, but the smaller scale of the search means that the coordinate-exchange algorithm is more likely to become trapped in a local minimum.

## Version History

Introduced before R2006a