HowToAddModels.tex

Adding a new model to the data base consists of four steps. First, the original model has to be translated into a DYNARE mod-file and the common Modelbase variables have to be defined as functions of the original model variables. Second, the mod-file must be stored under the model name in a folder with exactly the same label. Third, a json-file, which builds the link between the mod file and the GUI, has to be created. It also has to have the same  name and be stored in the same folder. The folder with both files has to be stored in the subdirectory `resources/app/dist/electron/static/mmci-cli/models'. Fourth, the GUI needs to be reloaded to incorporate the new model.\\
%Third, the new model has to be initialized in the Modelbase interface.  {\bf Figure 9} illustrates the Modelbase folders and in red we attract attention to the folders/files where one should initialize the new model. In the following, each of these steps is described in detail. \\

%\begin{figure}[H]
%\centering
%\caption{\textsc{Adding models in the Modelbase}}
%\vspace{0.2cm}
%\includegraphics[width=15cm,keepaspectratio]{../figures2_3/12addmodel.jpg}
%\label{img:MenuStructure6}
%\end{figure}

\noindent {\it Step 1: Create a Dynare mod-file}

\begin{itemize}
\item The first task when adding a new model to the Modelbase is to create a DYNARE mod-file. The file should start with a comment section giving some information about the associated reference paper(s) for the model.
\item The file must have the usual structure of a DYNARE mod-file. That is, one starts with the initialization of variables, shocks and parameters. Then the equations describing the model follow and finally the variance-covariance structure of the shocks is specified.
\item However, each of the sections mentioned before has to be augmented by a Modelbase block. This Modelbase block should be visually separated from the original model sections through a comment line \textit{//*******}.
\item After the initialization of the original model variables, the common block \textit{Modelbase Variables} follows. It consists of the six common variables \textit{interest}, \textit{inflation}, \textit{inflationq}, \textit{outputgap}, \textit{output} and \textit{fispol}. Those variables will be described below. If output is not specified in the model, then the common variable \textit{output} has to be left out. Furthermore, in some small models, one may have to leave out the \textit{fispol} variable. This common block corresponds to lines 4 to 7 in {\bf Figure \ref{img:modStructureRW97a}}
\item The common block \textit{Modelbase Shocks} is added after the initialization of the original model shocks as in lines 10 to 13 of {\bf Figure \ref{img:modStructureRW97a}}. It consists of a common monetary policy shock, \textit{interest\_}, and of a common fiscal policy shock, \textit{fiscal\_}.
\item The third common block is the \textit{Modelbase Parameters} section. Following the initialization of the original model parameters, the common Modelbase parameters are preset, consisting of the monetary policy rule parameters and the discretionary fiscal policy parameter \textit{coffispol}. For the Dynare 4 version of the Modelbase, one first defines the Modelbase parameters and afterwards the original model-specific parameters.
\item It follows the numeric specification of the parameters. This is done first for the model-specific parameters and then separately for the common Modelbase parameters in the block called \textit{Specification of Modelbase Parameters}. First, the parameter values of the selected monetary policy rule are loaded. They are contained in the file \textit{policy\_param.mat} in the subfolder \textit{WORK}. For models in which the original shocks are expressed in percent/100, the parameter \textit{std\_r\_} has to be reset to 100 after the parameter-loading command. This specification is required for the proper calculation of impulse response functions. In our example this would have to be done after line 44. However, the shocks in the example are already expressed in percentage terms. Secondly, the discretionary fiscal policy parameter \textit{coffispol} is defined as a function of the model-specific parameters such that a unit government spending shock has a unit impact on output. In our example no adjustment is needed and hence \textit{coffispol} is set equal to one. %In the Dynare 4 version of the Modelbase the command lines to load the policy rule parameters are slightly different, as documented in {\bf Figure \ref{img:modStructureRW97D4}}.
\item At the beginning of the model section, a \textit{model-specific} Modelbase block has to be added in order to define the common Modelbase variables in terms of original model variables. This is done in lines 52 to 59 in our example. The variable \textit{interest} is defined as the annualized short-term interest rate set by the policy maker. The variable \textit{inflation} denotes the year-on-year inflation rate in percent and \textit{inflationq} denotes the annualized quarter-to-quarter inflation rate in percent. If for instance the original model variable representing quarterly inflation is not annualized, then \textit{inflationq} would have to be specified as four times the original quarter-to-quarter inflation variable. The common variables \textit{outputgap} and \textit{output} represent the output gap and output, respectively.
\item The variable \textit{fispol} specifies the common discretionary fiscal policy variable. For implementation of the discretionary fiscal policy variable, one does not have to change the original model equations. The original shock that should represent the common fiscal policy shock has to be initialized as endogenous variable, i.e. following the command \textit{var} instead of \textit{varexo}. In our example the original government spending shock \textit{g\_} is initialized in this way. Furthermore, in the section in which the shock variances are specified, this original shock has to be replaced by the common shock \textit{fiscal\_}. The \textit{fispol} variable has to be set equal to the original shock variable.
If there does not exist a fiscal policy shock in the original model, \textit{fiscal\_} and \textit{fispol} should not be initialized.
\item Afterwards the common \textit{Policy Rule} block is added to the mod-file, specifying the general monetary policy rule, as it is done in lines 62 to 72 in {\bf Figure \ref{img:modStructureRW97b}}. For the sake of brevity we have not displayed the complete general policy rule in our example. The original monetary policy rule has to be commented out in the original model code. In case the model contains a fiscal policy shock, common discretionary government spending is also specified in the \textit{Policy Rule} block, expressing \textit{fispol} as a function of the \textit{fiscal\_} shock, as in line 75 of {\bf Figure \ref{img:modStructureRW97b}}. Hence, the common shock \textit{fiscal\_} affects the fiscal policy
variable \textit{fispol} through this common discretionary government spending expression and \textit{fispol} is set equal to the model-specific
government spending shock \textit{g\_} in line 59. The original model equations following this block remain unchanged.
\item The variances of the two common shocks are specified together with the variances/covariances of the model-specific shocks. Specifically, the variance of the monetary policy shock \textit{interest\_} is set equal to zero and therefore it does not have to show up explicitly. For the fiscal policy shock \textit{fiscal\_} one adopts the original covariance specification of the replaced shock if available. Otherwise one sets the variance of the fiscal policy shock equal to zero.
\item Finally, one has to delete or out-comment the commands for finding the steady state and solving the model as it is done in line 95 of our example.
\item NOTE: if your mod-file draws on other files, e.g. a `\textit{steadystate.m}' file, put these into the same folder.

