favar 0.1.0__py3-none-any.whl

favar/__init__.py

@@ -0,0 +1,8 @@
+"""Factor-Augmented Vector Autoregression (FAVAR)."""
+
+from .model import FAVAR
+from .order_selection import FAVAROrderSelection
+from .results import FAVARResults
+
+__all__ = ["FAVAR", "FAVAROrderSelection", "FAVARResults"]
+__version__ = "0.1.0"

favar/factor.py

@@ -0,0 +1,105 @@
+"""Factor extraction and input preparation helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def as_float_dataframe(data, name: str) -> pd.DataFrame:
+    """Return *data* as a numeric DataFrame with unique column names."""
+    if not isinstance(data, pd.DataFrame):
+        data = pd.DataFrame(data)
+
+    if data.ndim != 2:
+        raise ValueError(f"{name} must be two-dimensional.")
+    if data.shape[1] == 0:
+        raise ValueError(f"{name} must contain at least one column.")
+    if data.columns.has_duplicates:
+        raise ValueError(f"{name} has duplicate column names.")
+
+    out = data.copy()
+    try:
+        out = out.apply(pd.to_numeric, errors="raise").astype(float)
+    except Exception as exc:  # pragma: no cover - pandas exception details vary
+        raise ValueError(f"{name} must contain only numeric values.") from exc
+    return out
+
+
+def align_panels(x: pd.DataFrame, y: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Align X and Y on the time index and reject missing values."""
+    if not x.index.equals(y.index):
+        x, y = x.align(y, join="inner", axis=0)
+        if len(x) == 0:
+            raise ValueError("X and Y do not share any index values.")
+
+    if len(x) != len(y):
+        raise ValueError("X and Y must have the same number of observations.")
+    if x.isna().any().any():
+        raise ValueError("X contains missing values after alignment.")
+    if y.isna().any().any():
+        raise ValueError("Y contains missing values after alignment.")
+    return x, y
+
+
+def standardize_frame(x: pd.DataFrame) -> tuple[pd.DataFrame, np.ndarray, np.ndarray]:
+    """Standardize columns with population standard deviations."""
+    values = x.to_numpy(dtype=float)
+    mean = values.mean(axis=0)
+    std = values.std(axis=0, ddof=0)
+    std[std == 0] = 1.0
+    standardized = (values - mean) / std
+    return pd.DataFrame(standardized, columns=x.columns, index=x.index), mean, std
+
+
+def principal_components(z, k_factors: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Extract principal-component scores using the BBE normalization.
+
+    Parameters
+    ----------
+    z : array_like
+        Standardized information panel with shape ``(nobs, nseries)``.
+    k_factors : int
+        Number of principal components.
+
+    Returns
+    -------
+    factors : ndarray
+        Principal-component scores, normalized as ``U S / sqrt(N)``.
+    loadings : ndarray
+        Right singular vectors for the selected components.
+    explained_variance_ratio : ndarray
+        Share of panel variation captured by each selected component.
+    """
+    z = np.asarray(z, dtype=float)
+    if z.ndim != 2:
+        raise ValueError("z must be two-dimensional.")
+    nobs, nseries = z.shape
+    if k_factors < 1:
+        raise ValueError("k_factors must be at least 1.")
+    if k_factors > min(nobs, nseries):
+        raise ValueError("k_factors cannot exceed min(nobs, nseries).")
+
+    u, s, vt = np.linalg.svd(z, full_matrices=False)
+    factors = u[:, :k_factors] * s[:k_factors] / np.sqrt(nseries)
+    loadings = vt[:k_factors].T
+    total = np.sum(s**2)
+    ratio = (s[:k_factors] ** 2) / total if total > 0 else np.zeros(k_factors)
+    return factors, loadings, ratio
+
+
+def validate_slow_columns(
+    x_columns: pd.Index, slow_columns: list[str] | None, k_factors: int
+) -> list[str]:
+    """Validate slow-moving column names and return the effective list."""
+    if slow_columns is None:
+        slow = list(x_columns)
+    else:
+        missing = [col for col in slow_columns if col not in x_columns]
+        if missing:
+            raise ValueError(f"slow_columns contains unknown columns: {missing}")
+        slow = list(slow_columns)
+
+    if len(slow) < k_factors:
+        raise ValueError("slow_columns must contain at least k_factors columns.")
+    return slow

favar/model.py

@@ -0,0 +1,240 @@
+"""FAVAR model classes."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from statsmodels.tsa.api import VAR
+
+from .factor import (
+    align_panels,
+    as_float_dataframe,
+    principal_components,
+    standardize_frame,
+    validate_slow_columns,
+)
+from .order_selection import FAVAROrderSelection
+from .results import FAVARResults
+
+
+class FAVAR:
+    """Factor-Augmented VAR estimated with the BBE two-step procedure.
+
+    Parameters
+    ----------
+    X : DataFrame or array_like
+        Large information panel with shape ``(nobs, nseries)``.
+    Y : DataFrame or array_like
+        Observed variables included directly in the VAR. Must contain
+        ``policy_var``.
+    policy_var : str
+        Policy instrument ordered last for recursive identification.
+    k_factors : int, default 3
+        Number of factors extracted from ``X``.
+    slow_columns : sequence[str], optional
+        Columns of ``X`` treated as slow-moving. If omitted, all X columns are
+        used. Supplying this list is recommended for monetary-policy studies.
+    standardize : bool, default True
+        Standardize ``X`` before principal components.
+    """
+
+    def __init__(
+        self,
+        X,
+        Y,
+        policy_var: str,
+        k_factors: int = 3,
+        slow_columns: list[str] | None = None,
+        standardize: bool = True,
+    ):
+        self.X = as_float_dataframe(X, "X")
+        self.Y = as_float_dataframe(Y, "Y")
+        self.X, self.Y = align_panels(self.X, self.Y)
+
+        if policy_var not in self.Y.columns:
+            raise ValueError("policy_var must be a column of Y.")
+        self.policy_var = policy_var
+        self.k_factors = int(k_factors)
+        self.slow_columns = (
+            list(slow_columns) if slow_columns is not None else None
+        )
+        self.standardize = bool(standardize)
+        self._results: FAVARResults | None = None
+
+    def _prepare_system(self):
+        """Run the factor steps and build the augmented FAVAR system."""
+        X = self.X
+        Y = self.Y
+        nobs, nseries = X.shape
+
+        if self.standardize:
+            Xs, x_mean, x_std = standardize_frame(X)
+        else:
+            Xs = X.copy()
+            x_mean = np.zeros(nseries)
+            x_std = np.ones(nseries)
+
+        slow_columns = validate_slow_columns(
+            X.columns, self.slow_columns, self.k_factors
+        )
+        factor_names = [f"F{i + 1}" for i in range(self.k_factors)]
+
+        f0, pc_loadings, pc_var_ratio = principal_components(
+            Xs.to_numpy(), self.k_factors
+        )
+        fslow, slow_pc_loadings, slow_pc_var_ratio = principal_components(
+            Xs.loc[:, slow_columns].to_numpy(), self.k_factors
+        )
+
+        policy = Y[self.policy_var].to_numpy(dtype=float)
+        cleaning_design = np.column_stack([np.ones(nobs), policy, fslow])
+        cleaning_coef, *_ = np.linalg.lstsq(cleaning_design, f0, rcond=None)
+        policy_cleaning_coef = cleaning_coef[1, :]
+        factors = f0 - np.outer(policy, policy_cleaning_coef)
+
+        y_order = [col for col in Y.columns if col != self.policy_var]
+        y_order.append(self.policy_var)
+        order = factor_names + y_order
+        y_ordered = Y.loc[:, y_order]
+        var_data = pd.DataFrame(
+            np.column_stack([factors, y_ordered.to_numpy(dtype=float)]),
+            columns=order,
+            index=X.index,
+        )
+
+        measurement_design = np.column_stack(
+            [np.ones(nobs), factors, y_ordered.to_numpy(dtype=float)]
+        )
+        measurement_coef, *_ = np.linalg.lstsq(
+            measurement_design, Xs.to_numpy(dtype=float), rcond=None
+        )
+
+        return {
+            "var_data": var_data,
+            "order": order,
+            "factor_names": factor_names,
+            "y_names": y_order,
+            "x_names": list(X.columns),
+            "slow_columns": slow_columns,
+            "factors": factors,
+            "principal_components": f0,
+            "slow_principal_components": fslow,
+            "pc_loadings": pc_loadings,
+            "slow_pc_loadings": slow_pc_loadings,
+            "explained_variance_ratio": pc_var_ratio,
+            "slow_explained_variance_ratio": slow_pc_var_ratio,
+            "cleaning_coefficients": cleaning_coef,
+            "policy_cleaning_coefficients": policy_cleaning_coef,
+            "measurement_intercept": measurement_coef[0, :],
+            "measurement_loadings": measurement_coef[1:, :],
+            "x_mean": x_mean,
+            "x_std": x_std,
+        }
+
+    def select_order(self, maxlags: int = 12, trend: str = "c"):
+        """Select the lag order of the augmented FAVAR system.
+
+        Returns
+        -------
+        FAVAROrderSelection
+            Object with selected orders, a DataFrame representation, and a
+            printable summary table.
+        """
+        prepared = self._prepare_system()
+        var_model = VAR(prepared["var_data"])
+        order_results = var_model.select_order(maxlags=maxlags, trend=trend)
+        return FAVAROrderSelection(
+            order_results,
+            k_factors=self.k_factors,
+            n_x=len(prepared["x_names"]),
+            n_slow=len(prepared["slow_columns"]),
+            policy_var=self.policy_var,
+            maxlags=maxlags,
+        )
+
+    def fit(
+        self,
+        lags: int | None = 13,
+        select_order: str | None = None,
+        maxlags: int | None = None,
+        trend: str = "c",
+        verbose: bool = False,
+    ):
+        """Estimate the FAVAR.
+
+        Parameters
+        ----------
+        lags : int, default 13
+            Fixed VAR lag order. Ignored when ``select_order`` is provided.
+        select_order : {"aic", "bic", "hqic", "fpe"}, optional
+            Information criterion used to select the VAR lag order.
+        maxlags : int, optional
+            Maximum lag considered when ``select_order`` is used. If omitted,
+            ``lags`` is used.
+        trend : {"c", "ct", "ctt", "n"}, default "c"
+            Deterministic terms in the VAR step.
+        verbose : bool, default False
+            Print lag-selection details when available.
+        """
+        prepared = self._prepare_system()
+        var_model = VAR(prepared["var_data"])
+        if select_order is None:
+            var_results = var_model.fit(
+                maxlags=lags, ic=None, trend=trend, verbose=verbose
+            )
+        else:
+            lag_cap = maxlags if maxlags is not None else lags
+            var_results = var_model.fit(
+                maxlags=lag_cap, ic=select_order, trend=trend, verbose=verbose
+            )
+
+        self._results = FAVARResults(
+            model=self,
+            var_results=var_results,
+            var_data=prepared["var_data"],
+            order=prepared["order"],
+            factor_names=prepared["factor_names"],
+            y_names=prepared["y_names"],
+            x_names=prepared["x_names"],
+            slow_columns=prepared["slow_columns"],
+            policy_var=self.policy_var,
+            factors=prepared["factors"],
+            principal_components=prepared["principal_components"],
+            slow_principal_components=prepared["slow_principal_components"],
+            pc_loadings=prepared["pc_loadings"],
+            slow_pc_loadings=prepared["slow_pc_loadings"],
+            explained_variance_ratio=prepared["explained_variance_ratio"],
+            slow_explained_variance_ratio=prepared["slow_explained_variance_ratio"],
+            cleaning_coefficients=prepared["cleaning_coefficients"],
+            policy_cleaning_coefficients=prepared["policy_cleaning_coefficients"],
+            measurement_intercept=prepared["measurement_intercept"],
+            measurement_loadings=prepared["measurement_loadings"],
+            x_mean=prepared["x_mean"],
+            x_std=prepared["x_std"],
+            index=self.X.index,
+            standardize=self.standardize,
+        )
+        return self._results
+
+    def _check_results(self) -> FAVARResults:
+        if self._results is None:
+            raise RuntimeError("Call fit() before accessing results.")
+        return self._results
+
+    def summary(self):
+        return self._check_results().summary()
+
+    def forecast(self, steps: int, alpha: float = 0.05, confidence_level=None):
+        return self._check_results().forecast(
+            steps, alpha=alpha, confidence_level=confidence_level
+        )
+
+    def impulse_response(self, periods: int = 10, shock: str | None = None, **kwargs):
+        return self._check_results().impulse_response(periods, shock=shock, **kwargs)
+
+    def panel_impulse_response(
+        self, periods: int = 10, shock: str | None = None, **kwargs
+    ):
+        return self._check_results().panel_impulse_response(
+            periods, shock=shock, **kwargs
+        )

favar/order_selection.py

@@ -0,0 +1,71 @@
+"""Lag-order selection results for FAVAR models."""
+
+from __future__ import annotations
+
+import pandas as pd
+from statsmodels.iolib.table import SimpleTable
+
+
+class FAVAROrderSelection:
+    """Lag-order selection table for the augmented FAVAR system."""
+
+    def __init__(
+        self,
+        order_results,
+        k_factors: int,
+        n_x: int,
+        n_slow: int,
+        policy_var: str,
+        maxlags: int,
+    ):
+        self.order_results = order_results
+        self.ics = order_results.ics
+        self.selected_orders = dict(order_results.selected_orders)
+        self.aic = self.selected_orders["aic"]
+        self.bic = self.selected_orders["bic"]
+        self.fpe = self.selected_orders["fpe"]
+        self.hqic = self.selected_orders["hqic"]
+        self.k_factors = k_factors
+        self.n_x = n_x
+        self.n_slow = n_slow
+        self.policy_var = policy_var
+        self.maxlags = maxlags
+
+    def __repr__(self):
+        return str(self.summary())
+
+    def __str__(self):
+        return (
+            "<FAVAROrderSelection: "
+            f"AIC={self.aic}, BIC={self.bic}, FPE={self.fpe}, HQIC={self.hqic}>"
+        )
+
+    def to_frame(self, mark_min: bool = False) -> pd.DataFrame:
+        """Return the information criteria as a DataFrame."""
+        columns = ["aic", "bic", "fpe", "hqic"]
+        nrows = len(self.ics[columns[0]])
+        p_min = self.maxlags - nrows + 1
+        index = range(p_min, self.maxlags + 1)
+        frame = pd.DataFrame(
+            {col.upper(): self.ics[col] for col in columns}, index=index
+        )
+        if mark_min:
+            out = pd.DataFrame(index=frame.index, columns=frame.columns, dtype=object)
+            for row in frame.index:
+                for col in frame.columns:
+                    out.loc[row, col] = f"{frame.loc[row, col]:#.4g}"
+            for col, selected in self.selected_orders.items():
+                out.loc[selected, col.upper()] = f"{frame.loc[selected, col.upper()]:#.4g}*"
+            return out
+        return frame
+
+    def summary(self):
+        """Return a printable order-selection table."""
+        frame = self.to_frame(mark_min=True)
+        table = SimpleTable(
+            frame.to_numpy(dtype=object),
+            headers=list(frame.columns),
+            stubs=[str(i) for i in frame.index],
+            title="FAVAR Lag Order Selection (* highlights the minimums)",
+        )
+        return table