dcovary
D-optimal design with fixed covariates
Syntax
Description
uses a coordinate-exchange algorithm to generate a D-optimal design for a linear additive
model with dCV
= dcovary(nfactors
,fixed
)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
.
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.dCV
= dcovary(___,Name=Value
)
Examples
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.
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 is a fixed covariate.
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 and have two levels, and the factor has three levels. By default, the software sets the number of levels for each factor as its maximum exponent in the model terms. The values in fixed
determine the settings for the fourth factor in each run.
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.
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
Number of nonfixed factors in the design, specified as a positive integer scalar.
Example: 3
Data Types: single
| double
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 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
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: 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
.
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
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
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
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
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
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
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
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 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 |
UseSubstreams | Set this value to To compute
reproducibly, set | 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
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.
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
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 R2006aYou 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.
dcovary
has updated name-value argument names. These more intuitive
names are now supported:
Bounds
CategoricalVariables
NumLevels
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)