Estimation

Procedure

The goal of the estimation step is to sample from the posterior distribution of the model parameters. DSGE.jl uses either a Metropolis-Hastings or Sequential Monte Carlo sampler to do this. The Metropolis-Hastings sampler requires as a proposal covariance matrix the Hessian matrix corresponding to the posterior mode. Depending on the value of the model setting sampling_method (which can be checked via get_setting(m, :sampling_method) and set via m <= Setting(:sampling_method, :SMC), the function estimate will either find the mode, compute the Hessian, and run Metropolis-Hastings (if get_setting(m, :sampling_method)==:MH)) or run Sequential Monte Carlo (if get-setting(m, :sampling_method)==:SMC).

Metropolis Hastings

Main Steps:

Initialization: Read in and transform raw data from save/input_data/. See Input Data for more details.
Reoptimize parameter vector: The main program will call the csminwel optimization routine (located in csminwel.jl) to find modal parameter estimates.
Compute Hessian matrix: Computing the Hessian matrix to scale the proposal distribution in the Metropolis-Hastings algorithm.
Sample from Posterior: Posterior sampling is performed using the Metropolis-Hastings algorithm. A proposal distribution is constructed centered at the posterior mode and with proposal covariance scaled by the inverse of the Hessian matrix. Settings for the number of sampling blocks and the size of those blocks can be altered as described in Editing or Extending a Model.

Remark: In addition to saving each mh_thin-th draw of the parameter vector, the estimation program also saves the resulting posterior value and transition equation matrices implied by each draw of the parameter vector. This is to save time in the forecasting step since that code can avoid recomputing those matrices.

To run the entire procedure, the user simply calls the estimate routine:

DSGE.estimate — Function.

estimate(m, data; verbose=:low, proposal_covariance=Matrix(), method=:SMC)

Estimate the DSGE parameter posterior distribution.

Arguments:

m::AbstractModel: model object

Optional Arguments:

data: well-formed data as Matrix or DataFrame. If this is not provided, the load_data routine will be executed.

Keyword Arguments:

verbose::Symbol: The desired frequency of function progress messages printed to standard out.
- :none: No status updates will be reported.
- :low: Status updates will be provided in csminwel and at each block in Metropolis-Hastings.
- :high: Status updates provided at each iteration in Metropolis-Hastings.
proposal_covariance::Matrix: Used to test the metropolis_hastings algorithm with a precomputed covariance matrix for the proposal distribution. When the Hessian is singular, eigenvectors corresponding to zero eigenvectors are not well defined, so eigenvalue decomposition can cause problems. Passing a precomputed matrix allows us to ensure that the rest of the routine has not broken.
method::Symbol: The method to use when sampling from the posterior distribution. Can be either :MH for standard Metropolis Hastings Markov Chain Monte Carlo, or :SMC for Sequential Monte Carlo.
mle: Set to true if parameters should be estimated by maximum likelihood directly. If this is set to true, this function will return after estimating parameters.
sampling: Set to false to disable sampling from the posterior.

source

Optimizing or Reoptimizing

Generally, the user will want to reoptimize the parameter vector (and consequently, calculate the Hessian at this new mode) every time they conduct posterior sampling; that is, when:

the input data are updated with a new quarter of observations or revised
the model sub-specification is changed
the model is derived from an existing model with different equilibrium conditions or measurement equation.

This behavior can be controlled more finely.

Reoptimize from a Specified Starting Vector

Reoptimize the model starting from the parameter values supplied in a specified file. Ensure that you supply an HDF5 file with a variable named params that is the correct dimension and data type.

m = Model990()
params = load_parameters_from_file(m, "path/to/parameter/file.h5")
update!(m, params)
estimate(m)

Skip Reoptimization Entirely

You can provide a modal parameter vector and optionally a Hessian matrix calculated at that mode to skip the reoptimization entirely. These values are usually computed by the user previously.

You can skip reoptimization of the parameter vector entirely.

m = Model990()
specify_mode!(m, "path/to/parameter/mode/file.h5")
estimate(m)

The specify_mode! function will update the parameter vector to the mode and skip reoptimization by setting the reoptimize model setting. Ensure that you supply an HDF5 file with a variable named params that is the correct dimension and data type. (See also the utility function load_parameters_from_file.)

Calculating the Hessian

By default, estimate will recompute the Hessian matrix. You can skip calculation of the Hessian matrix entirely if you provide a file with a Hessian that has been pre-computed.

