estimate

Fit conditional variance model to data

Syntax

EstMdl = estimate(Mdl,y)

[EstMdl,EstParamCov,logL,info] = estimate(Mdl,y)

EstMdl = estimate(Mdl,Tbl1)

[EstMdl,EstParamCov,logL,info] = estimate(Mdl,Tbl1)

[___] = estimate(___,Name,Value)

Description

EstMdl = estimate(Mdl,y) returns the fully specified, estimated conditional variance model EstMdl. This model stores the estimated parameter values resulting from fitting the partially specified conditional variance model Mdl to the observed univariate time series y by using maximum likelihood. EstMdl and Mdl are the same model type and have the same structure (see garch, egarch, and gjr).

[EstMdl,EstParamCov,logL,info] = estimate(Mdl,y) also returns the estimated variance-covariance matrix associated with estimated parameters EstParamCov, the optimized loglikelihood objective function logL, and a data structure of summary information info.

EstMdl = estimate(Mdl,Tbl1) fits the partially specified conditional variance model Mdl to response variable in the input table or timetable Tbl1, which contains time series data, and returns the fully specified, estimated conditional variance model EstMdl. estimate selects the response variable named in Mdl.SeriesName or the sole variable in Tbl1. To select a different response variable in Tbl1 to fit the model to, use the ResponseVariable name-value argument. (since R2023a)

[EstMdl,EstParamCov,logL,info] = estimate(Mdl,Tbl1) also returns the estimated variance-covariance matrix associated with estimated parameters EstParamCov, the optimized loglikelihood objective function logL, and a data structure of summary information info. (since R2023a)

[___] = estimate(___,Name,Value) specifies options using one or more name-value arguments in addition to any of the input argument combinations in previous syntaxes. estimate returns the output argument combination for the corresponding input arguments. For example, estimate(Mdl,y,Y0=y0) fits the conditional variance model Mdl to the vector of response data y, and specifies the vector of presample response data y0.

Supply all input data using the same data type. Specifically:

• If you specify the numeric vector y, optional data sets must be numeric arrays and you must use the appropriate name-value argument. For example, to specify a presample, set the Y0 name-value argument to a numeric matrix of presample data.

• If you specify the table or timetable Tbl1, optional data sets must be tables or timetables, respectively, and you must use the appropriate name-value argument. For example, to specify a presample, set the Presample name-value argument to a table or timetable of presample data.

Examples

Fit GARCH Model to Vector of Response Data

Fit a GARCH(1,1) model to a simulated vector of data.

Simulate 500 data points from the GARCH(1,1) model

$$y_t={\epsilon }_t,$$

where $${\epsilon }_t={\sigma }_t{z}_t$$ and

$${\sigma }_t^2=0.0001+0.5{\sigma }_{t-1}^2+0.2{\epsilon }_{t-1}^2.$$

Use the default Gaussian innovation distribution for $$z_t$$.

Mdl0 = garch(Constant=0.0001,GARCH=0.5,ARCH=0.2);
rng("default") % For reproducibility
[v,y] = simulate(Mdl0,500);

The output v contains simulated conditional variances. y is a column vector of simulated responses (innovations).

Specify a GARCH(1,1) model with unknown coefficients, and fit it to the series y.

Mdl = garch(1,1);
EstMdl = estimate(Mdl,y)

 
    GARCH(1,1) Conditional Variance Model (Gaussian Distribution):
 
                  Value       StandardError    TStatistic      PValue  
                __________    _____________    __________    __________

    Constant    9.8911e-05     3.0726e-05        3.2191        0.001286
    GARCH{1}       0.45394        0.11193        4.0557      4.9986e-05
    ARCH{1}        0.26374       0.056931        4.6326      3.6111e-06

EstMdl = 
  garch with properties:

     Description: "GARCH(1,1) Conditional Variance Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
               P: 1
               Q: 1
        Constant: 9.89107e-05
           GARCH: {0.453936} at lag [1]
            ARCH: {0.263739} at lag [1]
          Offset: 0

The result is a new garch model called EstMdl. The parameter estimates in EstMdl resemble the parameter values that generated the simulated data.

Estimate EGARCH Model Parameters Without Initial Values

Fit an EGARCH(1,1) model to simulated data.

Simulate 500 data points from an EGARCH(1,1) model

$$y_t={\epsilon }_t,$$

where $${\epsilon }_t={\sigma }_t{z}_t,$$ and

$$\log {\sigma }_t^2=0.001+0.7\log {\sigma }_{t-1}^2+0.5\left[\frac{\left|{\epsilon }_{t-1}\right|}{{\sigma }_{t-1}}-\sqrt{\frac{2}{\pi }}\right]-0.3\left(\frac{{\epsilon }_{t-1}}{{\sigma }_{t-1}}\right)$$

