DFM#

class cultivars.multivariate.large_dim.dynamic_factor.DFM(panel, *, order, n_factors=None, max_factors=8, series_names=None)[source]

Bases: object

Dynamic factor model, Stock-Watson two-step.

Principal components of the standardized panel estimate the factor space; a VAR on the scores estimates the common dynamics. Left unspecified, the factor count minimizes Bai and Ng’s ICp2,

\[IC_{p2}(r) = \ln V(r) + r\,\frac{N + T}{N T}\,\ln\min(N, T),\]

with \(V(r)\) the mean squared residual of the \(r\)-component approximation, over 1 .. max_factors; the criterion values are kept on the result so the choice can be audited. The procedure is transparent and fast at any width: one singular-value decomposition and one least-squares VAR.

Variables:

  • _panel – The validated (nobs, n_series) panel as a float array.

  • _order – The autoregressive order of the factor VAR.

  • _n_factors – The fixed factor count, or None to select.

  • _max_factors – The largest candidate count, capped at what the panel can support.

  • _series_names – One label per column.

Parameters:

  • panel (ArrayLike) – The observed (nobs, n_series) panel; wide is welcome.

  • order (int) – Autoregressive order of the factor VAR, at least 0.

  • n_factors (int | None) – Factor count, or None to minimize Bai-Ng ICp2 over 1 .. max_factors.

  • max_factors (int) – Largest candidate count for the criterion search, at least 1; silently capped at min(nobs - 1, n_series).

  • series_names (Sequence[str] | None) – One label per series. Defaults to x1 ... xN.

Raises:

  • SpecificationError – If n_factors or max_factors is not a positive integer, or series_names does not have one entry per column. A negative order is rejected by the factor VAR at fit.

  • DimensionError – If the panel is not a time-down-the-rows matrix or n_factors exceeds min(nobs - 1, n_series).

See also

  • DFMResult – the record fit returns.

  • VAR – the model fitted to the factor scores.

  • FAVAR – the same factors augmented with observed variables.

References

Stock, J. H., & Watson, M. W. (2002). Forecasting using principal components from a large number of predictors. Journal of the American Statistical Association, 97(460), 1167-1179.

Bai, J., & Ng, S. (2002). Determining the number of factors in approximate factor models. Econometrica, 70(1), 191-221.

Example

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> f = np.zeros((200, 2))
>>> for t in range(1, 200):
...     f[t] = 0.7 * f[t - 1] + rng.standard_normal(2)
>>> lam = rng.standard_normal((30, 2))
>>> panel = f @ lam.T + 1.5 * rng.standard_normal((200, 30))
>>> res = DFM(panel, order=1).fit()
>>> res.n_factors
2
>>> res.factors.coefficients.shape
(1, 2, 2)
>>> fixed = DFM(panel, order=2, n_factors=3).fit()
>>> fixed.n_factors, fixed.criterion_values.shape, fixed.factors.order
(3, (0,), 2)
>>> DFM(panel, order=1, n_factors=31)
Traceback (most recent call last):
cultivars.exceptions.DimensionError: n_factors (31) exceeds what a (200, 30) panel ...

Private attributes#

_max_factors

_n_factors

_order

_panel

_series_names

Private methods#

_bai_ng(standardized, max_factors)

Bai-Ng ICp2 over candidate counts, and its argmin.