# daugment

D-optimal augmentation

## Syntax

```dCE2 = daugment(dCE,mruns) [dCE2,X] = daugment(dCE,mruns) [dCE2,X] = daugment(dCE,mruns,model) [dCE2,X] = daugment(...,param1,val1,param2,val2,...) ```

## Description

`dCE2 = daugment(dCE,mruns)` uses a coordinate-exchange algorithm to D-optimally add `mruns` runs to an existing experimental design `dCE` for a linear additive model.

`[dCE2,X] = daugment(dCE,mruns)` also returns the design matrix `X` associated with the augmented design.

`[dCE2,X] = daugment(dCE,mruns,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.

`[dCE2,X] = daugment(...,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, where `nfactors` is the number of factors. 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, where `nfactors` is the number of factors, 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 `mruns`-by-`nfactors` matrix, where `nfactors` is the number of factors. 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'`

The value is a structure that contains options specifying whether to compute multiple tries in parallel, and specifying how to use random numbers when generating the starting points for the tries. Create the options structure with `statset`. Applicable `statset` parameters are:

• `'UseParallel'` — If `true` and if Parallel Computing Toolbox™ is installed, compute in parallel. If the Parallel Computing Toolbox is not installed, or `'UseParallel',false`, then computation occurs in serial mode. Default is `false`, meaning serial computation.

• `UseSubstreams` — Set to `true` to compute in parallel 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`, `daugment` 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`.

### Note

The `daugment` function augments an existing design using a coordinate-exchange algorithm; the `'start'` parameter of the `candexch` function provides the same functionality using a row-exchange algorithm.

## Examples

The following eight-run design is adequate for estimating main effects in a four-factor model:

```dCEmain = cordexch(4,8) dCEmain = 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 estimate the six interaction terms in the model, augment the design with eight additional runs:

```dCEinteraction = daugment(dCEmain,8,'interaction') dCEinteraction = 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 1 1 1 -1```

The augmented design is full factorial, with the original eight runs in the first eight rows.