fitrm

Fit repeated measures model

Syntax

rm = fitrm(t,modelspec)

rm = fitrm(t,modelspec,Name=Value)

Description

rm = fitrm(t,modelspec) returns a repeated measures model, specified by modelspec, fitted to the variables in the table or dataset array t. The model rm is returned as a RepeatedMeasuresModel object. For more information about the properties of this model object, see RepeatedMeasuresModel.

example

rm = fitrm(t,modelspec,Name=Value) returns a repeated measures model with additional options specified by one or more name-value arguments. For example, you can specify the hypothesis for the within-subject factors.

example

Examples

collapse all

Fit a Repeated Measures Model

Open Live Script

Load the fisheriris data set.

load fisheriris

The column vector species consists of iris flowers of three different species: setosa, versicolor, and virginica. The double matrix meas consists of four types of measurements for the flowers: the length and width of sepals and petals in centimeters.

Store the data in a table array.

t = table(species,meas(:,1),meas(:,2),meas(:,3),meas(:,4),...
VariableNames=["species","meas1","meas2","meas3","meas4"]);
Meas = table([1 2 3 4]',VariableNames="Measurements");

Fit a repeated measures model, where the measurements are the responses and the species is the predictor variable.

rm = fitrm(t,"meas1-meas4~species",WithinDesign=Meas)

rm = 
  RepeatedMeasuresModel with properties:

   Between Subjects:
         BetweenDesign: [150x5 table]
         ResponseNames: {'meas1'  'meas2'  'meas3'  'meas4'}
    BetweenFactorNames: {'species'}
          BetweenModel: '1 + species'

   Within Subjects:
          WithinDesign: [4x1 table]
     WithinFactorNames: {'Measurements'}
           WithinModel: 'separatemeans'

   Estimates:
          Coefficients: [3x4 table]
            Covariance: [4x4 table]

Display the coefficients.

rm.Coefficients

ans=3×4 table
                           meas1       meas2      meas3      meas4  
                          ________    ________    ______    ________

    (Intercept)             5.8433      3.0573     3.758      1.1993
    species_setosa        -0.83733     0.37067    -2.296    -0.95333
    species_versicolor    0.092667    -0.28733     0.502     0.12667

fitrm uses the "effects" contrasts, which means that the coefficients sum to 0. The rm.DesignMatrix has one column of 1s for the intercept, and two other columns species_setosa and species_versicolor with these values:

$\begin{array}{c} s p e c i e s_s e t o s a = {\begin{array}{llllllllllllllllllll} 1 & i f s e t o s a \\ 0 & i f v e r s i c o l o r \\ - 1 & i f v i r g i n i c a \end{array} a n d s p e c i e s_v e r s i c o l o r = {\begin{array}{llllllllllllllllllll} 0 & i f s e t o s a \\ 1 & i f v e r s i c o l o r \\ - 1 & i f v i r g i n i c a \end{array} \end{array}$

Display the covariance matrix.

rm.Covariance

ans=4×4 table
              meas1       meas2       meas3       meas4  
             ________    ________    ________    ________

    meas1     0.26501    0.092721     0.16751    0.038401
    meas2    0.092721     0.11539    0.055244     0.03271
    meas3     0.16751    0.055244     0.18519    0.042665
    meas4    0.038401     0.03271    0.042665    0.041882

Specify Within-Subject Hypothesis

Open Live Script

Load the sample data.

load('longitudinalData.mat');

The matrix Y contains response data for 16 individuals. The response is the blood level of a drug measured at five time points (time = 0, 2, 4, 6, and 8). Each row of Y corresponds to an individual, and each column corresponds to a time point. The first eight subjects are female, and the second eight subjects are male. This data is simulated.

Define a variable that stores gender information.

Gender = ["F" "F" "F" "F" "F" "F" "F" "F" "M" "M" "M" "M" "M" "M" "M" "M"]';

Store the data in a table array format to conduct repeated measures analysis.

t = table(Gender,Y(:,1),Y(:,2),Y(:,3),Y(:,4),Y(:,5),...
VariableNames=["Gender","t0","t2","t4","t6","t8"]);

Define the within-subject variable.

Time = [0 2 4 6 8]';

Fit a repeated measures model, where blood levels are the responses and gender is the predictor variable. Also, define the hypothesis for within-subject factors.

rm = fitrm(t,"t0-t8 ~ Gender",WithinDesign=Time,WithinModel="orthogonalcontrasts")

rm = 
  RepeatedMeasuresModel with properties:

   Between Subjects:
         BetweenDesign: [16x6 table]
         ResponseNames: {'t0'  't2'  't4'  't6'  't8'}
    BetweenFactorNames: {'Gender'}
          BetweenModel: '1 + Gender'

   Within Subjects:
          WithinDesign: [5x1 table]
     WithinFactorNames: {'Time'}
           WithinModel: 'orthogonalcontrasts'

   Estimates:
          Coefficients: [2x5 table]
            Covariance: [5x5 table]

Fit Model with Covariates

Open Live Script

Load the sample data.

load repeatedmeas

The table between includes the eight repeated measurements y1 through y8 as responses, and the between-subject factors Group, Gender, IQ, and Age. IQ and Age are continuous variables. The table within includes the within-subject factors w1 and w2.

Fit a repeated measures model, where age, IQ, group, and gender are the predictor variables, and the model includes the interaction effect of group and gender. Also, define the within-subject factors.

rm = fitrm(between,'y1-y8 ~ Group*Gender+Age+IQ','WithinDesign',within)

rm = 
  RepeatedMeasuresModel with properties:

   Between Subjects:
         BetweenDesign: [30x12 table]
         ResponseNames: {'y1'  'y2'  'y3'  'y4'  'y5'  'y6'  'y7'  'y8'}
    BetweenFactorNames: {'Age'  'IQ'  'Group'  'Gender'}
          BetweenModel: '1 + Age + IQ + Group*Gender'

   Within Subjects:
          WithinDesign: [8x2 table]
     WithinFactorNames: {'w1'  'w2'}
           WithinModel: 'separatemeans'

   Estimates:
          Coefficients: [8x8 table]
            Covariance: [8x8 table]

Display the coefficients.

rm.Coefficients

ans=8×8 table
                                y1         y2         y3         y4          y5           y6         y7          y8   
                             ________    _______    _______    _______    _________    ________    _______    ________

    (Intercept)                141.38     195.25     9.8663    -49.154       157.77     0.23762    -42.462      76.111
    Age                       0.32042    -4.7672    -1.2748     0.6216      -1.0621     0.89927     1.2569    -0.38328
    IQ                        -1.2671    -1.1653    0.05862     0.4288      -1.4518    -0.25501    0.22867    -0.72548
    Group_A                   -1.2195    -9.6186     22.532     15.303       12.602      12.886     10.911      11.487
    Group_B                    2.5186      1.417    -2.2501    0.50181       8.0907      3.1957     11.591      9.9188
    Gender_Female              5.3957    -3.9719     8.5225     9.3403       6.0909       1.642    -2.1212      4.8063
    Group_A:Gender_Female      4.1046     10.064    -7.3053    -3.3085       4.6751      2.4907     -4.325     -4.6057
    Group_B:Gender_Female    -0.48486    -2.9202     1.1222    0.69715    -0.065945    0.079468     3.1832      6.5733

The display shows the coefficients for fitting the repeated measures as a function of the terms in the between-subjects model.

Input Arguments

collapse all

`t` — Input data
table

Input data, which includes the values of the response variables and the between-subject factors to use as predictors in the repeated measures model, specified as a table.

The variable names in t must be valid MATLAB^® identifiers. You can verify the variable names by using the isvarname function. If the variable names are not valid, then you can convert them by using the matlab.lang.makeValidName function.

Data Types: table

`modelspec` — Formula for model specification
character vector or string scalar of the form `'y1-yk ~ terms'`

Formula for the model specification, specified as a character vector or string scalar of the form 'y1-yk ~ terms'. The responses and terms are specified using Wilkinson notation. fitrm treats the variables used in model terms as categorical if they are categorical (nominal or ordinal), logical, character arrays, string arrays, or cell arrays of character vectors. The software uses dummy variables with effects coding to represent categorical variables. For more information about dummy variables, see Dummy Variables for more information.

For example, if you have four repeated measures as responses and the factors x1, x2, and x3 as the predictor variables, then you can define a repeated measures model as follows.

Example: 'y1-y4 ~ x1 + x2 * x3'

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: WithinDesign="W",WithinModel="w1+w2" specifies the matrix w as the design matrix for within-subject factors, and the model for the within-subject factors w1 and w2 as "w1+w2".

`WithinDesign` — Design for within-subject factors
numeric vector of length r (default) | r-by-k numeric matrix | r-by-k table

Design for the within-subject factors, specified as one of the following:

Numeric vector of length r, where r is the number of repeated measures for the single within-subject factor.
In this case, fitrm treats the values in the vector as continuous. These values are typically time values.
r-by-k numeric matrix of the values of the k within-subject factors.
In this case, fitrm treats all k variables as continuous. Each row of WithinDesign corresponds to a different combination of values for the k within-subject factors.
r-by-k table that contains the values of the k within-subject factors.
In this case, each row of WithinDesign corresponds to a different combination of values for the k within-subject factors. fitrm treats all numeric variables as continuous, and all categorical (nominal or ordinal) variables as categorical. The software uses dummy variables with effects coding to represent categorical variables. For more information about dummy variables, see Dummy Variables for more information.

For example, if the table weeks contains the values of the within-subject factors, then you can define the design table as follows.

Example: WithinDesign=weeks

Data Types: single | double | table

`WithinModel` — Model specifying within-subject hypothesis test
`'separatemeans'` (default) | `'orthogonalcontrasts'` | character vector or string scalar

Model specifying the within-subject hypothesis test, specified as one of the following:

'separatemeans' — Compute a separate mean for each group.
'orthogonalcontrasts' — This value is valid only when the within-subject model has a single numeric factor T. Responses are the average, the slope of centered T, and, in general, all orthogonal contrasts for a polynomial up to T^(p – 1), where p is the number of rows in the within-subject model.
A character vector or string scalar that defines a model specification in the within-subject factors. You can define the model based on the rules for the terms in modelspec.

For example, if you have three within-subject factors w1, w2, and w3, then you can specify a model for the within-subject factors as follows.

Example: WithinModel="w1+w2+w2*w3"

Data Types: char | string

More About

collapse all

Model Specification Using Wilkinson Notation

Wilkinson notation describes the factors present in models. It does not describe the multipliers (coefficients) of those factors.

The following rules specify the responses in modelspec.

Wilkinson Notation	Description
`Y1,Y2,Y3`	Specific list of variables
`Y1-Y5`	All table variables from `Y1` through `Y5`

The following rules specify the terms in modelspec.

Wilkinson notation	Factors in Standard Notation
`1`	Constant (intercept) term
`X^k`, where `k` is a positive integer	`X`, `X²`, ..., `X^k`
`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`
`X1X2X3 - X1:X2:X3`	`X1`, `X2`, `X3`, `X1X2`, `X1X3`, `X2*X3`
`X1*(X2 + X3)`	`X1`, `X2`, `X3`, `X1X2`, `X1X3`

Statistics and Machine Learning Toolbox™ notation includes a constant term unless you explicitly remove the term using -1.

Version History

Introduced in R2014a

fitrm

Syntax

Description

Examples

Fit a Repeated Measures Model

Specify Within-Subject Hypothesis

Fit Model with Covariates

Input Arguments

t — Input data table

modelspec — Formula for model specification character vector or string scalar of the form 'y1-yk ~ terms'

Name-Value Arguments

WithinDesign — Design for within-subject factors numeric vector of length r (default) | r-by-k numeric matrix | r-by-k table

WithinModel — Model specifying within-subject hypothesis test 'separatemeans' (default) | 'orthogonalcontrasts' | character vector or string scalar

More About

Model Specification Using Wilkinson Notation

Version History

See Also

`t` — Input data
table

`modelspec` — Formula for model specification
character vector or string scalar of the form `'y1-yk ~ terms'`

`WithinDesign` — Design for within-subject factors
numeric vector of length r (default) | r-by-k numeric matrix | r-by-k table

`WithinModel` — Model specifying within-subject hypothesis test
`'separatemeans'` (default) | `'orthogonalcontrasts'` | character vector or string scalar