From 4c0f8ec6be368ac12e1b6f71e6372944288cb8e8 Mon Sep 17 00:00:00 2001 From: Willi Mutschler Date: Wed, 11 Aug 2021 07:32:07 +0200 Subject: [PATCH] :book:Added documentation for method of moments --- doc/manual/source/the-model-file.rst | 595 ++++++++++++++++++++++++++- 1 file changed, 587 insertions(+), 8 deletions(-) diff --git a/doc/manual/source/the-model-file.rst b/doc/manual/source/the-model-file.rst index fce87716f..eff616c1a 100644 --- a/doc/manual/source/the-model-file.rst +++ b/doc/manual/source/the-model-file.rst @@ -3634,6 +3634,8 @@ strong nonlinearities or binding constraints. Such a solution is computed using the ``extended_path`` command. +.. _stoch-sol-simul: + Computing the stochastic solution --------------------------------- @@ -4622,8 +4624,8 @@ elements are never repeated (for more details, see the description of .. _estim: -Estimation -========== +Estimation based on likelihood +============================== Provided that you have observations on some endogenous variables, it is possible to use Dynare to estimate some or all parameters. Both @@ -4640,6 +4642,8 @@ observed variables. The estimation using a first order approximation can benefit from the block decomposition of the model (see :opt:`block`). +.. _varobs: + .. command:: varobs VARIABLE_NAME...; |br| This command lists the name of observed endogenous variables @@ -4699,7 +4703,6 @@ block decomposition of the model (see :opt:`block`). P (mu/eta); end; - .. block:: estimated_params ; |br| This block lists all parameters to be estimated and specifies @@ -4707,12 +4710,12 @@ block decomposition of the model (see :opt:`block`). Each line corresponds to an estimated parameter. - In a maximum likelihood estimation, each line follows this syntax:: + In a maximum likelihood or a method of moments estimation, each line follows this syntax:: stderr VARIABLE_NAME | corr VARIABLE_NAME_1, VARIABLE_NAME_2 | PARAMETER_NAME , INITIAL_VALUE [, LOWER_BOUND, UPPER_BOUND ]; - In a Bayesian estimation, each line follows this syntax:: + In a Bayesian MCMC or a penalized method of moments estimation, each line follows this syntax:: stderr VARIABLE_NAME | corr VARIABLE_NAME_1, VARIABLE_NAME_2 | PARAMETER_NAME | DSGE_PRIOR_WEIGHT [, INITIAL_VALUE [, LOWER_BOUND, UPPER_BOUND]], PRIOR_SHAPE, @@ -7633,8 +7636,585 @@ Dynare also has the ability to estimate Bayesian VARs: See ``bvar-a-la-sims.pdf``, which comes with Dynare distribution, for more information on this command. +Estimation based on moments +=========================== + +Provided that you have observations on some endogenous variables, it +is possible to use Dynare to estimate some or all parameters using a +method of moments approach. Both the Simulated Method of Moments (SMM) +and the Generalized Method of Moments (GMM) are available. The general +idea is to minimize the distance between unconditional model moments +and corresponding data moments (so called orthogonality or moment +conditions). For SMM Dynare computes model moments via stochastic +simulations based on the perturbation approximation up to any order, +whereas for GMM model moments are computed in closed-form based on the +pruned state-space representation of the perturbation solution up to third +order. The implementation of SMM is inspired by *Born and Pfeifer (2014)* +and *Ruge-Murcia (2012)*, whereas the one for GMM is adapted from +*Andreasen, Fernández-Villaverde and Rubio-Ramírez (2018)* and *Mutschler +(2018)*. The estimation heavily relies on the accuracy and efficiency of +the perturbation approximation, so it is advised to tune this as much as +possible (see :ref:`stoch-sol-simul`). The estimator is consistent and +asymptotically normally distributed given certain regularity conditions +(see *Duffie and Singleton (1993)* for SMM and *Hansen (1982)* for GMM). +For instance, it is required to have at least as many moment conditions as +estimated parameters. Moreover, the Jacobian of the moments with respect to +the estimated parameters needs to be full rank. :ref:`identification-analysis` +helps evaluating this regularity condition. + +In case you declare more moment conditions than estimated parameters, the +choice of :opt:`weighting_matrix ` +matters for the efficiency of the estimation, because the estimated +orthogonality conditions are random variables with unequal variances and +usually non-zero cross-moment covariances. Using a weighting matrix you can +re-weigh moments to pay more attention to orthogonality conditions that are +more informative or better measured (in the sense of having a smaller +variance). To achieve asymptotic efficiency, the weighting matrix needs to +be chosen such that, after appropriate scaling, it has probability limit +proportional to the inverse of the covariance matrix of the limiting +distribution of the vector of orthogonality conditions. Dynare uses a +Newey-West estimator with a Bartlett kernel to compute an estimate of this +so-called optimal weighting matrix. Moreover, in this over-identified case, +it is advised to perform the estimation in at least two stages by setting +e.g. :opt:`weighting_matrix=['DIAGONAL','DIAGONAL'] ` +so that the computation of the optimal weighting matrix benefits from the +consistent estimation of the previous stages. The optimal weighting matrix +is used to compute standard errors and the J-test of overidentifying +restrictions which tests whether the model and selection of moment +conditions fits the data sufficiently well. If the null hypothesis of a +"valid" model is rejected, then something is wrong with either your model +or selection of orthogonality conditions. + +In case the global minimum is found in a region of the parameter space that +is typically considered unlikely (`dilemma of absurd parameters`), you may +opt to choose the :opt:`penalized_estimator ` option. +Similar to adding priors to the likelihood, this option includes prior +knowledge (i.e. the prior mean) as additional moment restrictions and +weighs them by their prior precision to guide the minimization algorithm +in more plausible regions of the parameter space. Ideally, these are +characterized by slightly worse values of the objective function. Note that +this comes at the cost of a loss in efficiency of the estimator. + +|br| + +.. command:: varobs VARIABLE_NAME...; + + Required. All variables used in the :bck:`matched_moments` block + need to be observable. See :ref:`varobs ` for more details. + +|br| + +.. block:: matched_moments ; + + This block specifies the product moments which are used in estimation. + Currently, only linear product moments (e.g. + :math:`E[y_t], E[y_t^2], E[x_t y_t], E[y_t y_{t-1}], E[y_t^3 x^2_{t-4}]`) + are supported. For other functions like :math:`E[log(y_t)e^{x_t}]` you + need to declare auxiliary endogenous variables. + + Each line inside of the block should be of the form:: + + VARIABLE_NAME(LEAD/LAG)^POWER*VARIABLE_NAME(LEAD/LAG)^POWER*...*VARIABLE_NAME(LEAD/LAG)^POWER; + + where `VARIABLE_NAME` is the name of a declared observable variable, + `LEAD/LAG` is either a negative integer for lags or a positive one + for leads, and `POWER` is a positive integer indicating the exponent on + the variable. You can omit `LEAD/LAG` equal to `0` or `POWER` equal to `1`. + + *Example* + + For :math:`E[c_t], E[y_t], E[c_t^2], E[c_t y_t], E[y_t^2], E[c_t c_{t+3}], E[y_{t+1}^2 c^3_{t-4}], E[c^3_{t-5} y_{t}^2]` + use the following block: + + :: + + matched_moments; + c; + y; + c*c; + c*y; + y^2; + c*c(3); + y(1)^2*c(-4)^3; + c(-5)^3*y(0)^2; + end; + + *Limitations* + + 1. For GMM Dynare can only compute the theoretical mean, covariance and + autocovariances. Higher-order moments are only supported for SMM. + + 2. The product moments are not demeaned by default, unless the + :opt:`prefilter ` option is set to 1. That is, by default, + `c*c` corresponds to :math:`E[c_t^2]` and not to :math:`Var[c_t]=E[c_t^2]-E[c_t]^2`. + + *Output* + + Dynare translates the :bck:`matched_moments` block into a cell array + ``M_.matched_moments`` where: + + * the first column contains a vector of indices for the chosen variables in declaration order + * the second column contains the corresponding vector of leads and lags + * the third column contains the corresponding vector of powers + + During the estimation phase Dynare gets rid of redundant or duplicate + orthogonality conditions in ``M_.matched_moments`` and tells you which + conditions are removed. In the example above it would get grid of the + last row. The original block stays available in ``M_.matched_moments_orig``. + +|br| + +.. block:: estimated_params ; + + Required. See :bck:`estimated_params` for the meaning and syntax. + +|br| + +.. block:: estimated_params_init ; + + See :bck:`estimated_params_init` for the meaning and syntax. + +|br| + +.. block:: estimated_params_bounds ; + + See :bck:`estimated_params_bounds` for the meaning and syntax. + +|br| + +.. command:: method_of_moments (OPTIONS...); + + This command runs the method of moments estimation. The following + information will be displayed in the command window: + + * Overview of options chosen by the user + * Estimation results for each stage and iteration + * Value of minimized moment distance objective function + * Result of J-test + * Table of data moments and estimated model moments + + *Necessary options* + + .. option:: mom_method = SMM|GMM + + "Simulated Method of Moments" is triggered by `SMM` and + "Generalized Method of Moments" by `GMM`. + + .. option:: datafile = FILENAME + + The name of the file containing the data. See + :opt:`datafile ` for the meaning and syntax. + + *Common options for SMM and GMM* + + .. option:: order = INTEGER + + Order of perturbation approximation. For GMM only orders 1|2|3 are + supported. For SMM you can choose an arbitrary order. Note that the + order set in other functions does not overwrite the default. + Default: ``1``. + + .. option:: pruning + + Discard higher order terms when iteratively computing simulations + of the solution. See :opt:`pruning ` for more details. + Default: not set for SMM, always set for GMM. + + .. option:: penalized_estimator + + This option includes deviations of the estimated parameters from the + prior mean as additional moment restrictions and weighs them by + their prior precision. + Default: not set. + + .. option:: weighting_matrix = ['WM1','WM2',...,'WMn'] + + Determines the weighting matrix used at each estimation stage. Note + that this defines the number of stages, i.e. ``weighting_matrix = ['DIAGONAL','DIAGONAL','OPTIMAL']`` + performs a three-stage estimation. Possible values for ``WM`` are: + + ``IDENTITY_MATRIX`` + + Sets the weighting matrix equal to the identity matrix. + + ``OPTIMAL`` + + Uses the optimal weighting matrix that is computed by a + Newey-West estimate with a Bartlett kernel. At the first + stage the data-moments are used as initial estimate of the + model moments, whereas at subsequent stages the previous + state estimate of model moments is used when computing + the optimal weighting matrix. + + ``DIAGONAL`` + + Uses the diagonal of the ``OPTIMAL`` weighting matrix. + + ``FILENAME`` + + The name of the M-file (extension ``.m``) containing a + user-specified weighting matrix. The file must include a + square matrix called `weighting_matrix` with both dimensions + equal to the number of orthogonality conditions. + + Default value is ``['DIAGONAL','OPTIMAL']``. + + .. option:: weighting_matrix_scaling_factor = DOUBLE + + Scaling of weighting matrix in objective function. + Default: ``1``. + + .. option:: bartlett_kernel_lag = INTEGER + + Bandwidth of kernel for computing the optimal weighting matrix. + Default: ``20``. + + .. option:: se_tolx = DOUBLE + + Step size of numerical differentiation when computing standard + errors numerically. + Default: ``1e-5``. + + .. option:: verbose + + Display and store intermediate estimation results in ``oo_.mom``. + Default: not set. + + *SMM-specific options* + + .. option:: burnin = INTEGER + + Number of periods dropped at the beginning of simulation. + Default: ``500``. + + .. option:: bounded_shock_support + + Trim shocks in simulations to :math:`\pm 2` standard deviations. + Default: not set. + + .. option:: seed = INTEGER + + Common seed used in simulations. + Default: ``24051986``. + + .. option:: simulation_multiple = INTEGER + + Multiple of data length used for simulation. + Default: ``7``. + + *GMM-specific options* + + .. option:: analytic_standard_errors + + Compute standard errors using analytical derivatives of moments + with respect to estimated parameters. + Default: not set, i.e. standard errors are computed using a two-sided + finite difference method, see :opt:`se_tolx `. + + *General options* + + .. option:: dirname + + Directory in which to store ``estimation`` output. + See :opt:`dirname ` for more details. + Default: ````. + + .. option:: graph_format = FORMAT + + Specify the file format(s) for graphs saved to disk. + See :opt:`graph_format ` for more details. + Default: ``eps``. + + .. option:: nodisplay + + See :opt:`nodisplay`. Default: not set. + + .. option:: nograph + + See :opt:`nograph`. Default: not set. + + .. option:: noprint + + See :opt:`noprint`. Default: not set. + + .. option:: plot_priors = INTEGER + + Control the plotting of priors. + See :opt:`plot_priors ` for more details. + Default: ``1``, i.e. plot priors. + + .. option:: prior_trunc = DOUBLE + + See :opt:`prior_trunc ` for more details. + Default: ``1e-10``. + + .. option:: tex + + See :opt:`tex`. Default: not set. + + *Data options* + + .. option:: first_obs = INTEGER + + See :opt:`first_obs `. + Default: ``1``. + + .. option:: nobs = INTEGER + + See :opt:`nobs `. + Default: all observations are considered. + + .. option:: prefilter = INTEGER + + A value of 1 means that the estimation procedure will demean each data + series by its empirical mean and each model moment by its theoretical + mean. See :opt:`prefilter ` for more details. + Default: `0`, i.e. no prefiltering. + + .. option:: logdata + + See :opt:`logdata `. Default: not set. + + .. option:: xls_sheet = QUOTED_STRING + + See :opt:`xls_sheet `. + + .. option:: xls_range = RANGE + + See :opt:`xls_range `. + + *Optimization options* + + .. option:: huge_number = DOUBLE + + See :opt:`huge_number `. + Default: ``1e7``. + + .. option:: mode_compute = INTEGER | FUNCTION_NAME + + See :opt:`mode_compute `. + Default: ``13``, i.e. ``lsqnonlin``. + + .. option:: additional_optimizer_steps = [INTEGER|FUNCTION_NAME,INTEGER|FUNCTION_NAME,...] + + Vector of additional minimization algorithms run after + ``mode_compute``. If :opt:`verbose` option is set, then the additional estimation + results are saved into the ``oo_.mom`` structure prefixed with `verbose_`. + Default: no additional optimization iterations. + + .. option:: optim = (NAME, VALUE, ...) + + See :opt:`optim `. + + .. option:: silent_optimizer + + See :opt:`silent_optimizer`. + Default: not set. + + *Numerical algorithms options* + + .. option:: aim_solver + + See :opt:`aim_solver `. Default: not set. + + .. option:: k_order_solver + + See :opt:`k_order_solver `. + Default: disabled for order 1 and 2, enabled for order 3 and above. + + .. option:: dr = OPTION + + See :opt:`dr `. Default: ``default``, i.e. generalized + Schur decomposition. + + .. option:: dr_cycle_reduction_tol = DOUBLE + + See :opt:`dr_cycle_reduction_tol `. + Default: ``1e-7``. + + .. option:: dr_logarithmic_reduction_tol = DOUBLE + + See :opt:`dr_logarithmic_reduction_tol `. + Default: ``1e-12``. + + .. option:: dr_logarithmic_reduction_maxiter = INTEGER + + See :opt:`dr_logarithmic_reduction_maxiter `. + Default: ``100``. + + .. option:: lyapunov = OPTION + + See :opt:`lyapunov `. Default: ``default``, i.e. + based on Bartlets-Stewart algorithm. + + .. option:: lyapunov_complex_threshold = DOUBLE + + See :opt:`lyapunov_complex_threshold `. + Default: ``1e-15``. + + .. option:: lyapunov_fixed_point_tol = DOUBLE + + See :opt:`lyapunov_fixed_point_tol `. + Default: ``1e-10``. + + .. option:: lyapunov_doubling_tol = DOUBLE + + See :opt:`lyapunov_doubling_tol `. + Default: ``1e-16``. + + .. option:: sylvester = OPTION + + See :opt:`sylvester `. + Default: ``default``, i.e. uses ``gensylv``. + + .. option:: sylvester_fixed_point_tol = DOUBLE + + See :opt:`sylvester_fixed_point_tol `. + Default: ``1e-12``. + + .. option:: qz_criterium = DOUBLE + + See :opt:`qz_criterium `. + Default: ``0.999999`` as it is assumed that the observables are weakly + stationary. + + .. option:: qz_zero_threshold = DOUBLE + + See :opt:`qz_zero_threshold `. + Default: ``1e-6``. + + .. option:: schur_vec_tol = DOUBLE + + Tolerance level used to find nonstationary variables in Schur decomposition + of the transition matrix. Default: ``1e-11``. + + .. option:: mode_check + + Plot the moments distance objective function for values around the + computed minimum for each estimated parameter in turn. This is + helpful to diagnose problems with the optimizer. + Default: not set. + + .. option:: mode_check_neighbourhood_size = DOUBLE + + See :opt:`mode_check_neighbourhood_size `. + Default: ``0.5``. + + .. option:: mode_check_symmetric_plots = INTEGER + + See :opt:`mode_check_symmetric_plots `. + Default: ``1``. + + .. option:: mode_check_number_of_points = INTEGER + + See :opt:`mode_check_number_of_points `. + Default: ``20``. + *Output* + + ``method_of_moments`` stores user options in a structure called + `options_mom_` in the global workspace. After running the estimation, + the parameters ``M_.params`` and the covariance matrices of the shocks + ``M_.Sigma_e`` and of the measurement errors ``M_.H`` are set to the + parameters that minimize the quadratic moments distance objective + function. The estimation results are stored in the ``oo_.mom`` structure + with the following fields: + + .. matvar:: oo_.mom.data_moments + + Variable set by the ``method_of_moments`` command. Stores the mean + of the selected empirical moments of data. NaN values due to leads/lags + or missing data are omitted when computing the mean. Vector of dimension + equal to the number of orthogonality conditions. + + + .. matvar:: oo_.mom.m_data + + Variable set by the ``method_of_moments`` command. Stores the selected + empirical moments at each point in time. NaN values due to leads/lags + or missing data are replaced by the corresponding mean of the moment. + Matrix of dimension time periods times number of orthogonality conditions. + + + .. matvar:: oo_.mom.Sw + + Variable set by the ``method_of_moments`` command. Stores the + Cholesky decomposition of the currently used weighting matrix. + Square matrix of dimensions equal to the number of orthogonality + conditions. + + + .. matvar:: oo_.mom.model_moments + + Variable set by the ``method_of_moments`` command. Stores the implied + selected model moments given the current parameter guess. Model moments + are computed in closed-form from the pruned state-space system for GMM, + whereas for SMM these are based on averages of simulated data. Vector of dimension equal + to the number of orthogonality conditions. + + + .. matvar:: oo_.mom.Q + + Variable set by the ``method_of_moments`` command. Stores the scalar + value of the quadratic moment's distance objective function. + + + .. matvar:: oo_.mom.model_moments_params_derivs + + Variable set by the ``method_of_moments`` command. Stores the analytically + computed Jacobian matrix of the derivatives of the model moments with + respect to the estimated parameters. Only for GMM with :opt:`analytic_standard_errors`. + Matrix with dimension equal to the number of orthogonality conditions + times number of estimated parameters. + + + .. matvar:: oo_.mom.gmm_stage_1_mode, oo_.mom.gmm_stage_2_mode,... + .. matvar:: oo_.mom.smm_stage_1_mode, oo_.mom.smm_stage_2_mode,... + .. matvar:: oo_.mom.verbose_gmm_stage_1_mode, oo_.mom.verbose_gmm_stage_2_mode,... + .. matvar:: oo_.mom.verbose_smm_stage_1_mode, oo_.mom.verbose_smm_stage_2_mode,... + + Variables set by the ``method_of_moments`` command when estimating + with GMM or SMM. Stores the estimated values at stages 1, 2,.... + The structures contain the following fields: + + - ``measurement_errors_corr``: estimated correlation between two measurement errors + - ``measurement_errors_std``: estimated standard deviation of measurement errors + - ``parameters``: estimated model parameters + - ``shocks_corr``: estimated correlation between two structural shocks. + - ``shocks_std``: estimated standard deviation of structural shocks. + + If the :opt:`verbose` option is set, additional fields prefixed with + ``verbose_`` are saved for all :opt:`additional_optimizer_steps`. + + .. matvar:: oo_.mom.gmm_stage_1_std_at_mode, oo_.mom.gmm_stage_2_std_at_mode,... + .. matvar:: oo_.mom.smm_stage_1_std_at_mode, oo_.mom.smm_stage_2_std_at_mode,... + .. matvar:: oo_.mom.verbose_gmm_stage_1_std_at_mode, oo_.mom.verbose_gmm_stage_2_std_at_mode,... + .. matvar:: oo_.mom.verbose_smm_stage_1_std_at_mode, oo_.mom.verbose_smm_stage_2_std_at_mode,... + + Variables set by the ``method_of_moments`` command when estimating + with GMM or SMM. Stores the estimated standard errors at stages 1, 2,.... + The structures contain the following fields: + + - ``measurement_errors_corr``: standard error of estimated correlation between two measurement errors + - ``measurement_errors_std``: standard error of estimated standard deviation of measurement errors + - ``parameters``: standard error of estimated model parameters + - ``shocks_corr``: standard error of estimated correlation between two structural shocks. + - ``shocks_std``: standard error of estimated standard deviation of structural shocks. + + If the :opt:`verbose` option is set, additional fields prefixed with + ``verbose_`` are saved for all :opt:`additional_optimizer_steps`. + + + .. matvar:: oo_.mom.J_test + + Variable set by the ``method_of_moments`` command. Structure where the + value of the test statistic is saved into a field called ``j_stat``, the + degress of freedom in a field called ``degrees_freedom`` and the p-value + of the test statistic in a field called ``p_val``. + + + Model Comparison ================ @@ -9970,6 +10550,7 @@ IRF and moment calibration can be defined in ``irf_calibration`` and @#endfor end; +.. _identification-analysis: Performing identification analysis ---------------------------------- @@ -10102,9 +10683,7 @@ Performing identification analysis .. option:: schur_vec_tol = DOUBLE - Tolerance level used to find nonstationary variables in Schur decomposition - of the transition matrix. - Default: ``1.e-11``. + See :opt:`schur_vec_tol `. *Identification Strength Options*