Econometrics Toolbox: Modeling guide

Complete worksheet schemas, time series data conventions, parameter lag specifications, series role mappings, and step-by-step instructions for authoring new models.

← Overview · Getting started · Modeling guide · Methods guide · Examples · Reference

Modeling architecture

The Econometrics Toolbox decouples model selection, time series observations, and mathematical lag specifications into standardized worksheet tables. This architecture allows financial and macroeconomic analysts to:

  • Maintain a central repository of historical economic indicators on a single sheet;
  • Configure model orders (\(p, d, q, \text{lags}\)) without embedding complex mathematical logic into cell formulas;
  • Add new corporate or macroeconomic series and immediately run institutional-grade time series regressions.

Worksheet schemas

1. The Start sheet

The Start sheet contains the high-level operational controls and the catalog of available models.

Econometric controls table (A5:B9)

Cell Control Allowed Values Default Purpose
B6 Active model Valid ID from Model Catalog us_gdp_growth Selects which dataset and model family are compiled and estimated.
B7 Forecast horizon Integer: 1 to 12 4 Number of multi-step out-of-sample periods to project forward.
B8 Confidence level Numeric: 0.50 to 0.999 0.95 Statistical confidence probability for analytical forecast error bands. Supports percentages (e.g. 95%).
B9 Frequency Quarterly, Monthly, Annual Quarterly Controls the calendar date advancement logic used on the Forecasts sheet.

Model catalog table (D5:H11)

Column Header Type Description
D Model String Unique machine-readable identifier (join key). Examples: us_gdp_growth, cpi_inflation_arma.
E Label String Human-readable title displayed on summary cards and charts.
F Family String Econometric model family: ARIMA, ARMA, SARIMAX, VAR, Cointegration, or Stationarity.
G Specification String Concise mathematical notation (e.g., ARIMA(1,0,1), VAR(1)).
H Description String Contextual summary of the underlying economic relationship.

2. Time Series Data sheet

The Time Series Data sheet stores all historical time-sequenced observations.

Table structure (A5:F200)

┌───────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│ Model │ Period  │ Date    │ Series1 │ Series2 │ Series3 │
├───────┼─────────┼─────────┼─────────┼─────────┼─────────┤
│ ...   │ 1       │ 2018-Q1 │ 3.5     │ 0.0     │ 0.0     │
│ ...   │ 2       │ 2018-Q2 │ 4.2     │ 0.0     │ 0.0     │
└───────┴─────────┴─────────┴─────────┴─────────┴─────────┘
Column Header Data Type Requirement Description
A Model String Required Model identifier joining to Start!D5:D11. Rows are filtered by the active model.
B Period Integer Required Sequence index (\(1, 2, \dots, N\)) representing chronological time steps.
C Date String Required Calendar period label formatted according to frequency conventions.
D Series1 Float Required Primary dependent variable (\(Y_t\)).
E Series2 Float Optional Secondary dependent variable (in VAR) or exogenous covariate (\(X_t\) in SARIMAX).
F Series3 Float Optional Tertiary series reserved for high-order multivariate expansions.

3. Specification sheet

The Specification sheet defines the mathematical lag structures, integration orders, and test parameters for each model.

Table structure (A5:D30)

┌───────────────────────┬───────────┬───────┬────────────────────────────────────┐
│ Model                 │ Parameter │ Value │ Description                        │
├───────────────────────┼───────────┼───────┼────────────────────────────────────┤
│ us_gdp_growth         │ p         │ 1     │ Autoregressive lag order           │
│ us_gdp_growth         │ d         │ 0     │ Integration differencing order     │
│ us_gdp_growth         │ q         │ 1     │ Moving average lag order           │
│ retail_sales_sarimax  │ P         │ 0     │ Seasonal autoregressive lag order  │
│ retail_sales_sarimax  │ D         │ 1     │ Seasonal differencing order        │
│ retail_sales_sarimax  │ Q         │ 1     │ Seasonal moving average lag order  │
│ retail_sales_sarimax  │ s         │ 4     │ Seasonal periodicity               │
│ treasury_rates_var    │ lags      │ 1     │ VAR lag order                      │
│ macro_stationarity    │ maxlag    │ 4     │ Maximum lag for unit root tests    │
└───────────────────────┴───────────┴───────┴────────────────────────────────────┘
Column Header Data Type Description
A Model String Model identifier joining to Start and Time Series Data.
B Parameter String Key denoting the mathematical parameter (case-sensitive).
C Value Integer / Float Numerical value of the parameter.
D Description String Human-readable explanation of parameter function.

Date and frequency conventions

The notebook features an intelligent period-advancement parser (advance_period) that generates accurate out-of-sample date labels based on the final historical observation and the selected frequency.

