Special Model Types

PoolModel{T}

Implements several model averaging methods to pool the predictions of different models. Currently, PoolModel only works for pooling two different models, although it can be extended to more models. Confer with the paper for details.

The available methods are

• dynamic: weights on pooled models evolve over time and are treated as a stochastic process.

• static: weights on pooled models are assumed time-invariant.

• equal: weights are set to 1/2.

• bma: weights are updated according to Bayesian model averaging.

The default method is dynamic, which implements the Dynamic Pools method developed by Del Negro et al. (2016). To choose another method, use the keyword weight_type::Symbol, e.g.

pm = PoolModel(weight_type = :static) # creates a static PoolModel

The weight_type is stored as a setting, so users can retrieve at any point by using get_setting.

Fields

Parameters

• parameters::Vector{AbstractParameter}: Vector of all time-invariant hyperparameters for the chosen method of model averaging.

• keys::OrderedDict{Symbol,Int}: Maps human-readable names for predictive densities of pooled models.

Inputs to Measurement and Equilibrium Condition Equations

• model::OrderedDict{Symbol,AbstractDSGEModel}: Maps name to its underlying model object.

Model Specifications and Settings

• spec::String: The model specification identifier, "an_schorfheide", cached here for filepath computation.

• subspec::String: The model subspecification number, indicating that some parameters from the original model spec ("ss0") are initialized differently. Cached here for filepath computation.

• settings::Dict{Symbol,Setting}: Settings/flags that affect computation without changing the economic or mathematical setup of the model.

• test_settings::Dict{Symbol,Setting}: Settings/flags for testing mode

Other Fields

• rng::MersenneTwister: Random number generator. Can be is seeded to ensure reproducibility in algorithms that involve randomness (such as Metropolis-Hastings).

• testing::Bool: Indicates whether the model is in testing mode. If true, settings from m.test_settings are used in place of those in m.settings.

• observable_mappings::OrderedDict{Symbol,Observable}: A dictionary that stores data sources, series mnemonics, and transformations to/from model units. DSGE.jl will fetch data from the Federal Reserve Bank of St. Louis's FRED database; all other data must be downloaded by the user. See load_data and Observable for further details.

estimate_bma(m, data, prior; return_output = false, filestring_addl = [])

Estimate a Bayesian Model Average.

Arguments:

• m::PoolModel: PoolModel object

Optional Arguments:

• data: well-formed data as Matrix or DataFrame. If this is not provided, the load_data routine will be executed.
• prior::Float64: prior probability between the two models

Keyword Arguments:

• return_output::Bool: option to return output. If false, nothing is returned.
• filestring_addl::Vector{String}: Additional strings to append to output files.

sample_λ(m, pred_dens, θs, T = -1; parallel = true) where S<:AbstractFloat
sample_λ(m, pred_dens, T = -1; parallel = true) where S<:AbstractFloat

Computes and samples from the conditional density p(λt|θ, It, P) for particle in θs, which represents the posterior distribution. The sampled λ particles represent the posterior distribution p(λ{t|t} | It, P).

If no posterior distribution is passed in, then the function computes the distribution of λ_{t|t} for a static pool.

Inputs

• m::PoolModel{S}: PoolModel object
• pred_dens::Matrix{S}: matrix of predictive densities
• θs::Matrix{S}: matrix of particles representing posterior distribution of θ
• T::Int64: final period for tempered particle filter

where S<:AbstractFloat.

Keyword Argument

• parallel::Bool: use parallel computing to compute and sample draws of λ

Outputs

• λ_sample::Vector{Float64}: sample of draws of λs; together with (θ,λ) represents a joint density

```

propgate_λ(λvec, h, m, θvec) where T<:AbstractFloat

Propagates a λ particle h periods forward.

Inputs

• λ::T: λ sample from (θ,λ) joint distribution
• h::Int64: forecast horizon
• m::PoolModel: PoolModel object
• θvec::Vector{T}: optional vector of parameters to update PoolModel

```

compute_Eλ(m, h, λvec, θmat = [], weights = [];
    current_period = true, parallel = true) where T<:AbstractFloat

