Merge pull request #12 from european-central-bank/fixedInputs2

Fixed inputs in lambda4, moved apps one directory up, checked repackaging

README.md

@@ -14,11 +14,15 @@
 - [Installing BEAR](#Installing-BEAR)
   * [For users](#For-users)
   * [For developers](#For-developers)
+  * [For non-MATLAB users](#For-non-MATLAB-users)
 - [Getting started](#Getting-started)
   * [Creating a settings object](#Creating-a-settings-object)
   * [Running BEAR from the command line](#Running-BEAR-from-the-command-line)
   * [Running BEAR interactively](#Running-BEAR-interactively)
-- [For non-MATLAB users](#For-non-MATLAB-users)
+- [Documentation](#Documentation)
+- [Distribute BEAR](#Distribute-BEAR)
+  * [With other MATLAB users](#With-other-MATLAB-users)
+  * [With non MATLAB users](#With-non-MATLAB-users)
 - [License](#License)
 
 ## Introduction
@@ -66,6 +70,12 @@ Opening the MATLAB project will shadow the installed version of BEAR as long as
 
 ```>> which BEARmain```
 
+### For non-MATLAB users
+
+In the ECB website below, you will find a compiled version of BEAR that does not require a MATLAB license to install.
+
+[BEAR at ECB](https://www.ecb.europa.eu/pub/research/working-papers/html/bear-toolbox.en.html)
+
 ## Getting started
 
 ### Creating a settings object
@@ -96,15 +106,77 @@ From MATLAB run the command below to open the main BEAR interface.
 >> BEARapp
 ```
 
+### Examples
+
+If you want to see an example on how to run BEAR, you can run any of the following files directly:
+
+```
+s = bear_settings_BVAR
+s = bear_settings_PANEL
+s = bear_settings_SV
+s = bear_settings_TVP
+s = bear_settings_MF
+```
+
+change your inputs accordingly and then run `BEARmain(s)`. Alternatively, if you wanted to build your own settings files, you use any of these as a template running for example:
+
+```
+copyfile(fullfile(bearroot(), 'examples', 'bear_settings_BVAR.m'), pwd)
+edit('bear_settings_BVAR')
+```
+
+
 ## Documentation
 
 For a full BEAR documentation please visit our [doc page](https://github.com/european-central-bank/BEAR-toolbox/tree/master/tbx/doc).
 
-## For non-MATLAB users
+## Distribute BEAR
 
-In the ECB website below, you will find a compiled version of BEAR that does not require a MATLAB license to install.
+### With other MATLAB users
+Any MATLAB user can download the latest version of BEAR from the GitHub repository. However, if you wanted to create your own custom distribution you can package it as a MATLAB toolbox as follows:
 
-[BEAR at ECB](https://www.ecb.europa.eu/pub/research/working-papers/html/bear-toolbox.en.html)
+1. Open the `tbx.prj` and edit the main fields such as author, version, and description.
+2. Either click on package or run:
+``` 
+projectFile = 'tbx.prj';
+matlab.addons.toolbox.packageToolbox(projectFile,'C:\Work\myOtherToolbox')
+```
+
+### With non-MATLAB users
+
+If you wanted to share BEAR with someone who is not a MATLAB user, there are several routes you can take:
+1. You can use MATLAB Compiler to share the APP as a standalone program. For this, please open the **Application Compiler** from the toolstrip:
+<br/>
+
+![app toolstrip](/images/AppToolstrip.PNG "Open application compiler")
+
+<br/>
+
+2. Select as **MAIN FILE** the appropriate BEAR app from your set of files. For example, `tbx\app\BEARapp20a`.
+
+<br/>
+
+![Compile app](/images/CompilerScreenshot.PNG "Compiler Screenshot")
+
+<br/>
+
+3. Under **Files required for your application to run** add the following in addition to the automatically detected ones:
+
++ tbx\bear\+bear\results.xlsx
++ tbx\replications\data_AAU2009.xlsx
++ tbx\replications\data_BBE2005.xlsx
++ tbx\replications\data_BvV2018.xlsx
++ tbx\replications\data_CH2019.xlsx 
++ tbx\replications\data_WGP2016.xlsx
++ tbx\default_bear_data.xlsx
+
+4. Click on Package.
+5. You will get a subfolder with the files that you can use to redistribute the application
+
+### For external language integration
+
+If you wanted to share specific functionality with users of other languages, you can take a look at [Compiler SDK](https://uk.mathworks.com/help/compiler_sdk/index.html). The process is analgous to the previous one but selecting a different target.
 
 ## License
+Use of BEAR implies acceptance of the End User Licence Agreement (EULA) for the Use of the Software “the Bayesian Estimation, Analysis and Regression (BEAR) toolbox”.
 [License](/tbx/doc/BEAR%20End%20User%20Licence%20Agreement.pdf)

resources/project/Root.type.Files/images.type.File/CompilerScreenshot.PNG.type.File.xml

@@ -0,0 +1,2 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info />

resources/project/Root.type.Files/tbx.type.File/examples.type.File.xml

@@ -0,0 +1,2 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info />

resources/project/Root.type.Files/tbx.type.File/examples.type.File/1.type.DIR_SIGNIFIER.xml

@@ -0,0 +1,2 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info />

resources/project/Root.type.Files/tbx.type.File/examples.type.File/bear_settings_BVAR.m.type.File.xml

@@ -0,0 +1,6 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design" />
+    </Category>
+</Info>

resources/project/Root.type.Files/tbx.type.File/examples.type.File/bear_settings_MF.m.type.File.xml

@@ -0,0 +1,6 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design" />
+    </Category>
+</Info>

resources/project/Root.type.Files/tbx.type.File/examples.type.File/bear_settings_PANEL.m.type.File.xml

@@ -0,0 +1,6 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design" />
+    </Category>
+</Info>

resources/project/Root.type.Files/tbx.type.File/examples.type.File/bear_settings_SV.m.type.File.xml

@@ -0,0 +1,6 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design" />
+    </Category>
+</Info>

resources/project/Root.type.Files/tbx.type.File/examples.type.File/bear_settings_TVP.m.type.File.xml

@@ -0,0 +1,6 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info>
+    <Category UUID="FileClassCategory">
+        <Label UUID="design" />
+    </Category>
+</Info>

resources/project/Root.type.ProjectPath/183214cc-1642-40bf-9d29-d83d7444255a.type.Reference.xml

@@ -0,0 +1,2 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<Info Ref="tbx/examples" Type="Relative" />

tbx/app/BEARapp.m

@@ -1,7 +1,7 @@
 function BEARapp()
 % Launch the appropriate version of the BEAR app
 if verLessThan('matlab','9.9')
-    eval('bear.app.BEARapp20a');
+    eval('BEARapp20a');
 else
-    eval('bear.app.BEARapp21a');
+    eval('BEARapp21a');
 end

tbx/bear/+bear/+settings/BVARsettings.m

@@ -60,7 +60,7 @@
         % Lag decay: lambda3
         lambda3 (1,1) double {mustBeInRange(lambda3, 1, 2)} = 1;
         % Exogenous variable and constant: lambda4
-        lambda4 (:,1) double {mustBeGreaterThanOrEqual(lambda4,0)} = 1;
+        lambda4 (:,:) double {mustBeGreaterThanOrEqual(lambda4,0)} = 1;
         % Block exogeneity shrinkage: lambda5
         lambda5 (1,1) double {mustBeInRange(lambda5,0, 1)} = 0.001;
         % Sum-of-coefficients tightness: lambda6

tbx/bear/+bear/+settings/MADJsettings.m

@@ -1,5 +1,6 @@
 classdef MADJsettings < bear.settings.BASEsettings
-
+% This is the settings template for VARtype 3 which is unused at the
+% moment.
     methods
 
         function obj = MADJsettings(excelPath, varargin)

tbx/bear/+bear/+settings/SVsettings.m

@@ -70,7 +70,7 @@
         % Lag decay: lambda3
         lambda3 (1,1) double {mustBeInRange(lambda3, 1, 2)} = 1;
         % Exogenous variable and constant: lambda4
-        lambda4 (:,1) double {mustBeGreaterThanOrEqual(lambda4,0)} = 100;
+        lambda4 (:,:) double {mustBeGreaterThanOrEqual(lambda4,0)} = 100;
         % Block exogeneity shrinkage: lambda5
         lambda5 (1,1) double {mustBeGreaterThanOrEqual(lambda5,0), mustBeLessThanOrEqual(lambda5,1)} = 0.001;
         % IG shape on residual variance: alpha0

tbx/bear/+bear/gensample.m

@@ -116,7 +116,8 @@
 % Similarly, create the matrix of exogenous variables for the estimation sample
 data_exo=[];
 for ii=1:numexo
-    data_exo=[data_exo data(startlocation:endlocation,exolocation(ii,1))];
+%     data_exo=[data_exo data(startlocation:endlocation,exolocation(ii,1))];
+    data_exo=[data_exo data(:,exolocation(ii,1))];
 end
 
 

tbx/bear/BEARsettings.m

@@ -8,15 +8,12 @@
 p = inputParser;
 p.KeepUnmatched = true;
 addRequired(p, 'VARtype', @(x) isnumeric(x) || isstring(x) || ischar(x));
-addParameter(p,'ExcelFile', '', @(x) isstring(x) || ischar(x));
+addParameter(p,'ExcelFile', fullfile(bearroot(), 'default_bear_data.xlsx'), @(x) isstring(x) || ischar(x));
 parse(p, VARtype, varargin{:});
 
 VARtype = bear.VARtype(p.Results.VARtype);
 
 ExcelFile = p.Results.ExcelFile;
-if isempty(ExcelFile)
-    ExcelFile = getExcelpath();
-end
 
 if isempty(fieldnames(p.Unmatched))
     params = {};
@@ -41,15 +38,4 @@
 
 end
 
-end
-
-function var = getExcelpath()
-f = dir('*.xlsx');
-
-if length(f) ~= 1
-    error('bear:settings:UndefinedExcelFile', ...
-        'Unable to automatically determine the Excel file, please specifiy the property ExcelFile with the address of the input file');
-end
-
-var = fullfile(f.folder, f.name);
 end

tbx/examples/bear_settings_BVAR.m

@@ -0,0 +1,129 @@
+function s = bear_settings_BVAR(excelPath)
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% BAYESIAN ESTIMATION, ANALYSIS AND REGRESSION (BEAR) TOOLBOX version 5.1 %
+%                                                                         %
+% Alistair Dieppe ([email protected])                         %
+% Björn van Roye  ([email protected])                                %
+%                                                                         %
+% Using the BEAR toolbox implies acceptance of the End User Licence       %
+% Agreement and appropriate acknowledgement should be made.               %
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+%% BVAR EXAMPLE 
+
+% VAR model selected (1=OLS VAR, 2=BVAR, 3=mean-adjusted BVAR, 4=panel Bayesian VAR, 5=Stochastic volatility BVAR, 6=Time varying, 7=Mixed Frequency)
+if nargin < 1
+    s = BEARsettings(2);
+else
+    s = BEARsettings(2, 'ExcelFile', excelPath);
+end
+
+%% general data and model information
+% data frequency (1=yearly, 2= quarterly, 3=monthly, 4=weekly, 5=daily, 6=undated)
+s.frequency=2;
+% sample start date; must be a string consistent with the date formats of the toolbox
+s.startdate='1974q1';
+% sample end date; must be a string consistent with the date formats of the toolbox
+s.enddate='2018q4';
+% endogenous variables; must be a single string, with variable names separated by a space
+s.varendo='YER HICSA STN';
+% endogenous variables; must be a single string, with variable names separated by a space
+s.varexo='';
+% number of lags
+s.lags=4;
+% inclusion of a constant (1=yes, 0=no)
+s.const=1;
+% excel results file name
+s.results_sub='results_BVAR';
+s.results_path = fullfile(pwd, 'results');
+% to output results in excel
+s.results=1;
+% output charts
+s.plot=1;
+% save matlab workspace (1=yes, 0=no)
+s.workspace=1;
+
+%% FAVAR
+% augment VAR model with factors (1=yes, 0=no)
+s.favar.FAVAR=0; 
+
+%% selected prior
+% 11=Minnesota (univariate AR), 12=Minnesota (diagonal VAR estimates), 13=Minnesota (full VAR estimates)
+% 21=Normal-Wishart(S0 as univariate AR), 22=Normal-Wishart(S0 as identity)
+% 31=Independent Normal-Wishart(S0 as univariate AR), 32=Independent Normal-Wishart(S0 as identity)
+% 41=Normal-diffuse
+% 51=Dummy observations
+s.prior=12;
+% hyperparameter: autoregressive coefficient
+s.ar=0.8;
+% set to 1 if you want individual priors, 0 for default
+s.PriorExcel=0; 
+% set to 1 if you want individual priors, 0 for default
+s.priorsexogenous=0; 
+% hyperparameter: lambda1
+s.lambda1=0.1;
+% hyperparameter: lambda2
+s.lambda2=0.5;
+% hyperparameter: lambda3
+s.lambda3=1;
+% hyperparameter: lambda4
+s.lambda4=100;
+% hyperparameter: lambda5
+s.lambda5=0.001;
+% hyperparameter: lambda6
+s.lambda6=1;
+% hyperparameter: lambda7
+s.lambda7=0.1;
+% hyperparameter: lambda8
+s.lambda8=1;
+
+
+% total number of iterations for the Gibbs sampler
+s.It=5000;
+% number of burn-in iterations for the Gibbs sampler
+s.Bu=2000;
+% hyperparameter optimisation by grid search (1=yes, 0=no)
+s.hogs=0;
+% block exogeneity (1=yes, 0=no)
+s.bex=0;
+% sum-of-coefficients application (1=yes, 0=no)
+s.scoeff=0;
+% dummy initial observation application (1=yes, 0=no)
+s.iobs=0;
+% Long run prior option
+s.lrp=0;
+% create H matrix for the long run priors % H=[1 1 0 0;-1 1 0 0;0 0 1 1;0 0 -1 1];
+% now taken from excel loadH.m
+
+s.priorf=100;
+
+%% Model options
+s.IRF=1;          % activate impulse response functions (1=yes, 0=no)
+s.IRFperiods=20;  % number of periods for impulse response functions
+s.F=1;            % activate unconditional forecasts (1=yes, 0=no)
+s.FEVD=0;         % activate forecast error variance decomposition (1=yes, 0=no)
+s.HD=1;           % activate historical decomposition (1=yes, 0=no)
+s.HDall=0;        % if we want to plot the entire decomposition, all contributions (includes deterministic part)HDall
+s.CF=0;           % activate conditional forecasts (1=yes, 0=no)
+s.CFt=1;          % 1=standard (all shocks), 2=standard (shock-specific), 3=tilting (median), 4=tilting (interval)
+
+% structural identification (1=none, 2=Cholesky, 3=triangular factorisation, 4=sign, zero, magnitude, relative magnitude, FEVD, correlation restrictions,
+% 5=IV identification, 6=IV identification & sign, zero, magnitude, relative magnitude, FEVD, correlation restrictions)
+s.IRFt=2;
+
+%% Forecast 
+s.Fstartdate='2019q1'; % start date for forecasts (has to be an in-sample date; otherwise, ignore and set Fendsmpl=1)
+s.Fenddate='2021q4';   % end date for forecasts
+s.Fendsmpl=1;          % start forecasts immediately after the final sample period (1=yes, 0=no) has to be set to 1 if start date for forecasts is not in-sample
+s.Feval=0;             % activate forecast evaluation (1=yes, 0=no)
+s.hstep=1;             % step ahead evaluation
+s.window_size=0;       % window_size for iterative forecasting 0 if no iterative forecasting
+s.evaluation_size=0.5; % evaluation_size as percent of window_size                                      <                                                                                    -
+
+%% Credibility bands
+s.cband=0.68;    % confidence/credibility level for VAR coefficients
+s.IRFband=0.68;  % confidence/credibility level for impusle response functions
+s.Fband=0.68;    % confidence/credibility level for forecasts
+s.FEVDband=0.68; % confidence/credibility level for forecast error variance decomposition
+s.HDband=0.68;   % confidence/credibility level for historical decomposition