From d8424b162073d51a58030787ea5b74b76e544d6e Mon Sep 17 00:00:00 2001
From: Marco Ratto <marco.ratto@jrc.ec.europa.eu>
Date: Mon, 20 Apr 2015 11:06:21 +0200
Subject: [PATCH] updated documentation for IRF/moment restrictions and
 refreshed sensitivity analyses and plots

---
 doc/dynare.texi | 794 +++++++++++++++++++++++++++++-------------------
 1 file changed, 484 insertions(+), 310 deletions(-)

diff --git a/doc/dynare.texi b/doc/dynare.texi
index fcb976aecd..05c58ce42e 100644
--- a/doc/dynare.texi
+++ b/doc/dynare.texi
@@ -241,13 +241,19 @@ Stochastic solution and simulation
 
 Sensitivity and identification analysis
 
+* Performing sensitivity analysis::
+* Performing identification analysis::
+* IRF/moment calibration::
+* Types of analysis and output files::
+
+Types of analysis and output files
 * Sampling::
 * Stability Mapping::
+* IRF/moment restrictions::
 * Reduced Form Mapping::
 * RMSE::
 * Screening Analysis::
 * Identification Analysis::
-* Performing Sensitivity and Identification Analysis::
 
 Macro-processing language
 
@@ -6869,311 +6875,8 @@ With respect to the previous version of the toolbox, in order to work
 properly, the GSA toolbox no longer requires that the Dynare
 estimation environment is set up.
 