(the distribution of $$z_t$$ is Gaussian).

Mdl0 = egarch(Constant=0.001,GARCH=0.7, ...
    ARCH=0.5,Leverage=-0.3);

rng("default") % For reproducibility 
[v,y] = simulate(Mdl0,500);

The output v contains simulated conditional variances. y is a column vector of simulated responses (innovations).

Specify an EGARCH(1,1) model with unknown coefficients, and fit it to the series y.

Mdl = egarch(1,1);
EstMdl = estimate(Mdl,y)

 
    EGARCH(1,1) Conditional Variance Model (Gaussian Distribution):
 
                      Value       StandardError    TStatistic      PValue  
                   ___________    _____________    __________    __________

    Constant       -0.00063866      0.031698       -0.020148        0.98392
    GARCH{1}           0.70506      0.067359          10.467     1.2221e-25
    ARCH{1}            0.56774      0.074746          7.5956      3.063e-14
    Leverage{1}       -0.32116      0.053345         -6.0204     1.7399e-09

EstMdl = 
  egarch with properties:

     Description: "EGARCH(1,1) Conditional Variance Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
               P: 1
               Q: 1
        Constant: -0.000638661
           GARCH: {0.705065} at lag [1]
            ARCH: {0.567741} at lag [1]
        Leverage: {-0.321158} at lag [1]
          Offset: 0

The result is a new egarch model called EstMdl. The parameter estimates in EstMdl resemble the parameter values that generated the simulated data.

Estimate GJR Model Parameters Without Initial Values

Fit a GJR(1,1) model to simulated data.

Simulate 500 data points from a GJR(1,1) model.

$$y_t={\epsilon }_t,$$

where $${\epsilon }_t={\sigma }_t{z}_t$$ and

$${\sigma }_t^2=0.001+0.5{\sigma }_{t-1}^2+0.2{\epsilon }_{t-1}^2+0.2I\left[{\epsilon }_{t-1}<0\right]{\epsilon }_{t-1}^2.$$

Use the default Gaussian innovation distribution for $$z_t$$.

Mdl0 = gjr(Constant=0.001,GARCH=0.5, ...
    ARCH=0.2,Leverage=0.2);

rng("default") % For reproducibility
[v,y] = simulate(Mdl0,500);

The output v contains simulated conditional variances. y is a column vector of simulated responses (innovations).

Specify a GJR(1,1) model with unknown coefficients, and fit it to the series y.

Mdl = gjr(1,1);
EstMdl = estimate(Mdl,y)

 
    GJR(1,1) Conditional Variance Model (Gaussian Distribution):
 
                     Value       StandardError    TStatistic      PValue  
                   __________    _____________    __________    __________

    Constant       0.00097382     0.00025135        3.8743      0.00010694
    GARCH{1}          0.46056       0.071793        6.4151      1.4077e-10
    ARCH{1}           0.24126       0.063409        3.8047      0.00014196
    Leverage{1}       0.25051        0.11265        2.2237        0.026171

EstMdl = 
  gjr with properties:

     Description: "GJR(1,1) Conditional Variance Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
               P: 1
               Q: 1
        Constant: 0.000973819
           GARCH: {0.460555} at lag [1]
            ARCH: {0.241256} at lag [1]
        Leverage: {0.250507} at lag [1]
          Offset: 0

The result is a new gjr model called EstMdl. The parameter estimates in EstMdl resemble the parameter values that generated the simulated data.

Estimate GARCH Model Parameters Using Presample Data

Fit a GARCH(1,1) model to the daily close NASDAQ Composite Index returns.

Load the NASDAQ data included with the toolbox. Convert the index to returns.

load Data_EquityIdx
nasdaq = DataTable.NASDAQ;
y = price2ret(nasdaq);
T = length(y);

figure
plot(y)
xlim([0,T])
title("NASDAQ Returns")

The returns exhibit volatility clustering.

Specify a GARCH(1,1) model, and fit it to the series. One presample innovation is required to initialize this model. Use the first observation of y as the necessary presample innovation.

Mdl = garch(1,1);
[EstMdl,EstParamCov] = estimate(Mdl,y(2:end),E0=y(1))

 
    GARCH(1,1) Conditional Variance Model (Gaussian Distribution):
 
                  Value       StandardError    TStatistic      PValue  
                __________    _____________    __________    __________

    Constant    2.0419e-06     5.4779e-07        3.7275      0.00019337
    GARCH{1}       0.88074      0.0086252        102.11               0
    ARCH{1}        0.11193      0.0078755        14.212      7.6874e-46

