Add comment with brief description of each auxiliary function

mikkelpm · Oct 31, 2020 · 0d90b78 · 0d90b78
1 parent 593586a
commit 0d90b78
Show file tree

Hide file tree

Showing 28 changed files with 62 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Instrumental variable identification of dynamic variance decompositions
 
-Matlab code for inference on variance decompositions and the degree of invertibility/recoverability in a general Structural Vector Moving Average (SVMA) model identified by external instruments (IVs)
+Matlab code for inference on variance decompositions and the degree of invertibility/recoverability in a general Structural Vector Moving Average (SVMA) model identified by external instruments (IVs, also known as proxies)
 
 **Reference:**
 Plagborg-Møller, Mikkel and Christian K. Wolf (2020), "Instrumental Variable Identification of Dynamic Variance Decompositions", https://scholar.princeton.edu/mikkelpm/decomp_iv
@@ -43,7 +43,7 @@ Output:
 - `id_recov` structure: results under additional assumption of recoverability
   - `id_recov.estim`: point estimates of parameters
   - `id_recov.ci`: confidence intervals for parameters
-- `inv_test` structure: pre-test for invertibility, implemented either as a Granger casuality test for all equations jointly (subfield `all`) or in each *y* equation separately (subfield `eqns`)
+- `inv_test` structure: pre-test for invertibility, implemented as a Granger casuality test, either in all equations jointly (subfield `all`) or in each *y* equation separately (subfield `eqns`)
   - `inv_test.wald_stat`: Wald statistics
   - `inv_test.df`: degrees of freedom
   - `inv_test.pval`: p-values

diff --git a/functions/CI_SVARIV_fun.m b/functions/CI_SVARIV_fun.m
@@ -1,5 +1,7 @@
 function [IRF_CI,FVD_CI] = CI_SVARIV_fun(SVARIV_OLS,SVARIV_boot,settings)
 
+% Bootstrap confidence intervals, SVAR-IV
+
 %----------------------------------------------------------------
 % IRF
 %----------------------------------------------------------------

diff --git a/functions/CI_fun.m b/functions/CI_fun.m
@@ -1,5 +1,7 @@
 function [bounds_CI_IS,bounds_CI_para] = CI_fun(bounds_boot,bounds_OLS,settings)
 
+% Bootstrap confidence intervals
+
 %----------------------------------------------------------------
 % Get Inputs
 %----------------------------------------------------------------
@@ -29,7 +31,7 @@
 end
 
 %----------------------------------------------------------------
-% CI for Parameter
+% CI for Parameter (Stoye, 2009)
 %----------------------------------------------------------------
 
 bounds_CI_para = struct;

diff --git a/functions/FVD_IS.m b/functions/FVD_IS.m
@@ -1,5 +1,7 @@
 function FVD_LB = FVD_IS(yzt_aux,model,settings,alpha)
 
+% Identified set for forecast variance decomposition
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/FVD_fun.m b/functions/FVD_fun.m
@@ -1,5 +1,7 @@
 function FVD = FVD_fun(var,hor,yzt_aux,alpha);
 
+% Forecast variance decomposition bound
+
 Sigma_yzt       = yzt_aux.Sigma_yzt;
 
 maxVar_yt_ythor = yzt_aux.maxVar_yt_ythor(:,:,hor);

diff --git a/functions/FVR_IS.m b/functions/FVR_IS.m
@@ -1,5 +1,7 @@
 function [FVR_LB,FVR_UB,FVR_true] = FVR_IS(yzt_aux,model,settings,alpha)
 
+% Identified set for forecast variance ratio
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/FVR_fun.m b/functions/FVR_fun.m
@@ -1,5 +1,7 @@
 function FVR = FVR_fun(var,hor,yzt_aux,alpha);
 
+% Forecast variance ratio, given alpha
+
 Sigma_yzt     = yzt_aux.Sigma_yzt;
 
 Var_y_yhor = yzt_aux.Var_y_yhor(:,:,hor);

diff --git a/functions/Kalman_filter.m b/functions/Kalman_filter.m
@@ -1,5 +1,7 @@
 function [cond_var,cond_var_1] = Kalman_filter(A,B,C,y)
 
+% Kalman filter for conditional variance calculations
+
 % number of observations and variables
 T = size(y,1);
 n_s = size(A,1);

diff --git a/functions/R2_IS.m b/functions/R2_IS.m
@@ -1,5 +1,7 @@
 function [R2_LB,R2_UB,R2_true] = R2_IS(yzt_aux,model,settings,R2_hor,alpha);
 
