Skip to content

"Vibe-Trading: Your Personal Trading Agent"

18.3 KB
Raw Blame
"""Brinson-Fachler performance attribution with residual-free multi-period linking.

Single-period decomposition splits the active return (portfolio minus benchmark)
into three sector-level effects::

    Allocation_i  = (w_p,i - w_b,i) * (r_b,i - R_b)
    Selection_i   =  w_b,i          * (r_p,i - r_b,i)
    Interaction_i = (w_p,i - w_b,i) * (r_p,i - r_b,i)

The sum of all three over all sectors equals ``R_p - R_b`` *identically* -- there
is no residual and none is reported. The identity holds for any sector returns
whatsoever, provided only that the two weight vectors carry the same total; that
is the one precondition this module enforces (see :func:`brinson_fachler`).

Multi-period linking uses **Carino** logarithmic linking, for three reasons:

1. It is residual-free. Naively summing single-period arithmetic effects does not
   reproduce the compounded active return, because returns compound and effects
   are added; Carino's scaling factors absorb exactly that gap.
2. Its scaling factor for a period depends only on that period's total portfolio
   and benchmark return -- never on the effects being linked. Linking is therefore
   deterministic, order-independent, and cannot be steered by how the analyst
   chose to bucket sectors. Menchero's linking is likewise residual-free but
   distributes a correction term computed from the effects themselves, which adds
   machinery this module does not need.
3. It is what ``skills/performance-attribution/SKILL.md`` already prescribes, so
   the tested implementation and the documented method agree.

Carino defines a total factor ``k`` and a per-period factor ``k_t``::

    k   = (ln(1 + R_P) - ln(1 + R_B)) / (R_P - R_B)
    k_t = (ln(1 + R_p,t) - ln(1 + R_b,t)) / (R_p,t - R_b,t)

and scales every single-period effect by ``k_t / k``. Because each period's
effects sum to ``R_p,t - R_b,t``, the linked effects telescope through the
logarithms and sum to the compounded active return ``R_P - R_B`` exactly.

Only the standard library is imported here, so this module stays importable even
when an optional numerical dependency used elsewhere in ``quantlib`` is missing.
"""

from __future__ import annotations

import math
from collections.abc import Mapping, Sequence
from dataclasses import dataclass

#: Public surface. `quantlib_call` dispatches on ``__all__`` alone, so a module
#: without it is unreachable from Web / API / MCP even when the tool allowlists
#: it — which is exactly what happened to this module until 0.1.13.
__all__ = [
    "DEFAULT_WEIGHT_SUM_TOLERANCE",
    "BrinsonResult",
    "LinkedAttribution",
    "LinkedSectorEffect",
    "SectorEffect",
    "brinson_fachler",
    "carino_factor",
    "carino_link",
]

#: Largest tolerated difference between the portfolio and benchmark weight sums.
#: Beyond this the Brinson identity stops holding, so it is an error, not a warning.
DEFAULT_WEIGHT_SUM_TOLERANCE = 1e-9

#: Below this absolute gap between a period's portfolio and benchmark return, the
#: Carino factor is evaluated at its analytic limit rather than by a difference of
#: logarithms, which would lose precision to catastrophic cancellation.
_CARINO_LIMIT_EPS = 1e-9


@dataclass(frozen=True)
class SectorEffect:
    """One sector's single-period Brinson-Fachler decomposition.

    Attributes:
        sector: Sector label.
        portfolio_weight: Portfolio weight of the sector (``w_p,i``).
        benchmark_weight: Benchmark weight of the sector (``w_b,i``).
        portfolio_return: Portfolio return within the sector (``r_p,i``).
        benchmark_return: Benchmark return within the sector (``r_b,i``).
        allocation: Allocation effect, from over/under-weighting the sector.
        selection: Selection effect, from picking better names inside the sector.
        interaction: Interaction effect, the cross term of the two.
    """

    sector: str
    portfolio_weight: float
    benchmark_weight: float
    portfolio_return: float
    benchmark_return: float
    allocation: float
    selection: float
    interaction: float

    @property
    def total(self) -> float:
        """Return the sector's total contribution to the active return.

        Returns:
            Sum of the allocation, selection and interaction effects.
        """
        return self.allocation + self.selection + self.interaction


