Source code for kaxanuk.attribution_analysis.interfaces.factor_model_arrow_interface

import abc
import pyarrow as pa




class FactorModelArrowAttributionInterface(metaclass=abc.ABCMeta):
    """
    Abstract interface for multi-factor model attribution using PyArrow Tables.

    Defines the contract for decomposing portfolio returns into contributions
    from individual risk factors (style, industry, etc.) using factor return
    data and portfolio weights.

    Parameters
    ----------
    daily_portfolio_weights : pa.Table
        Daily portfolio weights with a date column and one float64 column
        per asset ticker.
    by_factor_factor_returns : dict[str, pa.Table]
        Mapping of factor name to a ``pa.Table`` of per-asset factor returns.
        Each table has a date column and one float64 column per asset.
    asset_returns : pa.Table
        Total asset returns with a date column and one float64 column per
        asset ticker.
    portfolio_returns : pa.Table, optional
        Pre-computed portfolio-level returns with columns ``date`` and
        ``portfolio_returns``. If ``None``, computed internally from
        weights and asset returns.
    benchmark_returns : pa.Table, optional
        Benchmark-level returns with a date column and a returns column.
    """

    def __init__(
            self,
            daily_portfolio_weights: pa.Table,
            by_factor_factor_returns: dict[str, pa.Table],
            asset_returns: pa.Table,
            portfolio_returns: pa.Table | None = None,
            benchmark_returns: pa.Table | None = None,
    ) -> None:
        self.daily_portfolio_weights = daily_portfolio_weights
        self.by_factor_factor_returns = by_factor_factor_returns
        self.asset_returns = asset_returns
        self.portfolio_returns = portfolio_returns
        self.benchmark_returns = benchmark_returns



    @abc.abstractmethod
    def multifactor_attribution(self) -> None:
        """
        Calculate the multi-factor attribution model across all dates.

        For each date, computes the weighted sum of each factor's per-asset
        returns using portfolio weights, producing a time series of daily
        factor contributions.

        Returns
        -------
        None
            Results are stored in ``self.portfolio_attribution_ts`` as a
            ``pa.Table`` with a date column and one float64 column per factor.
        """
        ...