Factor attribution (a)

PortfolioOptimisers.AbstractUnknownEntryRule — Type
abstract type AbstractUnknownEntryRule <: AbstractAlgorithm

Abstract 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.

  • EntrywiseUnknown keeps every entry the model states, and gives NaN for every number that reads an entry it does not state. It is the default.
  • ZeroUnknown reads every entry the model does not state as zero, and an absent return as a zero return.
  • KindwiseUnknown applies 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: true at every asset whose unknown entries stay NaN. 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 of A.

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 of act.

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, or nothing when the model marks no pair.
  • h1: The leverage-one mask, observations × assets, or nothing when 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 reads B[t, :, :], and it must now read B[:, :, t], or the slice that attribution_slice(B, t) gives.

Returns

  • lv::Option{<:LeverageSplitResult}: nothing when the rule marks nothing. Otherwise a LeverageSplitResult with the asset mask assets and the factor mask factors, whose constructor refuses marks that name no asset. attribution_leverage_nan puts NaN in 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, or nothing when the model marks no pair.
  • reg: Whether each pair is in the regression, observations × assets.
  • ses: The standard errors, an AttributionErrorsResult with the fields sys, factor and family.
  • pass: The reduction of attribution_error_pass, a function of a matrix of variances, observations × assets, which returns an AttributionErrorsResult.

Returns

  • ses::AttributionErrorsResult: The standard errors after the rule. A method that changes an error builds a new AttributionErrorsResult, whose constructor checks that the three answers agree on what they state.

Related

source
PortfolioOptimisers.AttributionComponent — Type
struct AttributionComponent{__T_vol, __T_vol_contrib, __T_pct_var, __T_mu_contrib, __T_corr, __T_mu_se} <: AbstractResult

One 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 is NaN on 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 is NaN on the predicted side of the unattributed remainder.
  • mu_se: Standard error of mu_contrib, or nothing. The realised side fills it under se = true, and it is nothing everywhere else. Under EntrywiseUnknown it is NaN when 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)    -> AttributionComponent

Arguments 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

source
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} <: AbstractResult

The 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, or nothing. It is nothing on the factor axis and the sorted unique family labels on the family axis.
  • exposure: Portfolio exposure to each row. It is M' * w on 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, or nothing. It is nothing on the predicted side, which reads one exposure and no history.
  • vol: Standalone volatility of each factor, or nothing on the family axis.
  • corr: Correlation of each factor with the portfolio return, or nothing on 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, or nothing on 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 of mu_contrib, one entry per row, or nothing. The realised side fills it under se = true, and a row of an observed factor, or of a family of observed factors, reports NaN. Under EntrywiseUnknown a row is NaN when 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) -> AttributionBreakdown

Arguments 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

source
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} <: AbstractResult

The 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, or nothing. It is nothing wherever 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 is NaN at a held Leverage-One Pair under EntrywiseUnknown, 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 is NaN at a held Leverage-One Pair under EntrywiseUnknown, 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) -> AssetAttributionBreakdown

Arguments 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

source
PortfolioOptimisers.AssetFactorContribution — Type
struct AssetFactorContribution{__T_vol_contrib, __T_mu_contrib} <: AbstractResult

The 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) -> AssetFactorContribution

Arguments 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

source
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} <: AbstractResult

Decomposes 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, or nothing when the block names no family.
  • abd: The asset axis, or nothing unless the caller passed assets = true.
  • afc: The asset-by-factor contributions, or nothing unless the caller passed assets = 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 by ppy, volatilities by its square root, and shares and correlations not at all.

Constructors

FactorAttributionResult(sys, idio, unattr, total, fbd, fmbd, abd, afc, realised, ppy)    -> FactorAttributionResult

Arguments 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

source
PortfolioOptimisers.EntrywiseUnknown — Type
struct EntrywiseUnknown <: AbstractUnknownEntryRule

Keeps 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

source
PortfolioOptimisers.ZeroUnknown — Type
struct ZeroUnknown <: AbstractUnknownEntryRule

Reads 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

source
PortfolioOptimisers.KindwiseUnknown — Type
struct KindwiseUnknown{__T_unstated, __T_leverage} <: AbstractUnknownEntryRule

Applies 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. EntrywiseUnknown gives NaN for every variance number that reads the split of a held pair. ZeroUnknown reads 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()) -> KindwiseUnknown