@dataclass(frozen=True)
class BrinsonResult:
    """Single-period attribution for a whole portfolio.

    The three aggregate effects sum to :attr:`active_return` exactly; no residual
    term exists or is reported.

    Attributes:
        sectors: Per-sector decompositions, portfolio order first, then any
            benchmark-only sectors.
        portfolio_return: Total portfolio return ``R_p = sum(w_p,i * r_p,i)``.
        benchmark_return: Total benchmark return ``R_b = sum(w_b,i * r_b,i)``.
        active_return: ``R_p - R_b``.
        allocation: Sum of every sector's allocation effect.
        selection: Sum of every sector's selection effect.
        interaction: Sum of every sector's interaction effect.
    """

    sectors: tuple[SectorEffect, ...]
    portfolio_return: float
    benchmark_return: float
    active_return: float
    allocation: float
    selection: float
    interaction: float

    @property
    def total_effect(self) -> float:
        """Return the summed effects, which equal :attr:`active_return`.

        Returns:
            Allocation plus selection plus interaction.
        """
        return self.allocation + self.selection + self.interaction


@dataclass(frozen=True)
class LinkedSectorEffect:
    """One sector's Carino-linked effects across every period.

    Weights and returns are deliberately absent: they compound rather than add,
    so a multi-period "weight" would have no single defensible definition.

    Attributes:
        sector: Sector label.
        allocation: Linked allocation effect.
        selection: Linked selection effect.
        interaction: Linked interaction effect.
    """

    sector: str
    allocation: float
    selection: float
    interaction: float

    @property
    def total(self) -> float:
        """Return the sector's total linked contribution.

        Returns:
            Sum of the linked allocation, selection and interaction effects.
        """
        return self.allocation + self.selection + self.interaction


@dataclass(frozen=True)
class LinkedAttribution:
    """Multi-period attribution produced by Carino linking.

    The three aggregate effects sum to :attr:`active_return`, the *compounded*
    active return, exactly.

    Attributes:
        sectors: Per-sector linked decompositions.
        portfolio_return: Compounded portfolio return over all periods.
        benchmark_return: Compounded benchmark return over all periods.
        active_return: ``portfolio_return - benchmark_return``.
        allocation: Linked allocation effect, summed over sectors.
        selection: Linked selection effect, summed over sectors.
        interaction: Linked interaction effect, summed over sectors.
        scaling_factors: The ``k_t / k`` multiplier applied to each period, in
            period order. Exposed so an attribution report can be audited.
    """

    sectors: tuple[LinkedSectorEffect, ...]
    portfolio_return: float
    benchmark_return: float
    active_return: float
    allocation: float
    selection: float
    interaction: float
    scaling_factors: tuple[float, ...]

    @property
    def total_effect(self) -> float:
        """Return the summed linked effects, which equal :attr:`active_return`.

        Returns:
            Allocation plus selection plus interaction.
        """
        return self.allocation + self.selection + self.interaction