Computes and samples from the conditional density p(λt|θ, It, P) for particle in θs, which represents the posterior distribution.

Inputs

• m::PoolModel{T}: PoolModel object
• h::Int64: forecast horizon
• λvec::Vector{T}: vector of particles of λ samples from (θ,λ) joint distribution
• `θmat::Matrix{T}': matrix of posterior parameter samples
• weights::Vector{T}: weights of λ particles, defaults to equal weights

Keyword Argument

• current_period::Bool: compute Eλ for current period t
• parallel::Bool: use parallel computing to compute and sample λ
• get_dpp_pred_dens::Bool: compute predictive densities according to dynamic prediction pools

Outputs

• λhat_tplush::Float64: E[λ{t+h|t} | It^P, P]
• λhat_t::Float64: E[λ{t|t} | It^P, P]

```

DSGEVAR{T} <: AbstractDSGEVARModel{T}

implements a simple interface for combining a given DSGE model with a VAR to create a DSGE-VAR. Confer with Del Negro and Schorfheide (2004), Del Negro and Schorfheide (2006), Del Negro, Schorfheide, Smets, and Wouters (2007), and/or Del Negro and Schorfheide (2009) for details about DSGE-VARs. We recommend the first two papers as initial introductions to DSGE-VARs.

The recommended constructor requires the user to provide (1) an AbstractDSGEModel object, (2) which structural shocks from the DSGE to use, and (3) the subspec (optional, defaults to "ss0"). If the subspec "ss0" is used, then the result is a DSGEVAR whose VAR component is "empty" in that the observables, lags, and λ weight are not specified. The reason why this constructor requires the user to specify which structural shocks of DSGE to use is that this information is DSGE-specific rather than information about the VAR.

However, we can also construct a DSGEVAR without having to specify the structural shocks when calling the constructor, although we still need to give an instance of an AbstractDSGEModel.

Example

The code below instantiates an empty DSGEVAR with AnSchorfheide as the underlying DSGE and then calls update! on the empty DSGE-VAR to add information about the desired DSGE-VAR spec.

dsgevar = DSGEVAR(AnSchorfheide())
DSGE.update!(dsgevar, shocks = [:rm_sh, :z_sh, :g_sh],
    observables = [:obs_gdp, :obs_cpi, :obs_nominalrate],
    λ = 1., lags = 4)

Fields

DSGE object

• dsge::AbstractDSGEModel{T}: underlying DSGE model object

DSGE-VAR Information

• observables::OrderedDict{Symbol,Int}: dictionary mapping observables of the VAR to their index in the matrices representing the DSGE-VAR
• shocks::OrderedDict{Symbol,Int}: dictionary mapping structural shocks in the DSGE to their index in the matrices representing the DSGE-VAR
• lags::Int: number of lags in the VAR
• λ::T: weight on the DSGE prior

Auxiliary Information

• spec::String: concatenates dsgevar with the spec of the DSGE, e.g. for AnSchorfheide, we have dsgevar_an_schorfheide.
• subspec::String: specifies the model subspecification. Cached here for filepath computation.
• testing::Bool: indicates whether the model is in testing mode. Currently, this setting has no uses in practice

DSGEVECM{T} <: AbstractDSGEVECMModel{T}

implements a simple interface for combining a given DSGE model with a VECM (a VAR with cointegrating terms) to create a DSGE-VECM. Confer with Del Negro and Schorfheide (2006) and/or Del Negro, Schorfheide, Smets, and Wouters (2007) for details about DSGE-VECMs. We recommend the first paper as an initial introduction to DSGE-VECMs.

The recommended constructor requires the user to provide (1) an AbstractDSGEModel object, (2) which structural shocks from the DSGE to use, and (3) the subspec (optional, defaults to "ss0"). If the subspec "ss0" is used, then the result is a DSGEVECM whose VECM component is "empty" in that the observables, cointegrating relationships, lags, and λ weight are not specified. The reason why this constructor requires the user to specify which structural shocks of DSGE to use is that this information is DSGE-specific rather than information about the VECM.

However, we can also construct a DSGEVECM without having to specify the structural shocks when calling the constructor, although we still need to give an instance of an AbstractDSGEModel.

