Econometrics Toolbox: Reference

Complete control specifications, input/output schemas, status codes, numerical tolerances, parameter limits, and troubleshooting guide for the Econometrics Toolbox.

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

Control reference

The Start sheet defines the top-level execution parameters in range A5:B9. The table below documents their types, default values, validation constraints, and coercion behavior:

Control Name Excel Cell Default Allowed Values / Types Coercion & Validation Rules
Active model Start!B6 us_gdp_growth Any valid Model in Start!D5:D11 Checked against the model catalog. If an invalid or unlisted model identifier is entered, execution halts with ValueError: Unknown active model '<name>'.
Forecast horizon Start!B7 4 Integer: 1 to 12 Parsed via int(float(...)). Clamped strictly between 1 and 12 steps: values below 1 become 1; values above 12 are clamped to 12. Non-numeric entries default to 4.
Confidence level Start!B8 0.95 Float or percentage string: 0.50 to 0.999 Accepts decimal floats (e.g. 0.95), percentage strings (e.g. "95%"), or integers (e.g. 95). Values \(> 1.0\) are automatically divided by 100. Clamped between 0.50 and 0.999.
Frequency Start!B9 Quarterly Closed list: Quarterly, Monthly, Annual Coerced to title-case string. Unrecognized frequency strings fall back to Quarterly. Controlled by workbook data validation in B9.

Input range schemas

The notebook reads four fixed structured ranges from the workbook via bf.inputs(...):

┌───────────────────┬──────────────────────┬─────────────┬────────────────────────────────────┐
│ Input Block Name  │ Excel Range          │ Capacity    │ Content                            │
├───────────────────┼──────────────────────┼─────────────┼────────────────────────────────────┤
│ controls          │ Start!A5:B9          │ 4 controls  │ Active model, horizon, conf, freq  │
│ models            │ Start!D5:H11         │ 6 models    │ Model metadata and catalog         │
│ data              │ Time Series Data!    │ 195 rows    │ Chronological observations:        │
│                   │ A5:F200              │             │ Period, Date, Series1, 2, 3        │
│ specs             │ Specification!       │ 25 specs    │ Lag orders (p, d, q, P, D, Q, s)   │
│                   │ A5:D30               │             │ and test options                   │
└───────────────────┴──────────────────────┴─────────────┴────────────────────────────────────┘

[!IMPORTANT] If you add more than 195 historical observations or more than 25 specification rows, update both the workbook layout and the bf.ref(...) boundary in notebook.py to ensure complete ingestion.

Published output schemas

The notebook returns four standardized DataFrames via bf.publish, which populate dedicated worksheet ranges through BF.OUTPUT formula spill anchors:

1. summary (Results!A5:B17)

Reports high-level estimation metrics, goodness-of-fit statistics, and runtime performance.

Column Header Type Description
A Metric String Description of the estimation metric.
B Value String / Float / Int Metric value formatted to four decimal places.

Standard published rows:

  • Active model: Human-readable model label.
  • Family: Econometric family (ARIMA, ARMA, SARIMAX, VAR, Cointegration, Stationarity).
  • Status: Termination status code (OPTIMAL, CONVERGED, STATIONARY, NON_STATIONARY, FAILED).
  • Specification: Mathematical formula notation.
  • Sample periods: Total count of chronological observation periods (\(N\)).
  • Forecast horizon (steps): Number of multi-step out-of-sample periods (\(H\)).
  • AIC: Akaike Information Criterion (lower indicates superior trade-off between fit and complexity).
  • BIC: Bayesian Information Criterion (applies higher penalty for parameter count).
  • HQIC: Hannan-Quinn Information Criterion.
  • Log-Likelihood: Value of the maximized log-likelihood function (\(\ln L\)).
  • Mean forecast: Average point forecast across the projected horizon.
  • Runtime (s): Wall-clock execution time in seconds.

2. coefficients (Results!D5:I20)

Displays the estimated parameter vector, standard errors, test statistics, and significance.

Column Header Type Description
D Term String Parameter name (e.g. const, ar.L1, ma.L1, ShortRate: L1.ShortRate).
E Coefficient Float Estimated parameter value (\(\hat{\beta}_j\) or \(\hat{\phi}_j\)).
F StdError Float Asymptotic standard error (\(SE\)).
G zStat Float Asymptotic \(z\)-statistic (\(t\)-ratio): \(\hat{\theta} / SE(\hat{\theta})\).
H pValue Float Two-sided asymptotic \(p\)-value for hypothesis \(H_0: \theta = 0\).
I Significance String Significance notation: *** (\(p < 0.01\)), ** (\(p < 0.05\)), * (\(p < 0.10\)), ns (\(p \ge 0.10\)).

3. forecasts (Forecasts!A5:F25)

Contains multi-step out-of-sample projections and analytical confidence intervals.

