designMatrix

Fixed- and random-effects design matrices

collapse all in page

Syntax

D = designMatrix(lme)
D = designMatrix(lme,'Fixed')
D = designMatrix(lme,'Random')
Dsub = designMatrix(lme,'Random',gnumbers)
[Dsub,gnames] = designMatrix(lme,'Random',gnumbers)

Description

D = designMatrix(lme) or D = designMatrix(lme,'Fixed') returns the fixed-effects design matrix for the linear mixed-effects model lme.

example

D = designMatrix(lme,'Random') returns the random-effects design matrix for the linear mixed-effects model lme.

example

Dsub = designMatrix(lme,'Random',gnumbers) returns a subset of the random-effects design matrix for the linear mixed-effects model lmecorresponding to the grouping variables indicated by the integers in gnumbers.

example

[Dsub,gnames] = designMatrix(lme,'Random',gnumbers) also returns the grouping variable names corresponding to the integers in gnumbers.

example

Examples

collapse all

Open Live Script

Load the sample data. 

load('shift.mat');

The data shows the deviations from the target quality characteristic measured from the products that 5 operators manufacture during three different shifts, morning, evening, and night. This is a randomized block design, where the operators are the blocks. The experiment is designed to study the impact of the time of shift on the performance. The performance measure is the deviation of the quality characteristics from the target value. This is simulated data.

Shift and Operator are nominal variables. 

shift.Shift = nominal(shift.Shift);
shift.Operator = nominal(shift.Operator);

Fit a linear mixed-effects model with a random intercept grouped by operator to assess if performance significantly differs according to the time of the shift.

lme = fitlme(shift,'QCDev ~ Shift + (1|Operator)');

Display the fixed-effects design matrix. 

designMatrix(lme)
ans = 15×3

     1     1     0
     1     0     0
     1     0     1
     1     1     0
     1     0     0
     1     0     1
     1     1     0
     1     0     0
     1     0     1
     1     1     0
     1     0     0
     1     0     1
     1     1     0
     1     0     0
     1     0     1
      ⋮

The column of 1s represents the constant term in the model. fitlme takes the evening shift as the reference group and creates two dummy variables to represent the morning and night shifts, respectively.

Display the random-effects design matrix. 

designMatrix(lme,'random')
ans = 15×5 sparse double matrix (15 nonzeros)
   (1,1)        1
   (2,1)        1
   (3,1)        1
   (4,2)        1
   (5,2)        1
   (6,2)        1
   (7,3)        1
   (8,3)        1
   (9,3)        1
  (10,4)        1
  (11,4)        1
  (12,4)        1
  (13,5)        1
  (14,5)        1
  (15,5)        1

The first number, i, in the (i,|j|) indices corresponds to the observation number, and |j| corresponds to the level of the grouping variable, Operator, i.e., the operator number.

Show the full display of the random-effects design matrix. 

full(designMatrix(lme,'random'))
ans = 15×5

     1     0     0     0     0
     1     0     0     0     0
     1     0     0     0     0
     0     1     0     0     0
     0     1     0     0     0
     0     1     0     0     0
     0     0     1     0     0
     0     0     1     0     0
     0     0     1     0     0
     0     0     0     1     0
     0     0     0     1     0
     0     0     0     1     0
     0     0     0     0     1
     0     0     0     0     1
     0     0     0     0     1
      ⋮

Each column corresponds to a level of the grouping variable, Operator.

Open Live Script

Load and display the sample data. 

load fertilizer.mat;
tbl
tbl=60×4 table
      Soil          Tomato       Fertilizer    Yield
    _________    ____________    __________    _____

    {'Sandy'}    {'Plum'    }        1          104 
    {'Sandy'}    {'Plum'    }        2          136 
    {'Sandy'}    {'Plum'    }        3          158 
    {'Sandy'}    {'Plum'    }        4          174 
    {'Sandy'}    {'Cherry'  }        1           57 
    {'Sandy'}    {'Cherry'  }        2           86 
    {'Sandy'}    {'Cherry'  }        3           89 
    {'Sandy'}    {'Cherry'  }        4           98 
    {'Sandy'}    {'Heirloom'}        1           65 
    {'Sandy'}    {'Heirloom'}        2           62 
    {'Sandy'}    {'Heirloom'}        3          113 
    {'Sandy'}    {'Heirloom'}        4           84 
    {'Sandy'}    {'Grape'   }        1           54 
    {'Sandy'}    {'Grape'   }        2           86 
    {'Sandy'}    {'Grape'   }        3           89 
    {'Sandy'}    {'Grape'   }        4          115 
      ⋮

