dcovary

D-optimal design with fixed covariates

Syntax

dCV = dcovary(nfactors,fixed)

dCV = dcovary(nfactors,fixed,model)

dCV = dcovary(___,Name=Value)

[dCV,X] = dcovary(___)

Description

dCV = dcovary(nfactors,fixed) uses a coordinate-exchange algorithm to generate a D-optimal design for a linear additive model with nfactors factors, subject to the constraint that the model must include the fixed covariate values in fixed. The design dCV augments fixed with initial columns for treatments of the model terms, and has the same number of rows as fixed.

example

dCV = dcovary(nfactors,fixed,model) returns a D-optimal design with the terms specified in model.

example

dCV = dcovary(___,Name=Value) specifies 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 maximum number of start points for generating the design, and whether to perform computations in parallel.

example

[dCV,X] = dcovary(___) additionally returns the design matrix X, whose columns are the model terms evaluated at each row of dCV.

example

Examples

collapse all

D-Optimal Design with Fixed Covariates

Open Live Script

Use the dummyvar function to create an eight-run experiment with four blocks of size 2 for estimating a linear additive model with two factors.

fixed = dummyvar([1 1 2 2 3 3 4 4])

fixed = 8×4

     1     0     0     0
     1     0     0     0
     0     1     0     0
     0     1     0     0
     0     0     1     0
     0     0     1     0
     0     0     0     1
     0     0     0     1

Generate a two-factor D-optimal design for the linear additive model by using the dcovary function. Because only n-1 dummy variables are needed to represent n blocks, specify only the first 3 columns of fixed in the function call.

dCV = dcovary(2,fixed(:,1:3))

dCV = 8×5

    -1     1     1     0     0
     1    -1     1     0     0
    -1    -1     0     1     0
     1     1     0     1     0
     1     1     0     0     1
    -1    -1     0     0     1
    -1     1     0     0     0
     1    -1     0     0     0

The first two columns of dCV contain the settings for the two factors. The last three columns are the dummy variable encodings for the four blocks.

D-Optimal Design with Model Terms and Fixed Covariate

Open Live Script

Generate a nine-run D-optimal design for estimating the parameters of the following model, which has five terms and four factors. The fourth factor $X_{4}$ is a fixed covariate.

$y = β_{0} + β_{1} X_{1} X_{4} + β_{2} X_{2} + β_{13} X_{1} X_{3} + β_{23} X_{2} X_{3}^{2} + ϵ$

fixed = (0:8)';
model = [0 0 0 0 ; 1 0 0 1; 0 1 0 0; 1 0 1 0; 0 1 2 0];
dCV = dcovary(3,fixed,model)

dCV = 9×4

     1     1     1     0
     1    -1     1     1
    -1     1     0     2
     1    -1    -1     3
    -1    -1    -1     4
    -1     1     1     5
     1    -1     0     6
    -1    -1     0     7
     1     1     1     8

Each row of dCV contains the factor settings for a run. The factors $X_{1}$ and $X_{2}$ have two levels, and the factor $X_{3}$ has three levels. By default, the software sets the number of levels for each factor as $1 +$ its maximum exponent in the model terms. The values in fixed determine the settings for the fourth factor $X_{4}$ in each run.

D-Optimal Design and Design Matrix with Fixed Covariates

Open Live Script

Generate a D-optimal design to estimate the parameters in a three-factor linear additive model, with nine runs that necessarily occur at different times. To account for temporal linear drift in the process, include the run time as a variable in the model.

time = linspace(-1,1,9)';
[dCV,X] = dcovary(3,time)

dCV = 9×4

    1.0000    1.0000    1.0000   -1.0000
    1.0000   -1.0000   -1.0000   -0.7500
   -1.0000    1.0000   -1.0000   -0.5000
   -1.0000   -1.0000    1.0000   -0.2500
   -1.0000   -1.0000    1.0000         0
   -1.0000    1.0000   -1.0000    0.2500
    1.0000   -1.0000   -1.0000    0.5000
   -1.0000   -1.0000   -1.0000    0.7500
    1.0000    1.0000    1.0000    1.0000

