# empiricalbvarm

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

## 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

### Syntax

``Mdl = empiricalbvarm(numseries,numlags,'CoeffDraws',CoeffDraws,'SigmaDraws',SigmaDraws)``
``Mdl = empiricalbvarm(numseries,numlags,'CoeffDraws',CoeffDraws,'SigmaDraws',SigmaDraws,Name,Value)``

### Description

example

``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 $\lambda =\text{vec}\left(\Lambda \right)=\text{vec}\left({\left[\begin{array}{ccccccc}{\Phi }_{1}& {\Phi }_{2}& \cdots & {\Phi }_{p}& c& \delta & Β\end{array}\right]}^{\prime }\right)$ 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).`
``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 pair 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:

`$\left[\stackrel{{y}_{1,t}}{\overbrace{\begin{array}{ccccccccccc}{\varphi }_{1,11}& {\varphi }_{1,12}& {\varphi }_{2,11}& {\varphi }_{2,12}& {\varphi }_{3,11}& {\varphi }_{3,12}& {c}_{1}& {\beta }_{11}& {\beta }_{12}& {\beta }_{13}& {\beta }_{14}\end{array}}}\text{\hspace{0.17em}}\text{\hspace{0.17em}}\stackrel{{y}_{2,t}}{\overbrace{\begin{array}{ccccccccccc}{\varphi }_{1,21}& {\varphi }_{1,22}& {\varphi }_{2,21}& {\varphi }_{2,22}& {\varphi }_{3,21}& {\varphi }_{3,22}& {c}_{2}& {\beta }_{21}& {\beta }_{22}& {\beta }_{23}& {\beta }_{24}\end{array}}}\right],$`

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
`false`Response equations do not include a model constant.
`true`All 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
`false`Response equations do not include a linear time trend term.
`true`All 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 y`j`,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

 `summarize` Distribution 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.

`$\left[\begin{array}{l}{\text{INFL}}_{t}\\ {\text{UNRATE}}_{t}\\ {\text{FEDFUNDS}}_{t}\end{array}\right]=c+\sum _{j=1}^{4}{\Phi }_{j}\left[\begin{array}{l}{\text{INFL}}_{t-j}\\ {\text{UNRATE}}_{t-j}\\ {\text{FEDFUNDS}}_{t-j}\end{array}\right]+\left[\begin{array}{c}{\epsilon }_{1,t}\\ {\epsilon }_{2,t}\\ {\epsilon }_{3,t}\end{array}\right].$`

For all $t$, ${\epsilon }_{t}$ is a series of independent 3-D normal innovations with a mean of 0 and covariance $\Sigma$.

You can create an empirical Bayesian VAR model for the coefficients ${\left[{\Phi }_{1},...,{\Phi }_{4},\mathit{c}\right]}^{\prime }$ and innovations covariance matrix $\Sigma$ 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:

• $\mathrm{vec}\left({\left[{\Phi }_{1},...,{\Phi }_{4},\mathit{c}\right]}^{\prime }\right)|\Sigma \sim {Ν}_{39}\left(\mu ,\mathit{V}\right)$, where $\mu$ is a 39-by-1 vector of means and $\mathit{V}$ is the 39-by-39 covariance matrix.

• $\Sigma \sim Inverse\phantom{\rule{0.16666666666666666em}{0ex}}Wishart\left(\Omega ,\nu \right)$, where $\Omega$ is the 3-by-3 scale matrix and $\nu$ 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)```

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 $\lambda \text{\hspace{0.17em}}$ and $\Sigma \text{\hspace{0.17em}}$ 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 ```