EstMdl = 
  garch with properties:

     Description: "GARCH(1,1) Conditional Variance Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
               P: 1
               Q: 1
        Constant: 2.04192e-06
           GARCH: {0.880735} at lag [1]
            ARCH: {0.111929} at lag [1]
          Offset: 0

EstParamCov = 3×3
10-4 ×

    0.0000   -0.0000    0.0000
   -0.0000    0.7439   -0.5640
    0.0000   -0.5640    0.6202

The output EstMdl is a new garch model with estimated parameters.

Use the output variance-covariance matrix to calculate the estimate standard errors.

se = sqrt(diag(EstParamCov))

se = 3×1

    0.0000
    0.0086
    0.0079

These are the standard errors shown in the estimation output display. They correspond (in order) to the constant, GARCH coefficient, and ARCH coefficient.

Estimate EGARCH Model Parameters Using Presample Data

Fit an EGARCH(1,1) model to the daily close NASDAQ Composite Index returns.

Load the NASDAQ data included with the toolbox. Convert the index to returns.

load Data_EquityIdx
nasdaq = DataTable.NASDAQ;
y = price2ret(nasdaq);
T = length(y);

figure
plot(y)
xlim([0,T])
title("NASDAQ Returns")

The returns exhibit volatility clustering.

Specify an EGARCH(1,1) model, and fit it to the series. One presample innovation is required to initialize this model. Use the first observation of y as the necessary presample innovation.

Mdl = egarch(1,1);
[EstMdl,EstParamCov] = estimate(Mdl,y(2:end),E0=y(1))

 
    EGARCH(1,1) Conditional Variance Model (Gaussian Distribution):
 
                     Value      StandardError    TStatistic      PValue  
                   _________    _____________    __________    __________

    Constant        -0.13478       0.022092        -6.101      1.0539e-09
    GARCH{1}         0.98391      0.0024221        406.22               0
    ARCH{1}          0.19964       0.013966        14.296      2.3323e-46
    Leverage{1}    -0.060243       0.005647       -10.668      1.4356e-26

EstMdl = 
  egarch with properties:

     Description: "EGARCH(1,1) Conditional Variance Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
               P: 1
               Q: 1
        Constant: -0.134785
           GARCH: {0.983909} at lag [1]
            ARCH: {0.199645} at lag [1]
        Leverage: {-0.0602432} at lag [1]
          Offset: 0

EstParamCov = 4×4
10-3 ×

    0.4881    0.0533   -0.1018    0.0106
    0.0533    0.0059   -0.0118    0.0017
   -0.1018   -0.0118    0.1950    0.0016
    0.0106    0.0017    0.0016    0.0319

The output EstMdl is a new egarch model with estimated parameters.

Use the output variance-covariance matrix to calculate the estimate standard errors.

se = sqrt(diag(EstParamCov))

se = 4×1

    0.0221
    0.0024
    0.0140
    0.0056

These are the standard errors shown in the estimation output display. They correspond (in order) to the constant, GARCH coefficient, ARCH coefficient, and leverage coefficient.

Fit GARCH Model to Response Variable in Timetable

Since R2023a

Fit a GARCH(1,1) model to the average weekly closing NASDAQ returns. Supply a timetable of data and specify the series for the fit.

Load the U.S. equity indices data Data_EquityIdx.mat.

load Data_EquityIdx

The timetable DataTimeTable contains the daily NASDAQ closing prices, among other indices.

Compute the weekly average closing prices of all timetable variables.

DTTW = convert2weekly(DataTimeTable,Aggregation="mean");

Compute the weekly returns.

DTTRet = price2ret(DTTW);
T = height(DTTRet)

T = 
626

Plot the weekly NASDAQ returns.

figure
plot(DTTRet.Time,DTTRet.NASDAQ)
title("NASDAQ Weekly Returns")

The returns exhibit volatility clustering.

When you plan to supply a timetable, you must ensure it has all the following characteristics:

• The selected response variable is numeric and does not contain any missing values.

• The timestamps in the Time variable are regular, and they are ascending or descending.

Remove all missing values from the timetable, relative to the NASDAQ returns series.

DTTRet = rmmissing(DTTRet,DataVariables="NASDAQ");
numobs = height(DTTRet)

numobs = 
626

Because all sample times have observed NASDAQ returns, rmmissing does not remove any observations.

Determine whether the sampling timestamps have a regular frequency and are sorted.

areTimestampsRegular = isregular(DTTRet,"weeks")

areTimestampsRegular = logical
   1

areTimestampsSorted = issorted(DTTRet.Time)

