fractionalFactorialDOE

Fractional factorial design of experiments (DOE)

Since R2026a

Description

A fractionalFactorialDOE object contains a two-level fractional factorial design for an experiment, and information about the design, experiment model, and factors. Create a fractionalFactorialDOE object to generate a design that contains a subset of the runs in a full factorial design.

Creation

Syntax

fracdoe = fractionalFactorialDOE(n)

fracdoe = fractionalFactorialDOE(bounds)

fracdoe = fractionalFactorialDOE(levels1,levels2,...,levelsN)

fracdoe = fractionalFactorialDOE(___,Name=Value)

Description

fracdoe = fractionalFactorialDOE(n) generates the smallest two-level fractional factorial design with resolution IV or higher for n factors, and returns the design information in a fractionalFactorialDOE object fracdoe. If no resolution IV design exists, the function generates the smallest possible design. For more information about resolution in fractional factorial designs, see Fractional Factorial Designs.

example

fracdoe = fractionalFactorialDOE(bounds) specifies the number of factors and the bounds for the design runs.

example

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

example

fracdoe = fractionalFactorialDOE(___,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.

example

Input Arguments

expand all

`n` — Number of factors
positive integer

Number of factors in the design, specified as a positive integer. Each factor has two levels. The default levels for each factor are –1 and 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.

This argument sets the Levels property.

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 | string vector | cell array of character vectors

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

This argument sets the Levels property.

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

Name-Value Arguments

expand 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: fractionalFactorialDOE(4,ModelSpecification="linear") uses a linear model for a design with four factors.

`CategoricalFactors` — Categorical factors
vector of positive integers | logical vector | string vector | cell array of character vectors | `"all"`

Categorical factors, 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.

By default, fractionalFactorialDOE treats all nonnumeric factors as categorical.

This argument sets the CategoricalFactors property.

Example: CategoricalFactors="all"

`ConfoundingDisplay` — Degree of confounding terms to display
positive integer

Degree of confounding terms to display, specified as a positive integer. The second column of the ConfoundingPattern table contains interaction terms up to a degree equal to ConfoundingDisplay. The default value of ConfoundingDisplay is the number of factors in the design.

Example: ConfoundingDisplay=3

Data Types: single | double

`FactorNames` — Factor names
string vector | cell array of character vectors

Factor names, specified as a string vector or a cell array of character vectors. The number of unique values in FactorNames must equal the number of factors in the design. The default value for FactorNames is ["Factor1","Factor2",..."FactorN"].

If you specify ModelSpecification as a character vector or string scalar formula in Wilkinson Notation, then FactorNames must contain only valid variable names.

If you pass levels for a factor using variable names in the input argument levels1,levels2,...,levelsN and do not specify FactorNames, then fractionalFactorialDOE assigns the workspace variable name to the corresponding factor.

Example: FactorNames=["compound","quantity"]

Data Types: char | string | cell

`ModelSpecification` — Experiment model
character vector | string scalar | 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.
`"interactions"`	The model contains an intercept, a linear term for each factor, and all products of pairs of distinct factors (no squared terms).
`"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: $\sum_{i = 1}^{n} b_{i} x_{i} + \sum_{i = 1}^{n} \sum_{j < i}^{n - 1} b_{i j} x_{i} x_{j}$
`"scheffe-special-cubic"`	The model is given by the formula: $\sum_{i = 1}^{n} b_{i} x_{i} + \sum_{i = 1}^{n} \sum_{j < i}^{n - 1} b_{i j} x_{i} x_{j} + \sum_{i = 1}^{n} \sum_{j < i}^{n - 1} \sum_{k < j}^{n - 2} b_{i j k} x_{i} x_{j} x_{k}$

A character vector or string scalar formula in Wilkinson notation. The factor names in the formula must be valid variable 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, see Terms Matrix.

ModelSpecification does not include the response variable and does not affect the factor values of the design runs.

This argument sets the ModelSpecification property.

Example: ModelSpecification="interactions"

Example: ModelSpecification="Factor1 + Factor2 + Factor1:Factor2"

Data Types: single | double | char | string

`Resolution` — Resolution of fractional factorial design
positive integer scalar greater than or equal to 3

Resolution of the fractional factorial design, specified as a positive integer scalar greater than or equal to 3. The default value of Resolution depends on the number of factors and the value of LogMaxNumRuns.

If fractionalFactorialDOE is unable to find a design at the specified resolution, the function tries to find a lower resolution design that is sufficient to calibrate the model. If the function is successful, it returns the generators for the lower resolution design, and issues a warning. If the function is unsuccessful, it issues an error.

In a design of resolution Resolution, no n-factor interaction is confounded with any other effect containing fewer than Resolution – n factors. So, a resolution III design does not confound main effects with each other, but might confound them with two-way interactions. A resolution IV design does not confound main effects with each other, and does not confound main effects with two-way interactions. However, the design might confound two-way interactions with each other.

This argument sets the Resolution property.

For more information about resolution in fractional factorial designs, see Fractional Factorial Designs.

Example: Resolution=4

Data Types: single | double

`FullFactors` — Full factors
`[]` (default) | vector of distinct positive integers | logical vector | string array | cell array of character vectors

Full factors, specified as a value in the following table. Full factors receive full factorial treatment in the design.

Value	Description	Size
Vector of distinct positive integers	Indices of columns of `fracdoe.Design` that are full factors	Base-2 logarithm of the number of runs in `fracdoe.Design`
Logical vector	Logical `true` or `false` values indicating whether each column of `fracdoe.Design` is a full factor	Number of factors in `fracdoe.Design`
String array	String array containing the elements of `FactorNames` that are full factors	Base-2 logarithm of the number of runs in `fracdoe.Design`
Cell array of character vectors	Cell array of character vectors containing the elements of `FactorNames` that are full factors	Base-2 logarithm of the number of runs in `fracdoe.Design`

Example: FullFactors=["a" "b" "c"]

Data Types: single | double

`LogMaxNumRuns` — Base-2 logarithm of maximum number of design runs
`[]` (default) | positive integer scalar greater than or equal to 2

Base-2 logarithm of the maximum number of design runs, specified as a positive integer scalar greater than or equal to 2. The fractionalFactorialDOE function generates a fractional factorial design with 2^{LogMaxNumRuns} runs, if possible. If LogMaxNumRuns is [], then the function generates the smallest possible design with resolution IV or higher. If no resolution IV design exists, the function returns the smallest possible design.

Example: LogMaxNumRuns=3

Data Types: single | double

`Generators` — Generators for fractional factorial design
string array | cell array of character vectors | string scalar | character vector

Generators for the fractional factorial design, specified as one of the following values.

A string array or a cell array of character vectors in which each element contains one word
A string scalar or character vector consisting of words separated by spaces

Words are case-sensitive letters or groups of letters, where "a" represents value 1, "b" represents value 2, ..., "A" represents value 27, ..., and "Z" represents value 52. Each word specifies how the corresponding factor’s levels are defined as products of generators from a 2^K full-factorial design. K is the number of letters of the alphabet in Generators.

Example: Generators=["a" "b" "c" "abc"]

Example: Generators={'a' 'b' 'c' 'abc'}

Example: Generators="a b c abc"

Data Types: string | char | cell

Properties

expand all

`Design` — Generated design runs
Read-only: table

This property is read-only.

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

`ConfoundingPattern` — Confounding pattern for the design
Read-only: table

This property is read-only.

Confounding pattern for the design, represented as a table. The first column contains a term in the model specification, and the second column contains the interaction term. Only interaction terms with a degree less than or equal to ConfoundingDisplay are displayed. For example, if the term Factor1 has an interaction term Factor2:Factor3:Factor4:Factor5, then in a linear model, you cannot estimate the term and the interaction term at the same time. The estimated effect for Factor1 is a combination of the effects of Factor1 and Factor2:Factor3:Factor4:Factor5.

`Levels` — Factor levels
Read-only: cell array

This property is read-only.

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 elements of Levels are [-1 1].

`Resolution` — Resolution of fractional factorial design
Read-only: positive integer scalar greater than or equal to 3

This property is read-only.

Resolution of the fractional factorial design, represented as a positive integer scalar greater than or equal to 3. If the fractionalFactorialDOE function is unable to find a design at the specified resolution, the function attempts to find a lower resolution design that is sufficient to calibrate the model. If the function is successful, it returns the generators for the lower resolution design, and issues a warning. If the function is unsuccessful, it issues an error.

Data Types: single | double

`CategoricalFactors` — Categorical factors
Read-only: vector of indices

This property is read-only.

Categorical factors, represented as a vector of indices indicating which factors are categorical.

Data Types: double

`ModelSpecification` — Experiment model
Read-only: formula in Wilkinson notation

This property is read-only.

Experiment model, represented 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.

Data Types: string

Object Functions

fitlm Fit linear regression model using design runs

Examples

collapse all

Generate Fractional Factorial Design

Open Live Script

Generate a two-level fractional factorial design for four factors.

fracdoe = fractionalFactorialDOE(4)

fracdoe = 
  fractionalFactorialDOE with properties:

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

fracdoe is a fractionalFactorialDOE object that contains information about the generated fractional 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 how the software generates design runs.

Display the design table.

fracdoe.Design

ans=8×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

The design table displays the values for the eight runs in the fractional factorial design, and shows that each factor has two levels (–1 and 1).

Specify Factor Bounds and Fit Linear Model

Open Live Script

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

fracdoe = fractionalFactorialDOE([10 20 30; 20 30 40])

fracdoe = 
  fractionalFactorialDOE with properties:

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

fracdoe is a fractionalFactorialDOE object that contains information about the generated fractional factorial design.

Display the levels for the factors.

fracdoe.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 = fracdoe.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 fracdoe as the predictor data and response as the response data.

mdl = fitlm(fracdoe,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

Open Live Script

Specify the number and factor levels for a fractional factorial design.

species = categorical(["cat","dog"]);
visitedvet = [true false];
foodmotivated = [true false];
sex = ["male" "female"];

Generate a design using the factor levels.

fracdoe = fractionalFactorialDOE(species,visitedvet,foodmotivated,sex)

fracdoe = 
  fractionalFactorialDOE with properties:

                Design: [8×4 table]
    ModelSpecification: "1 + species + visitedvet + foodmotivated + sex"
                Levels: {[cat    dog]  [0 1]  [0 1]  ["female"    "male"]}
    CategoricalFactors: [1 2 3 4]
            Resolution: 4
    ConfoundingPattern: [4×2 table]

Display the design table.

fracdoe.Design

ans=8×4 table
    species    visitedvet    foodmotivated      sex   
    _______    __________    _____________    ________

      cat        false           false        "female"
      cat        false           true         "male"  
      cat        true            false        "male"  
      cat        true            true         "female"
      dog        false           false        "male"  
      dog        false           true         "female"
      dog        true            false        "female"
      dog        true            true         "male"

The table shows the runs for the fractional factorial design. The table contains a subset of all possible combinations of the factor levels.

Six-Factor Design with Resolution IV

Open Live Script

Generate a two-level fractional factorial resolution IV design with six factors. A resolution IV design does not confound main effects with each other, and does not confound main effects with two-way interactions. However, the design might confound two-way interactions with each other.

fracdoe=fractionalFactorialDOE(6,Resolution=4)

fracdoe = 
  fractionalFactorialDOE with properties:

                Design: [16×6 table]
    ModelSpecification: "1 + Factor1 + Factor2 + Factor3 + Factor4 + Factor5 + Factor6"
                Levels: {[-1 1]  [-1 1]  [-1 1]  [-1 1]  [-1 1]  [-1 1]}
    CategoricalFactors: []
            Resolution: 4
    ConfoundingPattern: [6×2 table]

Display the runs in the design.

fracdoe.Design

ans=16×6 table
    Factor1    Factor2    Factor3    Factor4    Factor5    Factor6
    _______    _______    _______    _______    _______    _______

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

More About

expand all

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)

Version History

Introduced in R2026a

fractionalFactorialDOE

Description

Creation

Syntax

Description

Input Arguments

`n` — Number of factors
positive integer

`bounds` — Factor bounds
2-by-n matrix

`levels1,levels2,...,levelsN` — Factor levels
numeric vector | logical vector | categorical vector | string vector | cell array of character vectors

Name-Value Arguments

`CategoricalFactors` — Categorical factors
vector of positive integers | logical vector | string vector | cell array of character vectors | `"all"`

`ConfoundingDisplay` — Degree of confounding terms to display
positive integer

`FactorNames` — Factor names
string vector | cell array of character vectors

`ModelSpecification` — Experiment model
character vector | string scalar | t-by-p terms matrix

`Resolution` — Resolution of fractional factorial design
positive integer scalar greater than or equal to 3

`FullFactors` — Full factors
`[]` (default) | vector of distinct positive integers | logical vector | string array | cell array of character vectors

`LogMaxNumRuns` — Base-2 logarithm of maximum number of design runs
`[]` (default) | positive integer scalar greater than or equal to 2

`Generators` — Generators for fractional factorial design
string array | cell array of character vectors | string scalar | character vector

Properties

`Design` — Generated design runs
Read-only: table

`ConfoundingPattern` — Confounding pattern for the design
Read-only: table

`Levels` — Factor levels
Read-only: cell array

`Resolution` — Resolution of fractional factorial design
Read-only: positive integer scalar greater than or equal to 3

`CategoricalFactors` — Categorical factors
Read-only: vector of indices

`ModelSpecification` — Experiment model
Read-only: formula in Wilkinson notation

Object Functions

Examples

Generate Fractional Factorial Design

Specify Factor Bounds and Fit Linear Model

Specify Factor Levels

Six-Factor Design with Resolution IV

More About

Terms Matrix

Version History

See Also

Topics

fractionalFactorialDOE

Description

Creation

Syntax

Description

Input Arguments

n — Number of factors positive integer

bounds — Factor bounds 2-by-n matrix

levels1,levels2,...,levelsN — Factor levels numeric vector | logical vector | categorical vector | string vector | cell array of character vectors

Name-Value Arguments

CategoricalFactors — Categorical factors vector of positive integers | logical vector | string vector | cell array of character vectors | "all"

ConfoundingDisplay — Degree of confounding terms to display positive integer

FactorNames — Factor names string vector | cell array of character vectors

ModelSpecification — Experiment model character vector | string scalar | t-by-p terms matrix

Resolution — Resolution of fractional factorial design positive integer scalar greater than or equal to 3

FullFactors — Full factors [] (default) | vector of distinct positive integers | logical vector | string array | cell array of character vectors

LogMaxNumRuns — Base-2 logarithm of maximum number of design runs [] (default) | positive integer scalar greater than or equal to 2

Generators — Generators for fractional factorial design string array | cell array of character vectors | string scalar | character vector

Properties

Design — Generated design runs Read-only: table

ConfoundingPattern — Confounding pattern for the design Read-only: table

Levels — Factor levels Read-only: cell array

Resolution — Resolution of fractional factorial design Read-only: positive integer scalar greater than or equal to 3

CategoricalFactors — Categorical factors Read-only: vector of indices

ModelSpecification — Experiment model Read-only: formula in Wilkinson notation

Object Functions

Examples

Generate Fractional Factorial Design

Specify Factor Bounds and Fit Linear Model

Specify Factor Levels

Six-Factor Design with Resolution IV

More About

Terms Matrix

Version History

See Also

Topics

`n` — Number of factors
positive integer

`bounds` — Factor bounds
2-by-n matrix

`levels1,levels2,...,levelsN` — Factor levels
numeric vector | logical vector | categorical vector | string vector | cell array of character vectors

`CategoricalFactors` — Categorical factors
vector of positive integers | logical vector | string vector | cell array of character vectors | `"all"`

`ConfoundingDisplay` — Degree of confounding terms to display
positive integer

`FactorNames` — Factor names
string vector | cell array of character vectors

`ModelSpecification` — Experiment model
character vector | string scalar | t-by-p terms matrix

`Resolution` — Resolution of fractional factorial design
positive integer scalar greater than or equal to 3

`FullFactors` — Full factors
`[]` (default) | vector of distinct positive integers | logical vector | string array | cell array of character vectors

`LogMaxNumRuns` — Base-2 logarithm of maximum number of design runs
`[]` (default) | positive integer scalar greater than or equal to 2

`Generators` — Generators for fractional factorial design
string array | cell array of character vectors | string scalar | character vector

`Design` — Generated design runs
Read-only: table

`ConfoundingPattern` — Confounding pattern for the design
Read-only: table

`Levels` — Factor levels
Read-only: cell array

`Resolution` — Resolution of fractional factorial design
Read-only: positive integer scalar greater than or equal to 3

`CategoricalFactors` — Categorical factors
Read-only: vector of indices

`ModelSpecification` — Experiment model
Read-only: formula in Wilkinson notation