+% Identified set for degree of invertibility out to time t+l
+
 %----------------------------------------------------------------
 % Get Inputs
 %----------------------------------------------------------------

diff --git a/functions/SVARIV_analysis.m b/functions/SVARIV_analysis.m
@@ -1,5 +1,8 @@
 function [SVARIV_IRF,SVARIV_FVD,SVARIV_weights] = SVARIV_analysis(VAR,model,settings)
 
+% Impulse responses, forecast variance decompositions, and
+% non-invertibility weights for SVAR-IV analysis
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/SVARIV_estim.m b/functions/SVARIV_estim.m
@@ -31,7 +31,7 @@
 
     % Optional inputs: output requested
     addParameter(ip, 'horiz', 1:24, @isnumeric);            % 1 x k     Horizons of IRF/FVD to report (default: 1:24)
-    addParameter(ip, 'verbose', true, @islogical);          % bool      Print progress to screen?
+    addParameter(ip, 'verbose', true, @islogical);          % bool      Print progress to screen? (default: yes)
 
     % Optional inputs: inference/bootstrap
     addParameter(ip, 'signif', 0.1, @isnumeric);            % 1 x 1     Significance level (default: 10%)

diff --git a/functions/SVMAIV_estim.m b/functions/SVMAIV_estim.m
@@ -55,16 +55,16 @@
     addParameter(ip, 'compute_FVD', true, @islogical);      % bool      Compute Forecast Variance Decomposition? (default: yes)
     addParameter(ip, 'horiz', 1:24, @isnumeric);            % 1 x k     Horizons of FVR/FVD to report (default: 1:24)
     addParameter(ip, 'ci_param', false, @islogical);        % bool      Compute confidence intervals for parameters themselves (not identified sets)? (default: no)
-    addParameter(ip, 'verbose', true, @islogical);          % bool      Print progress to screen?
+    addParameter(ip, 'verbose', true, @islogical);          % bool      Print progress to screen? (default: yes)
 
     % Optional inputs: inference/bootstrap
     addParameter(ip, 'signif', 0.1, @isnumeric);            % 1 x 1     Significance level (default: 10%)
     addParameter(ip, 'n_boot', 1000, @isnumeric);           % 1 x 1     No. of bootstrap repetitions (default: 1000)
     addParameter(ip, 'optim_opts', optimoptions('fmincon', 'Display', 'notify'), @(x) isobject(x) | isempty(x)); % obj  Numerical options for Stoye CI construction
 
     % Optional inputs: numerical settings
-    addParameter(ip, 'use_kalman', true, @islogical);       % bool      Use Kalman filter for conditional variance calculations? (default: true)
-    addParameter(ip, 'VMA_hor', 100, @isnumeric);           % 1 x 1     Truncation horizon for VMA representation of VAR
+    addParameter(ip, 'use_kalman', true, @islogical);       % bool      Use Kalman filter for conditional variance calculations? (default: yes)
+    addParameter(ip, 'VMA_hor', 100, @isnumeric);           % 1 x 1     Truncation horizon for VMA representation of VAR (default: 100)
 
     parse(ip, Y, Z, varargin{:}); % Parse inputs
 

diff --git a/functions/alpha_IS.m b/functions/alpha_IS.m
@@ -1,5 +1,7 @@
 function [alpha_LB,alpha_UB,alpha_true,alpha_plot] = alpha_IS(yzt_aux,model,settings);
 
+% Identified set for scale parameter alpha
+
 %----------------------------------------------------------------
 % Get Inputs
 %----------------------------------------------------------------
@@ -36,7 +38,7 @@
 % Lower Bound
 %----------------------------------------------------------------
 
-if bnd_recov == 0
+if bnd_recov == 0 % Sharp lower bound
 
 alpha_LB_fun = @(omega) sqrt(real(ctranspose(s_yzt(omega)) * s_y(omega)^(-1) * s_yzt(omega)));
 omega_grid = linspace(0,2*pi,ngrid)';
@@ -49,7 +51,7 @@
 alpha_plot.alpha_LB_vals = alpha_LB_vals;
 alpha_plot.omega_grid    = omega_grid;
 
-elseif bnd_recov == 1
+elseif bnd_recov == 1 % Weaker lower bound (sharp under recoverability)
 
 Var_y = NaN((2*hor_pred+1) * n_y, (2*hor_pred+1) * n_y);
 for i = 1:2*hor_pred+1