-Sensitivity analysis results are saved locally in @code{<mod_file>/GSA},
-where @code{<mod_file>.mod} is the name of the DYNARE model file.
-
-@menu
-* Sampling::
-* Stability Mapping::
-* Reduced Form Mapping::
-* RMSE::
-* Screening Analysis::
-* Identification Analysis::
-* Performing Sensitivity and Identification Analysis::
-@end menu
-
-@node Sampling
-@subsection Sampling
-
-The following binary files are produced:
-@itemize
-@item
-@code{<mod_file>_prior.mat}: this file stores information about the analyses
-performed sampling from the prior ranges, @i{i.e.} @code{pprior=1} and @code{ppost=0};
-
-@item
-@code{<mod_file>_mc.mat}: this file stores information about the analyses performed
-sampling from multivariate normal, @i{i.e.} @code{pprior=0} and @code{ppost=0};
-
-@item
-@code{<mod_file>_post.mat}: this file stores information about analyses performed
-using the Metropolis posterior sample, @i{i.e.} @code{ppost=1}.
-@end itemize
-
-@node Stability Mapping
-@subsection Stability Mapping
-
-Figure files produced are of the form @code{<mod_file>_prior_*.fig} and store results
-for stability mapping from prior Monte-Carlo samples:
-@itemize
-@item
-@code{<mod_file>_prior_stab_SA_*.fig}: plots of the Smirnov test analyses
-confronting the cdf of the sample fulfilling Blanchard-Kahn conditions
-with the cdf of the rest of the sample;
-
-@item
-@code{<mod_file>_prior_stab_indet_SA_*.fig}: plots of the Smirnov test
-analyses confronting the cdf of the sample producing indeterminacy
-with the cdf of the original prior sample;
-
-@item
-@code{<mod_file>_prior_stab_unst_SA_*.fig}: plots of the Smirnov test
-analyses confronting the cdf of the sample producing unstable (explosive
-roots) behavior with the cdf of the original prior sample;
-
-@item
-@code{<mod_file>_prior_stable_corr_*.fig}: plots of bivariate projections
-of the sample fulfilling Blanchard-Kahn conditions;
-
-@item
-@code{<mod_file>_prior_indeterm_corr_*.fig}: plots of bivariate projections
-of the sample producing indeterminacy;
-
-@item
-@code{<mod_file>_prior_unstable_corr_*.fig}: plots of bivariate projections
-of the sample producing instability;
-
-@item
-@code{<mod_file>_prior_unacceptable_corr_*.fig}: plots of bivariate projections
-of the sample producing unacceptable solutions, @i{i.e.} either
-instability or indeterminacy or the solution could not be found (@i{e.g.}
-the steady state solution could not be found by the solver).
-@end itemize
-
-Similar conventions apply for @code{<mod_file>_mc_*.fig} files, obtained when
-samples from multivariate normal are used.
-
-@node Reduced Form Mapping
-@subsection Reduced Form Mapping
-
-The mapping of the reduced form solution forces the use of samples from
-prior ranges or prior distributions, @i{i.e.}: @code{pprior=1} and @code{ppost=0}. It
-uses 250 samples to optimize smoothing parameters and 1000 samples to compute the
-fit. The rest of the sample is used for out-of-sample validation. One can also
-load a previously estimated mapping with a new Monte-Carlo sample, to look at the
-forecast for the new Monte-Carlo sample.
-
-The following synthetic figures are produced:
-@itemize
-@item
-@code{<mod_file>_redform_<endo name>_vs_lags_*.fig}: shows bar charts
-of the sensitivity indices for the ten most important parameters driving
-the reduced form coefficients of the selected endogenous variables
-(@code{namendo}) versus lagged endogenous variables (@code{namlagendo}); suffix
-@code{log} indicates the results for log-transformed entries;
-
-@item
-@code{<mod_file>_redform_<endo name>_vs_shocks_*.fig}: shows bar charts
-of the sensitivity indices for the ten most important parameters driving
-the reduced form coefficients of the selected endogenous variables
-(@code{namendo}) versus exogenous variables (@code{namexo}); suffix @code{log}
-indicates the results for log-transformed entries;
-
-@item
-@code{<mod_file>_redform_GSA(_log).fig}: shows bar chart of all sensitivity
-indices for each parameter: this allows one to notice parameters that
-have a minor effect for any of the reduced form coefficients.
-@end itemize
-
-Detailed results of the analyses are shown in the subfolder @code{<mod_file>/GSA/redform_stab},
-where the detailed results of the estimation of the single functional relationships
-between parameters @math{\theta} and reduced form coefficient are stored in separate directories
-named as:
-
-@itemize
-@item
-@code{<namendo>_vs_<namlagendo>}: for the entries of the transition matrix;
-
-@item
-@code{<namendo>_vs_<namexo>}: for entries of the matrix of the shocks.
-@end itemize
-Moreover, analyses for log-transformed entries are denoted with the following
-suffixes (@math{y} denotes the generic reduced form coefficient):
-@itemize
-@item
-@code{log}: @math{y^* = \log(y)};
-@item
-@code{minuslog}: @math{y^* = \log(-y)};
-@item
-@code{logsquared}: @math{y^* = \log(y^2)} for symmetric fat tails;
-@item
-@code{logskew}: @math{y^* = \log(|y + \lambda|)} for asymmetric fat tails.
-@end itemize
-The optimal type of transformation is automatically selected without the
-need of user intervention.
-
-@node RMSE
-@subsection RMSE
-
-The RMSE analysis can be performed with different types of sampling options:
-@enumerate
-@item
-When @code{pprior=1} and @code{ppost=0}, the toolbox analyzes the RMSEs for
-the Monte-Carlo sample obtained by sampling parameters from their prior distributions
-(or prior ranges): this analysis provides some hints about
-what parameter drives the fit of which observed series, prior to the full
-estimation;
-
-@item
-When @code{pprior=0} and @code{ppost=0}, the toolbox analyzes the RMSEs for
-a multivariate normal Monte-Carlo sample, with covariance matrix based on
-the inverse Hessian at the optimum: this analysis is useful when maximum likelihood
-estimation is done (@i{i.e.} no Bayesian estimation);
-
-@item
-When @code{ppost=1} the toolbox analyzes the RMSEs for the posterior sample
-obtained by Dynare's Metropolis procedure.
-@end enumerate
-
-The use of cases 2 and 3 requires an estimation step beforehand. To
-facilitate the sensitivity analysis after estimation, the @code{dynare_sensitivity}
-command also allows you to indicate some options of the @code{estimation}
-command. These are:
-@itemize @bullet
-@item @code{datafile}
-@item @code{nobs}
-@item @code{first_obs}
-@item @code{prefilter}
-@item @code{presample}
-@item @code{nograph}
-@item @code{nodisplay}
-@item @code{graph_format}
-@item @code{conf_sig}
-@item @code{loglinear}
-@item @code{mode_file}
-@end itemize
-
-Binary files produced my RMSE analysis are:
-@itemize
-@item
-@code{<mod_file>_prior_*.mat}: these files store the filtered and smoothed
-    variables for the prior Monte-Carlo sample, generated when doing RMSE analysis
-    (@code{pprior=1} and @code{ppost=0});
-@item
-@code{<mode_file>_mc_*.mat}: these files store the filtered and smoothed variables
-    for the multivariate normal Monte-Carlo sample, generated when doing
-    RMSE analysis (@code{pprior=0} and @code{ppost=0}).
-@end itemize
-
-Figure files @code{<mod_file>_rmse_*.fig} store results for the RMSE analysis.
-
-@itemize
-@item
-@code{<mod_file>_rmse_prior*.fig}: save results for the analysis using prior
-Monte-Carlo samples;
-
-@item
-@code{<mod_file>_rmse_mc*.fig}: save results for the analysis using multivariate
-normal Monte-Carlo samples;
-
-@item
-@code{<mod_file>_rmse_post*.fig}: save results for the analysis using Metropolis
-posterior samples.
-@end itemize
-
-The following types of figures are saved (we show prior sample to fix ideas,
-but the same conventions are used for multivariate normal and posterior):
-
-@itemize
-@item
-@code{<mod_file>_rmse_prior_*.fig}: for each parameter, plots the cdfs
-corresponding to the best 10% RMSEs of each observed series;
-
-@item
-@code{<mod_file>_rmse_prior_dens_*.fig}: for each parameter, plots the
-pdfs corresponding to the best 10% RMESs of each observed series;
-
-@item
-@code{<mod_file>_rmse_prior_<name of observedseries>_corr_*.fig}: for
-each observed series plots the bi-dimensional projections of samples
-with the best 10% RMSEs, when the correlation is significant;
-
-@item
-@code{<mod_file>_rmse_prior_lnlik*.fig}: for each observed series, plots
-in red the cdf of the log-likelihood corresponding to the best 10%
-RMSEs, in green the cdf of the rest of the sample and in blue the
-cdf of the full sample; this allows one to see the presence of some
-idiosyncratic behavior;
-
-@item
-@code{<mod_file>_rmse_prior_lnpost*.fig}: for each observed series, plots
-in red the cdf of the log-posterior corresponding to the best 10% RMSEs,
-in green the cdf of the rest of the sample and in blue the cdf of the full
-sample; this allows one to see idiosyncratic behavior;
-
-@item
-@code{<mod_file>_rmse_prior_lnprior*.fig}: for each observed series, plots
-in red the cdf of the log-prior corresponding to the best 10% RMSEs,
-in green the cdf of the rest of the sample and in blue the cdf of the full
-sample; this allows one to see idiosyncratic behavior;
-
-@item
-@code{<mod_file>_rmse_prior_lik_SA_*.fig}: when @code{lik_only=1}, this shows
-the Smirnov tests for the filtering of the best 10% log-likelihood values;
-
-@item
-@code{<mod_file>_rmse_prior_post_SA_*.fig}: when @code{lik_only=1}, this shows
-the Smirnov test for the filtering of the best 10% log-posterior values.
-@end itemize
-
-@node Screening Analysis
-@subsection Screening Analysis
-
-Screening analysis does not require any additional options with respect to
-those listed in @ref{Sampling Options}. The toolbox performs all the
-analyses required and displays results.
-
-The results of the screening analysis with Morris sampling design are stored
-in the subfolder @code{<mod_file>/GSA/SCREEN}. The data file @code{<mod_file>_prior} stores
-all the information of the analysis (Morris sample, reduced form coefficients,
-etc.).
-
-Screening analysis merely concerns reduced form coefficients. Similar
-synthetic bar charts as for the reduced form analysis with Monte-Carlo samples are
-saved:
-@itemize
-@item
-@code{<mod_file>_redform_<endo name>_vs_lags_*.fig}: shows bar charts
-of the elementary effect tests for the ten most important parameters
-driving the reduced form coefficients of the selected endogenous variables
-(@code{namendo}) versus lagged endogenous variables (@code{namlagendo});
-
-@item
-@code{<mod_file>_redform_<endo name>_vs_shocks_*.fig}: shows bar charts
-of the elementary effect tests for the ten most important parameters
-driving the reduced form coefficients of the selected endogenous variables
-(@code{namendo}) versus exogenous variables (@code{namexo});
-
-@item
-@code{<mod_file>_redform_screen.fig}: shows bar chart of all elementary
-effect tests for each parameter: this allows one to identify parameters that
-have a minor effect for any of the reduced form coefficients.
-@end itemize
-
-@node Identification Analysis
-@subsection Identification Analysis
-
-Setting the option @code{identification=1}, an identification analysis based on
-theoretical moments is performed. Sensitivity plots are provided that allow
-to infer which parameters are most likely to be less identifiable.
-
-Prerequisite for properly running all the identification routines, is the keyword
-@code{identification}; in the Dynare model file. This keyword triggers
-the computation of analytic derivatives of the model with respect to estimated
-parameters and shocks. This is required for option @code{morris=2},
-which implements @cite{Iskrev (2010)} identification analysis.
-
-For example, the placing @code{identification; dynare_sensitivity(identification=1, morris=2);}
-in the Dynare model file trigger identification analysis using analytic derivatives
-@cite{Iskrev (2010)}, jointly with the mapping of the acceptable region.
-
-The identification analysis with derivatives can also be triggered by the
-commands @code{identification;} This does not do the mapping of
-acceptable regions for the model and uses the standard random sampler of Dynare.
-It completely offsets any use of the sensitivity analysis toolbox.
-
-@node Performing Sensitivity and Identification Analysis
-@subsection Performing Sensitivity and Identification Analysis
+@node Performing sensitivity analysis
+@subsection Performing sensitivity analysis
 
 @deffn Command dynare_sensitivity ;
 @deffnx Command dynare_sensitivity (@var{OPTIONS}@dots{});