X = 9×5

    1.0000    1.0000    1.0000    1.0000   -1.0000
    1.0000    1.0000   -1.0000   -1.0000   -0.7500
    1.0000   -1.0000    1.0000   -1.0000   -0.5000
    1.0000   -1.0000   -1.0000    1.0000   -0.2500
    1.0000   -1.0000   -1.0000    1.0000         0
    1.0000   -1.0000    1.0000   -1.0000    0.2500
    1.0000    1.0000   -1.0000   -1.0000    0.5000
    1.0000   -1.0000   -1.0000   -1.0000    0.7500
    1.0000    1.0000    1.0000    1.0000    1.0000

The column vector time is a fixed factor, normalized to values between ±1. The number of rows in the fixed factor specifies the number of runs in the design. The resulting design dCV contains factor settings for the three controlled model factors at each time.

D-Optimal Design with Custom Levels and Fixed Covariate

Open Live Script

Generate a nine-run D-optimal design for estimating the parameters of a two-factor pure quadratic model that includes a fixed covariate. The first factor has levels 1, 2, and 3, and the second factor has levels –1, 0, and 1. The third factor has values ranging from 0 to 8.

fixed = (0:8)';
dCV = dcovary(2,fixed,"purequadratic",Bounds={[1,2,3],[-1,0,1]})

dCV = 9×3

     2     1     0
     3     0     1
     1    -1     2
     3     1     3
     2    -1     4
     1     1     5
     1     0     6
     2     0     7
     3    -1     8

Each row of dCV contains the factor settings for a run.

Input Arguments

collapse all

`nfactors` — Number of nonfixed factors
positive integer scalar

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

Example: 3

Data Types: single | double

`fixed` — Fixed covariate values
numeric matrix

Fixed covariate values, specified as a numeric matrix. Each column of fixed contains the values of a fixed covariate factor in the design dCV. The design has the same number of rows as fixed.

Example: [1 1 -1 1]

Data Types: single | double

`model` — Model terms
`"linear"` or `"additive"` (default) | `"interaction"` | `"quadratic"` | `"purequadratic"` | numeric matrix

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

Value	Model 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 X1⁰X2¹X3². 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