areTimestampsSorted = logical
   1

areTimestampsRegular = 1 indicates that the timestamps of DTTRet represent a regular weekly sample. areTimestampsSorted = 1 indicates that the timestamps are sorted.

Specify a GARCH(1,1) model, and fit it to the series. Specify the entire timetable of returns and select the variable containing the NASDAQ returns.

Mdl = garch(1,1);
[EstMdl,EstParamCov] = estimate(Mdl,DTTRet,ResponseVariable="NASDAQ")

 
    GARCH(1,1) Conditional Variance Model (Gaussian Distribution):
 
                  Value       StandardError    TStatistic      PValue  
                __________    _____________    __________    __________

    Constant    1.7406e-06     8.9077e-07        1.9541        0.050694
    GARCH{1}       0.65947       0.059314        11.118      1.0229e-28
    ARCH{1}        0.33773       0.079595        4.2431      2.2044e-05

EstMdl = 
  garch with properties:

     Description: "GARCH(1,1) Conditional Variance Model (Gaussian Distribution)"
      SeriesName: "Y"
    Distribution: Name = "Gaussian"
               P: 1
               Q: 1
        Constant: 1.74062e-06
           GARCH: {0.659467} at lag [1]
            ARCH: {0.337731} at lag [1]
          Offset: 0

EstParamCov = 3×3

    0.0000   -0.0000    0.0000
   -0.0000    0.0035   -0.0039
    0.0000   -0.0039    0.0063

Specify Presample Data In Timetable

Since R2023a

Fit a GJR(1,1) model to the average weekly closing NASDAQ returns. Specify in-sample and presample data in a timetable.

Load the U.S. equity indices data Data_EquityIdx.mat.

load Data_EquityIdx

The timetable DataTimeTable contains the daily NASDAQ closing prices, among other indices.

Compute the weekly average closing prices of all timetable variables.

DTTW = convert2weekly(DataTimeTable,Aggregation="mean");

Compute the weekly returns.

DTTRet = price2ret(DTTW);
T = height(DTTRet)

T = 
626

Plot the weekly NASDAQ returns.

figure
plot(DTTRet.Time,DTTRet.NASDAQ)
title("NASDAQ Weekly Returns")

The returns exhibit volatility clustering.

When you plan to supply a timetable, you must ensure it has all the following characteristics:

• The selected response variable is numeric and does not contain any missing values.

• The timestamps in the Time variable are regular, and they are ascending or descending.

Remove all missing values from the timetable, relative to the NASDAQ returns series.

DTTRet = rmmissing(DTTRet,DataVariables="NASDAQ");
numobs = height(DTTRet)

numobs = 
626

Because all sample times have observed NASDAQ returns, rmmissing does not remove any observations.

Determine whether the sampling timestamps have a regular frequency and are sorted.

areTimestampsRegular = isregular(DTTRet,"weeks")

areTimestampsRegular = logical
   1

areTimestampsSorted = issorted(DTTRet.Time)

areTimestampsSorted = logical
   1

areTimestampsRegular = 1 indicates that the timestamps of DTTRet represent a regular weekly sample. areTimestampsSorted = 1 indicates that the timestamps are sorted.

Because $\max (p,q)=1$, one presample innovation is required to initialize this model. Partition the timetable of data into sets containing required presample and insample observations.

numpreobs = 1;
DTTRetPresample = DTTRet(1:numpreobs,:);
DTTRetInsample = DTTRet((numpreobs+1):end,:);

Specify a GJR(1,1) model, and fit it to the series. Specify the timetables of NASDAQ weekly returns for the required presample innovations and in-sample data.

Mdl = gjr(1,1);
[EstMdl,EstParamCov] = estimate(Mdl,DTTRetInsample,Presample=DTTRetPresample, ...
    ResponseVariable="NASDAQ",PresampleInnovationVariable="NASDAQ");

 
    GJR(1,1) Conditional Variance Model (Gaussian Distribution):
 
                     Value       StandardError    TStatistic      PValue   
                   __________    _____________    __________    ___________

    Constant       7.7296e-07     5.3835e-07        1.4358          0.15106
    GARCH{1}          0.77143       0.033165         23.26      1.1149e-119
    ARCH{1}          0.092918       0.033665        2.7601        0.0057785
    Leverage{1}       0.19222       0.050339        3.8185       0.00013428

The output EstMdl is a new gjr model with estimated parameters.

Use the output variance-covariance matrix to calculate the estimate standard errors.

se = sqrt(diag(EstParamCov))

se = 4×1

    0.0000
    0.0332
    0.0337
    0.0503

