update docs

docs/src/tutorials/sw03.md

@@ -12,7 +12,7 @@ ENV["GKSwstype"] = "100"
 
 ```@repl tutorial_2
 using MacroModelling
-@model SW03 begin
+@model Smets_Wouters_2003 begin
     -q[0] + beta * ((1 - tau) * q[1] + epsilon_b[1] * (r_k[1] * z[1] - psi^-1 * r_k[ss] * (-1 + exp(psi * (-1 + z[1])))) * (C[1] - h * C[0])^(-sigma_c))
     -q_f[0] + beta * ((1 - tau) * q_f[1] + epsilon_b[1] * (r_k_f[1] * z_f[1] - psi^-1 * r_k_f[ss] * (-1 + exp(psi * (-1 + z_f[1])))) * (C_f[1] - h * C_f[0])^(-sigma_c))
     -r_k[0] + alpha * epsilon_a[0] * mc[0] * L[0]^(1 - alpha) * (K[-1] * z[0])^(-1 + alpha)
@@ -77,7 +77,7 @@ First, we load the package and then use the [`@model`](@ref) macro to define our
 Next we need to add the parameters of the model. The macro [`@parameters`](@ref) takes care of this:
 
 ```@repl tutorial_2
-@parameters SW03 begin  
+@parameters Smets_Wouters_2003 begin  
     lambda_p = .368
     G_bar = .362
     lambda_w = 0.5
@@ -134,15 +134,15 @@ Second, there are calibration equations where we treat the value of a parameter
 
 Note that we have to write one parameter definition per line.
 
-Given the equations and parameters, the package will first attempt to solve the system of nonlinear equations symbolically (including possible calibration equations). If an analytical solution is not possible, numerical solution methods are used to try and solve it. There is no guarantee that a solution can be found, but it is highly likely, given that a solution exists. The problem setup tries to incorporate parts of the structure of the problem, e.g. bounds on variables: if one equation contains `log(k)` it must be that `k > 0`. Nonetheless, the user can also provide useful information such as variable bounds or initial guesses. Bounds can be set by adding another expression to the parameter block e.g.: `c > 0`. Large values are typically a problem for numerical solvers. Therefore, providing a guess for these values will increase the speed of the solver. Guesses can be provided as a `Dict` after the model name and before the parameter definitions block, e.g.: `@parameters RBC guess = Dict(k => 10) begin ... end`.
+Given the equations and parameters, the package will first attempt to solve the system of nonlinear equations symbolically (including possible calibration equations). If an analytical solution is not possible, numerical solution methods are used to try and solve it. There is no guarantee that a solution can be found, but it is highly likely, given that a solution exists. The problem setup tries to incorporate parts of the structure of the problem, e.g. bounds on variables: if one equation contains `log(k)` it must be that `k > 0`. Nonetheless, the user can also provide useful information such as variable bounds or initial guesses. Bounds can be set by adding another expression to the parameter block e.g.: `c > 0`. Large values are typically a problem for numerical solvers. Therefore, providing a guess for these values will increase the speed of the solver. Guesses can be provided as a `Dict` after the model name and before the parameter definitions block, e.g.: `@parameters Smets_Wouters_2003 guess = Dict(k => 10) begin ... end`.
 
 ## Plot impulse response functions (IRFs)
 
 A useful output to analyze are IRFs for the exogenous shocks. Calling [`plot_irf`](@ref) (different names for the same function are also supported: [`plot_irfs`](@ref), or [`plot_IRF`](@ref)) will take care of this. Please note that you need to import the `StatsPlots` packages once before the first plot. In the background the package solves (numerically in this complex case) for the non stochastic steady state (SS) and calculates the first order perturbation solution.
 
 ```@repl tutorial_2
 import StatsPlots
-plot_irf(SW03)
+plot_irf(Smets_Wouters_2003)
 ```
 
 ![RBC IRF](../assets/irf__SW03__eta_R__1.png)
@@ -156,7 +156,7 @@ The plots show the responses of the endogenous variables to a one standard devia
 Playing around with the model can be especially insightful in the early phase of model development. The package tries to facilitate this process to the extent possible. Typically one wants to try different parameter values and see how the IRFs change. This can be done by using the `parameters` argument of the [`plot_irf`](@ref) function. We pass a `Pair` with the `Symbol` of the parameter (`:` in front of the parameter name) we want to change and its new value to the `parameter` argument (e.g. `:alpha => 0.305`). Furthermore, we want to focus on certain shocks and variables. We select for the example the `eta_R` shock by passing it as a `Symbol` to the `shocks` argument of the [`plot_irf`](@ref) function. For the variables we choose to plot: `U`, `Y`, `I`, `R`, and `C` and achieve that by passing the `Vector` of `Symbol`s to the `variables` argument of the [`plot_irf`](@ref) function:
 
 ```@repl tutorial_2
-plot_irf(SW03, 
+plot_irf(Smets_Wouters_2003, 
          parameters = :alpha => 0.305, 
          variables = [:U,:Y,:I,:R,:C], 
          shocks = :eta_R)
@@ -171,10 +171,10 @@ First, the package finds the new steady state, solves the model dynamics around
 Another insightful output is simulations of the model. Here we can use the [`plot_simulations`](@ref) function. Again we want to only look at a subset of the variables and specify it in the `variables` argument. Please note that you need to import the `StatsPlots` packages once before the first plot. To the same effect we can use the [`plot_irf`](@ref) function and specify in the `shocks` argument that we want to `:simulate` the model and set the `periods` argument to 100.
 
 ```@repl tutorial_2
