# candgen

Candidate set generation

## Syntax

``dC = candgen(nfactors)``
``dC = candgen(nfactors,model)``
``dC = candgen(___,Name=Value)``
``[dC,C] = candgen(___)``

## Description

````dC = candgen(nfactors)` returns an m-by-`nfactors` numeric matrix `dC` containing a set of m candidate treatments for a D-optimal design with `nfactors` factors. The candidate treatments (combinations of factor levels) are for a linear additive model.```

example

````dC = candgen(nfactors,model)` returns a set of m candidate treatments appropriate for estimating the terms specified in `model` with `nfactors` factors.```

example

````dC = candgen(___,Name=Value)` specifies additional options using one or more name-value arguments in addition to any of the input argument combinations in the previous syntaxes. For example, you can specify the lower and upper bounds for each factor, and the indices of categorical factors.```

example

````[dC,C] = candgen(___)` additionally returns the design matrix `C` evaluated at the treatments in `dC`. Pass `C` to `candexch` to generate a D-optimal design using a coordinate-exchange algorithm.```

example

## Examples

collapse all

Generate a set of candidate treatments for a linear additive model with three factors, where each factor has two levels.

`dC = candgen(3)`
```dC = 8×3 -1 -1 -1 1 -1 -1 -1 1 -1 1 1 -1 -1 -1 1 1 -1 1 -1 1 1 1 1 1 ```

Generate a set of candidate treatments for a model containing factors ${x}_{1}$ and ${x}_{2}$, and terms ${x}_{1}{x}_{2}$, ${x}_{1}{x}_{2}^{2}$, and ${x}_{1}^{2}{x}_{2}^{2}$.

`dC = candgen(2,[1 1; 1 2; 2 2])`
```dC = 9×2 -1 -1 0 -1 1 -1 -1 0 0 0 1 0 -1 1 0 1 1 1 ```

Generate a set of candidate treatments for a two-factor linear additive model with levels 1 and 2 for the first factor, and levels –1, 0, and 1 for the second factor.

`dC = candgen(2,Bounds={[1,2],[-1,0,1]})`
```dC = 6×2 1 -1 2 -1 1 0 2 0 1 1 2 1 ```

Generate a set of candidate treatments and the design matrix for a pure quadratic model with two factors, where each factor has three levels.

```rng(0,"twister") % For reproducibility [dC, C] = candgen(2,"purequadratic")```
```dC = 9×2 -1 -1 0 -1 1 -1 -1 0 0 0 1 0 -1 1 0 1 1 1 ```
```C = 9×5 1 -1 -1 1 1 1 0 -1 0 1 1 1 -1 1 1 1 -1 0 1 0 1 0 0 0 0 1 1 0 1 0 1 -1 1 1 1 1 0 1 0 1 1 1 1 1 1 ```

Generate a five-run D-optimal design by passing the design matrix `C` to the `candexch` function.

`R = candexch(C,5)`
```R = 5×1 4 8 2 1 9 ```
`DOptimal = dC(R,:)`
```DOptimal = 5×2 -1 0 0 1 0 -1 -1 -1 1 1 ```

## Input Arguments

collapse all

Number of factors in the design, specified as a positive integer scalar.

Example: `3`

Data Types: `single` | `double`

Model terms, specified as value in the following table or as a numeric matrix.

ValueModel Contents
`"linear"` or `"additive"` (default)Constant and linear terms
`"interaction"`Constant, linear, and interaction terms
`"quadratic"`Constant, linear, interaction, and squared terms
`"purequadratic"`Constant, linear, and squared terms

If you specify `model` as a numeric matrix, it must contain one column for each factor and one row for each polynomial term in the model. The entries in each row are exponents for the factors in the columns. For example, if a model has factors `X1`, `X2`, and `X3`, then row `[0 1 2]` in `model` specifies the term `X10X21X32`. A row of all zeros in `model` specifies a constant term.

Example: `"interaction"`

Example: `[0 1 2; 1 2 1]`

Data Types: `single` | `double` | `char` | `string`

### 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: `candgen(2,NumLevels=3)` generates a set of candidate treatments for a model with two factors, where each factor has three levels.

Lower and upper bounds for each factor, specified as a `2`-by-`nfactors` numeric matrix or a cell array of `nfactors` elements. For a matrix, the first row contains the lower bounds, and the second row contains the upper bounds. For a cell array, each element contains a vector of allowable values for the corresponding factor. If `Bounds` is a cell array, `candgen` ignores the value of `CategoricalVariables`.

Example: `Bounds=[0 0; 2 1]`

Example: `Bounds={[0 1 2],[0 1]}`

Data Types: `single` | `double` | `cell array`

Indices of categorical factors, specified as a numeric vector of positive integers. By default, `candgen` sets two levels (`1` and `2`) for categorical factors.

Example: `CategoricalVariables=[1 3]`

Data Types: `single` | `double`

Number of levels for each factor, specified as an integer scalar greater than `1`, or a 1-by-`nfactors` numeric vector of integers greater than `1`. `candgen` ignores the value of `NumLevels` when you specify `Bounds` as a cell array. The default value of `NumLevels` depends on the value of `model`.

Value of `model`Default Value of `NumLevels`
`"linear"` or `"additive"` (default)`2`
`"interaction"``2`
`"quadratic"``3`
`"purequadratic"``3`

If you specify `model` as a numeric matrix, then the default number of levels for each factor is `1` + the maximum exponent in `model` for that factor. Any factors whose indices you specify in `CategoricalVariables` have two levels (`1` and `2`) by default.

Example: `NumLevels=[2 3]`

Data Types: `single` | `double`

## Output Arguments

collapse all

Candidate treatments for a D-optimal design with `nfactors` factors, returned as an m-by-`nfactors` numeric matrix, where m is the number of treatments. Each row in `dC` contains the coordinates of the `nfactors` candidate points.

Design matrix, returned as a numeric matrix. Pass `C` to `candexch` to generate a D-optimal design using a coordinate-exchange algorithm. `C` has the same number of rows as `dC`. The number of columns in `C` depends on the value of `model`.

If you specify `model="quadratic"`, the columns of C, in order, are:

1. Constant term

2. Linear terms in the order 1, 2, ..., `nfactors`

3. Interaction terms in the order (1, 2), (1, 3), ..., (1, `nfactors`), (2, 3), ..., (`nfactors` – 1, `nfactors`)

4. Squared terms in the order 1, 2, ..., `nfactors`

If you specify any value for `model`, `C` contains a subset of these terms, in the same order.

## Alternative Functionality

The `rowexch` function automatically generates a candidate set using `candgen`, and then creates a D-optimal design from that candidate set using `candexch`. Call `candexch` separately to specify your own candidate set for the row-exchange algorithm.

## Version History

Introduced before R2006a

expand all