@@ -7406,12 +7109,86 @@ Maximum number of lags for moments in identification analysis. Default: @code{1}
 
 @end deffn
 
-@deffn Command identification ;
-@deffnx Command identification (@var{OPTIONS}@dots{});
+@node IRF/Moment calibration
+@subsection IRF/Moment calibration
 
-@descriptionhead
+IRF and moment calibration can be defined in @code{irf_calibration} and @code{moment_calibration} blocks:
 
-This command triggers identification analysis.
+@deffn Block irf_calibration;
+@deffnx Block irf_calibration(@var{OPTIONS}@dots{});
+
+@descriptionhead
+
+This block allows defining IRF calibration criteria and is terminated by @code{end;}. 
+To set IRF sign restrictions, the following syntax is used
+@example
+@var{VARIABLE_NAME}(@var{INTEGER}),@var{EXOGENOUS_NAME}, -;
+@var{VARIABLE_NAME}(@var{INTEGER}:@var{INTEGER}),@var{EXOGENOUS_NAME}, +;
+@end example
+To set IRF restrictions with specific intervals, the following syntax is used
+@example
+@var{VARIABLE_NAME}(@var{INTEGER}),@var{EXOGENOUS_NAME}, [@var{DOUBLE} @var{DOUBLE}];
+@var{VARIABLE_NAME}(@var{INTEGER}:@var{INTEGER}),@var{EXOGENOUS_NAME}, [@var{DOUBLE} @var{DOUBLE}];
+@end example
+
+When @code{(@var{INTEGER}:@var{INTEGER})} is used, the restriction is considered to be fulfilled by a logical OR.
+A list of restrictions must always be fulfilled with logical AND.
+
+@examplehead
+
+@example
+irf_calibration;
+y(1:4), e_ys, [ -50 50]; //[first year response with logical OR]
+@@#for ilag in 21:40
+R_obs(@@@{ilag@}), e_ys, [0 6]; //[response from 5th to 10th years with logical AND]
+@@#endfor
+end;
+@end example
+
+@end deffn
+
+@deffn Block moment_calibration;
+@deffnx Block moment_calibration(@var{OPTIONS}@dots{});
+
+@descriptionhead
+
+This block allows defining moment calibration criteria. This block is terminated by @code{end;}, and contains lines of the
+form:
+@example
+@var{VARIABLE_NAME1},@var{VARIABLE_NAME2}(+/-@var{INTEGER}), [@var{DOUBLE} @var{DOUBLE}];
+@var{VARIABLE_NAME1},@var{VARIABLE_NAME2}(+/-@var{INTEGER}), +/-;
+@var{VARIABLE_NAME1},@var{VARIABLE_NAME2}(+/-(@var{INTEGER}:@var{INTEGER})), [@var{DOUBLE} @var{DOUBLE}];
+@var{VARIABLE_NAME1},@var{VARIABLE_NAME2}((-@var{INTEGER}:+@var{INTEGER})), [@var{DOUBLE} @var{DOUBLE}];
+@end example
+
+When @code{(@var{INTEGER}:@var{INTEGER})} is used, the restriction is considered to be fulfilled by a logical OR.
+A list of restrictions must always be fulfilled with logical AND.
+
+@examplehead
+
+@example
+moment_calibration;
+y_obs,y_obs, [0.5 1.5]; //[unconditional variance]
+y_obs,y_obs(-(1:4)), +; //[sign restriction for first year acf with logical OR]
+@@#for ilag in -2:2
+y_obs,R_obs(@@@{ilag@}), -; //[-2:2 ccf with logical AND]
+@@#endfor
+@@#for ilag in -4:4
+y_obs,pie_obs(@@@{ilag@}), -; //[-4_4 ccf with logical AND]
+@@#endfor
+end;
+@end example
+
+@end deffn
+@node Performing identification analysis
+@subsection Performing identification analysis
+
+@deffn Command identification ;
+@deffnx Command identification (@var{OPTIONS}@dots{});
+
+@descriptionhead
+
+This command triggers identification analysis.
 
 @optionshead
 
