# candexch

D-optimal design from candidate set using row exchanges

## Syntax

``rlist = candexch(C,nrows)``
``rlist = candexch(C,nrows,Name=Value)``

## Description

example

````rlist = candexch(C,nrows)` uses a row-exchange algorithm to select a D-optimal design from the candidate set `C`.```
````rlist = candexch(C,nrows,Name=Value)` generates a D-optimal design with additional options specified by one or more name-value arguments.```

## Examples

collapse all

Define a candidate set with a restriction.

```F = (fullfact([5 5 5])-1)/4; % Factor settings in a unit cube T = sum(F,2)<=1.51; % Find rows matching a restriction F = F(T,:); % Take only those rows C = [ones(size(F,1),1) F F.^2]; ```

Calculate model terms including a constant and all squared terms. Because the candidate set has a restriction, use the `candexch` function instead of the `rowexch` function.

```R = candexch(C,12); % Find a D-optimal 12-point subset X = F(R,:); % Get factor settings```

## Input Arguments

collapse all

Candidate set, specified as a matrix of size `N`-by-`P`. The candidate set contains the values of `P` model terms at each of `N` points.

Desired number of rows in the design, specified as a positive integer.

### 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: ```rlist = candexch(C,nrows,maxiter=7)``` specifies the maximum number of iterations as `7`.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: ```rlist = candexch(C,nrows,"maxiter",7)``` specifies the maximum number of iterations as `7`.

Display the iteration number, specified as `"on"` or `"off"`. By default, the `candexch` function displays the iteration number, except when the `UseParallel` field of the `options` name-value argument is `true`.

Initial design, specified as a numeric matrix of size `nrows`-by-`P`. By default, the `candexch` function uses a random subset of the rows of `C` as the initial design.

Maximum number of iterations, specified as a positive integer.

Parallel processing options, specified as a structure. Create the structure using `statset` function and set the fields listed in the table. Parallel processing requires Parallel Computing Toolbox™.

Field in `options`Description
`UseParallel`

Set to `true` to use parallel processing. By default, `UseParallel` is `false`.

`UseSubstreams`

Set to `true` to compute in parallel in a reproducible fashion. When `true`, also set the `Streams` field to a type allowing substreams: `"mlfg6331_64"` or `"mrg32k3a"`. By default, `UseSubstreams` is `false` and parallel computation is not reproducible.

`Streams`

A `RandStream` object or cell array of such objects. If you do not specify `Streams`, then `candexch` 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 of the same size as the parallel pool.

Factor settings, specified as a numeric matrix of size `nobs`-by-P, where `nobs` is the number of fixed design points. `candexch` finds `nrows` additional rows to add to the `start` design.

Number of tries to generate a design from a new starting point, specified as a positive integer. The algorithm uses random points for each try, except possibly the first.

## Output Arguments

collapse all

Selected rows, returned as a vector of length `nrows`.

## Algorithms

`candexch` selects a starting design `X` at random, and uses a row-exchange algorithm to iteratively replace rows of `X` by rows of `C` in an attempt to improve the determinant of `X'*X`.

## Alternatives

The `rowexch` function also generates D-optimal designs using a row-exchange algorithm, but it automatically generates a candidate set that is appropriate for a specified model.

The `daugment` function augments a set of fixed design points using a coordinate-exchange algorithm; the `start` name-value argument provides the same functionality using the row exchange algorithm.

## Version History

Introduced before R2006a