The table tbl includes data from a split-plot experiment, where soil is divided into three blocks based on the soil type: sandy, silty, and loamy. Each block is divided into five plots, where five different types of tomato plants (cherry, heirloom, grape, vine, and plum) are randomly assigned to these plots. The tomato plants in the plots are then divided into subplots, where each subplot is treated by one of four fertilizers. This is simulated data.

Store the data in a dataset array called ds, for practical purposes, and define Tomato, Soil, and Fertilizer as categorical variables. 

tbl.Tomato = categorical(tbl.Tomato);
tbl.Soil = categorical(tbl.Soil);
tbl.Fertilizer = categorical(tbl.Fertilizer);

Fit a linear mixed-effects model, where Fertilizer and Tomato are the fixed-effects variables, and the mean yield varies by the block (soil type), and the plots within blocks (tomato types within soil types) independently.

lme = fitlme(tbl,"Yield ~ Fertilizer * Tomato + (1|Soil) + (1|Soil:Tomato)");

Store and examine the full random-effects design matrix. 

D = full(designMatrix(lme,"random"));

The first three columns of matrix D contain the indicator variables fitlme creates for the three levels (Loamy, Silty, Sandy, respectively) of the first grouping variable, Soil. The next 15 columns contain the indicator variables created for the second grouping variable, Tomato nested under Soil. These are basically the elementwise products of the dummy variables representing the levels of Soil (Loamy, Silty, and Sandy, respectively) and the levels of Tomato (Cherry, Grape, Heirloom, Plum, Vine, respectively).

Open Live Script

Load and display the sample data. 

load fertilizer.mat;
tbl
tbl=60×4 table
      Soil          Tomato       Fertilizer    Yield
    _________    ____________    __________    _____

    {'Sandy'}    {'Plum'    }        1          104 
    {'Sandy'}    {'Plum'    }        2          136 
    {'Sandy'}    {'Plum'    }        3          158 
    {'Sandy'}    {'Plum'    }        4          174 
    {'Sandy'}    {'Cherry'  }        1           57 
    {'Sandy'}    {'Cherry'  }        2           86 
    {'Sandy'}    {'Cherry'  }        3           89 
    {'Sandy'}    {'Cherry'  }        4           98 
    {'Sandy'}    {'Heirloom'}        1           65 
    {'Sandy'}    {'Heirloom'}        2           62 
    {'Sandy'}    {'Heirloom'}        3          113 
    {'Sandy'}    {'Heirloom'}        4           84 
    {'Sandy'}    {'Grape'   }        1           54 
    {'Sandy'}    {'Grape'   }        2           86 
    {'Sandy'}    {'Grape'   }        3           89 
    {'Sandy'}    {'Grape'   }        4          115 
      ⋮

The table tbl includes data from a split-plot experiment, where soil is divided into three blocks based on the soil type: sandy, silty, and loamy. Each block is divided into five plots, where five different types of tomato plants (cherry, heirloom, grape, vine, and plum) are randomly assigned to these plots. The tomato plants in the plots are then divided into subplots, where each subplot is treated by one of four fertilizers. This is simulated data.

Convert Tomato, Soil, and Fertilizer to categorical variables. 

tbl.Tomato = categorical(tbl.Tomato);
tbl.Soil = categorical(tbl.Soil);
tbl.Fertilizer = categorical(tbl.Fertilizer);

Fit a linear mixed-effects model, where Fertilizer and Tomato are the fixed-effects variables, and the mean yield varies by the block (soil type), and the plots within blocks (tomato types within soil types) independently.

lme = fitlme(tbl,"Yield ~ Fertilizer * Tomato + (1|Soil) + (1|Soil:Tomato)");

Compute the random-effects design matrix for the second grouping variable, and display the first 12 rows. 

