Factor attribution (a)
PortfolioOptimisers.AbstractUnknownEntryRule — Type
abstract type AbstractUnknownEntryRule <: AbstractAlgorithmAbstract supertype of the rules a factor attribution applies to an entry the factor model does not state.
A Prior Estimator states no idiosyncratic variance for an asset in the warm-up of its variance, and no loadings for an asset that delisted. A portfolio that holds such an asset has a variance that reads the unknown entry, so the attribution must say what it does with it. Each concrete rule is one answer, and factor_attribution takes it through the keyword unknown.
EntrywiseUnknownkeeps every entry the model states, and givesNaNfor every number that reads an entry it does not state. It is the default.ZeroUnknownreads every entry the model does not state as zero, and an absent return as a zero return.KindwiseUnknownapplies one rule to each kind of unknown entry.
The rule applies on the predicted side to every number, and on both sides to the standalone moments of the asset axis. An entry of an asset the portfolio does not hold has a weight of zero, so it adds nothing to a sum under either rule.
A Leverage-One Pair is a second kind of unknown entry. The fit reproduced the return of the pair, so its total is exact and the split between its systematic and its idiosyncratic part is unknown. This is the opposite of an asset in the warm-up of its variance, whose split is exact up to its unknown idiosyncratic part. The rule applies to this kind on both sides, through attribution_leverage_split.
Interfaces
In order to implement a new rule for an unknown entry which will work seamlessly with the library, subtype AbstractUnknownEntryRule and implement the following six methods. The first four apply the rule to an entry the factor model does not state, and the last two apply it to the variance split of a Leverage-One Pair. A rule that implements all six applies to every kind, and it can also be a field of KindwiseUnknown.
The held assets that keep their unknown entries
attribution_unknown_keep(rule::MyRule, w::VecNum) -> BitVector: Returns the assets whose unknown entries stay unknown in a predicted attribution.
Arguments
rule: The rule.w: Portfolio weights.
Returns
keep::BitVector:trueat every asset whose unknown entries stayNaN. An asset with a weight of zero adds nothing to a sum, so the attribution reads its unknown entries as zero whatever the rule returns.
The standalone moments of the predicted asset axis
attribution_standalone(rule::MyRule, A::AbstractArray) -> AbstractArray: Returns the entries of a block that the standalone volatility and mean of each asset read.
Arguments
rule: The rule.A: The loadings, the factor-orthogonal mean or the idiosyncratic block.
Returns
A::AbstractArray: The entries the standalone moments read, the shape ofA.
The observations of the realised standalone moments
attribution_standalone_pairs(rule::MyRule, act::AbstractVector{Bool}) -> AbstractVector{Bool}: Returns the observations that the realised standalone moments of one asset read.
Arguments
rule: The rule.act: Whether each aligned pair of the asset is active.
Returns
a::AbstractVector{Bool}: The observations the moments read, the length ofact.
The note of the report
attribution_unknown_note(rule::MyRule) -> String: Returns the sentence that a predicted attribution adds to the report of a held asset that is not investable.
Arguments
rule: The rule.
Returns
note::String: The sentence. It states what the rule does with the unknown entries, so that the reader knows which numbers to trust.
The marks of a Leverage-One Pair
attribution_leverage_split(rule::MyRule, lev::Option{<:AbstractVector{Bool}}, w::VecNum, M::MatNum) -> Option{<:LeverageSplitResult}: Returns the marks of a predicted attribution.attribution_leverage_split(rule::MyRule, h1::Option{<:AbstractMatrix{Bool}}, W::VecNum_MatNum, B::MatNum_Arr3Num) -> Option{<:LeverageSplitResult}: Returns the marks of a realised attribution.
Arguments
rule: The rule.lev: Assets the leverage-one mask marks at one row or more, ornothingwhen the model marks no pair.h1: The leverage-one mask,observations × assets, ornothingwhen the model marks no pair.w: Portfolio weights.W: Portfolio weights, or the weight history,observations × assets.M: Loadings,assets × factors.B: Loadings, or the exposure history,assets × factors × observations. Earlier releases held the observations of the history on its first axis. A method written for them readsB[t, :, :], and it must now readB[:, :, t], or the slice thatattribution_slice(B, t)gives.
Returns
lv::Option{<:LeverageSplitResult}:nothingwhen the rule marks nothing. Otherwise aLeverageSplitResultwith the asset maskassetsand the factor maskfactors, whose constructor refuses marks that name no asset.attribution_leverage_nanputsNaNin every variance number that the marks read.
The standard errors of a Leverage-One Pair
attribution_leverage_errors(rule::MyRule, h1::Option{<:AbstractMatrix{Bool}}, reg::AbstractMatrix{Bool}, ses::AttributionErrorsResult, pass) -> AttributionErrorsResult: Returns the standard errors of the mean return contributions after the rule.
Arguments
rule: The rule.h1: The leverage-one mask,observations × assets, ornothingwhen the model marks no pair.reg: Whether each pair is in the regression,observations × assets.ses: The standard errors, anAttributionErrorsResultwith the fieldssys,factorandfamily.pass: The reduction ofattribution_error_pass, a function of a matrix of variances,observations × assets, which returns anAttributionErrorsResult.
Returns
ses::AttributionErrorsResult: The standard errors after the rule. A method that changes an error builds a newAttributionErrorsResult, whose constructor checks that the three answers agree on what they state.
Related
PortfolioOptimisers.AttributionComponent — Type
struct AttributionComponent{__T_vol, __T_vol_contrib, __T_pct_var, __T_mu_contrib, __T_corr, __T_mu_se} <: AbstractResultOne row of a factor attribution: the volatility, the volatility contribution, the variance share, the mean return contribution and the correlation of one component of the portfolio return.
A component is the systematic part, the idiosyncratic part, the unattributed remainder or the total. The four instances a FactorAttributionResult carries hold the same six numbers, so a reader that tabulates one tabulates all four. Every number is scaled to the ppy the Result carries.
Fields
vol: Volatility of the component's own return series. It isNaNon the predicted side of the unattributed remainder, which is a gap between two moments and carries no series.
vol_contrib: Contribution of the component to the portfolio volatility. The four components sum to the portfolio volatility exactly.
pct_var: Share of the portfolio variance the component explains. The four components sum to one exactly.
mu_contrib: Contribution of the component to the portfolio mean return. The four components sum to the portfolio mean return exactly.
corr: Correlation of the component's return series with the portfolio return series. It isNaNon the predicted side of the unattributed remainder.
mu_se: Standard error ofmu_contrib, ornothing. The realised side fills it underse = true, and it isnothingeverywhere else. UnderEntrywiseUnknownit isNaNwhen its sandwich gives a held Leverage-One Pair a coefficient that is not zero, because the variance of the pair is not identified.
Constructors
AttributionComponent(vol, vol_contrib, pct_var, mu_contrib, corr, mu_se) -> AttributionComponentArguments correspond to the struct's fields, in the order they are declared. The type is a part of a Result, so factor_attribution builds it and a caller reads it. It has no keyword constructor, and it validates nothing of its own.
Related
PortfolioOptimisers.AttributionBreakdown — Type
struct AttributionBreakdown{__T_labels, __T_exposure, __T_exposure_std, __T_vol, __T_corr, __T_vol_contrib, __T_pct_var, __T_mu, __T_mu_contrib, __T_mu_se} <: AbstractResultThe factor axis or the family axis of a factor attribution, one entry per row of the axis.
The factor axis carries no labels, because the factor names are carried input that the caller already holds. The family axis carries its own labels, because they are derived from the family labels of the block and exist nowhere else. Every number is scaled to the ppy the Result carries.
A family is a set of factors. The four additive fields exposure, vol_contrib, pct_var and mu_contrib carry the sum of the rows of the family. vol, corr and mu are nothing, because no single standalone volatility, correlation or mean return describes a set.
Fields
labels: Label of each row, ornothing. It isnothingon the factor axis and the sorted unique family labels on the family axis.
exposure: Portfolio exposure to each row. It isM' * won the predicted side, and the mean of the per-observation exposure on the realised side.
exposure_std: Standard deviation of the per-observation portfolio exposure to each row, ornothing. It isnothingon the predicted side, which reads one exposure and no history.
vol: Standalone volatility of each factor, ornothingon the family axis.
corr: Correlation of each factor with the portfolio return, ornothingon the family axis.
vol_contrib: Contribution of each row to the portfolio volatility. The rows sum to the systematic component.
pct_var: Share of the portfolio variance each row explains. The rows sum to the variance share of the systematic component.
mu: Mean return of each factor, ornothingon the family axis.
mu_contrib: Contribution of each row to the portfolio mean return. The rows sum to the mean return contribution of the systematic component.
mu_se: Standard error ofmu_contrib, one entry per row, ornothing. The realised side fills it underse = true, and a row of an observed factor, or of a family of observed factors, reportsNaN. UnderEntrywiseUnknowna row isNaNwhen its sandwich gives a held Leverage-One Pair a coefficient that is not zero: the level whose only member is the pair, and every factor that the zero-sum constraint of its family ties to that level.
Constructors
AttributionBreakdown(labels, exposure, exposure_std, vol, corr, vol_contrib, pct_var, mu, mu_contrib, mu_se) -> AttributionBreakdownArguments correspond to the struct's fields, in the order they are declared. The type is a part of a Result, so factor_attribution builds it and a caller reads it. It has no keyword constructor, and it validates nothing of its own.
Related
PortfolioOptimisers.AssetAttributionBreakdown — Type
struct AssetAttributionBreakdown{__T_weight, __T_weight_std, __T_sys_vol_contrib, __T_sys_mu_contrib, __T_idio_vol_contrib, __T_idio_mu_contrib, __T_vol, __T_corr, __T_vol_contrib, __T_pct_var, __T_mu, __T_mu_contrib} <: AbstractResultThe asset axis of a factor attribution, one entry per asset.
Each asset carries its weight, its standalone moments and its systematic, idiosyncratic and total contributions, so a reader sees which holding drove a factor row. Every number is scaled to the ppy the Result carries.
The axis decomposes the factor model, so the systematic rows sum to the systematic component, the idiosyncratic rows to the idiosyncratic component, and vol_contrib, which is the two together, to both of them. It does not reach the total. The difference is the unattributed remainder, which is a property of the portfolio and has no per-asset split.
Fields
weight: Weight of each asset. It is the weight vector on the predicted side and under a constant weight, and the mean of the weight history otherwise.
weight_std: Standard deviation of the weight of each asset, ornothing. It isnothingwherever the weights are constant, and a weight history fills it.
sys_vol_contrib: Contribution of each asset to the systematic part of the portfolio volatility. It isNaNat a held Leverage-One Pair underEntrywiseUnknown, because the split of the pair is not identified.
sys_mu_contrib: Contribution of each asset to the systematic part of the portfolio mean return.
idio_vol_contrib: Contribution of each asset to the idiosyncratic part of the portfolio volatility. It isNaNat a held Leverage-One Pair underEntrywiseUnknown, as the systematic part is.
idio_mu_contrib: Contribution of each asset to the idiosyncratic part of the portfolio mean return.
vol: Standalone volatility of each asset.
corr: Correlation of each asset with the portfolio return.
vol_contrib: Contribution of each asset to the portfolio volatility, the systematic and the idiosyncratic parts together. The rows sum to the systematic and idiosyncratic components together.
pct_var: Share of the portfolio variance each asset explains. The rows sum to the variance share of the systematic and idiosyncratic components together.
mu: Mean return of each asset.
mu_contrib: Contribution of each asset to the portfolio mean return, the systematic and the idiosyncratic parts together. The rows sum to the systematic and idiosyncratic components together.
Constructors
AssetAttributionBreakdown(weight, weight_std, sys_vol_contrib, sys_mu_contrib, idio_vol_contrib, idio_mu_contrib, vol, corr, vol_contrib, pct_var, mu, mu_contrib) -> AssetAttributionBreakdownAssetAttributionBreakdown(; weight, weight_std, sys_vol_contrib, sys_mu_contrib, idio_vol_contrib, idio_mu_contrib, vol, corr, vol_contrib, pct_var, mu, mu_contrib) -> AssetAttributionBreakdownArguments correspond to the struct's fields, in the order they are declared, and the keyword constructor takes each field by its name, with no default. The type is a part of a Result, so factor_attribution builds it and a caller reads it. The keyword form lets rebuild_struct replace a field, as attribution_leverage_nan does. It validates nothing of its own.
Related
PortfolioOptimisers.AssetFactorContribution — Type
struct AssetFactorContribution{__T_vol_contrib, __T_mu_contrib} <: AbstractResultThe asset-by-factor contributions of a factor attribution, two matrices of assets by factors.
The entry (i, k) is what asset i contributed through factor k. Summing a column over the assets gives the factor's row of the factor axis, and summing a row over the factors gives the asset's systematic row of the asset axis. Every number is scaled to the ppy the Result carries.
Fields
vol_contrib: Contribution to the portfolio volatility,assets × factors.
mu_contrib: Contribution to the portfolio mean return,assets × factors.
Constructors
AssetFactorContribution(vol_contrib, mu_contrib) -> AssetFactorContributionArguments correspond to the struct's fields, in the order they are declared. The type is a part of a Result, so factor_attribution builds it and a caller reads it. It has no keyword constructor, and it validates nothing of its own.
Related
PortfolioOptimisers.FactorAttributionResult — Type
struct FactorAttributionResult{__T_sys, __T_idio, __T_unattr, __T_total, __T_fbd, __T_fmbd, __T_abd, __T_afc, __T_realised, __T_ppy} <: AbstractResultDecomposes a portfolio's volatility and mean return over the factors, the factor families and the assets of a factor model.
FactorAttributionResult is what factor_attribution returns. It carries the four components and the factor axis. It also carries the family axis when the block names families, and the asset axis and the asset-by-factor matrices when the caller asks for assets. A caller can tabulate an attribution, plot it, compare it across runs or assert on it in a test.
Every field that an axis does not have is nothing, so a reader dispatches on ::Nothing rather than branching. fmbd is nothing when the block names no family, and abd and afc are nothing unless the caller passed assets = true.
Fields
sys: The systematic component, the part of the portfolio the factors explain.
idio: The idiosyncratic component, the part of the portfolio the assets' own residuals explain.
unattr: The unattributed remainder, the part of the portfolio the factor model does not explain.
total: The total, the portfolio's own volatility and mean return.
fbd: The factor axis, one row per raw factor.
fmbd: The family axis, one row per factor family, ornothingwhen the block names no family.
abd: The asset axis, ornothingunless the caller passedassets = true.
afc: The asset-by-factor contributions, ornothingunless the caller passedassets = true.
realised: Whether the attribution reads a realised history. A realised attribution reports a mean return, and a predicted one reports an expected return.
ppy: Periods per year the numbers are scaled to. Means and variances scale byppy, volatilities by its square root, and shares and correlations not at all.
Constructors
FactorAttributionResult(sys, idio, unattr, total, fbd, fmbd, abd, afc, realised, ppy) -> FactorAttributionResultArguments correspond to the struct's fields, in the order they are declared. The type is a Result, so factor_attribution builds it and a caller reads it. It has no keyword constructor, and it validates nothing of its own.
Related
PortfolioOptimisers.EntrywiseUnknown — Type
struct EntrywiseUnknown <: AbstractUnknownEntryRuleKeeps every entry the factor model states, and gives NaN for every number that reads an entry it does not state.
It is the default rule of factor_attribution. A held asset in the warm-up of its variance keeps its loadings, so the exposures, the systematic variance and the systematic mean are exact. Its idiosyncratic variance is unknown, so the portfolio volatility is unknown, and with it the idiosyncratic part, the total, the remainder and every number divided by the portfolio volatility. A held asset without loadings makes the exposures that read them unknown too. On the asset axis the standalone moments read the entries of the asset alone, and on the realised side its active pairs alone.
A portfolio that holds a Leverage-One Pair has an exact total and an unknown split. The volatility, the volatility contribution, the variance share and the correlation of the systematic and the idiosyncratic component are NaN, and so are those of the factor whose only member is the pair, and the systematic and idiosyncratic volatility contributions of the asset. The total, the remainder and every mean keep their values.
Related
PortfolioOptimisers.ZeroUnknown — Type
struct ZeroUnknown <: AbstractUnknownEntryRuleReads every entry the factor model does not state as zero, and an absent return as a zero return.
The rule is a stated assumption, not a fact of the model. An unknown idiosyncratic variance read as zero makes the portfolio variance a lower bound, so it understates the volatility and every share divided by it. A missing return read as zero dilutes the mean of an asset by the observations it was absent. A total moment the prior does not state reads the model, with every unknown entry of the model read as zero, so the gap of the remainder reads the stated entries alone.
A Leverage-One Pair keeps the split as fitted: its idiosyncratic variance is zero, so the attribution reports a held pair as wholly systematic. This understates the idiosyncratic part by the unknown own variance of the asset, and the factor whose only member is the pair carries that variance.
Related
PortfolioOptimisers.KindwiseUnknown — Type
struct KindwiseUnknown{__T_unstated, __T_leverage} <: AbstractUnknownEntryRuleApplies one rule to each kind of unknown entry.
EntrywiseUnknown and ZeroUnknown are presets that apply one rule to every kind. This rule holds one rule per kind, so a caller can read one kind as zero and keep the other unknown.
unstated: An entry the factor model does not state. It is the idiosyncratic variance of an asset in the warm-up of its variance, or the loadings of an asset that is not investable.leverage: The variance split of a Leverage-One Pair. The fit reproduced the return of the pair, so the data identify its total return and not the split between its systematic and its idiosyncratic part.EntrywiseUnknowngivesNaNfor every variance number that reads the split of a held pair.ZeroUnknownreads the split as fitted, the idiosyncratic variance of the pair as zero.
Fields
unstated: Rule for an entry the factor model does not state.
leverage: Rule for the variance split of a Leverage-One Pair.
Constructors
KindwiseUnknown(; unstated::AbstractUnknownEntryRule = EntrywiseUnknown(), leverage::AbstractUnknownEntryRule = EntrywiseUnknown()) -> KindwiseUnknownKeywords correspond to the struct's fields.
Validation
- Neither field is a
KindwiseUnknown, else anArgumentErroris raised. A field is the rule of one kind, and a rule per kind has no kind inside it to apply to.
Related
PortfolioOptimisers.factor_attribution — Function
factor_attribution(w::VecNum, pr::AbstractPriorResult; assets::Bool = false,
ppy::Number = 1, strict::Bool = false,
unknown::AbstractUnknownEntryRule = EntrywiseUnknown())
-> FactorAttributionResult
factor_attribution(res::OptimisationResult, pr::Option{<:Pr_RR} = nothing;
kwargs...) -> FactorAttributionResult
factor_attribution(w::VecNum, pr::AbstractPriorResult, X::MatNum,
fees::Option{<:Fees} = nothing; assets::Bool = false,
se::Bool = false, ppy::Number = 1, strict::Bool = false,
ddof::Integer = 1,
unknown::AbstractUnknownEntryRule = EntrywiseUnknown())
-> FactorAttributionResult
factor_attribution(w::VecNum, pr::AbstractPriorResult, rd::ReturnsResult,
fees::Option{<:Fees} = nothing; kwargs...) -> FactorAttributionResult
factor_attribution(res::OptimisationResult, pr::Option{<:Pr_RR}, rd::ReturnsResult;
kwargs...) -> FactorAttributionResult
factor_attribution(W::VecNum_MatNum, pr::AbstractPriorResult, ret::VecNum;
kwargs...) -> FactorAttributionResult
factor_attribution(pred::MultiPeriodPredictionResult, pr::AbstractPriorResult;
kwargs...) -> FactorAttributionResult
factor_attribution(ppred::PopulationPredictionResult, pr::AbstractPriorResult,
args...; kwargs...) -> Vector
factor_attribution(w::VecNum, B::MatNum, F::MatNum, d::VecNum_MatNum;
mu_f::Option{<:VecNum} = nothing, b::Option{<:VecNum} = nothing,
sigma::Option{<:MatNum} = nothing, mu::Option{<:VecNum} = nothing,
fam::Option{<:VecStr} = nothing,
lev::Option{<:AbstractVector{Bool}} = nothing, assets::Bool = false,
ppy::Number = 1, strict::Bool = false,
unknown::AbstractUnknownEntryRule = EntrywiseUnknown())
-> FactorAttributionResult
factor_attribution(W::VecNum_MatNum, B::MatNum_Arr3Num, f::MatNum, eps::MatNum,
ret::VecNum; lag::Integer = B isa Arr3Num ? 1 : 0,
trim::Bool = false, rw::Option{<:MatNum} = nothing,
vs::Option{<:MatNum} = nothing,
fcb::Option{<:FactorFamilyBasis} = nothing,
unseen::AbstractUnseenMemberRule = SolvedUnseenMember(),
observed::Integer = 0, fam::Option{<:VecStr} = nothing,
h1::Option{<:AbstractMatrix{Bool}} = nothing,
dc::Option{<:AbstractMatrix{Bool}} = nothing, assets::Bool = false,
se::Bool = false, ppy::Number = 1, ddof::Integer = 1,
unknown::AbstractUnknownEntryRule = EntrywiseUnknown())
-> FactorAttributionResult
factor_attribution(args..., window::Integer; step::Integer = 1,
kwargs...) -> Vector{<:FactorAttributionResult}Decompose a portfolio's volatility and mean return over the factors of a factor model.
The verb reads the weights and the factor model block, and returns one FactorAttributionResult. The predicted methods take no return series and decompose the moments the optimiser saw. The realised methods take one, and decompose the history the portfolio actually produced. Each realised method has a rolling twin that takes a positional window and returns one Result per window.
The bare arrays are the bottom level, and a prior method unpacks the prior result into them. A caller who holds a factor model as arrays, a vendor risk model for example, attributes with no fitted object. factor_attribution(w, pr) is the bare-array method on pr.rr.M, pr.fpr.sigma, the idiosyncratic covariance of the block, pr.fpr.mu, pr.rr.b, pr.sigma, pr.mu and the family labels of the block, so the two methods answer the same numbers. Without sigma and mu the model is the total, and the unattributed remainder is an exact zero. The realised bare-array method reads the histories on one observation axis, untrimmed, and aligns them itself: the returns of observation t pair with the exposures of observation t - lag. lag defaults to one for an exposure history. A static matrix has no time index, so it describes every observation, and a lag changes nothing for it unless trim = true cuts the first lag observations, for a common sample with a run on an exposure history. A prior method reads each of these arrays off the block.
A cross-validation is matched to the block row by row. The series of a walk-forward covers the test rows of its folds, and the prior result usually covers the whole sample, so the two do not end on the same row. Each fold records its rows, the positions idx of a PredictionResult and the timestamps of its rd.ts. A CrossSectionalFactorModel records the rows its fit covers, and a Regression records the observations of the prior result that FactorPrior fitted. A Pipeline fold records its positions only when every fitted step keeps the observations, see keeps_observations. The method matches the two by timestamp when both carry timestamps, and by position otherwise. The positions agree only when the prior read the returns data that the cross-validation split. The method aligns the exposures of the whole block before it cuts the block to the matched rows, so the first test row keeps the exposures of the row before it. The test rows before the first row the block decomposes, or after its last row, are left out. A block that records no rows, or a series that carries no key it shares, is lined up at the tail as a single series is. A CombinatorialCrossValidation or a MultipleRandomised produces a population of paths, and the method over a PopulationPredictionResult attributes each path in this way. A path of MultipleRandomised holds a subset of the assets, so it is attributed against a prior fitted on the same subset.
The predicted totals of a prior method come from the prior result, not from the model. pr.mu and pr.sigma are what the optimiser saw and what expected_return and expected_risk report, so they are the totals. A wrapping prior replaces them while it forwards the block unchanged, so the model no longer reproduces them, and the two gaps dot(w, pr.mu - M * fpr.mu - b) and dot(w, (pr.sigma - M * F * M' - D) * w) / sigma_P land in the unattributed remainder. The remainder is therefore present on the predicted side too, and it is at rounding level on a plain fit.
Every source of unexplained return lands in the remainder, and no guard reports it. On the realised side the identity per observation is portfolio return = systematic + idiosyncratic + unattributed, and the remainder holds the per-observation intercept share b_t * sum(w), the fees, the cash, the weight drift inside a period and the exposure lag. A large pct_var on the remainder means the model does not explain the portfolio, and the reader draws that conclusion.
A holding the prior could not estimate gets a warning, strict turns the warning into a refusal, and unknown states what the numbers do with it. A non-investable asset carries NaN at least on the diagonal of sigma, so its variance is unknown, and with it the variance of any portfolio that holds it. A portfolio that holds one takes the library's strictness policy through attribution_investable_diagnostic. Under strict = true an ArgumentError names the assets. Under the default strict = false a warning names them, and the rule unknown decides the numbers, entry by entry. The default EntrywiseUnknown keeps every entry the prior states, so the finite loadings of a held asset in the warm-up of its variance give exact exposures, an exact systematic variance and an exact systematic mean. Every number that reads an entry the prior does not state is NaN: the idiosyncratic part, the total, the remainder and every share divided by the portfolio volatility. ZeroUnknown reads every such entry as zero, which understates the portfolio variance, and on the realised side it reads an absent return as zero in the standalone moments of the asset axis.
A held pair with no return is a holiday when the asset is active, and an unknown otherwise. A returns result whose Asset Panel carries an active mask separates the two through attribution_net_returns. An active pair is a holiday, its price does not move, and it fills zero with no message. An inactive pair, after a delisting for example, takes the strictness policy: a warning names the observations and the assets and the pair contributes zero, or strict = true refuses. A bare matrix carries no mask, so every held pair with no return takes the policy. A pair the block cannot decompose, with no idiosyncratic return or no exposure, is zero in the systematic and the idiosyncratic series too, through attribution_zero_inactive, so a pair that adds nothing to the total adds nothing to any component. A weight history from a walk-forward holds exactly this shape whenever an asset delisted inside the history, which is why the default warns rather than refuses.
A held Leverage-One Pair has an exact total and an unknown split. The pair has a direction of the design of its own, for example the only member of a level of a one-hot family, so the fit reproduces its return and the factor return of that level holds the own return of the asset. Under the default the variance numbers that read the split are NaN: the volatility, the volatility contribution, the variance share and the correlation of the systematic and the idiosyncratic component, the same numbers of the factor whose only member is the pair, and the systematic and idiosyncratic volatility contributions of the asset. The total, the remainder and every mean keep their values, because the own return has an expected value of zero. The predicted side marks an asset that the fit marks at any row, because the factor covariance reads every row. The realised side marks a pair at each row the portfolio holds it, and a portfolio with a weight of zero at every marked pair is unchanged. Under se = true a standard error is NaN when its sandwich gives a marked pair a coefficient that is not zero, because the sandwich reads the variance of the pair. This holds for the systematic error of a holder, for the level whose only member is the pair, and for the factors that the zero-sum constraint of its family ties to the level. An error whose coefficient on the pair is round-off keeps its value. unknown = KindwiseUnknown(; leverage = ZeroUnknown()) reads the split as fitted, with no own variance, see KindwiseUnknown.
The weight spread of the realised asset axis divides by T - ddof. The exposure spread beside it divides by T - 1, and the exposure is linear in the weights, so the default ddof = 1 makes the two comparable. ddof = 0 gives the population spread. A constant weight states a spread of exactly zero.
The factor shares disagree with factor_risk_contribution, and the disagreement is one term. That verb computes (M' w)_k * (pinv(M) * grad)_k with grad a finite difference of any risk measure, so for the variance and sigma = M F M' + D it reads grad = (M F M' w + D w) / sigma_P and its factor share is (M' w)_k * (F M' w + pinv(M) D w)_k / sigma_P. This decomposition's factor share is the first term alone, (M' w)_k * (F M' w)_k / sigma_P, and it holds the second, the leakage (M' w)_k * (pinv(M) D w)_k / sigma_P, in the idiosyncratic component instead. The two therefore agree exactly when pinv(M) D w is zero. Neither is wrong. That verb is an Euler decomposition through a pseudo-inverse and holds for any risk measure, and this one is the analytic split of the model, specific to the variance.
Mathematical definition
The predicted side splits the portfolio variance and the expected portfolio return into three components, the systematic $S$, the idiosyncratic $I$ and the unattributed $U$:
\[\begin{align} \sigma_{P}^{2} &= \boldsymbol{w}^{\intercal} \mathbf{\Sigma} \boldsymbol{w}\,, \\ \sigma_{S}^{2} &= \boldsymbol{g}^{\intercal} \mathbf{F} \boldsymbol{g}\,, \\ \sigma_{I}^{2} &= \boldsymbol{w}^{\intercal} \mathbf{D} \boldsymbol{w}\,, \\ \sigma_{U}^{2} &= \sigma_{P}^{2} - \sigma_{S}^{2} - \sigma_{I}^{2}\,, \\ \mu_{P} &= \boldsymbol{w}^{\intercal} \boldsymbol{\mu}\,, \\ \mu_{S} &= \boldsymbol{g}^{\intercal} \boldsymbol{\mu}_{f}\,, \\ \mu_{I} &= \boldsymbol{w}^{\intercal} \boldsymbol{b}\,, \\ \mu_{U} &= \mu_{P} - \mu_{S} - \mu_{I}\,. \end{align}\]
Each component $C \in \{S, I, U\}$ and the total $P$ report a volatility contribution, a variance share and a mean return contribution. The systematic and the idiosyncratic component, and the total, also report a volatility and a correlation with the portfolio:
\[\begin{align} \mathrm{VC}_{C} &= \sqrt{p}\, \frac{\sigma_{C}^{2}}{\sigma_{P}}\,, \\ \mathrm{PV}_{C} &= \frac{\sigma_{C}^{2}}{\sigma_{P}^{2}}\,, \\ \mathrm{MC}_{C} &= p\, \mu_{C}\,, \\ \mathrm{vol}_{C} &= \sqrt{p}\, \sigma_{C}\,, \\ \rho_{C} &= \frac{\sigma_{C}}{\sigma_{P}}\,. \end{align}\]
The factor axis reports, for each factor $k$:
\[\begin{align} \mathrm{VC}_{k} &= \sqrt{p}\, \frac{g_{k} (\mathbf{F} \boldsymbol{g})_{k}}{\sigma_{P}}\,, \\ \mathrm{PV}_{k} &= \frac{g_{k} (\mathbf{F} \boldsymbol{g})_{k}}{\sigma_{P}^{2}}\,, \\ \mathrm{MC}_{k} &= p\, g_{k} \mu_{f,k}\,, \\ \mathrm{vol}_{k} &= \sqrt{p\, F_{kk}}\,, \\ \rho_{k} &= \frac{(\mathbf{F} \boldsymbol{g})_{k}}{\sqrt{F_{kk}}\, \sigma_{P}}\,. \end{align}\]
Where:
- $\mathbf{\Sigma}$: Covariance matrix of the prior result, $N \times N$, with every non-finite entry set to zero.
- $\boldsymbol{\mu}$: Expected returns of the prior result, $N \times 1$, with every non-finite entry set to zero.
- $\sigma_{C}^{2}$, $\mu_{C}$: Variance and expected return of component $C$. $\sigma_{U}^{2}$ is a difference of variances and can be negative.
- $\mu_{P}$: Expected portfolio return.
- $\mathrm{VC}$, $\mathrm{PV}$, $\mathrm{MC}$, $\mathrm{vol}$, $\rho$: Volatility contribution, variance share, mean return contribution, volatility and correlation with the portfolio.
- $F_{kk}$: Variance of factor $k$, the diagonal entry of $\mathbf{F}$.
- $\mu_{f,k}$: Expected return of factor $k$, entry $k$ of $\boldsymbol{\mu}_{f}$.
- $\sigma_{P}$: Predicted portfolio volatility, the square root of the quadratic form of the weights in the covariance of the prior result.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $\boldsymbol{g} = \mathbf{B}^{\intercal} \boldsymbol{w}$: Predicted factor exposure of the portfolio, $K \times 1$, with entry $g_{k}$ for factor $k$. The loadings and the weights do not move, so one exposure holds for every period.
- $\mathbf{B}$: Loadings the predicted attribution reads, $N \times K$, with entry $B_{ik}$ for asset $i$ and factor $k$. Every non-finite entry and every row of a non-investable asset is zero.
- $\mathbf{F}$: Factor covariance, $K \times K$, the covariance of the factor distribution that the prior result carries.
- $\boldsymbol{\mu}_{f}$: Expected factor returns, $K \times 1$, the mean of the factor distribution that the prior result carries.
- $\mathbf{D}$: Idiosyncratic covariance the predicted attribution reads, $N \times N$. It is diagonal when the block carries variances alone. Every non-finite entry, and every row and column of a non-investable asset, is zero.
- $\boldsymbol{b}$: Intercept the predicted attribution reads, $N \times 1$, the expected return of each asset that the factors do not explain. Every non-finite entry and the entry of every non-investable asset is zero.
- $p$: Periods per year.
- $N$: Number of assets.
- $K$: Number of factors.
The three components sum to the total: $\sum_{C} \mathrm{VC}_{C} = \sqrt{p}\, \sigma_{P}$, $\sum_{C} \mathrm{PV}_{C} = 1$ and $\sum_{C} \mathrm{MC}_{C} = p\, \mu_{P}$. The factor rows sum to the systematic component, because $\sum_{k} g_{k} (\mathbf{F} \boldsymbol{g})_{k} = \sigma_{S}^{2}$. The correlations are those of the model. Under $\mathbf{\Sigma} = \mathbf{B} \mathbf{F} \mathbf{B}^{\intercal} + \mathbf{D}$, with factors uncorrelated with the idiosyncratic returns, the covariance of the systematic return with the portfolio return is $\sigma_{S}^{2}$, and that of factor $k$ is $(\mathbf{F} \boldsymbol{g})_{k}$. The unattributed component carries no volatility and no correlation, because it is a gap between two moments and not a return series.
Algorithm
- Read the block and the factor distribution off
pr, and the five series off the block. - Take the totals from
pr.muandpr.sigmaon the predicted side, and from the return series on the realised side. - Decompose the systematic and the idiosyncratic parts, and put every gap into the remainder.
- Sum the factor rows by family when the block names families, and over the assets when
assets = true. - Scale by
ppy: means and variances byppy, volatilities by its square root.
The method on a net series ret is the canonical form of the realised side. It reports a holding in a non-investable asset through attribution_investable_diagnostic, and reads the block into bare arrays with attribution_block_arrays. The four methods on asset returns, a matrix X or a returns result rd, each with or without a window, check the weights through assert_attribution_assets, form the net series with attribution_net_returns, and call the method on ret. The method on rd passes the active mask of its Asset Panel through panel_active_cells, and the method on X passes none. The method on pred holds a copy of the steps of the method on ret, because it also passes the row key of each observation, and the copies agree.
Arguments
w: Portfolio weights.W: Portfolio weight history,observations × assets, or the constant weights.pr: Prior result carrying the factor model block.res: Optimisation result whose weights, prior and fees the verb reads throughresult_investable_view. The result's own prior is on the universe the fit solved, and its weights are on the caller's, so the two meet on the result's investable universe, a caller'sprorrdis viewed at the same mask, and the attribution's asset axis spans the investable assets alone.X: Asset returns,observations × assets.rd: Returns result carrying the asset returns.ret: Net portfolio return series.pred: Multi-period prediction result whose folds give the weight history, the return series and the row key of each observation.ppred: Population prediction result, whose paths are each attributed as apred.args: The positionalwindowof a rolling attribution, or nothing.B: Loadings,assets × factors, or on the realised side the exposure history,assets × factors × observations. ANaNrow marks an asset the model does not state.F: Factor covariance,factors × factors.d: Idiosyncratic variances,assets, or the idiosyncratic covariance,assets × assets.mu_f: Expected factor returns, ornothingfor zeros.b: Factor-orthogonal expected return of each asset, ornothingfor zeros.sigma: Asset covariance the total variance reads, ornothingfor the model's own.mu: Expected asset returns the total mean reads, ornothingfor the model's own.fam: Family label of each factor, ornothingfor no family axis.lev: Assets whose variance split the model does not identify, a Leverage-One Pair at one row or more, ornothingfor none. A prior method reads it off theh1field of a cross-sectional fit, throughattribution_marked_assets.h1: Leverage-one mask,observations × assets, on the observations ofeps, ornothingfor none.dc: Dropped-column mask of the fit,observations × estimated factors, on the observations ofepsand on the axis the regression was written in, ornothingfor none. A factor it marks took a return of zero by the rule ofDependentColumnDrop, sose = truegives it no estimation error, and reads the other factors on the columns that the fit kept. A prior method reads it off thedcfield of a cross-sectional fit.f: Factor returns,observations × factors.eps: Idiosyncratic returns,observations × assets,NaNat a pair the model does not decompose.lag: Number of observations by which the exposures lag the returns.trim: Whether a static loadings matrix drops the firstlagobservations, as an exposure history with the same lag does. A static matrix reads every observation otherwise.rw: Regression weight history,observations × assets, whichse = truereads, ornothing.vs: Idiosyncratic variance history,observations × assets, whichse = truereads, ornothing.fcb: Family re-basis the regression was written in, ornothing.unseen: The Unseen Member rule the regression ran under. The default changes no design, so the standard errors read the reduced exposures themselves.observed: Number of observed factors, the last columns off. The fit takes their returns as given, so they leave the standard errors.fees: Fees the net series is formed against.window: Size of the rolling window, in observations.step: Stride between two consecutive windows.assets: Whether to fill the asset axis and the asset-by-factor matrices.se: Whether to fill the standard errors of the mean return contributions.ppy: Periods per year the numbers are scaled to.strict: Whether a holding in a non-investable asset, or a non-finite return at an inactive held observation, raises anArgumentErrorrather than a warning.ddof: Degrees-of-freedom correction, an integer that the library subtracts from the number of observations itself. It sets the divisorT - ddofof the weight spread of the realised asset axis.unknown: Rule for an entry the factor model does not state, and for the variance split of a Leverage-One Pair, a subtype ofAbstractUnknownEntryRule.EntrywiseUnknowngivesNaNfor every number that reads one,ZeroUnknownreads it as zero, andKindwiseUnknownapplies one rule to each kind.
Validation
prcarries a factor model block, else theIsNothingErrorofassert_prior_regressionis raised.- The factor covariance and the expected factor returns are finite, else an
IsNonFiniteErroris raised. fandepscarry the same observations, an exposure history carries them too,retcarries at least as many, and0 <= lagis below their number, else aDimensionMismatchor aDomainErroris raised. Apredwhose folds share a row key with the block needs no length: at least one test row is a row the block decomposes, and no test row between two of them is missing from the block, else aDimensionMismatchor anArgumentErroris raised.ppy > 0, else aDomainErroris raised.- The weights hold one entry for each asset of
pr, else aDimensionMismatchis raised. - Every weight at a non-investable asset is zero, else a warning names the assets, or an
ArgumentErrornames them understrict. - Every held
(observation, asset)pair ofXoutside the active mask ofrdis finite, else a warning names the pairs, or anArgumentErrornames them understrict. A bareXcarries no mask, so the rule reads every held pair. retis finite throughout, else anIsNonFiniteErrornaming the observations is raised.- The block carries the fields the chosen decomposition reads, else an
IsNothingErrornames the field. - The portfolio variance is positive or
NaNon the predicted side, and the portfolio volatility is positive on the realised side, else aDomainErroris raised. The predicted variance isNaNwhen it reads an entry the prior does not state. 0 <= ddof < Tover the observations of the realised series or the window, else aDomainErroris raised.2 <= window <= T, else aDomainErroris raised. A window of one observation has no sample volatility.step >= 1, else aDomainErroris raised.se = trueneeds the regression weight history and the idiosyncratic variance history, else anIsNothingErrornames the field.
Returns
fa::FactorAttributionResult: The attribution, or a vector of them from a rolling method. A population gives one entry per path.
Related