estimate

Fit vector autoregression (VAR) model to data

Syntax

EstMdl = estimate(Mdl,Y)

EstMdl = estimate(Mdl,Y,Name,Value)

[EstMdl,EstSE] = estimate(___)

[EstMdl,EstSE,logL,E] = estimate(___)

Description

EstMdl = estimate(Mdl,Y) returns a fully specified VAR(p) model. This model stores the estimated parameter values resulting from fitting the VAR(p) model Mdl to the observed multivariate response series Y using maximum likelihood.

EstMdl = estimate(Mdl,Y,Name,Value) uses additional options specified by one or more name-value pair arguments. For example, you can specify presample responses or exogenous predictor data.

[EstMdl,EstSE] = estimate(___) returns the estimated, asymptotic standard errors of the estimated parameters using any of the input arguments in the previous syntaxes.

[EstMdl,EstSE,logL,E] = estimate(___) returns the optimized loglikelihood objective function value (logL) and the multivariate residuals (E).

Examples

Estimate VAR(4) Model

Fit a VAR(4) model to the consumer price index (CPI) and unemployment rate data.

Load the Data_USEconModel data set.

load Data_USEconModel

Plot the two series on separate plots.

figure;
plot(DataTable.Time,DataTable.CPIAUCSL);
title('Consumer Price Index');
ylabel('Index');
xlabel('Date');

figure;
plot(DataTable.Time,DataTable.UNRATE);
title('Unemployment Rate');
ylabel('Percent');
xlabel('Date');

Stabilize the CPI by converting it to a series of growth rates. Synchronize the two series by removing the first observation from the unemployment rate series.

rcpi = price2ret(DataTable.CPIAUCSL);
unrate = DataTable.UNRATE(2:end);

Create a default VAR(4) model using the shorthand syntax.

Mdl = varm(2,4)

Mdl = 
  varm with properties:

     Description: "2-Dimensional VAR(4) Model"
     SeriesNames: "Y1"  "Y2" 
       NumSeries: 2
               P: 4
        Constant: [2×1 vector of NaNs]
              AR: {2×2 matrices of NaNs} at lags [1 2 3 ... and 1 more]
           Trend: [2×1 vector of zeros]
            Beta: [2×0 matrix]
      Covariance: [2×2 matrix of NaNs]

Mdl is a varm model object. All properties containing NaN values correspond to parameters to be estimated given data.

Estimate the model using the entire data set.

EstMdl = estimate(Mdl,[rcpi unrate])

EstMdl = 
  varm with properties:

     Description: "AR-Stationary 2-Dimensional VAR(4) Model"
     SeriesNames: "Y1"  "Y2" 
       NumSeries: 2
               P: 4
        Constant: [0.00171639 0.316255]'
              AR: {2×2 matrices} at lags [1 2 3 ... and 1 more]
           Trend: [2×1 vector of zeros]
            Beta: [2×0 matrix]
      Covariance: [2×2 matrix]

EstMdl is an estimated varm model object. It is fully specified because all parameters have known values. The description indicates that the autoregressive polynomial is stationary.

Display summary statistics from the estimation.

summarize(EstMdl)

 
   AR-Stationary 2-Dimensional VAR(4) Model
 
    Effective Sample Size: 241
    Number of Estimated Parameters: 18
    LogLikelihood: 811.361
    AIC: -1586.72
    BIC: -1524
 
                      Value       StandardError    TStatistic      PValue  
                   ___________    _____________    __________    __________

    Constant(1)      0.0017164      0.0015988         1.0735        0.28303
    Constant(2)        0.31626       0.091961          3.439      0.0005838
    AR{1}(1,1)         0.30899       0.063356          4.877     1.0772e-06
    AR{1}(2,1)         -4.4834         3.6441        -1.2303        0.21857
    AR{1}(1,2)      -0.0031796      0.0011306        -2.8122       0.004921
    AR{1}(2,2)          1.3433       0.065032         20.656      8.546e-95
    AR{2}(1,1)         0.22433       0.069631         3.2217      0.0012741
    AR{2}(2,1)          7.1896          4.005         1.7951       0.072631
    AR{2}(1,2)       0.0012375      0.0018631         0.6642        0.50656
    AR{2}(2,2)        -0.26817        0.10716        -2.5025       0.012331
    AR{3}(1,1)         0.35333       0.068287         5.1742     2.2887e-07
    AR{3}(2,1)           1.487         3.9277        0.37858          0.705
    AR{3}(1,2)       0.0028594      0.0018621         1.5355        0.12465
    AR{3}(2,2)        -0.22709         0.1071        -2.1202       0.033986
    AR{4}(1,1)       -0.047563       0.069026       -0.68906        0.49079
    AR{4}(2,1)          8.6379         3.9702         2.1757       0.029579
    AR{4}(1,2)     -0.00096323      0.0011142       -0.86448        0.38733
    AR{4}(2,2)        0.076725       0.064088         1.1972        0.23123

 
   Innovations Covariance Matrix:
    0.0000   -0.0002
   -0.0002    0.1167

 
   Innovations Correlation Matrix:
    1.0000   -0.0925
   -0.0925    1.0000