-plot_simulations(SW03, variables = [:U,:Y,:I,:R,:C])
+plot_simulations(Smets_Wouters_2003, variables = [:U,:Y,:I,:R,:C])
 ```
 
-![Simulate SW03](../assets/irf__SW03__simulation__1.png)
+![Simulate Smets_Wouters_2003](../assets/irf__SW03__simulation__1.png)
 
 The plots show the models endogenous variables in response to random draws for all exogenous shocks over 100 periods.
 
@@ -187,7 +187,7 @@ using AxisKeys
 shock_series = KeyedArray(zeros(2,12), Shocks = [:eta_b, :eta_w], Periods = 1:12)
 shock_series[1,2] = 1
 shock_series[2,12] = -1
-plot_irf(SW03, shocks = shock_series, variables = [:W,:r_k,:w_star,:R])
+plot_irf(Smets_Wouters_2003, shocks = shock_series, variables = [:W,:r_k,:w_star,:R])
 ```
 
 ![Series of shocks RBC](../assets/irf__SW03__shock_matrix__1.png)
@@ -202,13 +202,13 @@ The plot shows the paths of the selected variables for the two shocks hitting th
 The package solves for the SS automatically and we got an idea of the SS values in the plots. If we want to see the SS values and the derivatives of the SS with respect to the model parameters we can call [`get_steady_state`](@ref). The model has 39 parameters and 54 variables. Since we are not interested in all derivatives for all parameters we select a subset. This can be done by passing on a `Vector` of `Symbol`s of the parameters to the `parameter_derivatives` argument:
 
 ```@repl tutorial_2
-get_steady_state(SW03, parameter_derivatives = [:alpha,:beta])
+get_steady_state(Smets_Wouters_2003, parameter_derivatives = [:alpha,:beta])
 ```
 
 The first column of the returned matrix shows the SS while the second to last columns show the derivatives of the SS values (indicated in the rows) with respect to the parameters (indicated in the columns). For example, the derivative of `C` with respect to `beta` is 14.4994. This means that if we increase `beta` by 1, `C` would increase by 14.4994 approximately. Let's see how this plays out by changing `beta` from 0.99 to 0.991 (a change of +0.001):
 
 ```@repl tutorial_2
-get_steady_state(SW03, 
+get_steady_state(Smets_Wouters_2003, 
                  parameter_derivatives = [:alpha,:G_bar], 
                  parameters = :beta => .991)
 ```
@@ -222,7 +222,7 @@ The new value of `beta` changed the SS as expected and `C` increased by 0.01465.
 Next to the SS we can also show the model implied standard deviations of the model. [`get_standard_deviation`](@ref) takes care of this. Additionally we will set the parameter values to what they were in the beginning by passing on a `Tuple` of `Pair`s containing the `Symbol`s of the parameters to be changed and their new (initial) values (e.g. `(:alpha => 0.3, :beta => .99)`).
 
 ```@repl tutorial_2
-get_standard_deviation(SW03, 
+get_standard_deviation(Smets_Wouters_2003, 
                        parameter_derivatives = [:alpha,:beta], 
                        parameters = (:alpha => 0.3, :beta => .99))
 ```
@@ -234,60 +234,60 @@ The function returns the model implied standard deviations of the model variable
 Another useful statistic is the model implied correlation of variables. We use [`get_correlation`](@ref) for this:
 
 ```@repl tutorial_2
-get_correlation(SW03)
+get_correlation(Smets_Wouters_2003)
 ```
 
 ### Autocorrelations
 
 Next, we have a look at the model implied aautocorrelations of model variables using the [`get_autocorrelation`](@ref) function:
 
 ```@repl tutorial_2
-get_autocorrelation(SW03)
+get_autocorrelation(Smets_Wouters_2003)
 ```
 
 ### Variance decomposition
 
 The model implied contribution of each shock to the variance of the model variables can be calculate by using the  [`get_variance_decomposition`](@ref) function:
 
 ```@repl tutorial_2
-get_variance_decomposition(SW03)
+get_variance_decomposition(Smets_Wouters_2003)
 ```
 
 ### Conditional variance decomposition
 
 Last but not least, we have look at the model implied contribution of each shock per period to the variance of the model variables (also called forecast error variance decomposition) by using the  [`get_conditional_variance_decomposition`](@ref) function:
 
 ```@repl tutorial_2
-get_conditional_variance_decomposition(SW03)
+get_conditional_variance_decomposition(Smets_Wouters_2003)
 ```
 
 ### Plot conditional variance decomposition
 
 Especially for the conditional variance decomposition it is convenient to look at a plot instead of the raw numbers. This can be done using the [`plot_conditional_variance_decomposition`](@ref) function. Please note that you need to import the `StatsPlots` packages once before the first plot.
 
 ```@repl tutorial_2
-plot_conditional_variance_decomposition(SW03, variables = [:U,:Y,:I,:R,:C])
+plot_conditional_variance_decomposition(Smets_Wouters_2003, variables = [:U,:Y,:I,:R,:C])
 ```
 
