gui_step_by_step

BEAR Toolbox GUI: Step-by-Step Guide

Introduction

The BEAR Toolbox Graphical User Interface provides an intuitive way to configure various vector autoregressive (VAR) models by allowing users to select the type of model, input data, tasks to execute, identification schemes, and other specifications through an easy-to-use interface. The GUI then auto-generates the corresponding Matlab script using the BEARX Toolbox, which can be opened, viewed, executed, and even edited by the user.

BEARX is an extended new version of the original BEAR Toolbox (version 5). It adds a new CLI (command-line interface, a text-based way to work with the toolbox by typing commands) and a new GUI, while the original BEAR remains available as before.

Importantly, the GUI does not run anything behind the scenes but works as a white (or glass) box where users can learn from the generated script. This transparent approach allows users to understand exactly what code is being executed and serves as an educational tool for learning VAR modeling with the BEARX Toolbox.

The GUI follows a logical progression: first you specify your data and model type, then configure identification and dummy observations, define tasks to execute, and finally generate a Matlab script that implements your complete model specification and can be customized as needed.

Getting Started

Before using the BEAR GUI, you need to set up a dedicated workspace for your model:

You also need to make sure the following three toolbox folders are on the Matlab path (this will be automated in a later version):

• bearx-toolbox/tbx/bear
• bearx-toolbox/tbx/bearing
• bearx-toolbox/tbx/gui

Here, bearx-toolbox refers to the location where the toolbox was installed. In Matlab, add these folders to the path using:

addpath your/path/to/bearx-toolbox/tbx/bear
addpath your/path/to/bearx-toolbox/tbx/bearing
addpath your/path/to/bearx-toolbox/tbx/gui

1. Create a Model Folder: Create a new folder where all your model files, settings, and outputs will be stored. This folder will serve as your complete modeling workspace.

2. Place Your Data: It is recommended (though not strictly necessary) to place your data file(s) in this folder. This makes it easier to share your complete analysis with others or port it to different locations while keeping everything self-contained.

3. Starting the GUI: Launch the GUI using the Matlab command:

   gui.start

   Important: This command recreates all local configuration files, so any prior choices or settings will be reset (though your original data files remain unchanged).

4. Resuming Work: If you wish to continue working on a previous analysis with your saved settings intact, use instead:

   gui.resume

Welcome to BEAR GUI

The BEAR GUI home page provides an overview of the workflow and navigation between different configuration tabs. The interface is organized into a logical sequence that guides you through the complete model setup process:

• Input Data: Configure your time series dataset and data sources
• Meta Information: Define project metadata and output settings
• Reduced-Form Estimation: Select and configure the VAR model type
• Dummy Observations: Set up prior information and dummy variables
• Structural Identification: Choose identification schemes for structural analysis
• Tasks to Execute: Select which analytical tasks to perform
• Matlab Script: Review and customize the generated code

Each tab contains forms that are automatically populated with default values and can be modified according to your analysis needs. The GUI maintains your settings across sessions when using gui.resume instead of gui.start.

Details of the GUI

The GUI operates as a form-based interface that generates Matlab scripts using the BEAR Toolbox. Key technical details:

Architecture: The GUI uses JSON configuration files stored in forms/ subdirectories to define interface elements. Each tab corresponds to a specific aspect of VAR model configuration.

File Management: When you run gui.start, it recreates local configuration files in your working directory:

• forms/: JSON files containing your current settings
• tables/: Spreadsheet-like data for restrictions and conditioning
• html/: Generated web interface files

Script Generation: The GUI assembles your choices into a complete Matlab script using the +scripter package functions. This includes:

• Data loading and preprocessing code
• Model estimation setup
• Task execution commands
• Output and visualization specifications

Web Interface: The GUI opens in Matlab's built-in web browser, allowing for a modern HTML-based interface while maintaining integration with the Matlab environment.

Your Notes

A workspace for recording your own observations, parameter choices, and modeling decisions throughout the analysis.

Reduced-Form Estimation

This section allows you to select the estimation method for your VAR model. The BEAR Toolbox offers a comprehensive range of estimators organized into several categories:

Plain Estimators:

• Ordinary: Ordinary Least Squares (OLS) estimation
• Flat: VAR with flat (uninformative) prior
• Minnesota: VAR with Minnesota prior (most commonly used Bayesian prior)
• NormalWishart: VAR with Normal-Wishart conjugate prior
• IndNormalWishart: VAR with independent Normal-Wishart priors
• NormalDiffuse: VAR with Normal-Diffuse prior