Specify Presample Values

Fit a VAR(4) model to the consumer price index (CPI) and unemployment rate data. The estimation sample starts at Q1 of 1980.

Load the Data_USEconModel data set.

load Data_USEconModel

Stabilize the CPI by converting it to a series of growth rates. Synchronize the two series by removing the first observation from the unemployment rate series.

rcpi = price2ret(DataTable.CPIAUCSL);
unrate = DataTable.UNRATE(2:end);

Identify the index corresponding to the start of the estimation sample.

estIdx = DataTable.Time(2:end) > '1979-12-31';

Create a default VAR(4) model using the shorthand syntax.

Mdl = varm(2,4);

Estimate the model using the estimation sample. Specify all observations before the estimation sample as presample data. Display a full estimation summary.

Y0 = [rcpi(~estIdx) unrate(~estIdx)];
EstMdl = estimate(Mdl,[rcpi(estIdx) unrate(estIdx)],'Y0',Y0,'Display',"full");

 
   AR-Stationary 2-Dimensional VAR(4) Model
 
    Effective Sample Size: 117
    Number of Estimated Parameters: 18
    LogLikelihood: 419.837
    AIC: -803.674
    BIC: -753.955
 
                     Value       StandardError    TStatistic      PValue  
                   __________    _____________    __________    __________

    Constant(1)      0.003564      0.0024697         1.4431        0.14898
    Constant(2)       0.29922        0.11882         2.5182       0.011795
    AR{1}(1,1)       0.022379       0.092458        0.24204        0.80875
    AR{1}(2,1)        -2.6318         4.4484       -0.59163         0.5541
    AR{1}(1,2)     -0.0082357      0.0020373        -4.0425     5.2884e-05
    AR{1}(2,2)         1.2567        0.09802          12.82     1.2601e-37
    AR{2}(1,1)        0.20954        0.10182         2.0581       0.039584
    AR{2}(2,1)         10.106         4.8987          2.063       0.039117
    AR{2}(1,2)      0.0058667       0.003194         1.8368       0.066236
    AR{2}(2,2)       -0.14226        0.15367       -0.92571        0.35459
    AR{3}(1,1)        0.56095       0.098691         5.6839     1.3167e-08
    AR{3}(2,1)        0.44406         4.7483       0.093518        0.92549
    AR{3}(1,2)      0.0049062       0.003227         1.5204        0.12841
    AR{3}(2,2)      -0.040037        0.15526       -0.25787         0.7965
    AR{4}(1,1)       0.046125        0.11163        0.41321        0.67945
    AR{4}(2,1)          6.758         5.3707         1.2583        0.20827
    AR{4}(1,2)     -0.0030032       0.002018        -1.4882         0.1367
    AR{4}(2,2)       -0.14412       0.097094        -1.4843        0.13773

 
   Innovations Covariance Matrix:
    0.0000   -0.0003
   -0.0003    0.0790

 
   Innovations Correlation Matrix:
    1.0000   -0.1686
   -0.1686    1.0000

Because the VAR model degree p is 4, estimate uses only the last four observations in Y0 as a presample.

Include Exogenous Predictor Variables

Estimate a VAR(4) model of consumer price index (CPI), the unemployment rate, and real gross domestic product (GDP). Include a linear regression component containing the current quarter and the last four quarters of government consumption expenditures and investment (GCE).