These are the standard errors shown in the estimation output display. They correspond (in order) to the constant, GARCH coefficient, ARCH coefficient, and leverage coefficient.

Input Arguments

Mdl — Partially specified conditional variance model

garch model object | egarch model object | gjr model object

Partially specified conditional variance model containing unknown parameters, specified as a garch, egarch, or gjr model object. Properties of Mdl describe the model structure and can specify parameter values.

estimate fits unspecified (NaN-valued) parameters to the data y.

estimate treats specified parameters as equality constraints during estimation.

y — Single path of observed response data y_t

numeric column vector

Single path of observed response data y_t, to which the conditional variance model Mdl is fit, specified as a numobs-by-1 numeric column vector. y represents numobs observations of a univariate time series.

y is usually a mean 0 series of innovations or residuals and conditional variance characterized by the conditional variance model Mdl. In this case, y is a continuation of the innovation series E0.

y can also represent an innovation series with mean 0 plus an offset. A nonzero value of Mdl.Offset signals the inclusion of an offset in Mdl.

The last observation of y is the latest observation.

Data Types: double

Tbl1 — Time series data

table | timetable

Since R2023a

Time series data containing response variable y_t, to which estimate fits the conditional variance model Mdl, specified as a table or timetable with numvars variables and numobs rows. You can optionally select a response variable by using the ResponseVariable name-value argument.

The selected response variable in Tbl1 is a numeric vector representing a single path of numobs observations.

Each row is an observation, and measurements in each row occur simultaneously.

If Tbl1 is a timetable, it must represent a sample with a regular datetime time step (see isregular), and the datetime vector Tbl1.Time must be strictly ascending or descending.

If Tbl1 is a table, the last row contains the latest observation.

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: Display="iter",E0=[0.1; 0.05] specifies to display iterative optimization information, and [0.05; 0.1] as presample innovations.

For GARCH, EGARCH, and GJR Models

ResponseVariable — Variable to select from Tbl1 to treat as response variable y_t

string scalar | character vector | integer | logical vector

Since R2023a

Variable to select from Tbl1 to treat as the response variable y_t, specified as one of the following data types:

• String scalar or character vector containing a variable name in Tbl1.Properties.VariableNames

• Variable index (integer) to select from Tbl1.Properties.VariableNames

• A length numvars logical vector, where ResponseVariable(j) = true selects variable j from Tbl1.Properties.VariableNames, and sum(ResponseVariable) is 1

The selected variable must be a numeric vector and cannot contain missing values (NaN).

If Tbl1 has one variable, the default specifies that variable. Otherwise, the default matches the variable to name in Mdl.SeriesName.

Example: ResponseVariable="StockRate2"

Example: ResponseVariable=[false false true false] or ResponseVariable=3 selects the third table variable as the response variable.

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

E0 — Presample innovations

numeric column vector

Presample innovations ε_t, specified as a numpreobs-by-1 numeric column vector. The presample innovations provide initial values for the innovations process of the conditional variance model Mdl. The presample innovations derive from a distribution with mean 0. Use E0 only when you supply the vector of response data y.

numpreobs is the number of presample observations. Each row is a presample observation. The last row contains the latest presample observation. numpreobs must be at least Mdl.Q. If numpreobs > Mdl.Q, estimate uses the latest required number of observations only. The last element or row contains the latest observation.

The defaults are:

• For GARCH(P,Q) and GJR(P,Q) models, estimate sets any necessary presample innovations to the square root of the average squared value of the offset-adjusted response series y.

• For EGARCH(P,Q) models, estimate sets any necessary presample innovations to zero.

Data Types: double

V0 — Presample conditional variances

positive numeric column vector

Presample conditional variances σ_t², specified as a numpreobs-by-1 positive column vector. V0 provides initial values for conditional variance process of the conditional variance model Mdl. Use V0 only when you supply the vector of response data y.

Each row is a presample observation. The last row contains the latest presample observation.

• For GARCH(P,Q) and GJR(P,Q) models, numpreobs must be at least Mdl.P.

• For EGARCH(P,Q) models,numpreobs must be at least max([Mdl.P Mdl.Q]).

If numpreobs exceeds the minimum number, estimate uses only the latest observations. The last element or row contains the latest observation.

By default, estimate sets the necessary presample conditional variances to the average squared value of the offset-adjusted response series y.

Data Types: double

Presample — Presample data

table | timetable

Since R2023a

Presample data for innovations ε_t or conditional variances σ_t² to initialize the model for estimation, specified as a table or timetable, the same type as Tbl1, with numprevars variables and numpreobs rows. Use Presample only when you supply a table or timetable of data Tbl1.

Each selected variable is a single path of numpreobs observations representing the presample of innovations or conditional variances for the selected response variable in Tbl1.

