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

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

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