Load the Data_USEconModel data set. Compute the real GDP.

load Data_USEconModel
DataTable.RGDP = DataTable.GDP./DataTable.GDPDEF*100;

Plot all variables on separate plots.

figure;
subplot(2,2,1)
plot(DataTable.Time,DataTable.CPIAUCSL);
ylabel('Index');
title('Consumer Price Index');
subplot(2,2,2)
plot(DataTable.Time,DataTable.UNRATE);
ylabel('Percent');
title('Unemployment Rate');
subplot(2,2,3)
plot(DataTable.Time,DataTable.RGDP);
ylabel('Output');
title('Real Gross Domestic Product')
subplot(2,2,4)
plot(DataTable.Time,DataTable.GCE);
ylabel('Billions of $');
title('Government Expenditures')

Stabilize the CPI, GDP, and GCE series by converting each to a series of growth rates. Synchronize the unemployment rate series with the others by removing its first observation.

inputVariables = {'CPIAUCSL' 'RGDP' 'GCE'};
Data = varfun(@price2ret,DataTable,'InputVariables',inputVariables);
Data.Properties.VariableNames = inputVariables;
Data.UNRATE = DataTable.UNRATE(2:end);

Expand the GCE rate series to a matrix that includes its current value and up through four lagged values. Remove the GCE variable from Data.

rgcelag4 = lagmatrix(Data.GCE,0:4);
Data.GCE = [];

Create a default VAR(4) model using the shorthand syntax. You do not have to specify the regression component when creating the model.

Mdl = varm(3,4);

Estimate the model using the entire sample. Specify the GCE rate matrix as data for the regression component. Extract standard errors and the loglikelihood value.

[EstMdl,EstSE,logL] = estimate(Mdl,Data.Variables,'X',rgcelag4);

Display the regression coefficient matrix.

EstMdl.Beta

ans = 3×5

    0.0777   -0.0892   -0.0685   -0.0181    0.0330
    0.1450   -0.0304    0.0579   -0.0559    0.0185
   -2.8138   -0.1636    0.3905    1.1799   -2.3328

EstMdl.Beta is a 3-by-5 matrix. Rows correspond to response series, and columns correspond to predictors.

Display the matrix of standard errors corresponding to the coefficient estimates.

EstSE.Beta

ans = 3×5

    0.0250    0.0272    0.0275    0.0274    0.0243
    0.0368    0.0401    0.0405    0.0403    0.0358
    1.4552    1.5841    1.6028    1.5918    1.4145

EstSE.Beta is commensurate with EstMdl.Beta.

Display the loglikelihood value.

logL

logL = 1.7056e+03

Input Arguments

Mdl — VAR model

varm model object

VAR model containing unknown parameter values, specified as a varm model object returned by varm.

NaN-valued elements in properties indicate unknown, estimable parameters. Specified elements indicate equality constraints on parameters in model estimation. The innovations covariance matrix Mdl.Covariance cannot contain a mix of NaN values and real numbers; you must fully specify the covariance or it must be completely unknown (NaN(Mdl.NumSeries)).

Y — Observed multivariate response series

numeric matrix

Observed multivariate response series to which estimate fits the model, specified as a numobs-by-numseries numeric matrix.

numobs is the sample size. numseries is the number of response variables (Mdl.NumSeries).

Rows correspond to observations, and the last row contains the latest observation.

Columns correspond to individual response variables.

Y represents the continuation of the presample response series in Y0.

Data Types: double

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Y0',Y0,'X',X uses the matrix Y0 as presample responses required for estimation and includes a linear regression component composed of the predictor data in X.

'Y0' — Presample responses

numeric matrix

Presample responses to initiate the model estimation, specified as the comma-separated pair consisting of 'Y0' and a numpreobs-by-numseries numeric matrix.

numpreobs is the number of presample observations.

Rows correspond to presample observations, and the last row contains the latest observation. Y0 must have at least Mdl.P rows. If you supply more rows than necessary, estimate uses the latest Mdl.P observations only.

Columns must correspond to the response series in Y.

By default, estimate uses Y(1:Mdl.P,:) as presample observations, and then fits the model to Y((Mdl.P + 1):end,:). This action reduces the effective sample size.

