Commit 4c0f8ec6 by Willi Mutschler Committed by Stéphane Adjemian

### :book:Added documentation for method of moments

parent 8d024117
 ... ... @@ -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.