Example

The code below instantiates an empty DSGEVECM with AnSchorfheide as the underlying DSGE and then calls update! on the empty DSGE-VECM to add information about the desired DSGE-VECM spec.

dsgevecm = DSGEVECM(AnSchorfheide())
DSGE.update!(dsgevecm, shocks = [:rm_sh, :z_sh, :g_sh],
    observables = [:obs_gdp, :obs_cpi, :obs_nominalrate],
    λ = 1., lags = 4)

Fields

DSGE object

• dsge::AbstractDSGEModel{T}: underlying DSGE model object

DSGE-VECM Information

• observables::OrderedDict{Symbol,Int}: dictionary mapping observables of the VECM to their index in the matrices representing the DSGE-VECM.
• cointegrating::OrderedDict{Symbol,Int}: dictionary mapping cointegrating relationships of the VECM to their index in the matrices representing the DSGE-VECM. When creating the state space representation of a DSGE-VECM, the cointegrating relationships will come after the observables. Accordingly, the first cointegrating index will be after the last observable.
• cointegrating_add::OrderedDict{Symbol,Int}: dictionary mapping additional cointegrating relationships of the VECM to their index in the matrices representing the DSGE-VECM. These relationships are intended to be ones that only add to the DD matrix in DSGE.jl's representation of a state space model. Importantly, these relationships do not require changing the ZZ matrix. As a result, the indices for these relationships start at 1.
• shocks::OrderedDict{Symbol,Int}: dictionary mapping structural shocks in the DSGE to their index in the matrices representing the DSGE-VECM
• lags::Int: number of lags in the VECM
• λ::T: weight on the DSGE prior

Auxiliary Information

• spec::String: concatenates dsgevar with the spec of the DSGE, e.g. for AnSchorfheide, we have dsgevar_an_schorfheide.
• subspec::String: specifies the model subspecification. Cached here for filepath computation.
• testing::Bool: indicates whether the model is in testing mode. Currently, this setting has no uses in practice

draw_VECM(YYYYC, XXYYC, XXXXC, T̄, n_obs, lags, n_coint; standard_orientation = true)

draws β and Σ from the distribution p(β, Σ | Y, θ) implied by the population moments (or covariances) YYYYC, XXYYC, and XXXXC for a VECM with parameters θ.

For example, if these population moments are generated by a DSGE-VECM, then θ are the structural parameters of the DSGE and the weight λ placed on the cross-restrictions implied by the DSGE. The population moments would represent the moments of the sample data and dummy observables generated to implement the DSGE prior.

Given these moments, we compute the maximum-likelihood estimates of β and Σ using OLS. Denote these estimates by Β and S. Then we generate draws from p(β, Σ | Y, θ) using the fact that

Σ | Y, θ ∼ ℐ𝒲 (T̄ × S, T̄ - (1 + lags * n_obs), n_obs),
β | Y, Σ,θ ∼ 𝒩 (B, Σ ⊗ XXXXC⁻¹).

Inputs

• YYYYC::Matrix{<:Real}: covariance of observables
• XXYYC::Matrix{<:Real}: covariance of observables with their lags
• XXXXC::Matrix{<:Real}: covariance of the lags of the observables
• T̄::Int: total number of time periods of observations, including sample observables from actual data and any dummy observables generated to implement priors.
• n_obs::Int: number of distinct observables
• lags::Int: number of lags in the VECM
• n_coint::Int: number of distinct cointegrating relationships

Keywords

• standard_orientation::Bool: if true, the draw of β has dimensions (n_obs * lags) x n_obs. Otherwise, it has the transposed dimensions.
• All other keywords are used for testing purposes.

draw_stationary_VAR(YYYYC, XXYYC, XXXXC, T̄, n_obs, lags; standard_orientation = true)
draw_stationary_VAR(YYYYC, XXYYC, XXXXC, T̄; standard_orientation = true)

draws β and Σ from the distribution p(β, Σ | Y, θ) implied by the population moments (or covariances) YYYYC, XXYYC, and XXXXC for a VAR with parameters θ.

