Main Content

empiricalbvarm

Bayesian vector autoregression (VAR) model with samples from prior or posterior distribution

Since R2020a

Description

The Bayesian VAR model object empiricalbvarm contains samples from the distributions of the coefficients Λ and innovations covariance matrix Σ of a VAR(p) model, which MATLAB® uses to characterize the corresponding prior or posterior distributions.

For Bayesian VAR model objects that have an intractable posterior, the estimate function returns an empiricalbvarm object representing the empirical posterior distribution. However, if you have random draws from the prior or posterior distributions of the coefficients and innovations covariance matrix, you can create a Bayesian VAR model with an empirical prior directly by using empiricalbvarm.

Creation

Description

Mdl = empiricalbvarm(numseries,numlags,'CoeffDraws',CoeffDraws,'SigmaDraws',SigmaDraws) creates a numseries-D Bayesian VAR(numlags) model object Mdl characterized by the random samples from the prior or posterior distributions of λ=vec(Λ)=vec([Φ1Φ2ΦpcδΒ]) and Σ, CoeffDraws and SigmaDraws, respectively.

  • numseries = m, a positive integer specifying the number of response time series variables.

  • numlags = p, a nonnegative integer specifying the AR polynomial order (that is, number of numseries-by-numseries AR coefficient matrices in the VAR model).

example

Mdl = empiricalbvarm(numseries,numlags,'CoeffDraws',CoeffDraws,'SigmaDraws',SigmaDraws,Name,Value) sets writable properties (except NumSeries and P) using name-value pair arguments. Enclose each property name in quotes. For example, empiricalbvarm(3,2,'CoeffDraws',CoeffDraws,'SigmaDraws',SigmaDraws,'SeriesNames',["UnemploymentRate" "CPI" "FEDFUNDS"]) specifies the random samples from the distributions of λ and Σ and the names of the three response variables.

Because the posterior distributions of a semiconjugate prior model (semiconjugatebvarm) are analytically intractable, estimate returns an empiricalbvarm object that characterizes the posteriors and contains the Gibbs sampler draws from the full conditionals.

Input Arguments

expand all

Number of time series m, specified as a positive integer. numseries specifies the dimensionality of the multivariate response variable yt and innovation εt.

numseries sets the NumSeries property.

Data Types: double

Number of lagged responses in each equation of yt, specified as a nonnegative integer. The resulting model is a VAR(numlags) model; each lag has a numseries-by-numseries coefficient matrix.

numlags sets the P property.

Data Types: double

Properties

expand all

You can set writable property values when you create the model object by using name-value argument syntax, or after you create the model object by using dot notation. For example, to create a 3-D Bayesian VAR(1) model from the coefficient and innovations covariance arrays of draws CoeffDraws and SigmaDraws, respectively, and then label the response variables, enter:

Mdl = empiricalbvarm(3,1,'CoeffDraws',CoeffDraws,'SigmaDraws',SigmaDraws);
Mdl.SeriesNames = ["UnemploymentRate" "CPI" "FEDFUNDS"];

Required Draws from Distribution

Random sample from the prior or posterior distribution of λ, specified as a NumSeries*k-by-numdraws numeric matrix, where k = NumSeries*P + IncludeIntercept + IncludeTrend + NumPredictors (the number of coefficients in a response equation). CoeffDraws represents the empirical distribution of λ based on a size numdraws sample.

Columns correspond to successive draws from the distribution. CoeffDraws(1:k,:) corresponds to all coefficients in the equation of response variable SeriesNames(1), CoeffDraws((k + 1):(2*k),:) corresponds to all coefficients in the equation of response variable SeriesNames(2), and so on. For a set of row indices corresponding to an equation:

  • Elements 1 through NumSeries correspond to the lag 1 AR coefficients of the response variables ordered by SeriesNames.

  • Elements NumSeries + 1 through 2*NumSeries correspond to the lag 2 AR coefficients of the response variables ordered by SeriesNames.

  • In general, elements (q – 1)*NumSeries + 1 through q*NumSeries correspond to the lag q AR coefficients of the response variables ordered by SeriesNames.

  • If IncludeConstant is true, element NumSeries*P + 1 is the model constant.

  • If IncludeTrend is true, element NumSeries*P + 2 is the linear time trend coefficient.

  • If NumPredictors > 0, elements NumSeries*P + 3 through k constitute the vector of regression coefficients of the exogenous variables.

This figure shows the row structure of CoeffDraws for a 2-D VAR(3) model that contains a constant vector and four exogenous predictors:

[ϕ1,11ϕ1,12ϕ2,11ϕ2,12ϕ3,11ϕ3,12c1β11β12β13β14y1,tϕ1,21ϕ1,22ϕ2,21ϕ2,22ϕ3,21ϕ3,22c2β21β22β23β24y2,t],

where

  • ϕq,jk is element (j,k) of the lag q AR coefficient matrix.

  • cj is the model constant in the equation of response variable j.

  • Bju is the regression coefficient of the exogenous variable u in the equation of response variable j.

CoeffDraws and SigmaDraws must be based on the same number of draws, and both must represent draws from either the prior or posterior distribution.

numdraws should be reasonably large, for example, 1e6.

Data Types: double

Random sample from the prior or posterior distribution of Σ, specified as a NumSeries-by-NumSeries-by-numdraws array of positive definite numeric matrices. SigmaDraws represents the empirical distribution of Σ based on a size numdraws sample.

Rows and columns correspond to innovations in the equations of the response variables ordered by SeriesNames. Columns correspond to successive draws from the distribution.

CoeffDraws and SigmaDraws must be based on the same number of draws, and both must represent draws from either the prior or posterior distribution.

numdraws should be reasonably large, for example, 1e6.

Data Types: double

Model Characteristics and Dimensionality

Model description, specified as a string scalar or character vector. The default value describes the model dimensionality, for example '2-Dimensional VAR(3) Model'.

Example: "Model 1"

Data Types: string | char

This property is read-only.

Number of time series m, specified as a positive integer. NumSeries specifies the dimensionality of the multivariate response variable yt and innovation εt.

Data Types: double

This property is read-only.

Multivariate autoregressive polynomial order, specified as a nonnegative integer. P is the maximum lag that has a nonzero coefficient matrix.

P specifies the number of presample observations required to initialize the model.

Data Types: double

Response series names, specified as a NumSeries length string vector. The default is ['Y1' 'Y2' ... 'YNumSeries']. empiricalbvarm stores SeriesNames as a string vector.

Example: ["UnemploymentRate" "CPI" "FEDFUNDS"]

Data Types: string

Flag for including a model constant c, specified as a value in this table.

ValueDescription
falseResponse equations do not include a model constant.
trueAll response equations contain a model constant.

Data Types: logical

Flag for including a linear time trend term δt, specified as a value in this table.

ValueDescription
falseResponse equations do not include a linear time trend term.
trueAll response equations contain a linear time trend term.

Data Types: logical

Number of exogenous predictor variables in the model regression component, specified as a nonnegative integer. empiricalbvarm includes all predictor variables symmetrically in each response equation.

VAR Model Parameters Derived from Distribution Draws

This property is read-only.

Distribution mean of the autoregressive coefficient matrices Φ1,…,Φp associated with the lagged responses, specified as a P-D cell vector of NumSeries-by-NumSeries numeric matrices.

AR{j} is Φj, the coefficient matrix of lag j. Rows correspond to equations and columns correspond to lagged response variables; SeriesNames determines the order of response variables and equations. Coefficient signs are those of the VAR model expressed in difference-equation notation.

If P = 0, AR is an empty cell. Otherwise, AR is the collection of AR coefficient means extracted from Mu.

Data Types: cell

This property is read-only.

Distribution mean of the model constant c (or intercept), specified as a NumSeries-by-1 numeric vector. Constant(j) is the constant in equation j; SeriesNames determines the order of equations.

If IncludeConstant = false, Constant is an empty array. Otherwise, Constant is the model constant vector mean extracted from Mu.