collapse all

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: dcovary(3,(1:5)',Bounds=[1 1; 2 2]) generates a five-run D-optimal design for a linear additive model that includes three factors with levels 1 and 2, and a fixed covariate with factor values ranging from 1 to 5.

`AvoidDuplicates` — Flag to avoid duplicate rows
`false` or `0` (default) | `true` or `1`

Flag to avoid duplicate rows in the D-optimal design, specified as a numeric or logical 0 (false) or 1 (true). If you set AvoidDuplicates=true and dcovary calculates nonduplicate points, the rows of the D-optimal design are unique. When AvoidDuplicates is false (the default), dcovary does not avoid calculating duplicate rows.

Example: AvoidDuplicates=true

Data Types: logical

`Bounds` — Lower and upper bounds for each factor
`2`-by-`nfactors` numeric matrix | cell array of `nfactors` elements

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, dcovary ignores the value of NumLevels.

Example: Bounds=[0 0; 2 1]

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

Data Types: single | double | cell

`CategoricalVariables` — Indices of categorical factors
numeric vector of positive integers

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

Example: CategoricalVariables=[1 3]

Data Types: single | double

`Display` — Flag to display iteration counter window
`"on"` (default) | `"off"`

Flag to display the iteration counter window, specified as "on" or "off". The window displays the trial number (see NumTries) and the iteration number during computation.

Example: Display="off"

Data Types: char | string

`ExcludeFcn` — Function to exclude unwanted runs
function handle

Function to exclude unwanted runs, specified as a function handle. If the function is f, it must support the syntax b = f(S), where S is a k-by-nfactors matrix. b is a vector of k Boolean values, where b(i) is true if the ith row of S is excluded.

Example: ExcludeFcn=@excludefun

Data Types: function_handle

`InitialDesign` — Initial design matrix
`nruns`-by-`nfactors` numeric matrix

Initial design matrix, specified as an nruns-by-nfactors numeric matrix, where nruns is the number of rows in fixed. The default is a randomly selected set of points.

Example: InitialDesign=[-1 0 1; 0 1 1; 0 -1 1]

Data Types: single | double

`MaxIterations` — Maximum number of iterations
10 (default) | positive integer scalar

Maximum number of iterations per trial in the coordinate-exchange algorithm, specified as a positive integer scalar. For more information, see the Algorithms section of cordexch.

Example: MaxIterations=20

Data Types: single | double

`NumLevels` — Number of levels for each factor
integer scalar greater than `1` | 1-by-`nfactors` numeric vector of integers greater than `1`

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. dcovary 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 factor whose indices you specify in CategoricalVariables has two levels (1 and 2) by default.

Note

If you specify AvoidDuplicates=true, the software adds more levels for any noncategorical factors, as needed, to avoid duplicate rows in the design.

Example: NumLevels=[2 3]

Data Types: single | double

`NumTries` — Number of trials
1 (default) | positive integer scalar

Number of trials for generating a D-optimal design starting from a new initial design matrix, specified as a positive integer scalar. If NumTries > 1 and you specify InitialDesign, then dcovary uses InitialDesign for the first trial, and a randomly selected set of points in subsequent trials.

Example: NumTries=3

Data Types: single | double

`Options` — Options for computing in parallel and setting random streams
structure

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 Name Value Default

UseParallel Set this value to true to run computations in parallel. false

Field Name	Value	Default
`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 `dcovary` uses the default stream or streams.

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

Output Arguments

collapse all

`dCV` — D-optimal design
`nruns`-by-`p` numeric matrix

D-optimal design for model, returned as an nruns-by-p numeric matrix. nruns is the number of rows in fixed, and p is nfactors + the number of columns in fixed. Each row (run) of dCV contains the settings for each factor in the design, which dcovary generates using a coordinate-exchange algorithm, subject to the constraint that the model must include the fixed covariate factors in fixed. The design dCV augments fixed with initial columns for treatments of the model terms.

dcovary creates a starting design that includes the fixed covariate values, and then iterates by changing the nonfixed coordinates of each design point in an attempt to reduce the variance of the coefficients estimated using this design.

`X` — Design matrix
numeric matrix

Design matrix, returned as a numeric matrix with nruns rows, where nruns is the number of rows in fixed. The number of columns in X depends on the value of model.

If you specify model as "quadratic" or a numeric matrix that includes constant, linear, interaction, and squared terms, the columns of X (in order) are:

Constant term
Linear terms in the order 1, 2, ..., nfactors
Interaction terms in the order (1, 2), (1, 3), ..., (1, nfactors), (2, 3), ..., (nfactors – 1, nfactors)
Squared terms in the order 1, 2, ..., nfactors
Columns of fixed

If you specify any other named value for model, X contains a subset of these terms, in the same order.

Alternative Functionality

You can also generate a D-optimal design with fixed covariate values by using the cordexch function with the covariates name-value argument.

Extended Capabilities

expand all

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

To run in parallel, specify the Options name-value argument in the call to this function and set the UseParallel field of the options structure to true using statset:

Options=statset(UseParallel=true)

For more information about parallel computing, see Run MATLAB Functions with Automatic Parallel Support (Parallel Computing Toolbox).

Version History

Introduced before R2006a

expand all

R2024b: Avoid duplicates in D-optimal designs

You can specify whether to avoid duplicate rows when using dcovary to augment a D-optimal design. Use the AvoidDuplicates name-value argument to avoid duplicate rows in the additional runs, when possible.

R2024b: Use updated names for name-value arguments

dcovary has updated name-value argument names. These more intuitive names are now supported:

Bounds
CategoricalVariables
NumLevels

dcovary

Syntax

Description

Examples

D-Optimal Design with Fixed Covariates

D-Optimal Design with Model Terms and Fixed Covariate

D-Optimal Design and Design Matrix with Fixed Covariates

D-Optimal Design with Custom Levels and Fixed Covariate

Input Arguments

`nfactors` — Number of nonfixed factors
positive integer scalar

`fixed` — Fixed covariate values
numeric matrix

`model` — Model terms
`"linear"` or `"additive"` (default) | `"interaction"` | `"quadratic"` | `"purequadratic"` | numeric matrix

Name-Value Arguments

`AvoidDuplicates` — Flag to avoid duplicate rows
`false` or `0` (default) | `true` or `1`

`Bounds` — Lower and upper bounds for each factor
`2`-by-`nfactors` numeric matrix | cell array of `nfactors` elements

`CategoricalVariables` — Indices of categorical factors
numeric vector of positive integers

`Display` — Flag to display iteration counter window
`"on"` (default) | `"off"`

`ExcludeFcn` — Function to exclude unwanted runs
function handle

`InitialDesign` — Initial design matrix
`nruns`-by-`nfactors` numeric matrix

`MaxIterations` — Maximum number of iterations
10 (default) | positive integer scalar

`NumLevels` — Number of levels for each factor
integer scalar greater than `1` | 1-by-`nfactors` numeric vector of integers greater than `1`

`NumTries` — Number of trials
1 (default) | positive integer scalar

`Options` — Options for computing in parallel and setting random streams
structure

Output Arguments

`dCV` — D-optimal design
`nruns`-by-`p` numeric matrix

`X` — Design matrix
numeric matrix

Alternative Functionality

Extended Capabilities

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Version History

R2024b: Avoid duplicates in D-optimal designs

R2024b: Use updated names for name-value arguments

See Also

Topics

dcovary

Syntax

Description

Examples

D-Optimal Design with Fixed Covariates

D-Optimal Design with Model Terms and Fixed Covariate

D-Optimal Design and Design Matrix with Fixed Covariates

D-Optimal Design with Custom Levels and Fixed Covariate

Input Arguments

nfactors — Number of nonfixed factors positive integer scalar

fixed — Fixed covariate values numeric matrix

model — Model terms "linear" or "additive" (default) | "interaction" | "quadratic" | "purequadratic" | numeric matrix

Name-Value Arguments

AvoidDuplicates — Flag to avoid duplicate rows false or 0 (default) | true or 1

Bounds — Lower and upper bounds for each factor 2-by-nfactors numeric matrix | cell array of nfactors elements

CategoricalVariables — Indices of categorical factors numeric vector of positive integers

Display — Flag to display iteration counter window "on" (default) | "off"

ExcludeFcn — Function to exclude unwanted runs function handle

InitialDesign — Initial design matrix nruns-by-nfactors numeric matrix

MaxIterations — Maximum number of iterations 10 (default) | positive integer scalar

NumLevels — Number of levels for each factor integer scalar greater than 1 | 1-by-nfactors numeric vector of integers greater than 1

NumTries — Number of trials 1 (default) | positive integer scalar

Options — Options for computing in parallel and setting random streams structure

Output Arguments

dCV — D-optimal design nruns-by-p numeric matrix

X — Design matrix numeric matrix

Alternative Functionality

Extended Capabilities

Automatic Parallel Support Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Version History

R2024b: Avoid duplicates in D-optimal designs

R2024b: Use updated names for name-value arguments

See Also

Topics

`nfactors` — Number of nonfixed factors
positive integer scalar

`fixed` — Fixed covariate values
numeric matrix

`model` — Model terms
`"linear"` or `"additive"` (default) | `"interaction"` | `"quadratic"` | `"purequadratic"` | numeric matrix

`AvoidDuplicates` — Flag to avoid duplicate rows
`false` or `0` (default) | `true` or `1`

`Bounds` — Lower and upper bounds for each factor
`2`-by-`nfactors` numeric matrix | cell array of `nfactors` elements

`CategoricalVariables` — Indices of categorical factors
numeric vector of positive integers

`Display` — Flag to display iteration counter window
`"on"` (default) | `"off"`

`ExcludeFcn` — Function to exclude unwanted runs
function handle

`InitialDesign` — Initial design matrix
`nruns`-by-`nfactors` numeric matrix

`MaxIterations` — Maximum number of iterations
10 (default) | positive integer scalar

`NumLevels` — Number of levels for each factor
integer scalar greater than `1` | 1-by-`nfactors` numeric vector of integers greater than `1`

`NumTries` — Number of trials
1 (default) | positive integer scalar

`Options` — Options for computing in parallel and setting random streams
structure

`dCV` — D-optimal design
`nruns`-by-`p` numeric matrix

`X` — Design matrix
numeric matrix

Automatic Parallel Support
Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.