%
\end{itemize}
%\begin{figure}[H]
%\centering
%\caption{\textsc{Adding models in the Modelbase}}
%\vspace{0.2cm}
%\includegraphics[width=15cm,keepaspectratio]{../figures/addmodel.eps}
%\label{img:MenuStructure6}
%\end{figure}

\noindent {\it Step 2: Save the Dynare mod-file}

\begin{itemize}
\item Next, the file has to be stored as mod-file under the model name. In the example, the \textit{NK\_RW97} model is stored as \textit{NK\_RW97.mod}. The name of calibrated New Keynesian models should start with \textit{NK}, models of the US economy should start with \textit{US} and models of the Euro area should start with \textit{EA}. The full model name should allow for the identification of the specific model among the other Modelbase models. The file must be stored in a folder that has to be created under exactly the same model name and that is positioned in the subfolder \textit{MODEL}, i.e. the created mod-file would be on the path `resources/app/dist/electron/static/mmci-cli/models/NK\_RW97/NK\_RW97.mod'.
\end{itemize}

\noindent {\it Step 3: Create a json-file.}

\begin{itemize}
\item The json creates the link between the mod-file and the MMB. The structure is as explained in section \ref{sec:ModelfileStructure} and shown in figure \ref{img:jsonstructure}. 
Please feel free to copy the format of any model's json-file provided in the MMB package to create your own json-file. While users should change some entries in the json-file based on their model features and preferences, please keep in mind that the style of punctuation marks should remain the same.
In particular, the contents of the json have to be in curly brackets (\{...\}) and blocks are separated by commas.
%\item First, specify that your json refers to a model by setting \texttt{"\$schema": "model"},
\item For \texttt{"\$schema"}, keep \texttt{"model"} to indicate that the json-file refers to a model.
%\item Second, specify the name of your model \texttt{"name": \textit{name}}, which should be the same you have given to the folder, the mod-file and the json-file.
\item For \texttt{"name"}, type the name of your new model, which should be the same as your mod-file's name.
%\item Third, the \texttt{"capabilities"} block specifies which of the common variables and shocks are available in the model; you can enable them by setting them to \texttt{true} or disable by \texttt{false}.
\item For \texttt{"capabilities"}, type \texttt{true} to enable common variables and shocks available in your new model, or \texttt{false} to disable them.
Type the corresponding numbers to the policy rules (see table below) chosen to run with your model. 
%You have to enter the rule ids in square brackets ($[$ ... $]$) and separate them by commas. The number coding is as follows:
	\begin{table}[H]
	\centering
	\begin{tabular}{rll}
		Rule number & Abbreviation & Reference paper\\
		\hline
		 3 & Taylor & \cite{Taylor1993}\\
		 4 & GR & \cite{GerdesmeierRoffia2004}\\
		 5 & LWW & \cite{LevinWielandWilliams2003}\\
		 6 & SW & \cite{SmetsWouters2007}\\
		 7 &  CEE & \cite{ChristianoEichenbaumEvans2005}\\
		 8 & OW08 & \cite{OrphanidesWieland2008}\\
		 9 & OW13 & \cite{OrphanidesWieland2013}\\
		 10 & Coenen & \citet{Coenenetal2012}\\
		 11 & CMR & \cite{CMR2014}\\		 
	\end{tabular}
	\end{table}
You can specify whether the variances shown are unconditional. For the moment being this is true for all models in the MMB, so set \texttt{"unconditional\_variances": true}.
%\item Fifth, add the \texttt{"description"}. \texttt{"category"} defines in which category the model falls and hence where it will be displayed in the interface. The option are \texttt{Calibrated model}, \texttt{Estimated euro area model}, \texttt{Estimated US model}, \texttt{Estimated other-country model} and \texttt{Adaptive learning model}. Note that these entries are case sensitive.
\item For \texttt{"description"}, change the entries based on the information of your new model. For \texttt{"category"}, type (case sensitive) \texttt{Calibrated model}, \texttt{Estimated euro area model}, \texttt{Estimated US model}, \texttt{Estimated other-country model}, or \texttt{Adaptive learning model} - your new model will be displayed in the corresponding list on the MMB interface.
%\item Sixth, specify whether a model-specific rule is available. If the model-specific rule cannot be expressed in terms of the common variables, set \texttt{"msr": null}. If a compatible model-specific rule is available, specify the parameters in square brackets. See section \ref{sec:HowToAddRules} for details.
\item For \texttt{"msr"}, specify the coefficients in square brackets if your modes has a specific monetary policy rule that can bee expressed in terms of the common variables (see details in section \ref{sec:HowToAddRules}), or type \texttt{null} otherwise.
%\item Seventh, specify the dimension of the shock by setting \texttt{"variabledim"} to \texttt{1}, if the shock is expressed in percent or to \texttt{2} if the shock is expressed in percent/100.
\item For \texttt{"variabledim"} type \texttt{1} if the shock is expressed in percent, or \texttt{2} if the shock is expressed in percent/100.
%\item Eighth, specify whether the model features adaptive learning. If not, set \texttt{"al": false} and \texttt{"al\_info": null}, if yes set \texttt{"al": true} and use the block \texttt{"al\_info": \{...\}} to specify the \texttt{forwards}, \texttt{states\_long} and \texttt{states\_short} (see figure \ref{img:jsonmsr} for an example).
\item For \texttt{"al"} type \texttt{true} if your new model features adaptive learning, or \texttt{false} otherwise.
%\item Ninth, specify the shocks available in your model by setting the \texttt{"shocks": $[$...$]$} block. Shocks need to be in curly brackets (\{...\}) and be separated by commas. For each shock you need a \texttt{"name": "\textit{name}"} which is the same as in the mod-file and a \texttt{"text": "\textit{displayed\_name}"} which will be shown in the MMB interface. This block should at least include the common Monetary Policy Shock.
\item For \texttt{"shocks"}, list all the shocks in your model. For each shock, type the shock's notation, same as that in your mod-file, after \texttt{"name"} and the shock's name after \texttt{"text"}, for instance \texttt{"name": "z", "text": "Technology shock"}.
\item For \texttt{"al\_info"} specify the \texttt{forwards}, \texttt{states\_long} and \texttt{states\_short} if your model features adaptive learning - see figure \ref{img:jsonmsr}, or \texttt{null} otherwise.
%\item Tenth, use the \texttt{"variables"} block to specify all variables in your model, i.e. both, model-specific variable as well as common variables. This block follow the same syntax as the  \texttt{"shocks"} block.
\item For \texttt{"variables"}, type alle of the variables in your new model, including the MMB common variables. For each variable, type the variable's notation, same as that in your mod-file, after \texttt{"name"} and the variable's name after \texttt{"text"}.
\item Save the json-file in the same folder where you saved the mod-file.

\end{itemize}


\noindent {\it Step 4: Initializing the model in the Modelbase interface.} %\textit{MMB.m} file}

\begin{itemize}
%\item As the final step, one initiates the model in the Modelbase interface.
\item After relaunching the interface, click on `Menu' in the upper right corner as shown in \ref{img:Settings} and click on `Reload Data'. The new model should now appear in the list that you specified in \texttt{"category"} of the json-file. 
%\item In \textit{MMB.m}, the model name has to be added at the corresponding position to the vector \textit{names}. Currently, one can substitute the New\_Model with the name of the model one is adding.
%  Next, a new entry has to be added at the corresponding position to the vector \textit{variabledim}. This entry has to be \textit{1} if the standard deviations of the model-specific shocks are expressed in percent and it has to be \textit{2} if the standard deviations are expressed in percent/100. Lastly, a new entry has to be added as well at \textit{mycolor}. Also, the model should be assigned to one of the five model categories in Modelbase.
%\item The new models should be also initialized in \textit{OPT1MENU.m} and \textit{OPT2MENU.m} files under the MMB\_OPTIONS folder. Please consult Section \ref{sec:HowToUseGUI} for instructions how to do this.
%\item The model name should be updated also in the Modelbase graphical interface with Graphical User Interface Developing Environment (in short GUIDE) available in MATLAB. Currently we show the reserved places for new models, under the name \textit{New Model}. For instructions how to do this please consult Section \ref{sec:HowToUseGUI}.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%