Data Types: double

This property is read-only.

Distribution mean of the linear time trend δ, specified as a NumSeries-by-1 numeric vector. Trend(j) is the linear time trend in equation j; SeriesNames determines the order of equations.

If IncludeTrend = false (the default), Trend is an empty array. Otherwise, Trend is the linear time trend coefficient mean extracted from Mu.

Data Types: double

This property is read-only.

Distribution mean of the regression coefficient matrix B associated with the exogenous predictor variables, specified as a NumSeries-by-NumPredictors numeric matrix.

Beta(j,:) contains the regression coefficients of each predictor in the equation of response variable j yj,t. Beta(:,k) contains the regression coefficient in each equation of predictor xk. By default, all predictor variables are in the regression component of all response equations. You can down-weight a predictor from an equation by specifying, for the corresponding coefficient, a prior mean of 0 in Mu and a small variance in V.

When you create a model, the predictor variables are hypothetical. You specify predictor data when you operate on the model (for example, when you estimate the posterior by using estimate). Columns of the predictor data determine the order of the columns of Beta.

Data Types: double

This property is read-only.

Distribution mean of the innovations covariance matrix Σ of the NumSeries innovations at each time t = 1,...,T, specified as a NumSeries-by-NumSeries positive definite numeric matrix. Rows and columns correspond to innovations in the equations of the response variables ordered by SeriesNames.

Data Types: double

Object Functions

summarizeDistribution summary statistics of Bayesian vector autoregression (VAR) model

Examples

collapse all

Consider the 3-D VAR(4) model for the US inflation (INFL), unemployment (UNRATE), and federal funds (FEDFUNDS) rates.

[INFLtUNRATEtFEDFUNDSt]=c+j=14Φj[INFLt-jUNRATEt-jFEDFUNDSt-j]+[ε1,tε2,tε3,t].

For all t, εt is a series of independent 3-D normal innovations with a mean of 0 and covariance Σ.

You can create an empirical Bayesian VAR model for the coefficients [Φ1,...,Φ4,c] and innovations covariance matrix Σ in two ways:

  1. Indirectly create an empiricalbvarm model by estimating the posterior distribution of a semiconjugate prior model.

  2. Directly create an empiricalbvarm model by supplying draws from the prior or posterior distribution of the parameters.

Indirect Creation

Assume the following prior distributions:

  • vec([Φ1,...,Φ4,c])|ΣΝ39(μ,V), where μ is a 39-by-1 vector of means and V is the 39-by-39 covariance matrix.

  • ΣInverseWishart(Ω,ν), where Ω is the 3-by-3 scale matrix and ν is the degrees of freedom.

Create a semiconjugate prior model for the 3-D VAR(4) model parameters.

numseries = 3;
numlags = 4;
PriorMdl = semiconjugatebvarm(numseries,numlags)
PriorMdl = 
  semiconjugatebvarm with properties:

        Description: "3-Dimensional VAR(4) Model"
          NumSeries: 3
                  P: 4
        SeriesNames: ["Y1"    "Y2"    "Y3"]
    IncludeConstant: 1
       IncludeTrend: 0
      NumPredictors: 0
                 Mu: [39x1 double]
                  V: [39x39 double]
              Omega: [3x3 double]
                DoF: 13
                 AR: {[3x3 double]  [3x3 double]  [3x3 double]  [3x3 double]}
           Constant: [3x1 double]
              Trend: [3x0 double]
               Beta: [3x0 double]
         Covariance: [3x3 double]

PriorMdl is a semiconjugatebvarm Bayesian VAR model object representing the prior distribution of the coefficients and innovations covariance of the 3-D VAR(4) model.

Load the US macroeconomic data set. Compute the inflation rate. Plot all response series.

load Data_USEconModel
seriesnames = ["INFL" "UNRATE" "FEDFUNDS"];
DataTimeTable.INFL = 100*[NaN; price2ret(DataTimeTable.CPIAUCSL)];
figure
plot(DataTimeTable.Time,DataTimeTable{:,seriesnames})
legend(seriesnames)

Figure contains an axes object. The axes object contains 3 objects of type line. These objects represent INFL, UNRATE, FEDFUNDS.

Stabilize the unemployment and federal funds rates by applying the first difference to each series.

DataTimeTable.DUNRATE = [NaN; diff(DataTimeTable.UNRATE)];
DataTimeTable.DFEDFUNDS = [NaN; diff(DataTimeTable.FEDFUNDS)];
seriesnames(2:3) = "D" + seriesnames(2:3);

Remove all missing values from the data.

rmDataTimeTable = rmmissing(DataTimeTable);

Estimate the posterior distribution by passing the prior model and entire data series to estimate.

rng(1); % For reproducibility
PosteriorMdl = estimate(PriorMdl,rmDataTimeTable{:,seriesnames},'Display','off')
PosteriorMdl = 
  empiricalbvarm with properties:

        Description: "3-Dimensional VAR(4) Model"
          NumSeries: 3
                  P: 4
        SeriesNames: ["Y1"    "Y2"    "Y3"]
    IncludeConstant: 1
       IncludeTrend: 0
      NumPredictors: 0
         CoeffDraws: [39x10000 double]
         SigmaDraws: [3x3x10000 double]
                 AR: {[3x3 double]  [3x3 double]  [3x3 double]  [3x3 double]}
           Constant: [3x1 double]
              Trend: [3x0 double]
               Beta: [3x0 double]
         Covariance: [3x3 double]

PosteriorMdl is an empiricalbvarm model representing the empirical posterior distribution of the coefficients and innovations covariance matrix. empiricalbvarm stores the draws from the posteriors of λ and Σ in the CoeffDraws and SigmaDraws properties, respectively.

Direct Creation

Draw a random sample of size 1000 from the prior distribution PriorMdl.

numdraws = 1000;
[CoeffDraws,SigmaDraws] = simulate(PriorMdl,'NumDraws',numdraws);
size(CoeffDraws)
ans = 1×2

          39        1000

size(SigmaDraws)
ans = 1×3

           3           3        1000

Create a Bayesian VAR model characterizing the empirical prior distributions of the parameters.

PriorMdlEmp = empiricalbvarm(numseries,numlags,'CoeffDraws',CoeffDraws,...
    'SigmaDraws',SigmaDraws)
PriorMdlEmp = 
  empiricalbvarm with properties:

        Description: "3-Dimensional VAR(4) Model"
          NumSeries: 3
                  P: 4
        SeriesNames: ["Y1"    "Y2"    "Y3"]
    IncludeConstant: 1
       IncludeTrend: 0
      NumPredictors: 0
         CoeffDraws: [39x1000 double]
         SigmaDraws: [3x3x1000 double]
                 AR: {[3x3 double]  [3x3 double]  [3x3 double]  [3x3 double]}
           Constant: [3x1 double]
              Trend: [3x0 double]
               Beta: [3x0 double]
         Covariance: [3x3 double]

Display the prior covariance mean matrices of the four AR coefficients by setting each matrix in the cell to a variable.

AR1 = PriorMdlEmp.AR{1}
AR1 = 3×3

   -0.0198    0.0181   -0.0273
   -0.0207   -0.0301   -0.0070
   -0.0009    0.0638    0.0113

AR2 = PriorMdlEmp.AR{2}
AR2 = 3×3

   -0.0453    0.0371    0.0110
   -0.0103   -0.0304   -0.0011
    0.0277   -0.0253    0.0061

AR3 = PriorMdlEmp.AR{3}
AR3 = 3×3

    0.0368   -0.0059    0.0018
   -0.0306   -0.0106    0.0179
   -0.0314   -0.0276    0.0116

AR4 = PriorMdlEmp.AR{4}
AR4 = 3×3

    0.0159    0.0406   -0.0315
   -0.0178    0.0415   -0.0024
    0.0476   -0.0128   -0.0165

More About

expand all

Version History

Introduced in R2020a

See Also

Functions

Objects