m = Model990()
specify_mode!(m, "path/to/parameter/mode/file.h5")
specify_hessian(m, "path/to/Hessian/matrix/file.h5")
estimate(m)

The specify_hessian function will cause estimate to read in the Hessian matrix rather than calculating it directly. Ensure that you supply an HDF5 file with a variable named hessian that is the correct dimension and data type. Specifying the Hessian matrix but not the parameter mode results in undefined behavior.

See [Hessian Approximation] for more details on the Hessian computation.

Computing the Posterior

In DSGE.jl, the function posterior computes the value of the posterior distribution at a given parameter vector. It calls the likelihood function, which in turn calls the filter routine. See Estimation routines for more details on these functions.

We implement the Kalman Filter via the filter function to compute the log-likelihood, and add this to the log prior to obtain the log posterior. See StateSpaceRoutines.jl for a model-independent implementation of the Kalman filter.

Sequential Monte Carlo

Procedure

Main Steps:

Initialization: Read in and transform raw data from save/input_data/. See Input Data for more details.
Sample from Posterior: Posterior sampling is performed using the Sequential Monte Carlo algorithm. A cloud of particles and their weights is initialized from the prior. These particles are mutated and their weights adjusted based on each value's likelihood. Settings for the number of particles, tempering schedule, and various other settings can be altered as described in Editing or Extending a Model.

To run the entire procedure, the user simply calls the estimate routine:

Missing docstring.

Missing docstring for DSGE.estimate. Check Documenter's build log for details.