Keywords correspond to the struct's fields.

Validation

  • Neither field is a KindwiseUnknown, else an ArgumentError is raised. A field is the rule of one kind, and a rule per kind has no kind inside it to apply to.

Related

source
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

  1. Read the block and the factor distribution off pr, and the five series off the block.
  2. Take the totals from pr.mu and pr.sigma on the predicted side, and from the return series on the realised side.
  3. Decompose the systematic and the idiosyncratic parts, and put every gap into the remainder.
  4. Sum the factor rows by family when the block names families, and over the assets when assets = true.
  5. Scale by ppy: means and variances by ppy, 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 through result_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's pr or rd is 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 a pred.
  • args: The positional window of a rolling attribution, or nothing.
  • B: Loadings, assets × factors, or on the realised side the exposure history, assets × factors × observations. A NaN row 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, or nothing for zeros.
  • b: Factor-orthogonal expected return of each asset, or nothing for zeros.
  • sigma: Asset covariance the total variance reads, or nothing for the model's own.
  • mu: Expected asset returns the total mean reads, or nothing for the model's own.
  • fam: Family label of each factor, or nothing for no family axis.
  • lev: Assets whose variance split the model does not identify, a Leverage-One Pair at one row or more, or nothing for none. A prior method reads it off the h1 field of a cross-sectional fit, through attribution_marked_assets.
  • h1: Leverage-one mask, observations × assets, on the observations of eps, or nothing for none.
  • dc: Dropped-column mask of the fit, observations × estimated factors, on the observations of eps and on the axis the regression was written in, or nothing for none. A factor it marks took a return of zero by the rule of DependentColumnDrop, so se = true gives it no estimation error, and reads the other factors on the columns that the fit kept. A prior method reads it off the dc field of a cross-sectional fit.
  • f: Factor returns, observations × factors.
  • eps: Idiosyncratic returns, observations × assets, NaN at 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 first lag observations, as an exposure history with the same lag does. A static matrix reads every observation otherwise.
  • rw: Regression weight history, observations × assets, which se = true reads, or nothing.
  • vs: Idiosyncratic variance history, observations × assets, which se = true reads, or nothing.
  • fcb: Family re-basis the regression was written in, or nothing.
  • 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 of f. 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 an ArgumentError rather than a warning.
  • ddof: Degrees-of-freedom correction, an integer that the library subtracts from the number of observations itself. It sets the divisor T - ddof of 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 of AbstractUnknownEntryRule. EntrywiseUnknown gives NaN for every number that reads one, ZeroUnknown reads it as zero, and KindwiseUnknown applies one rule to each kind.

Validation

  • pr carries a factor model block, else the IsNothingError of assert_prior_regression is raised.
  • The factor covariance and the expected factor returns are finite, else an IsNonFiniteError is raised.
  • f and eps carry the same observations, an exposure history carries them too, ret carries at least as many, and 0 <= lag is below their number, else a DimensionMismatch or a DomainError is raised. A pred whose 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 a DimensionMismatch or an ArgumentError is raised.
  • ppy > 0, else a DomainError is raised.
  • The weights hold one entry for each asset of pr, else a DimensionMismatch is raised.
  • Every weight at a non-investable asset is zero, else a warning names the assets, or an ArgumentError names them under strict.
  • Every held (observation, asset) pair of X outside the active mask of rd is finite, else a warning names the pairs, or an ArgumentError names them under strict. A bare X carries no mask, so the rule reads every held pair.
  • ret is finite throughout, else an IsNonFiniteError naming the observations is raised.
  • The block carries the fields the chosen decomposition reads, else an IsNothingError names the field.
  • The portfolio variance is positive or NaN on the predicted side, and the portfolio volatility is positive on the realised side, else a DomainError is raised. The predicted variance is NaN when it reads an entry the prior does not state.
  • 0 <= ddof < T over the observations of the realised series or the window, else a DomainError is raised.
  • 2 <= window <= T, else a DomainError is raised. A window of one observation has no sample volatility.
  • step >= 1, else a DomainError is raised.
  • se = true needs the regression weight history and the idiosyncratic variance history, else an IsNothingError names the field.

Returns

  • fa::FactorAttributionResult: The attribution, or a vector of them from a rolling method. A population gives one entry per path.

Related

source