Factor attribution realised methods

The verbs of this page are the methods that a new AbstractUnknownEntryRule implements. The private page documents the other names of this topic.

PortfolioOptimisers.attribution_leverage_split — Function

attribution_leverage_split(rule::ZeroUnknown, args...) -> Nothing
attribution_leverage_split(rule::EntrywiseUnknown, lev::Nothing, args...) -> Nothing
attribution_leverage_split(rule::EntrywiseUnknown, lev::AbstractVector{Bool}, w::VecNum,
                           M::MatNum) -> Option{<:NamedTuple}
attribution_leverage_split(rule::EntrywiseUnknown, h1::AbstractMatrix{Bool},
                           W::VecNum_MatNum, B::MatNum_Arr3Num) -> Option{<:NamedTuple}

Return the assets and the factors whose variance split the attribution does not identify, or nothing.

A Leverage-One Pair has a direction of the design of its own. At its row the data identify only the sum of the factor return of that direction and the own return of the asset, so every own variance from zero upwards fits the data equally well. ZeroUnknown reads the split as fitted, so it marks nothing. EntrywiseUnknown marks every asset that the portfolio holds at a row where the mask marks it, and every factor whose only member at that row is the asset.

The predicted method reads an asset mask and one set of loadings, through attribution_marked_assets. The realised method reads the mask and the weights row by row.

Arguments

rule: The rule for the variance split of a Leverage-One Pair.
lev: Assets the mask marks at one row or more.
h1: The leverage-one mask, observations × assets.
w: Portfolio weights.
W: Portfolio weights, or the weight history, observations × assets.
M: Loadings, assets × factors.
B: Loadings, or the exposure history, observations × assets × factors, zero at an inactive pair.

Returns

lv::Option{<:NamedTuple}: nothing when the portfolio holds no marked asset. Otherwise the asset mask assets and the factor mask factors.

Related

source

PortfolioOptimisers.attribution_leverage_errors — Function

attribution_leverage_errors(rule::ZeroUnknown, h1, reg, ses, pass) -> NamedTuple
attribution_leverage_errors(rule::EntrywiseUnknown, h1::Nothing, reg, ses, pass)
    -> NamedTuple
attribution_leverage_errors(rule::EntrywiseUnknown, h1::AbstractMatrix{Bool},
                            reg::AbstractMatrix{Bool}, ses::NamedTuple, pass)
    -> NamedTuple

Return the standard errors with NaN at every output whose sandwich reads a Leverage-One Pair.

The sandwich reads the idiosyncratic variance of a marked pair, and that variance is not identified: every own variance from zero upwards fits the data equally well. An output reads the pair when its sandwich gives the pair a coefficient that is not zero. The function runs the reduction of pass twice more, once with the indicator of the marked pairs and once with the indicator of every regression pair. The first sum is the leverage index of each output, and the second is its scale. An output is NaN when its leverage index exceeds $\varepsilon$ times its scale.

A coefficient of round-off gives a ratio far below $\varepsilon$, of the order of $10^{-19}$ on a panel of 40 assets, because the quadratic form adds round-off of its own to the square of the coefficient. This is the case of an output that the fit separates from the pair, a style factor or a portfolio that holds no marked pair. A real coefficient, through the zero-sum constraint of a family or through a holding of the pair, gives a ratio far above $\varepsilon$, of the order of $10^{-3}$ or more. The pair stays in the sandwich: without it the Gram matrix is singular in the direction of the level, and the pseudo-inverse gives a minimum-norm number that is not an error.

ZeroUnknown reads the plug-in variance of the pair, so it changes nothing. h1 = nothing marks no pair.

Mathematical definition

\[\begin{align} \boldsymbol{c}_{t} &= \mathbf{Q}_{t} \mathbf{B}_{t} \mathbf{G}_{t}^{+} \boldsymbol{g}_{t}\,, \\ \ell &= \sum_{t=1}^{T} \sum_{i=1}^{N} c_{ti}^{2}\, h_{ti}\,, \\ S &= \sum_{t=1}^{T} \sum_{i=1}^{N} c_{ti}^{2}\, a_{ti}\,. \end{align}\]