The user can also call smc(m, df) explicitly (where m is a model object and df is a DataFrame

Computing the Posterior

Estimation routines

Prior, Likelihood and Posterior calculations

DSGE.prior — Function.

prior(m::AbstractModel{T})

Calculates log joint prior density of m.parameters.

source

DSGE.likelihood — Function.

likelihood(m::AbstractModel, data::Matrix{T};
           sampler::Bool = false, catch_errors::Bool = false) where {T<:AbstractFloat}

Evaluate the DSGE likelihood function. Can handle two-part estimation where the observed sample contains both a normal stretch of time (in which interest rates are positive) and a stretch of time in which interest rates reach the zero lower bound. If there is a zero-lower-bound period, then we filter over the 2 periods separately. Otherwise, we filter over the main sample all at once.

Arguments

m: The model object
data: matrix of data for observables

Optional Arguments

sampler: Whether metropolis_hastings or smc is the caller. If sampler=true, the transition matrices for the zero-lower-bound period are returned in a dictionary.
catch_errors: If sampler = true, GensysErrors should always be caught.

source

DSGE.posterior — Function.

posterior(m::AbstractModel{T}, data::Matrix{T}; sampler::Bool = false, catch_errors::Bool = false, φ_smc = 1) where {T<:AbstractFloat}

Calculates and returns the log of the posterior distribution for m.parameters:

log posterior  = log likelihood + log prior + const
log Pr(Θ|data) = log Pr(data|Θ) + log Pr(Θ) + const

Arguments

m: the model object
data: matrix of data for observables

Optional Arguments

-sampler: Whether metropolishastings or smc is the caller. If sampler=true, the log likelihood and the transition matrices for the zero-lower-bound period are also returned. -`catcherrors: Whether to catch errors of typeGensysErrororParamBoundsError`

φ_smc: a tempering factor to change the relative weighting of the prior and the likelihood when calculating the posterior. It is used primarily in SMC.

source

DSGE.posterior! — Function.

posterior!(m::AbstractModel{T}, parameters::Vector{T}, data::Matrix{T}; sampler::Bool = false, catch_errors::Bool = false, φ_smc = 1) where {T<:AbstractFloat}

Evaluates the log posterior density at parameters.

Arguments

m: The model object
parameters: New values for the model parameters
data: Matrix of input data for observables

Optional Arguments

sampler: Whether metropolis_hastings or smc is the caller. If sampler=true, the log likelihood and the transition matrices for the zero-lower-bound period are also returned.
catch_errors: Whether to catch errors of type GensysError or ParamBoundsError If sampler = true, both should always be caught.
φ_smc: a tempering factor to change the relative weighting of the prior and the likelihood when calculating the posterior. It is used primarily in SMC.

source

find_density_bands(draws::Matrix, percents::Vector{T}; minimize::Bool=true) where T<:AbstractFloat

Returns a 2 x cols(draws) matrix bands such that percent of the mass of draws[:,i] is above bands[1,i] and below bands[2,i].

Arguments

draws: Matrix of parameter draws (from Metropolis-Hastings, for example)
percent: percent of data within bands (e.g. .9 to get 90% of mass within bands)

Optional Arguments

minimize: if true, choose shortest interval, otherwise just chop off lowest and highest (percent/2)

source

DSGE.find_density_bands — Method.

find_density_bands(draws::Matrix, percent::AbstractFloat; minimize::Bool=true)

Returns a 2 x cols(draws) matrix bands such that percent of the mass of draws[:,i] is above bands[1,i] and below bands[2,i].

Arguments

draws: ndraws by nperiods matrix of parameter draws (from Metropolis-Hastings, for example)
percent: percent of data within bands (e.g. .9 to get 90% of mass within bands)

Optional Arguments

minimize: if true, choose shortest interval, otherwise just chop off lowest and highest (percent/2)

source

DSGE.load_posterior_moments — Method.

function load_posterior_moments(m; load_bands = true, include_fixed = false)

Load posterior moments (mean, std) of parameters for a particular sample, and optionally also load 5% and 95% lower and upper bands.

Keyword Arguments

cloud::ParticleCloud: Optionally pass in a cloud that you want to load the sample from. If the cloud is non-empty then the model object will only be used to find fixed indices and parameter tex labels
load_bands::Bool: Optionally include the 5% and 95% percentiles for the sample of parameters in the returned df
include_fixed::Bool: Optionally include the fixed parameters in the returned df
excl_list::Vector{Symbol}: List parameters by their key that you want to exclude from

Outputs

df: A dataframe containing the aforementioned moments/bands

source

DSGE.moment_tables — Method.

moment_tables(m; percent = 0.90, subset_inds = 1:0, subset_string = "",
    groupings = Dict{String, Vector{Parameter}}(), use_mode = false,
    tables = [:prior_posterior_means, :moments, :prior, :posterior],
    caption = true, outdir = "", verbose = :none)

Computes prior and posterior parameter moments. Tabulates prior mean, posterior mean, and bands in various LaTeX tables. These tables will be saved in outdir if it is nonempty, or else in tablespath(m, "estimate").

Inputs

m::AbstractModel: model object

Keyword Arguments

percent::AbstractFloat: the percentage of the mass of draws from Metropolis-Hastings included between the bands displayed in output tables.
subset_inds::AbstractRange{Int64}: indices specifying the draws we want to use
subset_string::String: short string identifying the subset to be appended to the output filenames. If subset_inds is nonempty but subset_string is empty, an error is thrown
groupings::Dict{String, Vector{Parameter}}: see ?parameter_groupings
use_mode::Bool: use the modal parameters instead of the mean in the priorposteriormeans table
tables::Vector{Symbol}: which tables to produce
caption::Bool: whether to include table captions
outdir::String: where to save output tables
verbose::Symbol: desired frequency of function progress messages printed to standard out. One of :none, :low, or :high
use_mode::Bool: Return a table with the modal parameters as opposed to the mean

source

DSGE.moments — Method.

moments(θ::Parameter)

If θ's prior is a RootInverseGamma, τ and ν. Otherwise, returns the mean and standard deviation of the prior. If θ is fixed, returns (θ.value, 0.0).

source

DSGE.posterior_table — Method.

posterior_table(m, post_means, post_bands; percent = 0.9, subset_string = "",
    groupings = Dict{String, Vector{Parameter}}(), caption = true, outdir = "")

source

DSGE.prior_posterior_moments_table — Method.

prior_posterior_moments_table(m, post_means, post_bands; percent = 0.9,
    subset_string = "", groupings = Dict{String, Vector{Parameter}}(),
    caption = true, outdir = "")

Produces a table of prior means, prior standard deviations, posterior means, and 90% bands for posterior draws.

source

DSGE.prior_posterior_table — Method.

prior_posterior_table(m, post_values; subset_string = "",
    groupings = Dict{String, Vector{Parameter}}(), use_mode = false,
    caption = true, outdir = "")

Produce a table of prior means and posterior means or mode.

source

DSGE.prior_table — Method.

prior_table(m; subset_string = "", groupings = Dict{String, Vector{Parameter}}(),
    caption = true, outdir = "")

source