For example, if these population moments are generated by a DSGE-VAR, then θ are the structural parameters of the DSGE and the weight λ placed on the cross-restrictions implied by the DSGE. The population moments would represent the moments of the sample data and dummy observables generated to implement the DSGE prior.

Given these moments, we compute the maximum-likelihood estimates of β and Σ using OLS. Denote these estimates by Β and S. Then we generate draws from p(β, Σ | Y, θ) using the fact that

Σ | Y, θ ∼ ℐ𝒲 (T̄ × S, T̄ - (1 + lags * n_obs), n_obs),
β | Y, Σ,θ ∼ 𝒩 (B, Σ ⊗ XXXXC⁻¹).

Finally, we check that these draws generate a stationary state space system. If they do not, then we keep drawing until we obtain a pair of draws (β, Σ) that are stationary.

Inputs

• YYYYC::Matrix{<:Real}: covariance of observables
• XXYYC::Matrix{<:Real}: covariance of observables with their lags
• XXXXC::Matrix{<:Real}: covariance of the lags of the observables
• T̄::Int: total number of time periods of observations, including sample observables from actual data and any dummy observables generated to implement priors.
• n_obs::Int: number of distinct observables
• lags::Int: number of lags in the VAR

Keywords

• standard_orientation::Bool: if true, the draw of β has dimensions (n_obs * lags) x n_obs. Otherwise, it has the transposed dimensions.
• All other keywords are used for testing purposes.

var_approx_state_space(TTT, RRR, QQQ, DD, ZZ, EE, MM, p; get_population_moments = false,
use_intercept = false) where {S<:Real}

computes the VAR(p) approximation of the linear state space system

sₜ = TTT * sₜ₋₁ + RRR * ϵₜ,
yₜ = ZZ * sₜ + DD + uₜ,

where the disturbances are assumed to follow

ϵₜ ∼ 𝒩 (0, QQ),
uₜ = ηₜ + MM * ϵₜ,
ηₜ ∼ 𝒩 (0, EE).

The MM matrix implies

cov(ϵₜ, uₜ) = QQ * MM'.

Outputs

If get_population_moments = false:

• β: VAR(p) coefficients
• Σ: innovations variance-covariance matrix for the VAR(p) representation

yₜ = Xₜβ + μₜ

where Xₜ appropriately stacks the constants and p lags of yₜ, and μₜ ∼ 𝒩 (0, Σ).

If get_population_moments = true: we return the limit cross product matrices.

• yyyyd: 𝔼[y,y]
• XXXXd: 𝔼[y,X(lag rr)]
• XXyyd: 𝔼[X(lag rr),X(lag ll)]

Using these matrices, the VAR(p) representation is given by

β = XXXXd \ XXyyd
Σ = yyyyd - XXyyd' * β

The keyword use_intercept specifies whether or not to use an intercept term in the VAR approximation.

vecm_approx_state_space(TTT, RRR, QQQ, DD, ZZ, EE, MM, n_obs, p, n_coint,
n_coint, n_coint_add, DD_coint_add; get_population_moments = false,
use_intercept = false) where {S<:Real}

computes the VECM(p) approximation of the linear state space system

sₜ = TTT * sₜ₋₁ + RRR * ϵₜ,
yₜ = ZZ * sₜ + DD + uₜ,

where the disturbances are assumed to follow

ϵₜ ∼ 𝒩 (0, QQ),
uₜ = ηₜ + MM * ϵₜ,
ηₜ ∼ 𝒩 (0, EE).

The MM matrix implies

cov(ϵₜ, uₜ) = QQ * MM'.

Outputs

If get_population_moments = false:

• β: VECM(p) coefficients. The first n_coint + n_coint_add

coefficients for each observable comprise the error correction terms, while the following 1 + p * n_obs terms are the VAR terms.

• Σ: innovations variance-covariance matrix for the VECM(p) representation

Δyₜ = eₜβₑ + Xₜβᵥ + μₜ

where βₑ are the coefficients for the error correction terms; eₜ are the error correction terms specifying the cointegrating relationships; βᵥ are the coefficients for the VAR terms; Xₜ appropriately stacks the constants and p lags of Δyₜ; and μₜ ∼ 𝒩 (0, Σ).