Each row is a presample observation, and measurements in each row occur simultaneously. numpreobs must be one of the following values:

• Mdl.P when Presample provides only presample conditional variances

• Mdl.Q when Presample provides only presample innovations

• max([Mdl.P Mdl.Q]) when Presample provides presample innovations and conditional variances

If you supply more rows than necessary, estimate uses the latest required number of observations only.

If Presample is a timetable, all the following conditions must be true:

• Presample must represent a sample with a regular datetime time step (see isregular).

• The inputs Tbl1 and Presample must be consistent in time such that Presample immediately precedes Tbl1 with respect to the sampling frequency and order.

• The datetime vector of sample timestamps Presample.Time must be ascending or descending.

If Presample is a table, the last row contains the latest presample observation.

By default:

• For GARCH(P,Q) and GJR(P,Q) models, estimate sets any necessary presample innovations to the square root of the average squared value of the offset-adjusted response series y.

• For EGARCH(P,Q) models, estimate sets any necessary presample innovations to zero.

• estimate sets the necessary presample conditional variances to the average squared value of the offset-adjusted response series.

If you specify the Presample, you must specify the presample innovations or conditional variance variable names by using the PresampleInnovationVariable or PresampleVarianceVariable name-value argument.

PresampleInnovationVariable — Variable of Presample containing data for the presample innovations ε_t

string scalar | character vector | integer | logical vector

Since R2023a

Variable of Presample containing data for the presample innovations ε_t, specified as one of the following data types:

• String scalar or character vector containing the variable name to select from Presample.Properties.VariableNames

• Variable index (positive integer) to select from Presample.Properties.VariableNames

• A logical vector, where PresampleInnovationVariable(j) = true selects variable j from Presample.Properties.VariableNames

The selected variable must be a numeric vector and cannot contain missing values (NaNs).

If you specify presample innovations data by using the Presample name-value argument, you must specify PresampleInnovationVariable.

Example: PresampleInnovationVariable="StockRateInnov0"

Example: PresampleInnovationVariable=[false false true false] or PresampleInnovationVariable=3 selects the third table variable as the presample innovations variable.

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

PresampleVarianceVariable — Variable of Presample containing data for the presample conditional variances σ_t²

string scalar | character vector | integer | logical vector

Since R2023a

Variable of Presample containing data for the presample conditional variances σ_t², specified as one of the following data types:

• String scalar or character vector containing a variable name in Presample.Properties.VariableNames

• Variable index (positive integer) to select from Presample.Properties.VariableNames

• A logical vector, where PresampleVarianceVariable(j) = true selects variable j from Presample.Properties.VariableNames

The selected variable must be a numeric vector and cannot contain missing values (NaNs).

If you specify presample conditional variance data by using the Presample name-value argument, you must specify PresampleVarianceVariable.

Example: PresampleVarianceVariable="StockRateVar0"

Example: PresampleVarianceVariable=[false false true false] or PresampleVarianceVariable=3 selects the third table variable as the presample conditional variance variable.

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

Options — Optimization options

optimoptions optimization controller

Optimization options, specified as an optimoptions optimization controller. For details on modifying the default values of the optimizer, see optimoptions or fmincon in Optimization Toolbox™.

For example, to change the constraint tolerance to 1e-6, set options = optimoptions(@fmincon,ConstraintTolerance=1e-6,Algorithm="sqp"). Then, pass Options into estimate using Options=options.

By default, estimate uses the same default options as fmincon, except Algorithm is "sqp" and ConstraintTolerance is 1e-7.

Constant0 — Initial conditional variance model constant estimate

numeric scalar

Initial conditional variance model constant estimate, specified as a numeric scalar.

For GARCH(P,Q) and GJR(P,Q) models, Constant0 must be a positive scalar.

By default, estimate derives initial estimates using standard time series techniques.

Data Types: double

GARCH0 — Initial coefficient estimates for past conditional variance terms

numeric vector

Initial coefficient estimates for past conditional variance terms, specified as a numeric vector.

• For GARCH(P,Q) and GJR(P,Q) models:

  • GARCH0 must be a numeric vector containing nonnegative elements.

  • GARCH0 contains the initial coefficient estimates associated with the past conditional variance terms that compose the GARCH polynomial.

• For EGARCH(P,Q) models,GARCH0 contains the initial coefficient estimates associated with past log conditional variance terms that compose the GARCH polynomial.

The number of coefficients in GARCH0 must equal the number of lags associated with nonzero coefficients in the GARCH polynomial, as specified in the GARCHLags property of Mdl.

By default, estimate derives initial estimates using standard time series techniques.