def brinson_fachler(
    portfolio_weights: Mapping[str, float],
    benchmark_weights: Mapping[str, float],
    portfolio_returns: Mapping[str, float],
    benchmark_returns: Mapping[str, float],
    weight_sum_tolerance: float = DEFAULT_WEIGHT_SUM_TOLERANCE,
) -> BrinsonResult:
    """Decompose one period's active return into allocation, selection and interaction.

    Sector returns may be omitted only where the corresponding weight is zero; the
    missing return is then filled from the other side. That makes a benchmark-only
    sector's selection and interaction vanish and charges the whole effect to
    allocation -- you cannot show selection skill in something you did not own --
    and it treats an off-benchmark holding symmetrically. The choice never
    threatens the tie-out, which is independent of the sector returns used.

    Args:
        portfolio_weights: Sector label to portfolio weight.
        benchmark_weights: Sector label to benchmark weight.
        portfolio_returns: Sector label to within-sector portfolio return.
        benchmark_returns: Sector label to within-sector benchmark return.
        weight_sum_tolerance: Largest tolerated difference between the two weight
            sums. Defaults to :data:`DEFAULT_WEIGHT_SUM_TOLERANCE`.

    Returns:
        A :class:`BrinsonResult` whose allocation, selection and interaction sum
        to its ``active_return`` to floating-point precision, provided the two
        weight vectors really do carry the same total.

        The tie-out is exactly as good as ``weight_sum_tolerance`` allows: a
        weight-sum gap ``dW`` leaves a residual of ``-R_b * dW``, because the
        ``R_b * sum(w_p - w_b)`` term of the allocation effect no longer vanishes.
        At the default tolerance that residual is below 1e-10 and invisible.
        Loosen the tolerance and it becomes visible in basis points -- a 2%
        weight-sum gap against a 5% benchmark return is a 10bp residual -- so
        loosen it only to absorb rounding in the weights, never to force through
        two vectors that genuinely disagree.

    Raises:
        ValueError: If no sectors were supplied, if the two weight vectors do not
            sum to the same total within ``weight_sum_tolerance``, or if a sector
            carries a non-zero weight on a side but no return on that side,
            if a weight or resolved return is non-finite, or if the tolerance
            is non-finite or negative.
    """
    ordered: list[str] = list(portfolio_weights)
    ordered.extend(
        sector for sector in benchmark_weights if sector not in portfolio_weights
    )
    if not ordered:
        raise ValueError("brinson_fachler needs at least one sector")

    if not math.isfinite(weight_sum_tolerance) or weight_sum_tolerance < 0.0:
        raise ValueError("weight_sum_tolerance must be finite and non-negative")
    for side, weights in (
        ("portfolio", portfolio_weights),
        ("benchmark", benchmark_weights),
    ):
        for sector, weight in weights.items():
            if not math.isfinite(weight):
                raise ValueError(
                    f"sector {sector!r} has non-finite {side} weight {weight!r}"
                )

    portfolio_total = math.fsum(portfolio_weights.values())
    benchmark_total = math.fsum(benchmark_weights.values())
    if abs(portfolio_total - benchmark_total) > weight_sum_tolerance:
        raise ValueError(
            "portfolio and benchmark weights must sum to the same total for the Brinson "
            f"identity to hold; got {portfolio_total!r} and {benchmark_total!r} "
            f"(difference {portfolio_total - benchmark_total!r} exceeds {weight_sum_tolerance!r})"
        )

    resolved: list[tuple[str, float, float, float, float]] = []
    for sector in ordered:
        w_p = float(portfolio_weights.get(sector, 0.0))
        w_b = float(benchmark_weights.get(sector, 0.0))
        r_p = portfolio_returns.get(sector)
        r_b = benchmark_returns.get(sector)
        if r_p is None:
            if w_p != 0.0:
                raise ValueError(
                    f"sector {sector!r} has portfolio weight {w_p!r} but no portfolio return"
                )
            if r_b is None:
                raise ValueError(
                    f"sector {sector!r} has no portfolio return and no benchmark return"
                )
            r_p = r_b
        if r_b is None:
            if w_b != 0.0:
                raise ValueError(
                    f"sector {sector!r} has benchmark weight {w_b!r} but no benchmark return"
                )
            r_b = r_p
        for side, value in (("portfolio", r_p), ("benchmark", r_b)):
            if not math.isfinite(value):
                raise ValueError(
                    f"sector {sector!r} has non-finite {side} return {value!r}"
                )
        resolved.append((sector, w_p, w_b, float(r_p), float(r_b)))

    total_portfolio_return = math.fsum(w_p * r_p for _, w_p, _, r_p, _ in resolved)
    total_benchmark_return = math.fsum(w_b * r_b for _, _, w_b, _, r_b in resolved)

    effects: list[SectorEffect] = []
    for sector, w_p, w_b, r_p, r_b in resolved:
        active_weight = w_p - w_b
        effects.append(
            SectorEffect(
                sector=sector,
                portfolio_weight=w_p,
                benchmark_weight=w_b,
                portfolio_return=r_p,
                benchmark_return=r_b,
                allocation=active_weight * (r_b - total_benchmark_return),
                selection=w_b * (r_p - r_b),
                interaction=active_weight * (r_p - r_b),
            )
        )

    return BrinsonResult(
        sectors=tuple(effects),
        portfolio_return=total_portfolio_return,
        benchmark_return=total_benchmark_return,
        active_return=total_portfolio_return - total_benchmark_return,
        allocation=math.fsum(effect.allocation for effect in effects),
        selection=math.fsum(effect.selection for effect in effects),
        interaction=math.fsum(effect.interaction for effect in effects),
    )