@@ -7486,6 +7263,403 @@ Specify the parameter set to use. Default: @code{prior_mean}
 
 @end deffn
 
+@node Types of analysis and output files
+@subsection Types of analysis and output files
+
+The sensitivity analysis toolbox includes several types of analyses.
+Sensitivity analysis results are saved locally in @code{<mod_file>/GSA},
+where @code{<mod_file>.mod} is the name of the DYNARE model file.
+
+@menu
+* Sampling::
+* Stability Mapping::
+* IRF/moment restrictions::
+* Reduced Form Mapping::
+* RMSE::
+* Screening Analysis::
+* Identification Analysis::
+@end menu
+
+@node Sampling
+@subsubsection Sampling
+
+The following binary files are produced:
+@itemize
+@item
+@code{<mod_file>_prior.mat}: this file stores information about the analyses
+performed sampling from the prior, @i{i.e.} @code{pprior=1} and @code{ppost=0};
+
+@item
+@code{<mod_file>_mc.mat}: this file stores information about the analyses performed
+sampling from multivariate normal, @i{i.e.} @code{pprior=0} and @code{ppost=0};
+
+@item
+@code{<mod_file>_post.mat}: this file stores information about analyses performed
+using the Metropolis posterior sample, @i{i.e.} @code{ppost=1}.
+@end itemize
+
+@node Stability Mapping
+@subsubsection Stability Mapping
+
+Figure files produced are of the form @code{<mod_file>_prior_*.fig} and store results
+for stability mapping from prior Monte-Carlo samples:
+@itemize
+@item
+@code{<mod_file>_prior_stable.fig}: plots of the Smirnov test and the correlation analyses
+confronting the cdf of the sample fulfilling Blanchard-Kahn conditions (blue color)
+with the cdf of the rest of the sample (red color), @i{i.e.} either
+instability or indeterminacy or the solution could not be found (@i{e.g.}
+the steady state solution could not be found by the solver);
+
+@item
+@code{<mod_file>_prior_indeterm.fig}: plots of the Smirnov test and the correlation
+analyses confronting the cdf of the sample producing indeterminacy (red color)
+with the cdf of the rest of the sample (blue color);
+
+@item
+@code{<mod_file>_prior_unstable.fig}: plots of the Smirnov test and the correlation
+analyses confronting the cdf of the sample producing explosive roots (red color) 
+with the cdf of the rest of the sample (blue color);
+
+@item
+@code{<mod_file>_prior_wrong.fig}: plots of the Smirnov test and the correlation
+analyses confronting the cdf of the sample where the solution could not be found (@i{e.g.}
+the steady state solution could not be found by the solver - red color) 
+with the cdf of the rest of the sample (blue color);
+
+@item
+@code{<mod_file>_prior_calib.fig}: plots of the Smirnov test and the correlation
+analyses splitting the sample fulfilling Blanchard-Kahn conditions, 
+by confronting the cdf of the sample where IRF/moment restrictions are matched (blue color)
+with the cdf where IRF/moment restrictions are NOT matched (red color);
+
+@end itemize
+
+Similar conventions apply for @code{<mod_file>_mc_*.fig} files, obtained when
+samples from multivariate normal are used.
+
+@node IRF/Moment restrictions
+@subsubsection IRF/Moment restrictions
+
+The following binary files are produced:
+@itemize
+@item
+@code{<mod_file>_prior_restrictions.mat}: this file stores information about the IRF/moment restriction analysis
+performed sampling from the prior ranges, @i{i.e.} @code{pprior=1} and @code{ppost=0};
+
+@item
+@code{<mod_file>_mc_restrictions.mat}: this file stores information about the IRF/moment restriction analysis performed
+sampling from multivariate normal, @i{i.e.} @code{pprior=0} and @code{ppost=0};
+
+@item
+@code{<mod_file>_post_restrictions.mat}: this file stores information about IRF/moment restriction analysis performed
+using the Metropolis posterior sample, @i{i.e.} @code{ppost=1}.
+@end itemize
+
+Figure files produced are of the form @code{<mod_file>_prior_irf_calib_*.fig} and @code{<mod_file>_prior_moment_calib_*.fig} and store results
+for mapping restrictions from prior Monte-Carlo samples:
+@itemize
+@item
+@code{<mod_file>_prior_irf_calib_<ENDO_NAME>_vs_<EXO_NAME>_<PERIOD>.fig}: plots of the Smirnov test and the correlation
+analyses splitting the sample fulfilling Blanchard-Kahn conditions,
+by confronting the cdf of the sample where the individual IRF restriction 
+@code{<ENDO_NAME>} vs. @code{<EXO_NAME>} at period(s) @code{<PERIOD>} is matched (blue color)
+with the cdf where the IRF restriction is NOT matched (red color)
+
+@item
+@code{<mod_file>_prior_irf_calib_<ENDO_NAME>_vs_<EXO_NAME>_ALL.fig}: plots of the Smirnov test and the correlation
+analyses splitting the sample fulfilling Blanchard-Kahn conditions,
+by confronting the cdf of the sample where ALL the individual IRF restrictions for the same couple
+@code{<ENDO_NAME>} vs. @code{<EXO_NAME>} are matched (blue color)
+with the cdf where the IRF restriction is NOT matched (red color)
+
+@item
+@code{<mod_file>_prior_irf_restrictions.fig}: plots visual information on the IRF restrictions 
+compared to the actual Monte Carlo realization from prior sample.
+
+@item
+@code{<mod_file>_prior_moment_calib_<ENDO_NAME1>_vs_<ENDO_NAME2>_<LAG>.fig}: plots of the Smirnov test and the correlation
+analyses splitting the sample fulfilling Blanchard-Kahn conditions,
+by confronting the cdf of the sample where the individual acf/ccf moment restriction 
+@code{<ENDO_NAME1>} vs. @code{<ENDO_NAME2>} at lag(s) @code{<LAG>} is matched (blue color)
+with the cdf where the IRF restriction is NOT matched (red color)
+
+@item
+@code{<mod_file>_prior_moment_calib_<ENDO_NAME>_vs_<EXO_NAME>_ALL.fig}: plots of the Smirnov test and the correlation
+analyses splitting the sample fulfilling Blanchard-Kahn conditions,
+by confronting the cdf of the sample where ALL the individual acf/ccf moment restrictions for the same couple
+@code{<ENDO_NAME1>} vs. @code{<ENDO_NAME2>} are matched (blue color)
+with the cdf where the IRF restriction is NOT matched (red color)
+
+@item
+@code{<mod_file>_prior_moment_restrictions.fig}: plots visual information on the moment restrictions 
+compared to the actual Monte Carlo realization from prior sample.
+
+@end itemize
+
+Similar conventions apply for @code{<mod_file>_mc_*.fig} and @code{<mod_file>_post_*.fig} files, obtained when
+samples from multivariate normal or from posterior are used.
+
+@node Reduced Form Mapping
+@subsubsection Reduced Form Mapping
+
+When the option @code{threshold_redform} is not set, or it is empty (the default), this analysis estimates a multivariate
+smoothing spline ANOVA model (the 'mapping') for the selected entries in the transition matrix of the shock matrix of the reduce form first order solution of the model.
+The mapping of the reduced form solution forces the use of samples from
+prior ranges or prior distributions, @i{i.e.}: @code{pprior=1} and @code{ppost=0}. It
+uses 250 samples to optimize smoothing parameters and 1000 samples to compute the
+fit. The rest of the sample is used for out-of-sample validation. One can also
+load a previously estimated mapping with a new Monte-Carlo sample, to look at the
+forecast for the new Monte-Carlo sample.
+
+The following synthetic figures are produced:
+@itemize
+@item
+@code{<mod_file>_redform_<endo name>_vs_lags_*.fig}: shows bar charts
+of the sensitivity indices for the ten most important parameters driving
+the reduced form coefficients of the selected endogenous variables
+(@code{namendo}) versus lagged endogenous variables (@code{namlagendo}); suffix
+@code{log} indicates the results for log-transformed entries;
+
+@item
+@code{<mod_file>_redform_<endo name>_vs_shocks_*.fig}: shows bar charts
+of the sensitivity indices for the ten most important parameters driving
+the reduced form coefficients of the selected endogenous variables
+(@code{namendo}) versus exogenous variables (@code{namexo}); suffix @code{log}
+indicates the results for log-transformed entries;
+
+@item
+@code{<mod_file>_redform_GSA(_log).fig}: shows bar chart of all sensitivity
+indices for each parameter: this allows one to notice parameters that
+have a minor effect for any of the reduced form coefficients.
+@end itemize
+
+Detailed results of the analyses are shown in the subfolder @code{<mod_file>/GSA/redform_prior},
+where the detailed results of the estimation of the single functional relationships
+between parameters @math{\theta} and reduced form coefficient (denoted as @math{y} hereafter) are stored in separate directories
+named as:
+
+@itemize
+@item
+@code{<namendo>_vs_<namlagendo>}: for the entries of the transition matrix;
+
+@item
+@code{<namendo>_vs_<namexo>}: for entries of the matrix of the shocks.
+@end itemize
+
+The following files are stored in each directory:
+@itemize
+@item
+@code{<mod_file>_<namendo>_vs_<namexo>.fig}: histogram and CDF plot of the MC sample of the individual entry
+of the shock matrix, in sample and out of sample fit of the ANOVA model;
+
+@item
+@code{<mod_file>_<namendo>_vs_<namexo>_map_SE.fig}: for entries of the shock matrix it shows graphs of the estimated first order ANOVA terms @math{y = f(\theta_i)} for each deep parameter \math{\theta_i}; 
+
+@item
+@code{<mod_file>_<namendo>_vs_<namlagendo>.fig}: histogram and CDF plot of the MC sample of the individual entry
+of the transition matrix, in sample and out of sample fit of the ANOVA model;
+
+@item
+@code{<mod_file>_<namendo>_vs_<namlagendo>_map_SE.fig}: for entries of the transition matrix it shows graphs of the estimated first order ANOVA terms @math{y = f(\theta_i)} for each deep parameter @math{\theta_i}; 
+
+@item
+@code{<mod_file>_<namendo>_vs_<namexo>_map.mat}, @code{<mod_file>_<namendo>_vs_<namlagendo>_map.mat}: these files store info in the estimation; 
+
+@end itemize
+
+When option @code{logtrans_redform} is set, the ANOVA estimation is performed using a log-transformation of each @code{y}.
+The ANOVA mapping is then transformed back onto the original scale, to allow comparability with the baseline estimation.
+Graphs for this log-transformed case, are stored in the same folder in files denoted with the @code{_log} suffix.
+
+When the option @code{threshold_redform} is set, the analysis is performed via Monte Carlo filtering, by displaying parameters that drive the individual entry @code{y} inside the range specified in @code{threshold_redform}. If no entry is found (or all entries are in the range), the MCF algorithm ignores the range specified in @code{threshold_redform} and performs the analysis splitting the MC sample of @code{y} into deciles. Setting @code{threshold_redform=[-inf inf]} triggers this approach for all @code{y}'s.
+
+Results are stored in subdirectories of @code{<mod_file>/GSA/redform_prior} named 
+@itemize
+@item
+@code{<namendo>_vs_<namlagendo>_threshold}: for the entries of the transition matrix;
+
+@item
+@code{<namendo>_vs_<namexo>_threshold}: for entries of the matrix of the shocks.
+@end itemize
+
+The files saved are named
+@itemize
+@item
+@code{<mod_file>_<namendo>_vs_<namexo>_threshold.fig},@code{<mod_file>_<namendo>_vs_<namlagendo>_threshold.fig}: graphical outputs; 
+@item
+@code{<mod_file>_<namendo>_vs_<namexo>_threshold.mat},@code{<mod_file>_<namendo>_vs_<namlagendo>_threshold.mat}: info on the analysis; 
+
+@end itemize
+
+@node RMSE
+@subsubsection RMSE
+
+The RMSE analysis can be performed with different types of sampling options:
+@enumerate
+@item
+When @code{pprior=1} and @code{ppost=0}, the toolbox analyzes the RMSEs for
+the Monte-Carlo sample obtained by sampling parameters from their prior distributions
+(or prior ranges): this analysis provides some hints about
+what parameter drives the fit of which observed series, prior to the full
+estimation;
+
+@item
+When @code{pprior=0} and @code{ppost=0}, the toolbox analyzes the RMSEs for
+a multivariate normal Monte-Carlo sample, with covariance matrix based on
+the inverse Hessian at the optimum: this analysis is useful when maximum likelihood
+estimation is done (@i{i.e.} no Bayesian estimation);
+
+@item
+When @code{ppost=1} the toolbox analyzes the RMSEs for the posterior sample
+obtained by Dynare's Metropolis procedure.
+@end enumerate
+
+The use of cases 2 and 3 requires an estimation step beforehand. To
+facilitate the sensitivity analysis after estimation, the @code{dynare_sensitivity}
+command also allows you to indicate some options of the @code{estimation}
+command. These are:
+@itemize @bullet
+@item @code{datafile}
+@item @code{nobs}
+@item @code{first_obs}
+@item @code{prefilter}
+@item @code{presample}
+@item @code{nograph}
+@item @code{nodisplay}
+@item @code{graph_format}
+@item @code{conf_sig}
+@item @code{loglinear}
+@item @code{mode_file}
+@end itemize
+
+Binary files produced my RMSE analysis are:
+@itemize
+@item
+@code{<mod_file>_prior_*.mat}: these files store the filtered and smoothed
+    variables for the prior Monte-Carlo sample, generated when doing RMSE analysis
+    (@code{pprior=1} and @code{ppost=0});
+@item
+@code{<mode_file>_mc_*.mat}: these files store the filtered and smoothed variables
+    for the multivariate normal Monte-Carlo sample, generated when doing
+    RMSE analysis (@code{pprior=0} and @code{ppost=0}).
+@end itemize
+
+Figure files @code{<mod_file>_rmse_*.fig} store results for the RMSE analysis.
+
+@itemize
+@item
+@code{<mod_file>_rmse_prior*.fig}: save results for the analysis using prior
+Monte-Carlo samples;
+
+@item
+@code{<mod_file>_rmse_mc*.fig}: save results for the analysis using multivariate
+normal Monte-Carlo samples;
+
+@item
+@code{<mod_file>_rmse_post*.fig}: save results for the analysis using Metropolis
+posterior samples.
+@end itemize
+
+The following types of figures are saved (we show prior sample to fix ideas,
+but the same conventions are used for multivariate normal and posterior):
+
+@itemize
+@item
+@code{<mod_file>_rmse_prior_params_*.fig}: for each parameter, plots the cdfs 
+corresponding to the best 10% RMSEs of each observed series (only those cdfs below the significance threshold @code{alpha_rmse});
+
+@item
+@code{<mod_file>_rmse_prior_<var_obs>_*.fig}: if a parameter significantly affects the fit of @code{var_obs}, all possible trade-off's with other observables for same parameter are plotted;
+
+@item
+@code{<mod_file>_rmse_prior_<var_obs>_map.fig}: plots the MCF analysis of parameters significantly driving the fit the observed series @code{var_obs};
+
+@item
+@code{<mod_file>_rmse_prior_lnlik*.fig}: for each observed series, plots
+in BLUE the cdf of the log-likelihood corresponding to the best 10%
+RMSEs, in RED the cdf of the rest of the sample and in BLACK the
+cdf of the full sample; this allows one to see the presence of some
+idiosyncratic behavior;
+
+@item
+@code{<mod_file>_rmse_prior_lnpost*.fig}: for each observed series, plots
+in BLUE the cdf of the log-posterior corresponding to the best 10% RMSEs,
+in RED the cdf of the rest of the sample and in BLACK the cdf of the full
+sample; this allows one to see idiosyncratic behavior;
+
+@item
+@code{<mod_file>_rmse_prior_lnprior*.fig}: for each observed series, plots
+in BLUE the cdf of the log-prior corresponding to the best 10% RMSEs,
+in RED the cdf of the rest of the sample and in BLACK the cdf of the full
+sample; this allows one to see idiosyncratic behavior;
+
+@item
+@code{<mod_file>_rmse_prior_lik.fig}: when @code{lik_only=1}, this shows
+the MCF tests for the filtering of the best 10% log-likelihood values;
+
+@item
+@code{<mod_file>_rmse_prior_post.fig}: when @code{lik_only=1}, this shows
+the MCF tests for the filtering of the best 10% log-posterior values.
+@end itemize
+
+@node Screening Analysis
+@subsubsection Screening Analysis
+
+Screening analysis does not require any additional options with respect to
+those listed in @ref{Sampling Options}. The toolbox performs all the
+analyses required and displays results.
+
+The results of the screening analysis with Morris sampling design are stored
+in the subfolder @code{<mod_file>/GSA/SCREEN}. The data file @code{<mod_file>_prior} stores
+all the information of the analysis (Morris sample, reduced form coefficients,
+etc.).
+
+Screening analysis merely concerns reduced form coefficients. Similar
+synthetic bar charts as for the reduced form analysis with Monte-Carlo samples are
+saved:
+@itemize
+@item
+@code{<mod_file>_redform_<endo name>_vs_lags_*.fig}: shows bar charts
+of the elementary effect tests for the ten most important parameters
+driving the reduced form coefficients of the selected endogenous variables
+(@code{namendo}) versus lagged endogenous variables (@code{namlagendo});
+
+@item
+@code{<mod_file>_redform_<endo name>_vs_shocks_*.fig}: shows bar charts
+of the elementary effect tests for the ten most important parameters
+driving the reduced form coefficients of the selected endogenous variables
+(@code{namendo}) versus exogenous variables (@code{namexo});
+
+@item
+@code{<mod_file>_redform_screen.fig}: shows bar chart of all elementary
+effect tests for each parameter: this allows one to identify parameters that
+have a minor effect for any of the reduced form coefficients.
+@end itemize
+
+@node Identification Analysis
+@subsubsection Identification Analysis
+
+Setting the option @code{identification=1}, an identification analysis based on
+theoretical moments is performed. Sensitivity plots are provided that allow
+to infer which parameters are most likely to be less identifiable.
+
+Prerequisite for properly running all the identification routines, is the keyword
+@code{identification}; in the Dynare model file. This keyword triggers
+the computation of analytic derivatives of the model with respect to estimated
+parameters and shocks. This is required for option @code{morris=2},
+which implements @cite{Iskrev (2010)} identification analysis.
+
+For example, the placing @code{identification; dynare_sensitivity(identification=1, morris=2);}
+in the Dynare model file trigger identification analysis using analytic derivatives
+@cite{Iskrev (2010)}, jointly with the mapping of the acceptable region.
+
+The identification analysis with derivatives can also be triggered by the
+commands @code{identification;} This does not do the mapping of
+acceptable regions for the model and uses the standard random sampler of Dynare.
+It completely offsets any use of the sensitivity analysis toolbox.
+
+
 @node Markov-switching SBVAR
 @section Markov-switching SBVAR
 
-- 
GitLab