The output is NaN when $\ell > \varepsilon\, S$. The definition is that of the systematic error. A factor or a family takes the same sums with $\boldsymbol{g}_{t}$ restricted to its own entries.

Where:

$\boldsymbol{c}_{t}$: Coefficient of the output on each pair of observation $t$, one entry $c_{ti}$ per asset.
$\ell$, $S$: Leverage index and scale of the output.
$h_{ti}$: Whether pair $(t, i)$ is a Leverage-One Pair in the regression.
$a_{ti}$: Whether pair $(t, i)$ is in the regression: active, with a regression weight that is not zero.
$\mathbf{G}_{t}^{+}$: Inverse of the Gram matrix of observation $t$, or its pseudo-inverse, as attribution_sandwich states it.
$\mathbf{Q}_{t}$: Regression weight matrix of observation $t$, diagonal, holding the cross-sectional weight of each asset.
$\mathbf{B}_{t}$: Exposure slice of observation $t$, $N \times K$, the exposures the factor returns of $t$ are read against.
$\boldsymbol{g}_{t} = \mathbf{B}_{t}^{\intercal} \boldsymbol{w}_{t}$: Portfolio factor exposure of observation $t$, $K \times 1$, with entry $g_{tk}$ for factor $k$.
$\varepsilon$: Machine epsilon of the element type, twice its unit roundoff $u$.
$N$: Number of assets.
$T$: Number of observations.

Arguments

rule: The rule for the variance of a Leverage-One Pair.
h1: The leverage-one mask, observations × assets, or nothing.
reg: Whether each pair is in the regression, observations × assets.
ses: The standard errors, from attribution_error_pass.
pass: The reduction, a function of the matrix of variances.

Returns

ses::NamedTuple: The standard errors, with NaN at every output that reads a marked pair.

Related

source

PortfolioOptimisers.attribution_unknown_keep — Function

attribution_unknown_keep(rule::EntrywiseUnknown, w::VecNum)
attribution_unknown_keep(rule::ZeroUnknown, w::VecNum)

Return the assets whose unknown entries stay unknown in a predicted attribution.

An entry of an asset with a weight of zero adds nothing to a sum, so its value is irrelevant, and it is replaced by zero under either rule. EntrywiseUnknown keeps the unknown entries of every held asset, so a sum that reads one is NaN. ZeroUnknown keeps none.

Arguments

rule: The rule for an unknown entry.
w: Portfolio weights.

Returns

keep::BitVector: true at every asset whose unknown entries stay NaN.

Related

source

PortfolioOptimisers.attribution_standalone — Function

attribution_standalone(rule::EntrywiseUnknown, A::AbstractArray)
attribution_standalone(rule::ZeroUnknown, A::AbstractArray)

Return the entries of the block that the standalone moments of the predicted asset axis read.

The standalone volatility and mean of an asset are moments of the asset, not contributions, so they read the block's own entries. EntrywiseUnknown reads them as they are, so the model states no volatility for an asset whose idiosyncratic variance is unknown. ZeroUnknown reads every unknown entry as zero.

Arguments

rule: The rule for an unknown entry.
A: The loadings, the factor-orthogonal mean or the idiosyncratic block.

Returns

A::AbstractArray: The entries the standalone moments read.

Related

source

PortfolioOptimisers.attribution_unknown_note — Function

attribution_unknown_note(rule::EntrywiseUnknown)
attribution_unknown_note(rule::ZeroUnknown)

Return the sentence a predicted attribution adds to the report of a held non-investable asset.

The report names the assets, and this sentence states what the rule did with their unknown entries, so the reader knows which numbers to trust.

Arguments

rule: The rule for an unknown entry.

Returns

note::String: The sentence.

Related

source