Data Types: double

ARCH0 — Initial coefficient estimates corresponding to past innovation terms

numeric vector

Initial coefficient estimates corresponding to past innovation terms, specified as a numeric vector.

• For GARCH(P,Q) and GJR(P,Q) models:

  • ARCH0 must be a numeric vector containing nonnegative elements.

  • ARCH0 contains the initial coefficient estimates associated with the past squared innovation terms that compose the ARCH polynomial.

  • By default, estimate derives initial estimates using standard time series techniques.

• For EGARCH(P,Q) models:

  • ARCH0 contains the initial coefficient estimates associated with the magnitude of the past standardized innovations that compose the ARCH polynomial.

  • By default, estimate sets the initial coefficient estimate associated with the first nonzero lag in the model to a small positive value. All other values are zero.

The number of coefficients in ARCH0 must equal the number of lags associated with nonzero coefficients in the ARCH polynomial, as specified in the ARCHLags property of Mdl.

Data Types: double

Offset0 — Initial innovation mean model offset estimate

scalar

Initial innovation mean model offset estimate, specified as a scalar.

By default, estimate sets the initial estimate to the sample mean of y.

Data Types: double

DoF0 — Initial estimate of t-distribution degrees-of-freedom parameter

10 (default) | positive scalar

Initial estimate of the t-distribution degrees-of-freedom parameter ν, specified as a positive scalar. DoF0 must exceed 2.

Data Types: double

Display — Command Window display option

"params" (default) | "diagnostics" | "full'" | "iter" | "off" | string vector | cell vector of character vectors

Command Window display option, specified as one or more of the values in this table.

Value	Information Displayed
"diagnostics"	Optimization diagnostics
"full"	Maximum likelihood parameter estimates, standard errors, t statistics, iterative optimization information, and optimization diagnostics
"iter"	Iterative optimization information
"off"	None
"params"	Maximum likelihood parameter estimates, standard errors, and t statistics and p-values of coefficient significance tests

Example: Display="off" is well suited for running a simulation that estimates many models.

Example: Display=["params" "diagnostics"] displays all estimation results and the optimization diagnostics.

Data Types: char | cell | string

For EGARCH and GJR Models

Leverage0 — Initial coefficient estimates past leverage terms ξ

numeric vector

Initial coefficient estimates past leverage terms, specified as a numeric vector.

For EGARCH(P,Q) models, Leverage0 contains the initial coefficient estimates associated with past standardized innovation terms that compose the leverage polynomial.

For GJR(P,Q) models, Leverage0 contains the initial coefficient estimates associated with past, squared, negative innovations that compose the leverage polynomial.

The number of coefficients in Leverage0 must equal the number of lags associated with nonzero coefficients in the leverage polynomial (Leverage), as specified in LeverageLags.

By default, estimate sets the initial estimate of the coefficient associated with the first non-zero lag in the model to a small negative value, and it sets all others initial coefficients to zero.

Data Types: double

Note

• NaN values in Y, E0, and V0 indicate missing values. estimate removes missing values from specified data by list-wise deletion.

  • For the presample, estimate horizontally concatenates E0 and V0, and then it removes any row of the concatenated matrix containing at least one NaN.

  • For the estimation sample, estimate removes any row of Y containing at least one NaN.

  This type of data reduction reduces the effective sample size and can create an irregular time series.

• For numeric data inputs, estimate assumes that you synchronize the presample data such that the latest observations occur simultaneously.

• estimate issues an error when any table or timetable input contains missing values.

Output Arguments

EstMdl — Conditional variance model containing parameter estimates

garch model object | egarch model object | gjr model object

Conditional variance model containing parameter estimates, returned as a garch, egarch, or gjr model object. estimate uses maximum likelihood to calculate all parameter estimates not constrained by Mdl (i.e., constrained parameters have known values).

EstMdl is a fully specified conditional variance model. To infer conditional variances for diagnostic checking, pass EstMdl to infer. To simulate or forecast conditional variances, pass EstMdl to simulate or forecast, respectively.

EstParamCov — Variance-covariance matrix of maximum likelihood estimates

numeric matrix

Variance-covariance matrix of maximum likelihood estimates of model parameters known to the optimizer, returned as a numeric matrix.

The rows and columns associated with any parameters estimated by maximum likelihood contain the covariances of estimation error. The standard errors of the parameter estimates are the square root of the entries along the main diagonal.

The rows and columns associated with any parameters that are held fixed as equality constraints contain 0s.

estimate uses the outer product of gradients (OPG) method to perform covariance matrix estimation.

estimate orders the parameters in EstParamCov as follows:

• Constant

