fullFactorialDOE

Full factorial design of experiments (DOE)

Since R2024b

Description

A fullFactorialDOE object contains a full factorial design for an experiment. Use a fullFactorialDOE object to generate a design that contains all possible factor combinations. The object properties include information about the design, model, and factors used to generate the design.

Creation

Syntax

dff = fullFactorialDOE(n)

dff = fullFactorialDOE(bounds)

dff = fullFactorialDOE(levels1,levels2,...,levelsN)

dff = fullFactorialDOE(___,Name=Value)

Description

dff = fullFactorialDOE(n) generates a full factorial design for n factors, and returns the design information in a fullFactorialDOE object dff.

dff = fullFactorialDOE(bounds) specifies the number of factors and the bounds for the design points.

dff = fullFactorialDOE(levels1,levels2,...,levelsN) specifies the number and levels for the factors in the design.

dff = fullFactorialDOE(___,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 experiment model and indicate which factors are categorical.

Input Arguments

n — Number of factors

positive integer

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

If you do not also specify NumLevelsPerFactor when you pass n to fullFactorialDOE, each factor has two levels. The default range for each factor is [-1,1].

Data Types: single | double

bounds — Factor bounds

2-by-n matrix

Factor bounds, specified as a 2-by-n matrix, where n is the number of factors in the design. Each column of bounds corresponds to a factor. The first row of bounds contains the lower bounds for the factors, and the second row contains the upper bounds.

Example: [0.1 0.1 0; 0.5 0.7 0.7]

Data Types: single | double

levels1,levels2,...,levelsN — Factor levels

numeric vector | logical vector | categorical vector | cell array

Factor levels, specified as a numeric, logical, or categorical vector, or a cell array. levels1,...,levelsN must contain levels for each factor in the design.

Example: ["cohorta","cohortb"],[0,0.25,0.5,0.75],["drug1","drug2","drug3"]

Data Types: single | double | logical | char | string | cell | categorical

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: fullFactorialDOE(4,ModelSpecification="quadratic",NumLevelsPerFactor=3) specifies a quadratic model for a design with four factors, where each factor has three levels.

CategoricalFactors — Categorical factors list

vector of positive integers | logical vector | string vector | cell array of character vectors | "all"

Categorical factors list, specified as one of the values in this table.

Value	Description
Vector of positive integers	Each entry in the vector is an index value indicating that the corresponding factor is categorical. The index values are between 1 and n, where n is the number of factors in the design.
Logical vector	A true entry means that the corresponding factor is categorical. The length of the vector is n.
String vector or cell array of character vectors	Each element in the array is the name of a factor. The names must match the entries in FactorNames.
"all"	All factors are categorical.

Example: CategoricalFactors="all"

Data Types: single | double | logical | char | string | cell

FactorNames — Factor names

string vector | cell array of character vectors

Factor names, specified as a string vector or a cell array of character vectors. FactorNames must have the same number of elements as the number of factors. The default value for FactorNames is ["Factor1","Factor2",..."FactorN"].

If you do not specify FactorNames and pass levels for a factor using levels1,...,levelsN as a variable, fullFactorialDOE assigns the workspace variable name to the corresponding factor.

Example: FactorNames=["compound1","compound2"]

Data Types: char | string | cell

ModelSpecification — Experiment model

string scalar | character vector | t-by-p terms matrix

Experiment model, specified as one of the following values.

• A character vector or string scalar with the model name.

  Value	Model Description
  "linear"	The model contains an intercept and linear term for each factor.
  "constant"	The model contains only a constant (intercept) term.
  "interactions"	The model contains an intercept, a linear term for each factor, and all products of pairs of distinct factors (no squared terms).
  "purequadratic"	The model contains an intercept term, and linear and squared terms for each factor.
  "quadratic"	The model contains an intercept term, linear and squared terms for each factor, and all products of pairs of distinct factors.
  "scheffe-linear"	The model contains a linear term for each factor and does not include an intercept term.
  "scheffe-quad"	The model is given by the formula: $${\displaystyle \sum _{i=1}^n{b}_i{x}_i}+{\displaystyle \sum _{i=1}^n{\displaystyle \sum _{j<i}^{n-1}{b}_{ij}{x}_i{x}_j}}$$
  "scheffe-special-cubic"	The model is given by the formula: $${\displaystyle \sum _{i=1}^n{b}_i{x}_i}+{\displaystyle \sum _{i=1}^n{\displaystyle \sum _{j<i}^{n-1}{b}_{ij}{x}_i{x}_j}}+{\displaystyle \sum _{i=1}^n{\displaystyle \sum _{j<i}^{n-1}{\displaystyle \sum _{k<j}^{n-2}{b}_{ijk}{x}_i{x}_j{x}_k}}}$$
  "polyijk"	The model is a polynomial with all terms up to degree i in the first factor, degree j in the second factor, and so on. Specify the maximum degree for each factor by using numerals 0 though 9. The model contains interaction terms, but the degree of each interaction term does not exceed the maximum value of the specified degrees. For example, "poly13" has an intercept and x1, x2, x22, x23, x1*x2, and x1*x22 terms, where x1 and x2 are the first and second factors, respectively.

  In the above table, each x_i corresponds to the ith factor in the design, and b_i, b_ij, b_ijk, and d_ij are coefficients for the model terms.

• A character vector or string scalar formula in Wilkinson Notation. The factor names in the formula must be factor names specified by FactorNames.

• A t-by-n terms matrix, where t is the number of terms and n is the number of factors in the design. A terms matrix is convenient when the number of factors is large and you want to generate the terms programmatically. For more information about terms matrices, see Terms Matrix.

ModelSpecification does not include the response variable and does not affect the location of the design points.

Example: ModelSpecification="quadratic"

Example: ModelSpecification="x1 + x2^2 + x1:x2"

Data Types: single | double | char | string

NumLevelsPerFactor — Number of levels for each factor

positive integer scalar | vector of positive integers

Number of levels for each factor, specified as a positive integer scalar or vector of positive integers. If NumLevelsPerFactor is a scalar, then all factors have the same number of levels. If NumLevelsPerFactor is a vector, it must contain an element for each factor in the design.

If you specify two numeric levels for each level in levels1,levels2,...,levelsN and NumLevelsPerFactor is greater than 2, fullFactorialDOE automatically calculates additional levels.

Example: NumLevelsPerFactor=[2,4,3]

Data Types: single | double

Properties

Design — Generated design points

Read-only: table

This property is read-only.

Generated design points, represented as a table. Each column of Design corresponds to a factor in the design, and each row corresponds to a point.

Data Types: table

Levels — Factor levels

cell array

This property is read-only after object creation.

Factor levels, represented as a cell array with one element per factor. The software uses the value of bounds or levels1,levels2,...,levelsN to set Levels. Otherwise the software sets the elements of Levels to have n equally-spaced levels in the range [-1 1], where n is determined as follows:

• If you do not specify ModelSpecification or NumLevelsPerFactor, then n equals 2.

• If you specify NumLevelsPerFactor, then n equals NumLevelsPerFactor.

• If you specify ModelSpecification and do not specify NumLevelsPerFactor, then n equals 1 + the maximum order of the ModelSpecification model.

Data Types: cell

CategoricalFactors — Categorical factors

Read-only: vector of indices

This property is read-only.

This property is read-only after object creation.

Categorical factors, specified as a vector of indices indicating which factors are categorical. This property is set by the CategoricalFactors name-value argument when you create the fullFactorialDOE object.

Data Types: double

ModelSpecification — Experiment model

Read-only: formula in Wilkinson notation

This property is read-only.

Experiment model, specified as a formula in Wilkinson Notation. ModelSpecification indicates the model you want to fit with the specified design. ModelSpecification does not include the response variable.

This property is set by the ModelSpecification name-value argument when you create the fullFactorialDOE object.

Data Types: string

Object Functions

fitlm

Fit linear regression model using design points

Examples

Generate Full Factorial Design

Generate a full factorial design for four factors.

dff = fullFactorialDOE(4)

dff = 
  fullFactorialDOE with properties:

                Design: [16×4 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3 + Factor4"
                Levels: {[-1 1]  [-1 1]  [-1 1]  [-1 1]}
    CategoricalFactors: []

dff is a fullFactorialDOE object that contains information about the generated full factorial design. The output displays the size of the tables describing the design and factors. The output also displays the model for the design, although the model does not affect on how the software generates design points.

Display the design table.

dff.Design

ans=16×4 table
    Factor1    Factor2    Factor3    Factor4
    _______    _______    _______    _______

      -1         -1         -1         -1   
      -1         -1         -1          1   
      -1         -1          1         -1   
      -1         -1          1          1   
      -1          1         -1         -1   
      -1          1         -1          1   
      -1          1          1         -1   
      -1          1          1          1   
       1         -1         -1         -1   
       1         -1         -1          1   
       1         -1          1         -1   
       1         -1          1          1   
       1          1         -1         -1   
       1          1         -1          1   
       1          1          1         -1   
       1          1          1          1   

The design table displays the values for the 16 points in the full factorial design, and shows that each factor has two levels.

Specify Factor Bounds and Fit Linear Model

Generate a full factorial design and specify bounds for the design points.

dff = fullFactorialDOE([10 20 30; 20 30 40])

dff = 
  fullFactorialDOE with properties:

                Design: [8×3 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3"
                Levels: {[10 20]  [20 30]  [30 40]}
    CategoricalFactors: []

dff is a fullFactorialDOE object that contains information about the generated full factorial design.

Display the levels for the factors.

dff.Levels

ans=1×3 cell array
    {[10 20]}    {[20 30]}    {[30 40]}

The output shows that the ranges for the factors are identical to the bounds you specified when creating the object.

Generate some response data for the design points.

rng(0,"twister") %  For reproducibility
pts = dff.Design;
h = height(pts);
response = 2*pts.Factor1+3*pts.Factor2+pts.Factor3+0.01*randn(h,1);

Fit a linear model using the fitlm function. Specify the design points in dff as the predictor data and response as the response data.

mdl = fitlm(dff,response)

mdl = 
Linear regression model:
    y ~ 1 + Factor1 + Factor2 + Factor3

Estimated Coefficients:
                   Estimate        SE         tStat        pValue  
                   _________    _________    ________    __________

    (Intercept)    -0.005698      0.04714    -0.12087       0.90962
    Factor1           1.9995    0.0010287      1943.7    4.2035e-13
    Factor2           2.9993    0.0010287      2915.6    8.3027e-14
    Factor3           1.0009    0.0010287      972.98    6.6948e-12


Number of observations: 8, Error degrees of freedom: 4
Root Mean Squared Error: 0.0145
R-squared: 1,  Adjusted R-Squared: 1
F-statistic vs. constant model: 4.41e+06, p-value = 1.72e-13

mdl is a LinearModel object that contains the results of fitting a linear model to the data. The model display includes the model formula, estimated coefficients, and model summary statistics.

Specify Factor Levels

Specify the factor levels for a full factorial design.

species = categorical(["cat","dog"]);
vetvisits = 1:5;
foodmotivated = [true false];

Generate a design using the factor levels.

dff = fullFactorialDOE(species,vetvisits,foodmotivated)

dff = 
  fullFactorialDOE with properties:

                Design: [20×3 table]
    ModelSpecification: "1 + species + vetvisits + foodmotivated"
                Levels: {[cat    dog]  [1 2 3 4 5]  [0 1]}
    CategoricalFactors: [1 3]

Display the design table.

dff.Design

ans=20×3 table
    species    vetvisits    foodmotivated
    _______    _________    _____________

      cat          1            false    
      cat          1            true     
      cat          2            false    
      cat          2            true     
      cat          3            false    
      cat          3            true     
      cat          4            false    
      cat          4            true     
      cat          5            false    
      cat          5            true     
      dog          1            false    
      dog          1            true     
      dog          2            false    
      dog          2            true     
      dog          3            false    
      dog          3            true     
      ⋮

The table shows the points for the full factorial design. The table contains every possible combination of the factor levels.

Specify Number of Factor Levels

Generate a full factorial design with three factors. Specify two levels for the first factor, three levels for the second, and four levels for the third.

dff=fullFactorialDOE(3,NumLevelsPerFactor=[2,3,4])

dff = 
  fullFactorialDOE with properties:

                Design: [24×3 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3"
                Levels: {[-1 1]  [-1 0 1]  [-1 -0.3333 0.3333 1]}
    CategoricalFactors: []

Display the levels for the factors in dff.

dff.Levels

ans=1×3 cell array
    {[-1 1]}    {[-1 0 1]}    {[-1 -0.3333 0.3333 1]}

The output shows that the first factor has two levels, the second factor has three, and the third factor has four.

More About

Terms Matrix

A terms matrix T is a t-by-n matrix specifying the terms in a model, where t is the number of terms, and n is the number of factors in the design. The value of T(i,j) is the exponent of variable j in term i.

For example, suppose that a design includes three factors x1, x2, and x3. Each row of T represents one term:

• [0 0 0] — Constant term or intercept

• [0 1 0] — x2; equivalently, x1^0 * x2^1 * x3^0

• [1 0 1] — x1*x3

• [2 0 0] — x1^2

• [0 1 2] — x2*(x3^2)

Wilkinson Notation

Wilkinson notation describes the terms in a model. The notation relates to the terms included in the model, not to the multipliers (coefficients) of those terms.

Wilkinson notation uses these symbols:

• + means include the next variable.

• – means do not include the next variable.

• : defines an interaction, which is a product of the terms.

• * defines an interaction and all lower order terms.

• ^ raises the predictor to a power, exactly as in * repeated, so ^ includes lower order terms as well.

• () groups the terms.

This table shows typical examples of Wilkinson notation.

Wilkinson Notation	Terms in Standard Notation
1	Constant (intercept) term
x1^k, where k is a positive integer	x1, x12, ..., x1k
x1 + x2	x1, x2
x1*x2	x1, x2, x1*x2
x1:x2	x1*x2 only
–x2	Do not include x2
x1*x2 + x3	x1, x2, x3, x1*x2
x1 + x2 + x3 + x1:x2	x1, x2, x3, x1*x2
x1*x2*x3 – x1:x2:x3	x1, x2, x3, x1*x2, x1*x3, x2*x3
x1*(x2 + x3)	x1, x2, x3, x1*x2, x1*x3

For more details, see Wilkinson Notation.

Version History

Introduced in R2024b