Note that the error correction terms satisfy the mapping eₜ' = C * yₜ₋₁, where C is a matrix.

If get_population_moments = true: we return the limit cross product matrices.

• yyyyd: 𝔼[y,y]
• XXXXd: 𝔼[y,X(lag rr)]
• XXyyd: 𝔼[X(lag rr),X(lag ll)]

Note that in the rows of XXyyd and the rows and columns of XXXXd, the cointegrating relationships are stacked above the constants and lagged Δyₜ.

Using these matrices, the VAR(p) representation is given by

β = XXXXd \ XXyyd
Σ = yyyyd - XXyyd' * β,

where β has dimensions n_obs × (n_coint + n_coint_add + 1 + p * n_obs), and Σ has dimensions n_obs × n_obs.

The keyword use_intercept specifies whether or not to use an intercept term in the VECM approximation.

function compute_DD_coint_add(m::AbstractDSGEVECMModel{S}, system::System,
cointegrating_add::Vector{Symbol}) where {S <: Real}

computes DD_coint_add for a DSGEVECM model. This vector holds additional cointegrating relationships that do not require changes to the ZZ matrix.

Note

We recommend overloading this function if there are cointegrating relationships which a user does not want to add to the underlying DSGE. The function compute_system first checks for a method compute_DD_coint_add that takes a Type tuple of (model_type, Vector{Symbol}) and then (model_type, ) before calling this method.

This function is generally intended to be internal. As an example of other such functions, eqcond must be user-defined but is primarily used internally and not directly called by the user in a script.

dsgevar_likelihood(YYYY::Matrix{S}, XXYY::Matrix{S},
    XXXX::Matrix{S}, YYYYD::Matrix{S}, XXYYD::Matrix{S},
    XXXXD::Matrix{S}, T::Int, λ::S,
    lags::Int, n_obs::Int) where {S<:Real}

evaluates the likelihood of a DSGE-VAR given the population moments of the raw data (YYYY, XXYY, XXXX) and the population moments implied by the DSGE prior (YYYYD, XXYYD, XXXXD).

Other Inputs

• T: number of time periods in data
• λ: weight placed on the DSGE prior
• lags: number of lags in the VAR
• n_obs: number of observables (e.g. number of time series).

dsgevecm_likelihood(m::AbstractDSGEVECMModel{S}, data::Matrix{S};
    apply_altpolicy::Bool = false) where {S<:Real}

evaluates the likelihood of a DSGE-VECM. It is assumed that get_λ(m) retrieves the prior weight λ on the DSGE.

The matrix data is assumed an nobs x T+lags matrix, where the lags indicate we cut off the data for presampling.

In the future, this function may be combined with dsgevar_likelihood because the two functions are almost exactly the same. We currently have them implemented separately so that the naming convention does not create any confusion. One can think of DSGE-VECMs as DSGE-VARs with an additional regressor that corrects for errors to account for cointegration, hence it would not be "wrong" per se to add a couple if-else conditions inside dsgevar_likelihood and let this function cover both DSGE-VARs and DSGE-VECMS. But the current decision to have separate functions makes it clear that the dsgevar_likelihood specifically operates on DSGE-VARs without an error correction term, and dsgevecm_likelihood operates on DSGE-VECMs specifically.

dsgevecm_likelihood(YYYY::Matrix{S}, XXYY::Matrix{S},
    XXXX::Matrix{S}, YYYYD::Matrix{S}, XXYYD::Matrix{S},
    XXXXD::Matrix{S}, T::Int, λ::S,
    lags::Int, n_obs::Int,
    coint_inds::Union{Vector{Int}, UnitRange{Int}}) where {S<:Real}

evaluates the likelihood of a DSGE-VECM given the population moments of the raw data (YYYY, XXYY, XXXX) and the population moments implied by the DSGE prior (YYYYD, XXYYD, XXXXD).

Other Inputs

• T: number of time periods in data
• λ: weight placed on the DSGE prior
• lags: number of lags in the VECM
• n_obs: number of observables (e.g. number of time series).
• coint_inds: indices of the cointegrated observables