.. _factor_model:

Factor Model
============

Decomposes portfolio return into per-factor contributions plus an idiosyncratic residual, using
user-supplied factor return series (style factors such as size, momentum, beta, residual
volatility and value, plus industry factors).

Formulas
--------

For each date:

.. math::

   \text{factor\_contribution}_f &= \sum_{\text{assets}} \text{weight}_{\text{asset}}
       \cdot \text{factor\_return}_{f,\text{asset}} \\
   \text{portfolio\_return} &= \sum_{\text{assets}} \text{weight}_{\text{asset}}
       \cdot \text{asset\_return}_{\text{asset}}

Contributions are accumulated over time (cumulative sum). The percentage decomposition divides
each factor's contribution by the total return and captures the unexplained part as an
idiosyncratic residual (``f_idio_returns``).

Implementation
---------------

The PyArrow-based implementation lives in
:class:`~kaxanuk.attribution_analysis.interfaces.FactorModelArrowAttribution`, implementing
:class:`~kaxanuk.attribution_analysis.interfaces.FactorModelArrowAttributionInterface`. A pandas-based
reference implementation is also available as
:class:`~kaxanuk.attribution_analysis.interfaces.FactorModelAttribution`. See
:ref:`attribution_methodologies_factor_model_ref` for the full API reference.

Enable this methodology by setting ``factor_model_method = yes`` in
``attribution_analysis_parameters.xlsx`` (see :ref:`configuration`). When enabled and the entry
script runs with ``launch_dashboard=True``, an interactive Dash dashboard is served on
``dashboard_port`` (see :ref:`dashboard_ref`); with only Brinson-Fachler enabled, static matplotlib
plots are produced instead.