def carino_factor(portfolio_return: float, benchmark_return: float) -> float:
    """Return the Carino logarithmic scaling factor for one return pair.

    The factor is ``(ln(1 + Rp) - ln(1 + Rb)) / (Rp - Rb)``. When the two returns
    coincide that expression is 0/0, so the analytic limit ``1 / (1 + Rp)`` applies.
    It is evaluated in the equivalent symmetric form ``2 / ((1 + Rp) + (1 + Rb))``,
    which reduces to ``1 / (1 + Rp)`` when the returns are equal but stays accurate
    to second order just short of coincidence, where the difference of logarithms
    would lose most of its significant digits to cancellation.

    Args:
        portfolio_return: Portfolio return for the period, as a decimal fraction.
        benchmark_return: Benchmark return for the period, as a decimal fraction.

    Returns:
        The scaling factor.

    Raises:
        ValueError: If either return is at or below -100%, which would make the
            wealth relative non-positive and the logarithm undefined, or if
            either return is non-finite.
    """
    if not math.isfinite(portfolio_return) or not math.isfinite(benchmark_return):
        raise ValueError("Carino linking needs finite portfolio and benchmark returns")
    portfolio_wealth = 1.0 + portfolio_return
    benchmark_wealth = 1.0 + benchmark_return
    if portfolio_wealth <= 0.0 or benchmark_wealth <= 0.0:
        raise ValueError(
            "Carino linking needs returns above -100%; got portfolio "
            f"{portfolio_return!r} and benchmark {benchmark_return!r}"
        )
    # Near coincidence is relative to the remaining wealth, not to the
    # returns' absolute scale: two returns close to -100% can differ by a
    # tiny absolute amount while their wealth relatives differ severalfold.
    if abs(portfolio_return - benchmark_return) < _CARINO_LIMIT_EPS * min(
        portfolio_wealth, benchmark_wealth
    ):
        return 2.0 / (portfolio_wealth + benchmark_wealth)
    return (math.log(portfolio_wealth) - math.log(benchmark_wealth)) / (
        portfolio_return - benchmark_return
    )


def carino_link(periods: Sequence[BrinsonResult]) -> LinkedAttribution:
    """Link single-period Brinson results into a residual-free multi-period attribution.

    Every period's effects are scaled by ``k_t / k`` and summed. Because each
    period's three effects already sum to that period's active return, the linked
    effects sum to the compounded active return exactly.

    Sectors absent from a period are treated as contributing zero for that period,
    which is what a zero weight on both sides would have produced anyway.

    Args:
        periods: Single-period results in chronological order.

    Returns:
        A :class:`LinkedAttribution` whose allocation, selection and interaction
        sum to its ``active_return`` to floating-point precision.

    Raises:
        ValueError: If ``periods`` is empty, or if any period's return is at or
            below -100%, which the logarithmic linking cannot represent.
    """
    if not periods:
        raise ValueError("carino_link needs at least one period")

    portfolio_wealth = math.prod(1.0 + period.portfolio_return for period in periods)
    benchmark_wealth = math.prod(1.0 + period.benchmark_return for period in periods)
    total_portfolio_return = portfolio_wealth - 1.0
    total_benchmark_return = benchmark_wealth - 1.0
    total_factor = carino_factor(total_portfolio_return, total_benchmark_return)

    scaling_factors = tuple(
        carino_factor(period.portfolio_return, period.benchmark_return) / total_factor
        for period in periods
    )

    order: list[str] = []
    scaled: dict[str, list[float]] = {}
    for period, scale in zip(periods, scaling_factors, strict=True):
        for effect in period.sectors:
            if effect.sector not in scaled:
                order.append(effect.sector)
                scaled[effect.sector] = [0.0, 0.0, 0.0]
            bucket = scaled[effect.sector]
            bucket[0] += scale * effect.allocation
            bucket[1] += scale * effect.selection
            bucket[2] += scale * effect.interaction

    sectors = tuple(
        LinkedSectorEffect(
            sector=sector,
            allocation=scaled[sector][0],
            selection=scaled[sector][1],
            interaction=scaled[sector][2],
        )
        for sector in order
    )

    return LinkedAttribution(
        sectors=sectors,
        portfolio_return=total_portfolio_return,
        benchmark_return=total_benchmark_return,
        active_return=total_portfolio_return - total_benchmark_return,
        allocation=math.fsum(sector.allocation for sector in sectors),
        selection=math.fsum(sector.selection for sector in sectors),
        interaction=math.fsum(sector.interaction for sector in sectors),
        scaling_factors=scaling_factors,
    )