Column Header Type Description
A Horizon_Step Integer Relative forward step index (\(1, 2, \dots, H\)).
B Period_Date String Projected calendar date label (e.g. 2025-Q1, 2025-M01).
C Point_Forecast Float Expected conditional point projection: \(\mathbb{E}[Y_{t+h} \mid \mathcal{I}_t]\).
D Lower_CI Float Lower bound of confidence interval: \(\hat{Y}_{t+h} - z_{1-\alpha/2} \sigma_{t+h}\).
E Upper_CI Float Upper bound of confidence interval: \(\hat{Y}_{t+h} + z_{1-\alpha/2} \sigma_{t+h}\).
F Forecast_StdError Float Analytical standard error of forecast error (\(\sigma_{t+h}\)).

4. diagnostics (Diagnostics!A5:C25)

Presents the 7-part econometric validation battery.

Column Header Type Description
A Check String Name of the diagnostic test.
B Severity String Test result status: PASS, WARN, or INFO.
C Detail String Numerical test statistics, \(p\)-values, and economic interpretations.

Evaluated checks:

  1. Data continuity: Verifies that historical observation rows are contiguous without missing gaps.
  2. Convergence status: Validates numerical optimizer convergence.
  3. ADF unit root test: Augmented Dickey-Fuller test on series levels (PASS if \(p < 0.05\), WARN if unit root detected).
  4. KPSS stationarity test: Kwiatkowski-Phillips-Schmidt-Shin test (PASS if \(p \ge 0.05\), WARN if non-stationary).
  5. Ljung-Box autocorrelation: Residual portmanteau \(Q\)-statistic (PASS if \(p \ge 0.05\), WARN if residuals exhibit serial correlation).
  6. Jarque-Bera normality: Residual skewness/kurtosis test (PASS if \(p \ge 0.05\), INFO if non-Gaussian).
  7. ARCH heteroskedasticity: Engle’s LM test (PASS if \(p \ge 0.05\), WARN if conditional volatility clustering is present).

Status glossary

Status Code Severity Definition
OPTIMAL Success The numerical optimizer converged to a valid maximum likelihood solution; all parameters, information criteria, and forecasts were computed.
CONVERGED Success The dynamic system (e.g. VAR or ECM) achieved mathematical convergence within prescribed tolerance limits.
STATIONARY Information In the unit root workbench (macro_stationarity), confirms that the target series rejects the unit root null and is stationary.
NON_STATIONARY Warning In the unit root workbench, indicates that the level series fails to reject the unit root null and exhibits non-stationary trend behavior.
FAILED Error The numerical optimizer failed to reach convergence, the model matrix was singular, or fewer than 5 valid observations were provided.

Numerical limits & thresholds

  • Minimum Sample Size: At least 5 chronological observations are strictly required (\(N \ge 5\)). Estimating high-order models (such as seasonal SARIMAX or VAR) requires larger samples (\(N \ge 20\)) to prevent degrees-of-freedom exhaustion.
  • Maximum Forecast Horizon: Capped at 12 steps ahead (\(H \le 12\)). Long-term autoregressive forecasts naturally decay to the unconditional sample mean, and standard errors expand significantly beyond 12 periods.
  • Allowed Confidence Levels: Bounded between 50% (\(0.50\)) and 99.9% (\(0.999\)). Values outside this interval are clamped.
  • Stationarity Alpha: The significance threshold for rejecting unit roots in ADF and serial correlation in Ljung-Box is fixed at \(\alpha = 0.05\).

Troubleshooting guide

1. NON_STATIONARY status or ADF WARN on level series

  • Cause: The economic series contains a unit root or strong deterministic trend (\(I(1)\) process), such as price levels or stock indices.
  • Resolution: If modeling with ARIMA, increase differencing order d on the Specification sheet from 0 to 1 (\(\Delta Y_t = Y_t - Y_{t-1}\)). If modeling cointegrated systems (e.g. consumption_income_coint), this warning is normal and confirms the necessity of error-correction modeling.

2. Singular covariance matrix or near-singular warning

  • Cause: Occurs when two series are perfectly collinear, when the sample size is too small for the requested lag order, or when overparameterized seasonal orders (e.g. \(P=2, Q=2\)) exhaust available degrees of freedom.
  • Resolution:
    • Reduce lag orders \(p\), \(q\), \(P\), or \(Q\) on Specification.
    • Add more historical observation periods on Time Series Data.
    • Check that exogenous regressors (\(X_t\)) on Series2 are not constant or perfectly correlated with historical lags.

3. Maximum likelihood convergence failure

  • Cause: The parameter space contains near-unit roots on moving average polynomials (invertibility boundary), or non-linear optimization exceeded iteration budgets.
  • Resolution:
    • For SARIMAX, ensure that enforce_stationarity=False and enforce_invertibility=False are configured if series exhibit boundary roots.
    • Simplify the model from ARIMA(\(p,d,q\)) to a lower-order AR(\(p\)) or MA(\(q\)) specification.

4. Ljung-Box autocorrelation WARN in Diagnostics

  • Cause: Residuals exhibit remaining serial correlation, indicating that the chosen lag order (\(p\) or \(q\)) is too low to capture the historical persistence.
  • Resolution:
    • Open Specification and increase the autoregressive order p by 1.
    • If data is quarterly or monthly, check whether seasonal lag terms (\(P=1, s=4\) or \(s=12\)) should be introduced.