Time-Varying Estimators:

• BetaTV: Time-varying VAR with stochastic coefficients
• GeneralTV: VAR with time-varying parameters and stochastic volatility
• CogleySargentSV: Cogley-Sargent stochastic volatility VAR
• CarrieroSV: Carriero stochastic volatility VAR
• RandomInertiaSV: Stochastic volatility with random inertia
• CCMMSV: CCMM stochastic volatility VAR
• LargeShockSV: Stochastic volatility VAR for large shocks

Panel Estimators:

• HierarchicalPanel: Hierarchical panel VAR
• MeanOLSPanel: Mean OLS panel estimation
• DynamicCrossPanel: Dynamic cross-unit panel VAR
• StaticCrossPanel: Static cross-unit panel VAR

Factor-Augmented VARs (FAVAR):

• One-step and two-step FAVAR variants with different priors
• Time-varying FAVAR models

Specialized Estimators:

• Threshold: VAR with threshold-based regime switching
• MixedFrequency: Mixed-frequency VAR for datasets with different sampling frequencies

Once you select an estimator, additional configuration options specific to that method will become available in subsequent forms.

Input Data

The Input Data tab allows you to specify the source of your time series data and configure how it should be loaded:

Supported File Formats:

• Excel files (.xlsx, .xls) - specify sheet index or name
• CSV files (.csv) - standard comma-separated format
• Matlab data files (.mat) - specify table name (default: inputDataTbl)

Data Source Configuration:

• File Path: Browse and select your main dataset file using the file selection dialog
• Excel Sheet: For Excel files, specify which sheet contains your data (can be sheet number or name)
• Table Name: For MAT files, specify the variable name of the table containing your data
• Low-Frequency Data: Optional second dataset for mixed-frequency models

Data Requirements:

• Time series should be organized with dates in the first column
• Variable names should be in the header row
• Missing values should be represented as NaN or empty cells
• Dates should follow Matlab-compatible formats (e.g., 'dd-mmm-yyyy', 'yyyy-mm-dd')

Transformations: The interface allows you to define new transformed variables that will be calculated from your input data, such as growth rates, differences, or ratios.

Meta Information

Define metadata for your analysis including model labels, output directories, and documentation settings.

Dummy Observations

Dummy observations allow you to incorporate prior beliefs and additional constraints into your VAR model. The GUI provides several types of dummy variable specifications:

Available Dummy Types:

Minnesota Dummies:

• Implement the classic Minnesota prior through dummy observations
• Control shrinkage toward random walk behavior for individual variables
• Useful for imposing the belief that variables follow unit root processes

Initial Observations:

• Use the first few observations of your sample as dummy observations
• Helps with initialization and can improve estimation stability
• Particularly useful for short time series

Sum of Coefficients:

• Impose the constraint that coefficients sum to specific values
• Can be used to impose unit root or cointegration-like restrictions
• Helps control the long-run behavior of the model

Long-Run Constraints:

• Specify long-run relationships between variables
• Implemented through a table interface where you can define coefficient constraints
• Useful for incorporating theoretical restrictions on steady-state relationships

For each dummy type, you can configure:

• Whether to include the dummy observations
• Specific parameter values controlling the tightness of the constraints
• Variable-specific settings where applicable

The GUI provides interactive table editors for more complex dummy specifications, accessible through dedicated table editing interfaces.

Structural Identification

Structural identification transforms your reduced-form VAR into a structural VAR (SVAR) by imposing restrictions that allow economic interpretation of shocks. The GUI offers several identification strategies:

Available Identification Methods:

No Identification:

• Work only with reduced-form VAR results
• Suitable when structural interpretation is not needed
• Default option for purely forecasting applications

Cholesky (Triangular) Identification:

• Uses recursive identification through Cholesky decomposition
• Assumes a specific causal ordering of variables
• Variables ordered first are assumed to affect all subsequent variables contemporaneously
• Simple and commonly used, but ordering assumptions can be strong

Instant Zero Restrictions:

• Impose zero restrictions on the instantaneous impact matrix
• Specify which variables do not affect others contemporaneously
• Implemented through an editable table interface
• More flexible than Cholesky for capturing economic theory

Inequality (Sign) Restrictions:

• Impose sign restrictions on impulse response functions
• Specify that certain shocks must have positive or negative effects on specific variables
• Useful for identifying shocks based on economic intuition (e.g., demand vs. supply shocks)
• Implemented using Bayesian methods with multiple draws