[Dsub,gname]  = designMatrix(lme,"random",2);
full(Dsub(1:12,:))
ans = 12×15

     0     0     0     0     0     0     0     0     1     0     0     0     0     0     0
     0     0     0     0     0     0     0     0     1     0     0     0     0     0     0
     0     0     0     0     0     0     0     0     1     0     0     0     0     0     0
     0     0     0     0     0     0     0     0     1     0     0     0     0     0     0
     0     0     0     0     0     1     0     0     0     0     0     0     0     0     0
     0     0     0     0     0     1     0     0     0     0     0     0     0     0     0
     0     0     0     0     0     1     0     0     0     0     0     0     0     0     0
     0     0     0     0     0     1     0     0     0     0     0     0     0     0     0
     0     0     0     0     0     0     0     1     0     0     0     0     0     0     0
     0     0     0     0     0     0     0     1     0     0     0     0     0     0     0
     0     0     0     0     0     0     0     1     0     0     0     0     0     0     0
     0     0     0     0     0     0     0     1     0     0     0     0     0     0     0
      ⋮

Dsub contains the dummy variables created for the second grouping variable, that is, tomato nested under soil. These are the elementwise products of the dummy variables representing the levels of Soil (Loamy, Silty, Sandy, respectively) and the levels of Tomato (Cherry, Grape, Heirloom, Plum, Vine, respectively).

Display the name of the grouping variable. 

gname
gname = 1×1 cell array
    {'Soil:Tomato'}

Input Arguments

collapse all

Linear mixed-effects model, specified as a LinearMixedModel object constructed using fitlme or fitlmematrix.

Grouping variable numbers, specified as an integer array, where R is the length of the cell array that contains the grouping variables for the linear mixed-effects model lme.

For example, you can specify the grouping variables g1, g3, and gr as follows.

Example: [1,3,r]

Data Types: double | single

Output Arguments

collapse all

Design matrix of a linear mixed-effects model lme returned as one of the following:

  • Fixed-effects design matrix — n-by-p matrix consisting of the fixed-effects design of lme, where n is the number of observations and p is the number of fixed-effects terms. The order of fixed-effects terms in D matches the order of terms in the CoefficientNames property of the LinearMixedModel object lme.

  • Random-effects design matrix — n-by-k matrix, consisting of the random-effects design matrix of lme. Here, k is equal to length(B), where B is the random-effects coefficients vector of linear mixed-effects model lme.

    If lme has R grouping variables g1, g2, ..., gR, with levels m1, m2, ..., mR, respectively, and if q1, q2, ..., qR are the lengths of the random-effects vectors that are associated with g1, g2, ..., gR, respectively, then B is a column vector of length q1*m1 + q2*m2 + ... + qR*mR.

    B is made by concatenating the best linear unbiased predictors of random-effects vectors corresponding to each level of each grouping variable as [g1level1; g1level2; ...; g1levelm1; g2level1; g2level2; ...; g2levelm2; ...; gRlevel1; gRlevel2; ...; gRlevelmR]'.

Data Types: single | double

Submatrix of random-effects design matrix corresponding to the grouping variables indicated by the integers in gnumbers, returned as an n-by-k matrix, where k is length of the column vector Bsub.

Bsub contains the concatenated best linear unbiased predictors (BLUPs) of random-effects vectors, corresponding to each level of the grouping variables, specified by gnumbers.

If, for example, gnumbers is [1,3,r], this corresponds to the grouping variables g1, g3, and gr. Then, Bsub contains the concatenated BLUPs of random-effects vectors corresponding to each level of the grouping variables g1, g3, and gr, such as

[g1level1; g1level2; ...; g1levelm1; g3level1; g3level2; ...; g3levelm3; grlevel1; grlevel2; ...; grlevelmr]'.

Thus, Dsub*Bsub represents the contribution of all random effects corresponding to grouping variables g1, g3, and gr to the response of lme.

If gnumbers is empty, then Dsub is the full random-effects design matrix.

Data Types: single | double

Names of grouping variables corresponding to the integers in gnumbers if the design type is 'Random', returned as a k-by-1 cell array. If the design type is 'Fixed', then gnames is an empty matrix [].

Data Types: cell

Version History

Introduced in R2013b

See Also

| |