Supported formats

  1. Quarterly:
    • Format: YYYY-Q# (e.g., 2024-Q4).
    • Advancement logic: Incrementing quarter modulo 4, rolling over into the next year.
    • Example: Starting from 2024-Q4, 4 forward steps produce 2025-Q1, 2025-Q2, 2025-Q3, and 2025-Q4.
  2. Monthly:
    • Format: YYYY-M## (e.g., 2024-M12).
    • Advancement logic: Incrementing month modulo 12 with two-digit zero padding.
    • Example: Starting from 2024-M12, 3 forward steps produce 2025-M01, 2025-M02, and 2025-M03.
  3. Annual:
    • Format: YYYY (e.g., 2024).
    • Advancement logic: Incrementing calendar year by 1 per step.
    • Example: Starting from 2024, 2 forward steps produce 2025 and 2026.

[!NOTE] If a date string does not strictly match standard patterns (e.g., Period_28), the engine safely falls back to synthetic relative step indexing: Period_28+1, Period_28+2, etc.

Series role mappings

The table below explains how columns on the Time Series Data sheet are mapped by each econometric family:

Family Series1 Role Series2 Role Series3 Role
ARIMA / ARMA Target dependent variable (\(Y_t\)) Ignored Ignored
SARIMAX Target dependent variable (\(Y_t\)) Exogenous regressor (\(X_t\)) Reserved
VAR Endogenous variable 1 (\(Y_{1,t}\), e.g. ShortRate) Endogenous variable 2 (\(Y_{2,t}\), e.g. LongRate) Reserved for 3rd vector equation
Cointegration / ECM Cointegrating target (\(Y_t\), e.g. Real Consumption) Cointegrating regressor (\(X_t\), e.g. Real Income) Reserved
Stationarity Level series (\(Y_t\), non-stationary test candidate) First-differenced series (\(\Delta Y_t\), stationary candidate) Reserved

Specification parameters guide

Each econometric family expects specific keys in the Parameter column of the Specification sheet:

1. ARIMA & ARMA parameters

  • p — Non-seasonal autoregressive order: number of lagged values \(Y_{t-1}, \dots, Y_{t-p}\) included in the model.
  • d — Non-seasonal differencing order: number of times the series is differenced to induce stationarity (\(\Delta^d Y_t\)).
  • q — Non-seasonal moving average order: number of lagged shock terms \(\varepsilon_{t-1}, \dots, \varepsilon_{t-q}\) included.

2. SARIMAX parameters

In addition to \(p\), \(d\), and \(q\):

  • P — Seasonal autoregressive order: number of seasonal lag blocks \(Y_{t-s}, Y_{t-2s}, \dots\).
  • D — Seasonal differencing order: number of seasonal difference operations \(\Delta_s^D Y_t = Y_t - Y_{t-s}\).
  • Q — Seasonal moving average order: number of seasonal error blocks \(\varepsilon_{t-s}, \varepsilon_{t-2s}, \dots\).
  • s — Seasonal periodicity: number of periods in a seasonal cycle (\(s=4\) for quarterly, \(s=12\) for monthly).

3. Vector Autoregression (VAR) parameters

  • lags — Uniform lag order \(k\) across all equations in the VAR system (\(Y_t = c + A_1 Y_{t-1} + \dots + A_k Y_{t-k} + \varepsilon_t\)).

4. Cointegration & ECM parameters

  • lags — Dynamic lag length for the short-run differenced error-correction equations.

5. Stationarity parameters

  • maxlag — Maximum lag order evaluated in the Augmented Dickey-Fuller regression for automated lag selection.

Step-by-step: Authoring a custom model

Follow these steps to add a new custom time series model to the workbook:

Step 1: Register the model in the catalog

  1. Open the Start sheet.
  2. In the Included model library table (row 11 or next empty row), add a new row:
    • Model: housing_starts
    • Label: Housing Starts — ARIMA
    • Family: ARIMA
    • Specification: ARIMA(2,1,1)
    • Description: Monthly new privately owned housing units started.

Step 2: Paste historical observations

  1. Open the Time Series Data sheet.
  2. Scroll to the end of the existing data table.
  3. Paste your chronological observations:
    • Set column A (Model) to housing_starts.
    • Set column B (Period) sequentially from 1 to \(N\) (must have at least 5 observations).
    • Set column C (Date) to standard monthly dates (e.g. 2023-M01 through 2024-M12).
    • Set column D (Series1) to your historical numerical values.
    • Set columns E and F (Series2, Series3) to 0.0 if unused.

Step 3: Define model lag orders

  1. Open the Specification sheet.
  2. Scroll to the end of the table and add rows for housing_starts:
Model Parameter Value Description
housing_starts p 2 Autoregressive lag order
housing_starts d 1 Differencing order
housing_starts q 1 Moving average lag order

Step 4: Run and inspect results

  1. Return to the Start sheet.
  2. Select cell B6 (Active model) and enter housing_starts.
  3. Set Frequency in cell B9 to Monthly.
  4. Open the Results, Forecasts, and Diagnostics sheets to verify maximum likelihood convergence, parameter significance, out-of-sample monthly forecasts, and residual diagnostics.