Generalized Restrictions:

• Most flexible identification scheme
• Allows complex linear combinations of restrictions
• Can combine zero restrictions, sign restrictions, and magnitude restrictions
• Requires advanced knowledge of SVAR identification theory

For identification methods involving tables (zero restrictions, sign restrictions), the GUI provides:

• Interactive table editors accessible via "Open Table" buttons
• Automatic validation of restriction matrices
• Integration with Matlab's built-in table editing capabilities

Each identification method has specific parameter settings that control:

• Number of posterior draws for Bayesian identification
• Tolerance parameters for restriction satisfaction
• Prior specifications for identified parameters

Tasks to Execute

This section allows you to specify which analytical tasks should be performed after model estimation. The GUI organizes tasks into logical categories:

Core Estimation Tasks:

Reduced-Form Estimation:

• Estimate the reduced-form VAR model
• Sample from the reduced-form posterior distribution
• Always required and enabled by default
• Produces coefficient estimates, fitted values, and residuals

Structural Estimation:

• Estimate the structurally identified model
• Sample from the structurally identified posterior
• Only available when structural identification is specified
• Required for all structural analysis tasks

Forecasting Tasks:

Reduced-Form Forecast:

• Generate unconditional forecasts using the reduced-form model
• Produces point forecasts and credible intervals
• Suitable when structural interpretation is not needed

Structural Forecast:

• Generate unconditional forecasts using the structural model
• Allows for shock decomposition in forecast periods
• Requires structural identification

Conditional Forecast:

• Generate forecasts conditional on assumed paths for some variables
• Requires specification of conditioning data and plan tables
• Useful for policy analysis and scenario evaluation

Structural Analysis Tasks:

Shock Responses (Impulse Response Functions):

• Calculate responses of all variables to structural shocks
• Produces impulse response functions with credible bands
• Core tool for understanding dynamic relationships

Shock Contributions:

• Decompose historical paths of variables into shock contributions
• Shows which shocks drove observed movements
• Useful for historical narrative and understanding business cycles

Forecast Error Variance Decomposition (FEVD):

• Decompose forecast error variance into contributions from different shocks
• Shows relative importance of shocks at different forecast horizons
• Complements impulse response analysis

For each task, you can configure:

• Forecast horizons and sample periods
• Number of posterior draws for uncertainty quantification
• Output format and visualization options
• Specific parameters relevant to each analysis type

The conditional forecast task requires additional setup through table interfaces for:

• Conditioning Data: Values that some variables are constrained to follow
• Conditioning Plan: Specification of which variables are conditioned and in which periods

Matlab Script

The final tab displays the complete Matlab script that implements all your model specifications and analytical choices. This section provides full transparency into what the GUI has configured:

Script Generation Process: The GUI uses the +scripter package to automatically generate code that:

• Loads and preprocesses your input data
• Sets up all model parameters and prior specifications
• Configures dummy observations and identification restrictions
• Executes the selected estimation and analysis tasks
• Produces output tables, figures, and results files

Script Components:

Header Section:

• Clear documentation of model specifications
• Date and time stamps
• List of selected estimator and identification method

Data Loading:

• Code to read your specified input file
• Data transformation and preprocessing steps
• Variable name assignments and sample period selection

Model Configuration:

• Estimator-specific parameter settings
• Prior specifications and dummy variable setup
• Identification restriction matrices (if applicable)

Execution Section:

• Calls to appropriate BEAR Toolbox functions
• Task execution in the correct logical order
• Error handling and progress reporting

Output Generation:

• Figure creation and customization
• Table exports and result summaries
• File saving with organized directory structure

Script Management Features:

View Script: Display the complete generated code in a readable format

Edit Script: Open the script in Matlab's editor for customization

• Modify parameters that aren't available in the GUI
• Add custom analysis or visualization code
• Include additional post-processing steps

Run Script: Execute the script directly from the GUI

• Monitor execution progress
• Handle errors and provide feedback
• Automatically save results to designated folders

Export Options:

• Save the script as a standalone .m file
• Include all necessary function dependencies
• Create portable analysis packages

The generated script serves as both a complete implementation of your analysis and a learning tool for understanding how to use the BEAR Toolbox programmatically. You can use it as a starting point for more advanced customizations or as a template for similar analyses.

---

This guide is designed to be expanded with detailed instructions for each section. Each tab contains specific settings and options that will be documented step-by-step.