FunctionalVAR#

class cultivars.multivariate.reduced_form.functional.FunctionalVAR(curves, grid=None, *, order, basis='fpca', n_components=None, decay=None, df=None, degree=3, trend='c')[source]

Bases: object

A vector autoregression for observations that are curves on a grid.

Project, fit, map back. Each curve is reduced to its coordinates in a small basis, an ordinary VAR is estimated on those coordinates, and the curve-level surface – fitted curves, forecast curves, curve impulse responses – is the factor surface mapped through the basis. The choice of basis is the modelling decision, and the three on offer answer three different situations:

"fpca" estimates the basis from the sample: the leading eigenfunctions of the empirical covariance, optimal in mean square for these data, with the component count chosen explicitly or by a variance-share target.

"nelson-siegel" fixes the basis to level, slope, and curvature,

\[\phi(\tau) = \Bigl(1,\; \frac{1 - e^{-\lambda\tau}}{\lambda\tau},\; \frac{1 - e^{-\lambda\tau}}{\lambda\tau} - e^{-\lambda\tau}\Bigr),\]

which is the Diebold-Li dynamic form of the term-structure literature. The grid is then a vector of maturities and must be strictly positive; the decay \(\lambda\) is supplied, or profiled over the curvature-peak candidates the grid itself implies.

"bspline" fixes a local polynomial basis with a chosen number of degrees of freedom – the shape-agnostic option when neither the data-driven nor the yield-curve structure fits.

Variables:

  • _curves – The validated (nobs, n_points) panel.

  • _grid – The validated (n_points,) strictly increasing grid.

  • _basis (str) – The basis family.

  • _order – Autoregressive order of the factor VAR.

  • _trend (Literal['n', 'c', 'ct']) – Deterministic terms of the factor VAR.

  • _n_components – Retained components under "fpca", or None for the variance-share rule.

  • _decay – The Nelson-Siegel decay, or None to profile it.

  • _df – Spline degrees of freedom, resolved to min(8, n_points) when not given.

  • _degree – Spline degree.

See also

  • FunctionalVARResult – the record fit() returns.

  • VAR – the factor model fitted on the scores.

  • term_structure – the dedicated yield-curve models when the Nelson-Siegel structure is the point rather than a basis.

References

Diebold, F. X., & Li, C. (2006). Forecasting the term structure of government bond yields. Journal of Econometrics, 130(2), 337-364.

Ramsay, J. O., & Silverman, B. W. (2005). Functional Data Analysis. Springer.

Example

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> grid = np.linspace(0.0, 1.0, 25)
>>> level = np.cumsum(rng.standard_normal(80))[:, np.newaxis] * 0.1
>>> curves = level + np.sin(np.pi * grid) + 0.01 * rng.standard_normal((80, 25))
>>> res = FunctionalVAR(curves, grid, order=1, basis="fpca").fit()
>>> res.forecast_curves(3).shape
(3, 25)

Private attributes#

_basis

_curves

_decay

_degree

_df

_grid

_n_components

_order

_trend

Private methods#

_bspline_basis()

Build the clamped B-spline design on the grid.

_fpca_basis()

Estimate the principal-component basis from the centered sample.

_nelson_siegel_basis()

Fix or profile the Nelson-Siegel loadings.