diff --git a/functions/bootstrapVAR.m b/functions/bootstrapVAR.m
@@ -1,5 +1,7 @@
 function VAR_boot = bootstrapVAR(VAR,model,data,settings)
 
+% Homoskedastic recursive residual VAR bootstrap
+
 %----------------------------------------------------------------
 % Estimate VAR
 %----------------------------------------------------------------

diff --git a/functions/bootstrapVAR_IV.m b/functions/bootstrapVAR_IV.m
@@ -1,5 +1,7 @@
 function VAR_IV_boot = bootstrapVAR_IV(VAR,model,data,settings)
 
+% Homoskedastic recursive residual VAR bootstrap, with external IV
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/cross_sd_fun.m b/functions/cross_sd_fun.m
@@ -1,5 +1,7 @@
 function cross_sd = cross_sd_fun(omega,Sigma_yztilde)
 
+% Cross-spectrum of y and tilde{z}
+
 % preparations
 hor = size(Sigma_yztilde,1);
 

diff --git a/functions/disp_verbose.m b/functions/disp_verbose.m
@@ -1,4 +1,7 @@
 function disp_verbose(str, verbose)
+
+    % Display if verbose=true
+
     if verbose
         disp(str);
     end

diff --git a/functions/estimateVAR.m b/functions/estimateVAR.m
@@ -1,5 +1,7 @@
 function VAR_sim = estimateVAR(data,settings)
 
+% Least-squares VAR estimation
+
 % preliminaries
 n_x = size(data,2);
 T   = size(data,1);

diff --git a/functions/estimateVAR_IV.m b/functions/estimateVAR_IV.m
@@ -1,5 +1,7 @@
 function VAR_sim = estimateVAR_IV(data_y,data_z,settings)
 
+% Least-squares VAR estimation, with external IV
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/get2ndmoments_VAR.m b/functions/get2ndmoments_VAR.m
@@ -1,5 +1,7 @@
 function yzt_aux = get2ndmoments_VAR(VAR,model,settings)
 
+% Compute autocovariances implied by reduced-form VAR
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/get_IS.m b/functions/get_IS.m
@@ -1,5 +1,7 @@
 function bounds = get_IS(yzt_aux,model,settings)
 
+% Identified sets for all model parameters
+
 bounds = struct;
 
 %----------------------------------------------------------------

diff --git a/functions/popVAR.m b/functions/popVAR.m
@@ -1,5 +1,7 @@
 function VAR_pop = popVAR(model,settings)
 
+% Compute VAR representation of ABCD model
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/pop_analysis.m b/functions/pop_analysis.m
@@ -1,5 +1,8 @@
 function [IRF,FVD,M,tot_weights] = pop_analysis(model,settings);
 
+% Compute impulse responses and forecast variance decompositions
+% implied by ABCD representation of model
+
 %----------------------------------------------------------------
 % Preparations
 %----------------------------------------------------------------

diff --git a/functions/save_fig.m b/functions/save_fig.m
@@ -1,5 +1,7 @@
 function save_fig(folder,filename)
 
+    % Save figure in various formats
+
     saveas(gcf, fullfile(folder, strcat(filename, '.fig')));
     saveas(gcf, fullfile(folder, strcat(filename, '.png')));
     saveas(gcf, fullfile(folder, strcat(filename, '.eps')), 'epsc');

diff --git a/functions/sd_fun.m b/functions/sd_fun.m
@@ -1,5 +1,7 @@
 function sd = sd_fun(omega,Theta_Wold)
 
+% Spectral density of moving average
+
 % preparations
 hor = size(Theta_Wold,1);
 

diff --git a/functions/selectlag_IC.m b/functions/selectlag_IC.m
@@ -1,5 +1,7 @@
 function lag = selectlag_IC(data,maxlag,penalty);
 
+% Select VAR lag length using information criterion
+
 % preliminaries
 n_x = size(data,2);
 

diff --git a/functions/simulate_data.m b/functions/simulate_data.m
@@ -1,5 +1,7 @@
 function [data] = simulate_data(model,settings)
 
+% Simulate data for ABCD model
+
 T      = settings.T;
 n_eps  = model.n_eps;
 n_nu   = model.n_nu;

diff --git a/illustration/_auxiliary_functions/ABCD_fun.m b/illustration/_auxiliary_functions/ABCD_fun.m
@@ -1,5 +1,7 @@
 function ABCD = ABCD_fun(model);
 
+% ABCD representation of Dynare model
+
 % prepare inputs
 
 decision = model.decision;