-![FEVD SW03](../assets/fevd__SW03__1.png)
+![FEVD Smets_Wouters_2003](../assets/fevd__SW03__1.png)
 
 ## Model solution
 
 A further insightful output are the policy and transition functions of the the first order perturbation solution. To retrieve the solution we call the function [`get_solution`](@ref):
 
 ```@repl tutorial_2
-get_solution(SW03)
+get_solution(Smets_Wouters_2003)
 ```
 
 The solution provides information about how past states and present shocks impact present variables. The first row contains the SS for the variables denoted in the columns. The second to last rows contain the past states, with the time index `₍₋₁₎`, and present shocks, with exogenous variables denoted by `₍ₓ₎`. For example, the immediate impact of a shock to `eta_w` on `z` is 0.00222469.
 
 There is also the possibility to visually inspect the solution using the [`plot_solution`](@ref) function. Please note that you need to import the `StatsPlots` packages once before the first plot.
 
 ```@repl tutorial_2
-plot_solution(SW03, :pi, variables = [:C,:I,:K,:L,:W,:R])
+plot_solution(Smets_Wouters_2003, :pi, variables = [:C,:I,:K,:L,:W,:R])
 ```
 
-![SW03 solution](../assets/solution__SW03__1.png)
+![Smets_Wouters_2003 solution](../assets/solution__SW03__1.png)
 
 The chart shows the first order perturbation solution mapping from the past state `pi` to the present variables `C`, `I`, `K`, `L`, `W`, and `R`. The state variable covers a range of two standard deviations around the non stochastic steady state and all other states remain in the non stochastic steady state.
 
@@ -297,15 +297,15 @@ Last but not least the user might want to obtain simulated time series of the mo
 For IRFs this is possible by calling [`get_irf`](@ref):
 
 ```@repl tutorial_2
-get_irf(SW03)
+get_irf(Smets_Wouters_2003)
 ```
 
 which returns a 3-dimensional `KeyedArray` with variables  (absolute deviations from the relevant steady state by default) in rows, the period in columns, and the shocks as the third dimension.
 
 For simulations this is possible by calling [`simulate`](@ref):
 
 ```@repl tutorial_2
-simulate(SW03)
+simulate(Smets_Wouters_2003)
 ```
 
 which returns the simulated data in levels in a 3-dimensional `KeyedArray` of the same structure as for the IRFs.
@@ -340,20 +340,20 @@ The above shock `Matrix` means that for the first two periods shocks 1, 2, 3, 5,
 Finally we can get the conditional forecast:
 
 ```@repl tutorial_2
-get_conditional_forecast(SW03, conditions, shocks = shocks, variables = [:Y,:pi,:W], conditions_in_levels = false)
+get_conditional_forecast(Smets_Wouters_2003, conditions, shocks = shocks, variables = [:Y,:pi,:W], conditions_in_levels = false)
 ```
 
 The function returns a `KeyedArray` with the values of the endogenous variables and shocks matching the conditions exactly.
 
 We can also plot the conditional forecast. Please note that you need to import the `StatsPlots` packages once before the first plot.
 
 ```@repl tutorial_2
-plot_conditional_forecast(SW03,conditions, shocks = shocks, plots_per_page = 6,variables = [:Y,:pi,:W],conditions_in_levels = false)
+plot_conditional_forecast(Smets_Wouters_2003,conditions, shocks = shocks, plots_per_page = 6,variables = [:Y,:pi,:W],conditions_in_levels = false)
 ```
 
-![SW03 conditional forecast 1](../assets/conditional_fcst__SW03__conditional_forecast__1.png)
+![Smets_Wouters_2003 conditional forecast 1](../assets/conditional_fcst__SW03__conditional_forecast__1.png)
 
-![SW03 conditional forecast 2](../assets/conditional_fcst__SW03__conditional_forecast__2.png)
+![Smets_Wouters_2003 conditional forecast 2](../assets/conditional_fcst__SW03__conditional_forecast__2.png)
 
 and we need to set `conditions_in_levels = false` since the conditions are defined in deviations.