diff --git a/doc/dynare.texi b/doc/dynare.texi index 5fd0cc9cf..1f4c1a2ba 100644 --- a/doc/dynare.texi +++ b/doc/dynare.texi @@ -2,6 +2,8 @@ @c %**start of header @setfilename dynare.info @documentencoding UTF-8 +@codequoteundirected on + @settitle Dynare Reference Manual @afourwide @dircategory Math @@ -206,6 +208,9 @@ The Model file * Deterministic simulation:: * Stochastic solution and simulation:: * Estimation:: +* Model Comparison:: +* Shock Decomposition:: +* Calibrated Smoother:: * Forecasting:: * Optimal policy:: * Sensitivity and identification analysis:: @@ -1065,6 +1070,9 @@ end of line one and the parser would continue processing. * Deterministic simulation:: * Stochastic solution and simulation:: * Estimation:: +* Model Comparison:: +* Shock Decomposition:: +* Calibrated Smoother:: * Forecasting:: * Optimal policy:: * Sensitivity and identification analysis:: @@ -1104,6 +1112,9 @@ mutually exclusive arguments are separated by vertical bars: @samp{|}; @item @var{INTEGER} indicates an integer number; +@item +@var{INTEGER_VECTOR} indicates a vector of integer numbers [@var{INTEGER_1} ... @var{INTEGER_N}] + @item @var{DOUBLE} indicates a double precision number. The following syntaxes are valid: @code{1.1e3}, @code{1.1E3}, @code{1.1d3}, @code{1.1D3}. In @@ -6970,6 +6981,24 @@ estimates using a higher tapering are usually more reliable. @end table @end defvr +@deffn Command unit_root_vars @var{VARIABLE_NAME}@dots{}; + +This command is deprecated. Use @code{estimation} option @code{diffuse_filter} instead for estimating a model with non-stationary observed variables or @code{steady} option @code{nocheck} to prevent @code{steady} to check the steady state returned by your steady state file. +@end deffn + +Dynare also has the ability to estimate Bayesian VARs: + +@deffn Command bvar_density ; +Computes the marginal density of an estimated BVAR model, using +Minnesota priors. + +See @file{bvar-a-la-sims.pdf}, which comes with Dynare distribution, +for more information on this command. +@end deffn + +@node Model Comparison +@section Model Comparison + @deffn Command model_comparison @var{FILENAME}[(@var{DOUBLE})]@dots{}; @deffnx Command model_comparison (marginal_density = laplace | modifiedharmonicmean) @var{FILENAME}[(@var{DOUBLE})]@dots{}; @anchor{model_comparison} @@ -7045,6 +7074,8 @@ Posterior probability of the respective model @end defvr +@node Shock Decomposition +@section Shock Decomposition @deffn Command shock_decomposition [@var{VARIABLE_NAME}]@dots{}; @deffnx Command shock_decomposition (@var{OPTIONS}@dots{}) [@var{VARIABLE_NAME}]@dots{}; @@ -7083,8 +7114,8 @@ calibrated model. @xref{nobs}. @item use_shock_groups [= @var{STRING}] -@anchor{use_shock_groups} Uses groups of shocks instead of individual shocks in -the decomposition. Groups of shocks are defined in the @ref{shock_groups} block. +@anchor{use_shock_groups} Uses shock grouping defined by the string instead of individual shocks in +the decomposition. The groups of shocks are defined in the @ref{shock_groups} block. @item colormap = @var{STRING} @anchor{colormap} Controls the colormap used for the shocks decomposition @@ -7092,12 +7123,11 @@ graphs. See @code{colormap} in Matlab/Octave manual for valid arguments. @item nograph @xref{nograph}. Suppresses the display and creation only within the -@code{shock_decomposition}-command but does not affect other commands. +@code{shock_decomposition}-command, but does not affect other commands. @xref{plot_shock_decomposition} for plotting graphs. -@item init_state = @var{INTEGER} -@anchor{init_state} It can take values of @math{0} or @math{1}. If equal to -@math{0}, the shock decomposition is computed conditional on the smoothed state +@item init_state = @var{BOOLEAN} +@anchor{init_state} If equal to @math{0}, the shock decomposition is computed conditional on the smoothed state variables in period @math{0}, @i{i.e.} the smoothed shocks starting in period @math{1} are used. If equal to @math{1}, the shock decomposition is computed conditional on the smoothed state variables in period @math{1}. Default: @@ -7106,10 +7136,12 @@ conditional on the smoothed state variables in period @math{1}. Default: @outputhead +@defvr {MATLAB/Octave variable} oo_.shock_decomposition @vindex oo_.shock_decomposition +@anchor{oo_.shock_decomposition} The results are stored in the field @code{oo_.shock_decomposition}, which is a three dimensional array. The first dimension contains the @code{M_.endo_nbr} endogenous variables. -The second dimension stores +The second dimension stores in the first @code{M_.exo_nbr} columns the contribution of the respective shocks. Column @code{M_.exo_nbr+1} stores the contribution of the initial conditions, while column @code{M_.exo_nbr+2} stores the smoothed value of the respective @@ -7117,6 +7149,7 @@ endogenous variable in deviations from their steady state, @i{i.e.} the mean and subtracted. The third dimension stores the time periods. Both the variables and shocks are stored in the order of declaration, @i{i.e.} @code{M_.endo_names} and @code{M_.exo_names}, respectively. +@end defvr @end deffn @@ -7127,11 +7160,11 @@ and shocks are stored in the order of declaration, @i{i.e.} @code{M_.endo_names} of the shock groups is written in a block delimited by @code{shock_groups} and @code{end}. -Each line defines a group of shock as a list of exogenous variables: +Each line defines a group of shocks as a list of exogenous variables: @example SHOCK_GROUP_NAME = VARIABLE_1 [[,] VARIABLE_2 [,]@dots{}]; -`SHOCK GROUP NAME' = VARIABLE_1 [[,] VARIABLE_2 [,]@dots{}]; +'SHOCK GROUP NAME' = VARIABLE_1 [[,] VARIABLE_2 [,]@dots{}]; @end example @optionshead @@ -7155,12 +7188,13 @@ varexo e_a, e_b, e_c, e_d; shock_groups(name=group1); supply = e_a, e_b; -`aggregate demand' = e_c, e_d; +'aggregate demand' = e_c, e_d; end; shocks_decomposition(use_shock_groups=group1); @end example - +This example defines a shock grouping with the name @code{group1}, containing a set of supply and demand shocks +and conducts the shock decomposition for these two groups. @end deffn @deffn Command realtime_shock_decomposition [@var{VARIABLE_NAME}]@dots{}; @@ -7171,16 +7205,22 @@ shocks_decomposition(use_shock_groups=group1); This command computes the realtime historical shock decomposition for a given sample based on the Kalman smoother. For each period -@math{T=[@code{presample}@dots{}@code{nobs}]}, it computes the: +@math{T=[@code{presample},@dots{},@code{nobs}]}, it recursively computes three objects: @itemize @bullet @item -realtime historical shock decomposition @math{Y(t|T)} for @math{t=[1@dots{}T]}, -@i{i.e.} without observing data in @math{[T+1@dots{}@code{nobs}]}; +realtime historical shock decomposition @math{Y(t|T)} for @math{t=[1,@dots{},T]}, +@i{i.e.} without observing data in @math{[T+1,@dots{},@code{nobs}]}. This results in a standard +shock decomposition being computed for each additional datapoint becoming available after @code{presample}. @item -conditional shock decomposition @math{Y(T|T)} conditional on @math{Y(T|T-1)}, -@i{i.e.} @math{Y(t|T)} for @math{t=[T-1@dots{}T]}; +forecast shock decomposition @math{Y(T+k|T)} for @math{k=[1,@dots{},forecast]}, @i{i.e.} the @math{k}-step +ahead forecast made for every @math{T} is decomposed in its shock contributions. @item -forecast shock decomposition @math{Y(T|T-1)}. +realtime conditional shock decomposition of the difference between the realtime historical shock decomposition and the +forecast shock decomposition. If @ref{vintage} is equal to @math{0}, it computes the effect of shocks realizing in period +@math{T}, @i{i.e.} decomposes @math{Y(T|T)-Y(T|T-1)}. Put differently it conducts a @math{1}-period ahead shock decomposition from +@math{T-1} to @math{T}, by decomposing the update step of the Kalman filter. If @code{vintage>0} and smaller than @code{nobs}, +the decomposition is conducted of the forecast revision @math{Y(T+k|T+k)-Y(T+k|T)}. + @end itemize Like @ref{shock_decomposition} it decomposes the historical deviations of the endogenous @@ -7228,40 +7268,79 @@ realtime shock decompositions are computed, @i{i.e.} for @anchor{forecast_shock_decomposition} Compute shock decompositions up to @math{T+k} periods, @i{i.e.} get shock contributions to k-step ahead forecasts. -@item save_realtime = [@var{integer1} ... @var{integern}] +@item save_realtime = [@var{INTEGER_VECTOR}] @anchor{save_realtime} Choose for which vintages to save the full realtime shock decomposition. Default: @math{0}. @end table @outputhead +@defvr {MATLAB/Octave variable} oo_.realtime_shock_decomposition @vindex oo_.realtime_shock_decomposition -The results of realtime historical decompositions are stored in the field -@code{oo_.realtime_shock_decomposition}, which is a structure. Field -@code{pool} stores the pooled decomposition (@xref{plot_shock_decomposition}). -Fields @code{time_*} store the vintages of realtime historical shock -decompositions. +Structure storing the results of realtime historical decompositions. Fields are three-dimensional arrays with +the first two dimension equal to the ones of @ref{oo_.shock_decomposition}. The third dimension stores the time +periods and is therefore of size @code{T+forecast}. Fields are of the form: +@example +@code{oo_.realtime_shock_decomposition.@var{OBJECT}} +@end example +where @var{OBJECT} is one of the following: -@vindex oo_.conditional_shock_decomposition -The results of realtime conditional decompositions are stored in the field -@code{oo_.conditional_shock_decomposition}, which is a structure. Field -@code{pool} stores the pooled decomposition @math{Y(t|T)} for -@math{t=T-1@dots{}T} @xref{plot_shock_decomposition}. Conditional shock -decomposition sets the initial condition in @math{T-1}, so only computes the -effect of shocks in period @math{T}, @i{i.e.} it is just a @math{1}-period -shock decomposition from @math{T-1} to @math{T}. In practice it decomposes the -update step of the Kalman filter. Fields @code{time_*} store the vintages of -@math{k}-step conditional forecast shock decompositions @math{Y(t|T+k)}, for -@math{t=[T@dots{}T+k}. @xref{vintage}. +@table @code +@item pool +Stores the pooled decomposition, @i{i.e.} for every realtime shock decomposition terminal period +@math{T=[@code{presample},@dots{},@code{nobs}]} it collects the last period's decomposition @math{Y(T|T)} +(see also @ref{plot_shock_decomposition}). The third dimension of the array will have size +@code{nobs+forecast}. + +@item time_* +Stores the vintages of realtime historical shock decompositions if @code{save_realtime} is used. For example, if +@code{save_realtime=[5]} and @code{forecast=8}, the third dimension will be of size 13. + +@end table +@end defvr + +@defvr {MATLAB/Octave variable} oo_.realtime_conditional_shock_decomposition +@vindex oo_.realtime_conditional_shock_decomposition +Structure storing the results of realtime conditional decompositions. Fields are of the form: +@example +@code{oo_.realtime_conditional_shock_decomposition.@var{OBJECT}} +@end example +where @var{OBJECT} is one of the following: + +@table @code + +@item pool +Stores the pooled realtime conditional shock decomposition, @i{i.e.} collects the decompositions of +@math{Y(T|T)-Y(T|T-1)} for the terminal periods @math{T=[@code{presample},@dots{},@code{nobs}]}. +The third dimension is of size @code{nobs}. + +@item time_* +Store the vintages of @math{k}-step conditional forecast shock decompositions @math{Y(t|T+k)}, for +@math{t=[T@dots{}T+k]}. @xref{vintage}. The third dimension is of size @code{1+forecast}. + +@end table +@end defvr + +@defvr {MATLAB/Octave variable} oo_.realtime_forecast_shock_decomposition @vindex oo_.realtime_forecast_shock_decomposition -The results of realtime forecast decompositions are stored in the field -@code{oo_.realtime_forecast_shock_decomposition}, which is a structure. Field -@code{pool} stores the pooled decomposition @xref{plot_shock_decomposition}. -Forecast shock decomposition computes the @math{1}-step ahead effect of shocks -on the @math{1}-step ahead prediction, @i{i.e.} @math{Y(T|T-1)}. Fields -@code{time_*} store the vintages of @math{k}-step out-of-sample forecast shock +Structure storing the results of realtime forecast decompositions. Fields are of the form: +@example +@code{oo_.realtime_forecast_shock_decomposition.@var{OBJECT}} +@end example +where @var{OBJECT} is one of the following: + +@table @code + +@item pool +Stores the pooled realtime forecast decomposition of the @math{1}-step ahead effect of shocks +on the @math{1}-step ahead prediction, @i{i.e.} @math{Y(T|T-1)}. + +@item time_* +Stores the vintages of @math{k}-step out-of-sample forecast shock decompositions, @i{i.e.} @math{Y(t|T)}, for @math{t=[T@dots{}T+k]}. @xref{vintage}. +@end table +@end defvr @end deffn @@ -7272,12 +7351,11 @@ decompositions, @i{i.e.} @math{Y(t|T)}, for @math{t=[T@dots{}T+k]}. @xref{vintag @descriptionhead This command plots the historical shock decomposition already computed by -@code{shock_decomposition}. The @code{variable_names} provided govern which +@code{shock_decomposition} or @code{realtime_shock_decomposition}. For that reason, +it must come after one of these commands. The @code{variable_names} provided govern which variables the decomposition is plotted for. -Note that this command must come after @code{shock_decomposition} or @code{realtime_shock_decomposition}. - -Further note that, unlike the majority of dynare commands, the options +Further note that, unlike the majority of Dynare commands, the options specified below are overwritten with their defaults before every call to @code{plot_shock_decomposition}. Hence, if you want to reuse an option in a subsequent call to @code{plot_shock_decomposition}, you must pass it to the @@ -7300,14 +7378,14 @@ command again. @itemx graph_format = ( @var{FORMAT}, @var{FORMAT}@dots{} ) @xref{graph_format}. -@item detail_plot = @var{INT_NUMBER} +@item detail_plot Plots shock contributions using subplots, one per shock (or group of shocks). Pass @math{1} to turn it on and @math{0} to turn it off. Default: -@math{0} +not activated -@item interactive = @var{INT_NUMBER} -Under MATLAB, add uimenu's for detailed group plots. Pass @math{1} to turn it -on and @math{0} to turn it off. Default: @math{0} +@item interactive +Under MATLAB, add uimenus for detailed group plots. Pass @math{1} to turn it +on and @math{0} to turn it off. Default: not activated @item screen_shocks @anchor{screen_shcoks} For large models (@i{i.e.} for models with more than @math{16} @@ -7315,10 +7393,10 @@ shocks), plots only the shocks that have the largest historical contribution for chosen selected @code{variable_names}. Historical contribution is ranked by the mean absolute value of all historical contributions. -@item steadystate = @var{INTEGER} +@item steadystate @anchor{steadystate} If equal to @math{1}, the the @math{y}-axis value of the zero line in the shock decomposition plot is translated to the steady state -level. Default: @math{0} +level. Default: not activated @item type = @code{qoq} | @code{yoy} | @code{aoa} @anchor{type} For quarterly data, valid arguments are: @code{qoq} for @@ -7333,82 +7411,54 @@ default figure name set by @code{plot_shock_decomposition}. This can avoid to overwrite plots in case of sequential calls to @code{plot_shock_decomposition}. @item write_xls -@anchor{write_xls} Saves shock decompositions to excel. +@anchor{write_xls} Saves shock decompositions to Excel-file in the main directory, named +@code{FILENAME_shock_decomposition_TYPE_FIG_NAME.xls}. This option requires your system to be +configured to be able to write Excel files.@footnote{In case of Excel not being installed, +@url{https://mathworks.com/matlabcentral/fileexchange/38591-xlwrite--generate-xls-x--files-without-excel-on-mac-linux-win} may be helpful.} @item realtime = @var{INTEGER} @anchor{realtime} Which kind of shock decomposition to plot. @var{INTEGER} can take following values: @itemize @bullet @item -@code{0}: historical shock decomposition: @math{Y(t|T)} for -@math{t=[1@dots{}T]}, @math{T=} @code{nobs} full sample +@code{0}: standard historical shock decomposition. @xref{shock_decomposition}. @item -@code{1}: realtime historical shock decomposition: for -@math{T=[1@dots{}@code{nobs}]}, realtime shock decomposition @math{Y(t|T)} for -@math{t=[1@dots{}T]} +@code{1}: realtime historical shock decomposition. @xref{realtime_shock_decomposition}. @item -@code{2}: conditional shock decomposition: for @code{T=1:nobs}, realtime shock -decomposition of @math{Y(T|T)} conditional on @math{Y(T|T-1)}, @i{i.e.} -@math{Y(t|T)} for @math{t=[T-1@dots{}T]} +@code{2}: conditional realtime shock decomposition. @xref{realtime_shock_decomposition}. @item -@code{3}: forecast shock decomposition: for @math{T=[1@dots{}@code{nobs}]}, -realtime shock decomposition of @math{Y(T|T-1)} +@code{3}: realtime forecast shock decomposition. @xref{realtime_shock_decomposition}. @end itemize +If no @ref{vintage} is requested, @i{i.e.} @code{vintage=0} then the pooled objects from @ref{realtime_shock_decomposition} +will be plotted and the respective vintage otherwise. Default: @math{0} @item vintage = @var{INTEGER} -@anchor{vintage} Applies if @code{realtime}@math{>0}. Can take following values: -@itemize @bullet -@item -@code{0}: plots @math{1}-step pooled shock decompositions -@item -@code{1}: pooled realtime shock decomposition. For @math{T=[1@dots{}@code{nobs}]}, plots last -time point @math{Y(T|T)} of each vintage shock decomposition @math{Y(1:T|T)} -@item -@code{2}: pooled conditional shock decomposition. For -@math{T=[1@dots{}@code{nobs}]}, realtime @math{1}-step shock decomposition of -@math{Y(T|T)} conditional on @math{Y(T|T-1)} (@i{i.e.} decomposition of -@math{1}-step filter updates of each vintage @math{T}) -@item -@code{3}: pooled forecast shock decomposition. For -@math{T=[1@dots{}@code{nobs}]}, realtime @math{1}-step ahead shock -decomposition of @math{Y(T|T-1)} (@i{i.e.} decomposition of shock -contributions to @math{1}-step ahead forecasts of each vintage @math{T}) -@end itemize -When the value passed is greater than @math{0}, it plots the shock +@anchor{vintage} Selects a particular data vintage in @math{[presample,@dots{},nobs]} for which to plot the results from +@ref{realtime_shock_decomposition} selected via the @ref{realtime} option. If the standard +historical shock decomposition is selected (@code{realtime=0}), @code{vintage} will have no effect. If @code{vintage=0} +the pooled objects from @ref{realtime_shock_decomposition} will be plotted. If @code{vintage>0}, it plots the shock decompositions for vintage @math{T=@code{vintage}} under the following scenarios: @itemize @bullet @item @code{realtime=1}: the full vintage shock decomposition @math{Y(t|T)} for -@math{t=[1@dots{}T]} +@math{t=[1,@dots{},T]} @item @code{realtime=2}: the conditional forecast shock decomposition from @math{T}, @i{i.e.} plots @math{Y(T+j|T+j)} and the shock contributions needed to get to the data @math{Y(T+j)} conditional on @math{T=}@code{vintage}, with -@math{j=[0@dots{}@code{forecast}]}. +@math{j=[0,@dots{},@code{forecast}]}. @item @code{realtime=3}: plots unconditional forecast shock decomposition from @math{T}, @i{i.e.} @math{Y(T+j|T)}, where @math{T=@code{vintage}} and -@math{j=[0@dots{}@code{forecast}]}. +@math{j=[0,@dots{},@code{forecast}]}. @end itemize Default: @math{0} @end table @end deffn -@deffn Command unit_root_vars @var{VARIABLE_NAME}@dots{}; - -This command is deprecated. Use @code{estimation} option @code{diffuse_filter} instead for estimating a model with non-stationary observed variables or @code{steady} option @code{nocheck} to prevent @code{steady} to check the steady state returned by your steady state file. -@end deffn - -Dynare also has the ability to estimate Bayesian VARs: - -@deffn Command bvar_density ; -Computes the marginal density of an estimated BVAR model, using -Minnesota priors. - -See @file{bvar-a-la-sims.pdf}, which comes with Dynare distribution, -for more information on this command. -@end deffn +@node Calibrated Smoother +@section Calibrated Smoother Dynare can also run the smoother on a calibrated model: