tvpSvForecast#

Purpose#

Generate density forecasts from a fitted TVP-SV-VAR model with time-varying volatility propagation.

Format#

dfc = tvpSvForecast(result, h)#

dfc = tvpSvForecast(result, h, mode="simulate", n_paths=500)

dfc = tvpSvForecast(result, h, ctl=fctl)

Parameters:

result (struct) – an instance of a tvpSvResult structure returned by tvpSvFit().
h (scalar) – forecast horizon (number of steps ahead).
mode (string) – Optional keyword, forecast mode: "mean_path" (default) or "simulate".
n_paths (scalar) – Optional keyword, simulation paths per draw (simulate mode only). Default = 100.
seed (scalar) – Optional keyword, RNG seed for simulation. Default = 42.
level (scalar or vector) – Optional keyword, credible band level(s). Scalar or vector. Default = 0.68|0.90.
quiet (scalar) – Optional keyword, set to 1 to suppress output. Default = 0.

ctl –

Optional keyword, an instance of an svForecastControl structure. When provided, struct values are used and keywords are ignored. An instance is initialized by calling svForecastControlCreate() and the following members can be set:

ctl.h

Scalar, forecast horizon. Default = 12.

ctl.mode

String, forecast mode.

`"mean_path"`	Deterministic h-path using posterior mean innovations. Fast but underestimates forecast variance (Jensen’s inequality). (Default)
`"simulate"`	Draw innovation paths from the SV-implied time-varying covariance. Gives proper predictive density.

ctl.n_paths

Scalar, number of simulation paths per posterior draw ("simulate" mode only). Default = 100.

ctl.levels

Vector, credible band levels. Default = 0.68|0.90.

ctl.store_draws

Scalar, 1 to store raw forecast draws in dfc.draws, 0 to discard. Default = 0.

ctl.seed

Scalar, RNG seed for simulation mode. Default = 42.

Returns:

dfc (struct) –

An instance of a densityForecastResult structure containing:

dfc.fc_mean	hxm matrix, mean forecast across posterior draws.
dfc.fc_median	hxm matrix, median forecast across posterior draws.
dfc.bands	Array of `credibleBand` structures. Access via `dfc.bands[i].level`, `dfc.bands[i].lower`, `dfc.bands[i].upper`.
dfc.quantile_bands	Array of hxm matrices, one per quantile level. Access the i-th quantile band as `dfc.quantile_bands[i]`.
dfc.quantile_levels	n_quantiles x 1 vector, quantile levels corresponding to each band (e.g., 0.05, 0.16, 0.50, 0.84, 0.95).
dfc.log_vol_mean	hxm matrix, mean forecast log-volatility per equation.
dfc.log_vol_median	hxm matrix, median forecast log-volatility per equation.
dfc.h	Scalar, forecast horizon.
dfc.m	Scalar, number of variables.
dfc.n_draws	Scalar, effective number of posterior draws used.
dfc.mode	String, forecast mode used: `"mean_path"` or `"simulate"`.
dfc.var_names	Mx1 string array, variable names.
dfc.draws	(n_draws)x(h*m) matrix, raw forecast draws. Empty matrix unless `ctl.store_draws = 1`. Row layout: each row is one draw, columns ordered as h1_v1, h1_v2, …, h1_vm, h2_v1, …

Examples#

Basic Forecast#

new;
library timeseries;

fname = getGAUSSHome("pkgs/timeseries/examples/data/us_macro_quarterly.csv");
y = loadd(fname, "gdp_growth + cpi_inflation + fed_funds");

result = tvpSvFit(y, p=2, n_draws=5000, n_burn=5000);

// 12-step-ahead density forecast
dfc = tvpSvForecast(result, 12);

print "Median forecast:";
print dfc.fc_median;

The printed output shows median forecasts with 68% and 90% credible bands:

================================================================================
TVP-SV Density Forecast: 12 steps
Draws: 5000
================================================================================

gdp_growth
  h     Median     [16%     84%]     [5%      95%]
------------------------------------------------------------
  1      2.145     1.203    3.087     0.541    3.749
  2      2.038     0.892    3.184     0.134    3.942
    ...

Custom Credible Level#

new;
library timeseries;

fname = getGAUSSHome("pkgs/timeseries/examples/data/us_macro_quarterly.csv");
y = loadd(fname, "gdp_growth + cpi_inflation + fed_funds");

result = tvpSvFit(y);

// 80% credible bands
dfc = tvpSvForecast(result, 8, level=0.80);

// Access bands
print "80% lower:";
print dfc.bands[1].lower;
print "80% upper:";
print dfc.bands[1].upper;

Remarks#

Forecast with time-varying parameters: Unlike constant-parameter BVAR forecasts, the TVP-SV-VAR forecast uses the terminal (last-period) parameter estimates \(B_T\) and \(U_T\) from each posterior draw. This means the forecast reflects the most recent structural relationships in the data, which is critical for policy analysis during regime changes.

Credible bands: The forecast returns 68% and 90% credible bands by default, computed as pointwise quantiles across posterior draws. When a scalar level is provided instead of fctl, it replaces the outer band level (the 68% inner band is always included).

Point forecasts: The median forecast (dfc.fc_median) is generally preferred over the mean forecast (dfc.fc_mean) for asymmetric predictive distributions, which are common with stochastic volatility. Both are computed across posterior draws.

Volatility propagation: The log-volatility \(h_{i,t}\) is propagated forward using the estimated AR(1) dynamics:

\[h_{i,T+s} = \mu_i + \phi_i (h_{i,T+s-1} - \mu_i) + \sigma_i \eta_{i,T+s}\]

When persistence \(\phi_i\) is near 1, volatility shocks at the forecast origin decay slowly, producing wider forecast bands at longer horizons.

Library#

timeseries

Source#

var.src