Data Types: double

'X' — Predictor data

numeric matrix

Predictor data for the regression component in the model, specified as the comma-separated pair consisting of 'X' and a numeric matrix containing numpreds columns.

numpreds is the number of predictor variables.

Rows correspond to observations, and the last row contains the latest observation. estimate does not use the regression component in the presample period. X must have at least as many observations as are used after the presample period.

• If you specify Y0, then X must have at least numobs rows (see Y).

• Otherwise, X must have at least numobs – Mdl.P observations to account for the presample removal.

In either case, if you supply more rows than necessary, estimate uses the latest observations only.

Columns correspond to individual predictor variables. All predictor variables are present in the regression component of each response equation.

By default, estimate excludes the regression component, regardless of its presence in Mdl.

Data Types: double

'Display' — Estimation information display type

"off" (default) | "table" | "full"

Estimation information display type, specified as the comma-separated pair consisting of 'Display' and a value in this table.

Value	Description
"off"	estimate does not display estimation information at the command line.
"table"	estimate displays a table of estimation information. Rows correspond to parameters, and columns correspond to estimates, standard errors, t statistics, and p values.
"full"	In addition to a table of summary statistics, estimate displays the estimated innovations covariance and correlation matrices, loglikelihood value, Akaike Information Criterion (AIC), Bayesian Information Criterion (BIC), and other estimation information.

Example: 'Display',"full"

Data Types: string | char

'MaxIterations' — Maximum number of solver iterations allowed

1000 (default) | positive numeric scalar

Maximum number of solver iterations allowed, specified as the comma-separated pair consisting of 'MaxIterations' and a positive numeric scalar.

estimate dispatches MaxIterations to mvregress.

Data Types: double

Note

NaN values in Y, Y0, and X indicate missing values. estimate removes missing values from the data by list-wise deletion.

• For the presample, estimate removes any row containing at least one NaN.

• For the estimation sample, estimate removes any row of the concatenated data matrix [Y X] containing at least one NaN.

This type of data reduction reduces the effective sample size.

Output Arguments

EstMdl — Estimated VAR(p) model

varm model object

Estimated VAR(p) model, returned as a varm model object. EstMdl is a fully specified varm model.

estimate uses mvregress to implement multivariate normal, maximum likelihood estimation. For more details, see Estimation of Multivariate Regression Models (Statistics and Machine Learning Toolbox).

EstSE — Estimated, asymptotic standard errors of estimated parameters

structure array

Estimated, asymptotic standard errors of the estimated parameters, returned as a structure array containing the fields in this table.

Field	Description
Constant	Standard errors of model constants corresponding to the estimates in EstMdl.Constant, a numseries-by-1 numeric vector
AR	Standard errors of the autoregressive coefficients corresponding to estimates in EstMdl.AR, a cell vector with elements corresponding to EstMdl.AR
Beta	Standard errors of regression coefficients corresponding to the estimates in EstMdl.Beta, a numseries-by-numpreds numeric matrix
Trend	Standard errors of linear time trends corresponding to the estimates in EstMdl.Trend, a numseries-by-1 numeric vector

If estimate applies equality constraints during estimation by fixing any parameters to a value, then corresponding standard errors of those parameters are 0.

estimate extracts all standard errors from the inverse of the expected Fisher information matrix returned by mvregress (see Standard Errors (Statistics and Machine Learning Toolbox)).

logL — Optimized loglikelihood objective function value

numeric scalar

Optimized loglikelihood objective function value, returned as a numeric scalar.

E — Multivariate residuals

numeric matrix

Multivariate residuals from the fitted model, returned as a numeric matrix containing numseries columns.

• If you specify Y0, then E has numobs rows (see Y).

• Otherwise, E has numobs – Mdl.P rows to account for the presample removal.

References

[1] Hamilton, J. D. Time Series Analysis. Princeton, NJ: Princeton University Press, 1994.

[2] Johansen, S. Likelihood-Based Inference in Cointegrated Vector Autoregressive Models. Oxford: Oxford University Press, 1995.

[3] Juselius, K. The Cointegrated VAR Model. Oxford: Oxford University Press, 2006.

[4] Lütkepohl, H. New Introduction to Multiple Time Series Analysis. Berlin: Springer, 2005.