Main Content

candgen

Candidate set generation

collapse all in page

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

Open Live Script

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
Open Live Script

Generate a set of candidate treatments for a model containing factors x1 and x2, and terms x1x2, x1x22, and x12x22.

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
Open Live Script

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
Open Live Script

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 modelDefault 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

See Also

| |

Topics