# rowexch

Row exchange

## Syntax

```dRE = rowexch(nfactors,nruns) [dRE,X] = rowexch(nfactors,nruns) [dRE,X] = rowexch(nfactors,nruns,model) [dRE,X] = rowexch(...,param1,val1,param2,val2,...) ```

## Description

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

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

`[dRE,X] = rowexch(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.

`[dRE,X] = rowexch(...,param1,val1,param2,val2,...)` specifies additional parameter/value pairs for the design. Valid parameters and their values are listed in the following table.

ParameterValue
`'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 ith row S should be excluded.

`'init'`

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

`'levels'`

Vector of number of levels for each factor.

`'maxiter' `

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

`options`

A structure that specifies whether to run in parallel, and specifies the random stream or streams. Create the `options` structure with `statset`. Parallel computation requires Parallel Computing Toolbox™. Option fields are:

• `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`, `rowexch` 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.

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

## 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 `rowexch` to generate a D-optimal design with seven runs:

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

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

At each step, the row-exchange algorithm exchanges an entire row of X with a row from a design matrix C evaluated at a candidate set of feasible treatments. The `rowexch` function automatically generates a C appropriate for a specified model, operating in two steps by calling the `candgen` and `candexch` functions in sequence. Provide your own C by calling `candexch` directly. In either case, if C is large, its static presence in memory can affect computation.

## Version History

Introduced before R2006a