• Nonzero GARCH coefficients at positive lags

• Nonzero ARCH coefficients at positive lags

• For EGARCH and GJR models, nonzero leverage coefficients at positive lags

• Degrees of freedom (t innovation distribution only)

• Offset (models with nonzero offset only)

Data Types: double

logL — Optimized loglikelihood objective function value

scalar

Optimized loglikelihood objective function value, returned as a scalar.

Data Types: double

info — Optimization summary

structure array

Optimization summary, returned as a structure array with the fields described in this table.

Field	Description
exitflag	Optimization exit flag (see fmincon in Optimization Toolbox)
options	Optimization options controller (see optimoptions and fmincon in Optimization Toolbox)
X	Vector of final parameter estimates
X0	Vector of initial parameter estimates

For example, you can display the vector of final estimates by entering info.X in the Command Window.

Data Types: struct

Tips

• To access values of the estimation results, including the number of free parameters in the model, pass EstMdl to summarize.

Algorithms

• If you do not specify the presample data (E0 and V0 , or Presample), estimate derives the necessary presample observations from the unconditional, or long-run, variance of the offset-adjusted response process.

  • For all conditional variance models, presample conditional variances are the sample average of the squared disturbances of the offset-adjusted response data.

  • For GARCH(P,Q) and GJR(P,Q) models, presample innovations are the square root of the average squared value of the offset-adjusted response data.

  • For EGARCH(P,Q) models, presample innovations are 0.

  These specifications minimize initial transient effects.

• If you specify a value for the Display name-value argument, it takes precedence over the specifications of the optimization options Diagnostics and Display. Otherwise, estimate honors all selections related to the display of optimization information in the optimization options.

References

[1] Bollerslev, Tim. “Generalized Autoregressive Conditional Heteroskedasticity.” Journal of Econometrics 31 (April 1986): 307–27. https://doi.org/10.1016/0304-4076(86)90063-1.

[2] Bollerslev, Tim. “A Conditionally Heteroskedastic Time Series Model for Speculative Prices and Rates of Return.” The Review of Economics and Statistics 69 (August 1987): 542–47. https://doi.org/10.2307/1925546.

[3] Box, G. E. P., G. M. Jenkins, and G. C. Reinsel. Time Series Analysis: Forecasting and Control. 3rd ed. Englewood Cliffs, NJ: Prentice Hall, 1994.

[4] Enders, W. Applied Econometric Time Series. Hoboken, NJ: John Wiley & Sons, 1995.

[5] Engle, Robert. F. “Autoregressive Conditional Heteroscedasticity with Estimates of the Variance of United Kingdom Inflation.” Econometrica 50 (July 1982): 987–1007. https://doi.org/10.2307/1912773.

[6] Glosten, L. R., R. Jagannathan, and D. E. Runkle. “On the Relation between the Expected Value and the Volatility of the Nominal Excess Return on Stocks.” The Journal of Finance. Vol. 48, No. 5, 1993, pp. 1779–1801.

[7] Greene, W. H. Econometric Analysis. 3rd ed. Upper Saddle River, NJ: Prentice Hall, 1997.

[8] Hamilton, James D. Time Series Analysis. Princeton, NJ: Princeton University Press, 1994.

Version History

Introduced in R2012a

R2023a: estimate accepts input data in tables and timetables

In addition to accepting input data (in-sample and presample data) in numeric arrays, estimate accepts input data in tables or regular timetables. When you supply data in a table or timetable, estimate chooses the default series on which to operate, but you can use the specified optional name-value argument to select a different series.

Name-value arguments to support tabular workflows include:

• ResponseVariable specifies the variable name of the response series in the input data Tbl1, to which the model is fit.

• Presample specifies the input table or timetable of presample innovations and conditional variance data.

• PresampleInnovationVariable specifies the variable name of the innovations series to select from Presample.

• PresampleVarianceVariable specifies the variable name of the conditional variance series to select from Presample.

R2019b: estimate includes the final lag in all estimated univariate time series model polynomials

estimate includes the final polynomial lag as specified in the input model template for estimation. In other words, the specified polynomial degrees of an input model template returned by an object creation function and the corresponding polynomial degrees of the estimated model returned by estimate are equal.

Before R2019b, estimate removed trailing lags estimated below the tolerance of 1e-12.

Update Code

Polynomial degrees require minimum presample observations for operations downstream of estimation, such as model forecasting and simulation. If a model template in your code does not describe the data generating process well, then the polynomials in the estimated model can have higher degrees than in previous releases. Consequently, you must supply additional presample responses for operations on the estimated model; otherwise, the function issues an error. For more details, see the Y0 name-value argument.