Factor attribution (a): private API
PortfolioOptimisers.attribution_idiosyncratic_covariance — Function
attribution_idiosyncratic_covariance(rr::AbstractLoadingsRegressionResult)
attribution_idiosyncratic_covariance(rr::CrossSectionalFactorModel)
attribution_idiosyncratic_covariance(rr::Regression)Return the idiosyncratic covariance a factor attribution adds to the systematic block.
It is one of the five reads that factor_attribution takes off a loadings result. The root refuses, so the verb names a loadings result that carries no idiosyncratic block rather than attributing zero to it.
A Regression answers its own esigma, which FactorPrior fills under rsd = true. Under rsd = false the field is nothing and the read answers a vector of zeros rather than refusing, because the covariance of the prior result carries no residual block either. The predicted idiosyncratic component is then zero, the systematic component reaches the total on its own, and the remainder stays at rounding level. A realised attribution is unaffected, because it measures the idiosyncratic series from the returns rather than from this field.
Arguments
rr: A loadings regression result.
Validation
- The root method always raises an
ArgumentErrornaming the type. - A
CrossSectionalFactorModelwhoseesigmaisnothingraises anIsNothingError.
Returns
esigma::VecNum_MatNum: The idiosyncratic variances, or the idiosyncratic covariance. ARegressionthat carries none answers a vector of zeros.
Related
PortfolioOptimisers.attribution_idiosyncratic_returns — Function
attribution_idiosyncratic_returns(rr::AbstractLoadingsRegressionResult,
pr::AbstractPriorResult)
attribution_idiosyncratic_returns(rr::CrossSectionalFactorModel,
pr::AbstractPriorResult)
attribution_idiosyncratic_returns(rr::Regression, pr::AbstractPriorResult)Return the idiosyncratic return series a realised factor attribution weights by the portfolio.
It is one of the five reads that factor_attribution takes off a loadings result. The root refuses, so the verb names a loadings result that keeps no residual history rather than attributing zero to it.
The read takes the prior result pr beside the block, because a block that stores no series recovers it from the prior result that carries it. A CrossSectionalFactorModel keeps its own residuals and ignores pr. A Regression keeps none, so the series is original_returns(pr) - pr.X, the difference between the returns the prior was fitted on and the reconstruction F * M' .+ b' that pr holds. A wrapping prior that replaces X moves this series, and the difference lands in the unattributed remainder.
Arguments
rr: A loadings regression result.pr: The prior result that carries the block.
Validation
- The root method always raises an
ArgumentErrornaming the type. - A
CrossSectionalFactorModelwhosecsrisnothingraises anIsNothingError. - A
Regressionon a prior result whoseo_Xisnothingraises anIsNothingError, because such a prior result reconstructed nothing and the difference is zero at every observation.
Returns
eps::MatNum: The idiosyncratic returns,observations × assets.
Related
PortfolioOptimisers.attribution_factor_returns — Function
attribution_factor_returns(rr::AbstractLoadingsRegressionResult,
pr::AbstractPriorResult)
attribution_factor_returns(rr::CrossSectionalFactorModel, pr::AbstractPriorResult)
attribution_factor_returns(rr::Regression, pr::AbstractPriorResult)Return the factor return series a realised factor attribution multiplies by the exposures.
It is one of the five reads that factor_attribution takes off a loadings result. The series is on the raw factor axis, which is the axis the loadings name, so a family re-basis does not move it.
The read takes the prior result pr beside the block, as attribution_idiosyncratic_returns does and for the same reason. A CrossSectionalFactorModel fits the factor returns itself, and reads them off its own fit when no family is constrained, with its observed factor returns after them through cross_sectional_factor_returns. A constrained Factor Family makes the fit solve in a reduced basis, one column short per constrained family, so a re-based block reads its own fr instead, which holds the same coefficients already expanded onto the raw axis over every row of the fit. It does not read pr.fpr.X, because a Scenario Cap keeps the last rows of that field alone, and the other reads of the block cover every row. A Regression regresses on factors the caller supplied, so the series is pr.fpr.X, the scenarios of the nested factor-axis prior. That field needs no refusal of its own, because LowOrderPrior admits rr and fpr only together, so a prior result that answers a loadings result answers a factor-axis prior beside it.
Arguments
rr: A loadings regression result.pr: The prior result that carries the block.
Validation
- The root method always raises an
ArgumentErrornaming the type. - A
CrossSectionalFactorModelwhosecsrisnothingraises anIsNothingError, with or without a family re-basis. - A re-based
CrossSectionalFactorModelwhosefrisnothingraises anIsNothingError. A block the prior fits carries it.
Returns
f::MatNum: The factor returns,observations × factors.
Related
PortfolioOptimisers.attribution_observed_count — Function
attribution_observed_count(rr::AbstractLoadingsRegressionResult) -> Int
attribution_observed_count(rr::CrossSectionalFactorModel) -> IntReturn the number of observed factors of a loadings result, which are the last factors of its axis.
A Regression regresses on factor returns the caller supplied and estimates the loadings, so it has no observed factor in this sense. A CrossSectionalFactorModel states its observed factors through fx, and they are the trailing columns of both of its axes.
Arguments
rr: A loadings regression result.
Returns
no::Int: The number of observed factors.
Related
PortfolioOptimisers.attribution_exposures — Function
attribution_exposures(rr::AbstractLoadingsRegressionResult)
attribution_exposures(rr::CrossSectionalFactorModel)
attribution_exposures(rr::Regression)Return the exposure history a realised factor attribution reads, one slice per observation.
It is one of the five reads that factor_attribution takes off a loadings result. A block whose exposures do not move answers its loadings matrix, and the attribution then reads one static slice.
A Regression fits one loadings matrix over the whole sample, so it always answers that matrix and every observation reads the same slice.
Arguments
rr: A loadings regression result.
Validation
- The root method always raises an
ArgumentErrornaming the type.
Returns
Ms::Union{MatNum, Arr3Num}: The exposure historyassets × factors × observations, or the static loadingsassets × factors.
Related
PortfolioOptimisers.attribution_lag — Function
attribution_lag(rr::AbstractLoadingsRegressionResult)
attribution_lag(rr::CrossSectionalFactorModel)
attribution_lag(rr::Regression)Return the number of observations by which the exposures lag the returns.
It is one of the five reads that factor_attribution takes off a loadings result. The attribution keeps the exposures of observation t - lag with the returns of observation t, so a block that states no lag answers zero and the two axes line up as they stand.
A Regression fits the returns of an observation on the factor returns of the same observation, so its lag is zero.
Arguments
rr: A loadings regression result.
Validation
- The root method always raises an
ArgumentErrornaming the type.
Returns
lag::Int: The exposure lag, as a count.
Related
PortfolioOptimisers.AttributionRowKey — Type
struct AttributionRowKey{__T_idx, __T_ts}The key that names the observation of each row of a factor model block or of a return series: its position and its timestamp.
This type is an implementation detail and is not intended for direct use. attribution_row_key makes the key of a block, and attribution_series_key makes the key of the series of a cross-validation. attribution_key_pair reads both.
Fields
idx:idx: The position of each row in the returns data that it was read from, ornothing.
ts:ts: The timestamp of each row, ornothing.
Related
PortfolioOptimisers.attribution_row_key — Function
attribution_row_key(rr::AbstractLoadingsRegressionResult)
attribution_row_key(rr::CrossSectionalFactorModel)
attribution_row_key(rr::Regression)Return the key that names the observation of each row of a factor model block.
A realised factor_attribution of a cross-validation reads it to find the block rows of each fold. The key has two parts: idx, the position of each block row in the returns data that the prior read, and ts, the timestamp of each block row. A CrossSectionalFactorModel records both when its prior fits it. A Regression records both when FactorPrior fits it, and its rows are the observations of the factor returns and the reconstruction of the prior result. A block of another type records neither, so it answers nothing for each, and the attribution lines the series up with the block at their tail.
Arguments
rr: A loadings regression result.
Returns
key::AttributionRowKey: The positionidxof each block row, ornothing, and the timestamptsof each block row, ornothing.
Related
PortfolioOptimisers.attribution_families — Function
attribution_families(rr::AbstractLoadingsRegressionResult)
attribution_families(rr::CrossSectionalFactorModel)Return the family label of each raw factor, or nothing when the block names none.
The family axis of a FactorAttributionResult exists exactly when this read answers a vector, so a block type that carries no family concept answers nothing through the root and needs no method of its own.
Arguments
rr: A loadings regression result.
Returns
fam::Option{<:VecStr}: The family label of each raw factor, ornothing.
Related
PortfolioOptimisers.attribution_family_basis — Function
attribution_family_basis(rr::AbstractLoadingsRegressionResult)
attribution_family_basis(rr::CrossSectionalFactorModel)Return the family re-basis the block's fit was written in, or nothing.
A realised attribution computes its standard errors in the reduced full-rank basis and maps them back onto the raw axis, because a constrained family makes the raw Gram matrix singular. A block type that constrains no family answers nothing through the root, and the sandwich then runs on the raw axis.
Arguments
rr: A loadings regression result.
Returns
fcb::Option{<:AbstractFactorFamilyBasis}: The family re-basis, ornothing.
Related
PortfolioOptimisers.attribution_unseen_rule — Function
attribution_unseen_rule(rr::AbstractLoadingsRegressionResult)
attribution_unseen_rule(rr::CrossSectionalFactorModel)Return the Unseen Member rule the block's fit regressed under.
The standard errors of a realised attribution rebuild the design of each observation, and at an observation with an Unseen Member the fit regressed on a changed design. A block type that constrains no family has no Unseen Member, so the root answers SolvedUnseenMember, which changes no design.
Arguments
rr: A loadings regression result.
Returns
rule::AbstractUnseenMemberRule: The Unseen Member rule.
Related
PortfolioOptimisers.attribution_regression_weights — Function
attribution_regression_weights(rr::AbstractLoadingsRegressionResult)
attribution_regression_weights(rr::CrossSectionalFactorModel)Return the regression weight history the sandwich covariance reads, or nothing.
The standard errors of a realised attribution need the weight each asset carried in the fit of each observation. A block type that records none answers nothing through the root, and se = true then refuses.
Arguments
rr: A loadings regression result.
Returns
rw::Option{<:MatNum}: The regression weight historyobservations × assets, ornothing.
Related
PortfolioOptimisers.attribution_idiosyncratic_variances — Function
attribution_idiosyncratic_variances(rr::AbstractLoadingsRegressionResult)
attribution_idiosyncratic_variances(rr::CrossSectionalFactorModel)Return the idiosyncratic variance history the sandwich covariance reads, or nothing.
The standard errors of a realised attribution need the idiosyncratic variance of each asset at each observation. A block type that records none answers nothing through the root, and se = true then refuses.
Arguments
rr: A loadings regression result.
Returns
vs::Option{<:MatNum}: The idiosyncratic variance historyobservations × assets, ornothing.
Related
PortfolioOptimisers.assert_attribution_field — Function
assert_attribution_field(x::Nothing, sym::Symbol)
assert_attribution_field(x, sym::Symbol)Return an optional field of a factor model block, or raise naming it.
The five reads a factor attribution takes are optional fields of the block, so one refusal names the field a caller must keep rather than letting a nothing reach the arithmetic.
Arguments
x: The field's value.sym: The field's name.
Validation
xis notnothing, else anIsNothingErrornaming the field is raised.
Returns
x: The field's value, unchanged.
Related
PortfolioOptimisers.assert_attribution_prior_field — Function
assert_attribution_prior_field(x::Nothing, sym::Symbol)
assert_attribution_prior_field(x, sym::Symbol)Return an optional field of the prior result that carries a factor model block, or raise naming it.
It is the sibling of assert_attribution_field, and it names the prior result rather than the block. A Regression stores no return series of its own and reads the two series off the prior result, so a nothing there is a missing input of the attribution and not a missing field of the block.
Arguments
x: The field's value.sym: The field's name.
Validation
xis notnothing, else anIsNothingErrornaming the field is raised.
Returns
x: The field's value, unchanged.
Related
PortfolioOptimisers.attribution_finite — Function
attribution_finite(A::AbstractArray)
attribution_finite(A::Nothing)Return an array with every non-finite entry replaced by zero, or the array itself.
A point-in-time panel carries NaN at every cell of an inactive asset, and a Prior Estimator that fits on the coverage universe carries NaN in the rows of an asset it could not estimate. 0 * NaN is NaN, so the entry would make every sum NaN whether the asset is held or not. The verb replaces the entries once rather than guarding each of the sums. The callers apply it where an unknown entry reads as zero: the factor returns and the regression weights of the realised side, the asset returns of a pair the policy of attribution_net_returns fills, and every entry under ZeroUnknown.
The verb returns an array that is finite throughout as it is, without a copy. That is the case when every asset is investable. It is a repair, so it owns the identity on the form that needs no repair: an optional history that a block does not carry, such as the regression weights, is nothing, and the method on Nothing returns nothing.
Mathematical definition
\[\begin{align} \tilde{a}_{j} &= \begin{cases} a_{j} & \text{if } a_{j} \text{ is finite}\,, \\ 0 & \text{otherwise}\,. \end{cases} \end{align}\]
Where:
- $a_{j}$: Entry $j$ of the array, in any order of its indices.
- $\tilde{a}_{j}$: Entry $j$ of the returned array.
Arguments
A: The array, ornothing.
Returns
A::Option{<:AbstractArray}: The array, with every non-finite entry replaced by zero, ornothing.
Related
PortfolioOptimisers.attribution_investable_diagnostic — Function
attribution_investable_diagnostic(w::VecNum_MatNum, pr::AbstractPriorResult,
strict::Bool)
attribution_investable_diagnostic(w::VecNum_MatNum, imsk::Option{BitVector},
strict::Bool, note::AbstractString)Report a portfolio that holds an asset the prior could not estimate.
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 holding in it takes the library's strictness policy through strict_diagnostic. A warning names the assets and the decomposition proceeds, or, under strict, an ArgumentError names them.
The warning states what the decomposition does with the holding, in the sentence note. On the predicted side the sentence comes from the rule for an unknown entry, through attribution_unknown_note. On the realised side the first method states it: a pair the block does not decompose adds nothing to any component, so the return the holding earned there lands in the unattributed remainder, which is where the reader looks for what the model does not explain.
A walk-forward produces a weight history that holds a non-investable asset. A prior fit on the whole history marks every asset that delisted inside it non-investable, and an early fold held that asset while it was listed. That is why the default is to warn.
Algorithm
- Refuse weights that do not hold one entry for each asset of
prthroughassert_attribution_assets, so the mask is never read at an index it lacks. - Read the investable mask
imskoffpr. An absent mask means that every asset is investable, and the verb returns. - Find the non-investable assets that carry a non-zero weight, in the vector or at any observation of the history, giving
held. - When
heldis not empty, warn naming it and statingnote, or raise understrict, throughstrict_diagnostic.
Arguments
w: The constant weights, or the weight history.pr: The prior result.imsk: The assets the model states, ornothingwhen it states every asset.strict: Whether a held non-investable asset raises rather than warns.note: The sentence that states what the decomposition does with the holding.
Validation
wholds one entry for each asset ofpr, else aDimensionMismatchis raised.- Every weight at a non-investable asset is zero, else a warning naming the assets is emitted, or an
ArgumentErrornaming them is raised understrict.
Returns
- Nothing is returned.
Related
PortfolioOptimisers.assert_attribution_assets — Function
assert_attribution_assets(W::VecNum_MatNum, N::Integer)Refuse weights that do not hold one entry for each asset of the factor model.
The decomposition reads the weight of asset i against row i of the loadings, so the weights and the model must describe one universe. A path of MultipleRandomised holds a subset of the assets, so its weights describe fewer assets than a prior fitted on the whole universe. The check runs before any read of the weights, so the refusal names the two counts rather than an index the arithmetic would fail on.
Arguments
W: The constant weights, or the weight history,observations × assets.N: The number of assets of the factor model.
Validation
- The weights hold
Nassets, else aDimensionMismatchnaming both counts is raised.
Returns
- Nothing is returned.
Related
PortfolioOptimisers.attribution_prior_block — Function
attribution_prior_block(pr::AbstractPriorResult)Return the factor model block and the factor distribution a factor attribution decomposes.
A prior result carries the loadings in rr and the factor distribution in fpr, and its constructor keeps the two together, so one check establishes the whole block. Every wrapping prior forwards both unchanged while it replaces mu and sigma, which is why the totals come from the prior result and the gaps land in the unattributed remainder.
Arguments
pr: A prior result.
Validation
pr.rris notnothing, else theIsNothingErrorofassert_prior_regressionis raised.
Returns
The tuple (rr, fpr):
rr::AbstractLoadingsRegressionResult: The factor model block.fpr::LowOrderPrior: The factor distribution.
Related
PortfolioOptimisers.AnnualisationScale — Type
struct AnnualisationScale{__T_s1, __T_s2}The two scale factors that an annualisation applies, one for a mean or a variance and one for a volatility.
This type is an implementation detail and is not intended for direct use. attribution_scale makes it, and the predicted and the realised attribution read it.
Fields
s1:s1: The factor a mean or a variance takes.
s2:s2: The factor a volatility takes.
Related
PortfolioOptimisers.attribution_scale — Function
attribution_scale(ppy::Number, x::Number = ppy)Return the two scale factors an annualisation applies.
Means and variances scale by ppy, and volatilities by its square root. Shares and correlations are ratios of two quantities that scale alike, so they are not scaled at all.
The square root takes the type of ppy promoted with the type of x, a value of the data the factors scale. The default ppy = 1 is an Int, and its bare square root is a Float64, which would widen every volatility of Float32 data while the correlations beside them stayed Float32.
Mathematical definition
\[\begin{align} s_{1} &= p\,, \\ s_{2} &= \sqrt{p}\,. \end{align}\]
Where:
- $s_{1}$: Scale factor of a mean or a variance.
- $s_{2}$: Scale factor of a volatility.
- $p$: Periods per year.
Arguments
ppy: Periods per year the numbers are scaled to.x: A value of the data the factors scale. Only its type is read.
Validation
ppy > 0, else aDomainErroris raised.
Returns
sc::AnnualisationScale: The factors1a mean or a variance takes,ppyitself, and the factors2a volatility takes, in the type ofppy * one(x)or wider.
Related
PortfolioOptimisers.attribution_idiosyncratic_matrix — Function
attribution_idiosyncratic_matrix(esigma::VecNum)
attribution_idiosyncratic_matrix(esigma::MatNum)Return the idiosyncratic covariance as a matrix the quadratic form reads.
The idiosyncratic block takes two shapes, a vector of variances and a full covariance. The method dispatches on the shape, so no caller tests it.
Mathematical definition
\[\begin{align} \mathbf{D} &= \begin{cases} \operatorname{diag}(\boldsymbol{e}) & \text{for a vector of variances}\,, \\ \mathbf{E} & \text{for a covariance}\,. \end{cases} \end{align}\]
Where:
- $\boldsymbol{e}$: Idiosyncratic variances, $N \times 1$.
- $\mathbf{E}$: Idiosyncratic covariance, $N \times N$.
- $\mathbf{D}$: Returned idiosyncratic covariance, $N \times N$.
- $N$: Number of assets.
Arguments
esigma: The idiosyncratic variances, or the idiosyncratic covariance.
Returns
D::AbstractMatrix: The idiosyncratic covariance.
Related
PortfolioOptimisers.attribution_safe_corr — Function
attribution_safe_corr(cv::Number, s1::Number, s2::Number)Return a correlation, or NaN when the pair of volatilities cannot normalise it.
A factor whose standalone volatility is zero has no correlation with anything. The plain quotient would give Inf, -Inf or NaN by the sign of the covariance, so the verb answers NaN for every such row.
Mathematical definition
\[\begin{align} \rho &= \begin{cases} \dfrac{c}{\sigma_{1} \sigma_{2}} & \text{if } \sigma_{1} \sigma_{2} > 0\,, \\ \mathrm{NaN} & \text{otherwise}\,. \end{cases} \end{align}\]
Where:
- $\rho$: Correlation.
- $c$: Covariance of the two quantities.
- $\sigma_{1}$, $\sigma_{2}$: Volatilities of the two quantities.
A NaN product fails the test, so it also gives NaN.
Arguments
cv: The covariance.s1: The first volatility.s2: The second volatility.
Returns
rho::Real: The correlation, orNaN.
Related
PortfolioOptimisers.attribution_family_index — Function
attribution_family_index(fam::VecStr)Return the rows of the family axis and the raw factors each of them sums.
The axis is the sorted unique labels, so it is deterministic and independent of the order the factors were built in. Every consumer of the family axis reads the axis from here, so the labels, the sums, the exposure spread and the standard errors are in one order.
Algorithm
- Convert each label of
famto aString, remove the duplicates and sort the rest, givinglabels. - For each entry of
labels, find the positions offamthat carry it, giving one entry ofidx.
Arguments
fam: The family label of each raw factor.
Returns
The tuple (labels, idx):
labels::Vector{String}: The sorted unique family labels.idx::Vector{Vector{Int}}: The raw factors of each family.
Related
PortfolioOptimisers.attribution_family_axis — Function
attribution_family_axis(fam::Nothing, args...)
attribution_family_axis(fam::VecStr, fbd::AttributionBreakdown, exposure_std, mu_se)Return the family axis of a factor attribution as a sum of the rows of the factor axis.
A family is a set of factors, so the four additive fields sum over the rows of the family. The axis is the sorted unique labels, which makes it deterministic and independent of the order the factors were built in; a plot that shows the largest families sorts the rows it draws. vol, corr and mu are nothing, because no single standalone volatility, correlation or mean return describes a set of factors.
Mathematical definition
\[\begin{align} x_{\mathcal{F}} &= \sum_{k \in \mathcal{F}} x_{k}\,. \end{align}\]
Where:
- $x_{k}$: Entry of factor $k$ in one of the four additive fields of the factor axis: the exposure, the volatility contribution, the variance share and the mean return contribution.
- $x_{\mathcal{F}}$: Entry of the family in the same field of the family axis.
- $\mathcal{F}$: Raw factors of one family.
The families partition the raw factors, so each field of the family axis sums to the same total as that field of the factor axis.
Algorithm
- Index the families with
attribution_family_index, giving the sorted labels and the raw factors of each. - Sum each of the four additive fields of
fbdover the raw factors of each family. - Build the family axis from the labels, the four sums,
exposure_stdandmu_se, withnothingforvol,corrandmu.
Arguments
fam: The family label of each raw factor, ornothing.fbd: The factor axis.exposure_std: The standard deviation of the per-observation family exposure, ornothing.mu_se: The standard error of the family mean return contribution, ornothing.
Returns
fmbd::Option{<:AttributionBreakdown}: The family axis, ornothingwhen the block names no family.
Related
PortfolioOptimisers.AttributionBlock — Type
struct AttributionBlock{__T_B, __T_f, __T_eps, __T_lag, __T_rw, __T_vs, __T_fcb, __T_unseen, __T_no, __T_fam, __T_h1, __T_dc, __T_key}A factor model block as the bare arrays that a realised attribution reads, untrimmed, on one observation axis.
This type is an implementation detail and is not intended for direct use. attribution_block_arrays reads it off a factor model block, and attribution_array_block builds it from the arrays of a caller. attribution_align and attribution_key_align align it against a return series.
Fields
B:B: The static loadings,assets × factors, or the exposure history,assets × factors × observations.
f:f: The factor returns,observations × factors.
eps:eps: The idiosyncratic returns,observations × assets.
lag:lag: The number of observations by which the exposures lag the returns.
rw:rw: The regression weight history,observations × assets, ornothing.
vs:vs: The idiosyncratic variance history,observations × assets, ornothing.
fcb:fcb: The family re-basis the regression was written in, ornothing.
unseen:unseen: The Unseen Member rule the regression ran under.
no:no: The number of observed factors, the last factors of the axis.
fam:fam: The family label of each factor, ornothing.
h1:h1: The leverage-one mask,observations × assets, ornothing.
dc:dc: The dropped-column mask of the fit,observations × estimated factors, ornothing.
key:key: The row key of the block, fromattribution_row_key.
Related
PortfolioOptimisers.attribution_array_block — Function
attribution_array_block(B::MatNum_Arr3Num, f::MatNum, eps::MatNum;
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)
-> AttributionBlockReturn the bare arrays of a realised attribution as the block attribution_align reads.
The exposures, the factor returns and the idiosyncratic returns are the model, so they are positional. An exposure history lags the returns by one observation by default: the return of observation t pairs with the exposure known at t - lag. A static loadings matrix has no time index, so a lag pairs nothing for it, and the block reads every observation whatever lag is. trim = true cuts the first lag observations of a static matrix all the same, so its sample is the sample of a run on an exposure history with the same lag.
Arguments
B: Loadings,assets × factors, or the exposure history,assets × factors × observations.f: Factor returns,observations × factors.eps: Idiosyncratic returns,observations × assets.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, ornothing.vs: Idiosyncratic variance history, 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.fam: Family label of each factor, ornothing.
Validation
lag >= 0, else aDomainErroris raised. A negative lag pairs each return with an exposure from after it.
Returns
blk::AttributionBlock: The block, with the row key of no row. Itslagis zero for a static matrix unlesstrim = true.
Related
PortfolioOptimisers.AttributionModel — Type
struct AttributionModel{__T_M, __T_F, __T_d, __T_mu_f, __T_b, __T_sigma, __T_mu, __T_fam, __T_lev}The factor model that a predicted attribution reads, as bare arrays.
This type is an implementation detail and is not intended for direct use. attribution_array_model builds it, and predicted_attribution and attribution_array_mask read it.
Fields
M:M: The loadings,assets × factors.
F:F: The factor covariance,factors × factors.
d:d: The idiosyncratic variances, or the idiosyncratic covariance.
mu_f:mu_f: The expected factor returns.
b:b: The factor-orthogonal expected return of each asset.
sigma:sigma: The asset covariance the total variance reads, ornothing.
mu:mu: The expected asset returns the total mean reads, ornothing.
fam:fam: The family label of each factor, ornothing.
lev:lev: The assets whose variance split the model does not identify, ornothing.
Related
PortfolioOptimisers.attribution_array_model — Function
attribution_array_model(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) -> AttributionModelReturn the factor model a predicted attribution reads, from bare arrays.
The loadings, the factor covariance and the idiosyncratic block are the model, so they are positional. The two means default to zero, as a model that states no premium and no orthogonal mean. The two totals sigma and mu default to nothing, and the model then closes the total on its own.
Arguments
B: Loadings,assets × factors.F: Factor covariance,factors × factors.d: Idiosyncratic variances, or the idiosyncratic covariance.mu_f: Expected factor returns, ornothingfor zeros.b: Factor-orthogonal expected return of each asset, ornothingfor zeros.sigma: Asset covariance the total variance reads, ornothing.mu: Expected asset returns the total mean reads, ornothing.fam: Family label of each factor, ornothing.
Returns
mdl::AttributionModel: The model, with zeros for an absent mean.
Related
PortfolioOptimisers.attribution_array_mask — Function
attribution_array_mask(mdl::AttributionModel) -> Option{BitVector}Return the assets a predicted attribution can decompose, or nothing when it can decompose every asset.
An asset is decomposable when the model states it: its loadings, its idiosyncratic variance and its factor-orthogonal mean are finite, and so are its total mean and variance when the caller gives them. The last two are the rule of investable_mask, so on the arrays of a prior result the mask is the Investable Mask whenever the block states every investable asset.
Arguments
mdl: The factor model, fromattribution_array_model.
Returns
imsk::Option{BitVector}:trueat every decomposable asset, ornothingwhen every asset is decomposable.
Related
PortfolioOptimisers.PredictedTotal — Type
struct PredictedTotal{__T_total, __T_gap}The total of a predicted moment and its gap to the model.
This type is an implementation detail and is not intended for direct use. attribution_predicted_total makes it, and predicted_attribution reads it. The two values are numbers of one type, so a record names them.
Fields
total:total: The total of the moment.
gap:gap: The unattributed part, the total less the systematic and the idiosyncratic part.
Related
PortfolioOptimisers.attribution_predicted_total — Function
attribution_predicted_total(anchor::Nothing, keep, w, sys::Number, idio::Number, mdl)
attribution_predicted_total(sigma::MatNum, keep, w, sys::Number, idio::Number, mdl)
attribution_predicted_total(mu::VecNum, keep, w, sys::Number, idio::Number, mdl)Return the total of a predicted moment and its gap to the model.
Without an anchor the model is the total, so the gap is an exact zero and no round-off lands in the remainder. A covariance anchors the variance through its quadratic form, and a vector of expected returns anchors the mean through its linear form.
An entry the anchor does not state is unknown. Between two assets that keep their unknown entries it stays NaN, so the total that reads it is unknown. Every other unknown entry reads the model's entry, with each unknown entry of the model read as zero. Under EntrywiseUnknown that entry belongs to an asset the portfolio does not hold, so it adds nothing. Under ZeroUnknown it is the model's own value of the entry, so the entry adds nothing to the gap, and the remainder reads the entries the anchor states.
Mathematical definition
\[\begin{align} \tilde{\Sigma}_{ij} &= \begin{cases} \Sigma_{ij} & \text{if } \Sigma_{ij} \text{ is finite, or } k_{i} = k_{j} = 1\,, \\ (\mathbf{B} \mathbf{F} \mathbf{B}^{\intercal} + \mathbf{D})_{ij} & \text{otherwise}\,, \end{cases} \\ \tilde{\mu}_{i} &= \begin{cases} \mu_{i} & \text{if } \mu_{i} \text{ is finite, or } k_{i} = 1\,, \\ (\mathbf{B} \boldsymbol{\mu}_{f} + \boldsymbol{b})_{i} & \text{otherwise}\,, \end{cases} \\ t &= \begin{cases} s + i & \text{without an anchor}\,, \\ \boldsymbol{w}^{\intercal} \tilde{\mathbf{\Sigma}} \boldsymbol{w} & \text{for a covariance}\,, \\ \boldsymbol{w}^{\intercal} \tilde{\boldsymbol{\mu}} & \text{for expected returns}\,, \end{cases} \\ u &= \begin{cases} 0 & \text{without an anchor}\,, \\ t - s - i & \text{otherwise}\,. \end{cases} \end{align}\]
Where:
- $s$, $i$: Systematic and idiosyncratic part of the moment.
- $t$, $u$: Total and unattributed part of the moment.
- $\mathbf{\Sigma}$, $\tilde{\mathbf{\Sigma}}$: Asset covariance of the anchor, $N \times N$, before and after the rule.
- $\boldsymbol{\mu}$, $\tilde{\boldsymbol{\mu}}$: Expected asset returns of the anchor, $N \times 1$, before and after the rule.
- $k_{i}$: Whether asset $i$ keeps its unknown entries, from
attribution_unknown_keep. - $\mathbf{B}$, $\mathbf{D}$, $\boldsymbol{b}$: The loadings, the idiosyncratic covariance and the factor-orthogonal mean after the rule. A product that still reads a non-finite entry is set to zero for the fill.
- $\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.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $N$: Number of assets.
Arguments
anchor,sigma,mu: The anchor, ornothing.keep: Whether each asset keeps its unknown entries.w: Portfolio weights.sys: The systematic part.idio: The idiosyncratic part.mdl: The model after the rule: the loadingsM, the factor covarianceF, the idiosyncratic covarianceD, the expected factor returnsmu_fand the factor-orthogonal meanbp.
Returns
tv::PredictedTotal: The totaltotaland the unattributed partgap.
Related
PortfolioOptimisers.predicted_attribution — Function
predicted_attribution(w::VecNum, mdl::AttributionModel; assets::Bool = false,
ppy::Number = 1, strict::Bool = false,
unknown::AbstractUnknownEntryRule = EntrywiseUnknown())
-> FactorAttributionResultDecompose the predicted moments of a portfolio over the factors of a factor model.
Every predicted method of factor_attribution calls this function, the bare-array method and the prior method alike, so the two answer the same numbers on the same arrays. factor_attribution states the decomposition.
Algorithm
- Refuse weights over another universe through
assert_attribution_assets. Find the decomposable assetsimskwithattribution_array_mask, and report a holding outside them throughattribution_investable_diagnostic, with the sentence ofattribution_unknown_note. - Find the assets
keepwhose unknown entries stay unknown withattribution_unknown_keep. Zero every other non-finite entry of the loadingsM, the orthogonal meanbpand the idiosyncratic covarianceD. - Form the portfolio exposure
bexp, its productFbwith the factor covariance, and the systematic and idiosyncratic variances and means. - Take the totals and the two gaps from the anchors with
attribution_predicted_total. A total that reads an unknown entry isNaN, and so is every number divided by the portfolio volatility. - Build the four components, the factor axis, the family axis and, when
assets = true, the asset axis, each scaled byppy.
Arguments
w: Portfolio weights.mdl: The factor model, fromattribution_array_model.assets: Whether to fill the asset axis and the asset-by-factor matrices.ppy: Periods per year the numbers are scaled to.strict: Whether a holding in an asset the model does not state raises rather than warns.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
- The factor covariance and the expected factor returns are finite, else an
IsNonFiniteErroris raised. wholds one entry for each row of the loadings, else aDimensionMismatchis raised.- Every weight at an asset the model does not state is zero, else a warning names the assets, or an
ArgumentErrornames them understrict. - The portfolio variance is positive or
NaN, andppy > 0, else aDomainErroris raised. The variance isNaNwhen it reads an unknown entry.
Returns
fa::FactorAttributionResult: The attribution.
Related
PortfolioOptimisers.predicted_attribution_assets — Function
predicted_attribution_assets(assets::Bool, w, mdl::NamedTuple, Fb, sigma_p, sc)Return the asset axis and the asset-by-factor matrices of a predicted attribution.
The asset axis decomposes the model, not the totals. Every row reads M F M' + D and M mu_f + b, so the systematic rows sum to the systematic component, the idiosyncratic rows to the idiosyncratic component, and vol_contrib to the two together. It therefore does not reach the total, and the difference is the unattributed remainder, which is a property of the portfolio and has no per-asset split. The realised asset axis satisfies the same identity, so a reader compares the two sides row by row.
The contributions read the model after the rule for an unknown entry, as the components do. A contribution of an asset the portfolio does not hold is its weight, zero, times a finite number, so it is zero even when the portfolio volatility is unknown, through attribution_held_entries. The standalone numbers are moments of the asset, not contributions, so they read the block's own entries through attribution_standalone. Under EntrywiseUnknown the model states the mean of an asset whose loadings and factor-orthogonal mean it states, and it states no volatility for an asset whose idiosyncratic variance is unknown, in the warm-up of a relisted asset for example: that volatility and its correlation are NaN, and a zero would state a moment the block does not hold. Under ZeroUnknown every unknown entry reads as zero.
Mathematical definition
For each asset $i$, with the model covariance $\mathbf{\Sigma}_{M}$:
\[\begin{align} \mathbf{\Sigma}_{M} &= \mathbf{B} \mathbf{F} \mathbf{B}^{\intercal} + \mathbf{D}\,, \\ \mathrm{VC}^{S}_{i} &= \sqrt{p}\, \frac{w_{i} (\mathbf{B} \mathbf{F} \boldsymbol{g})_{i}}{\sigma_{P}}\,, \\ \mathrm{VC}^{I}_{i} &= \sqrt{p}\, \frac{w_{i} (\mathbf{D} \boldsymbol{w})_{i}}{\sigma_{P}}\,, \\ \mathrm{VC}_{i} &= \mathrm{VC}^{S}_{i} + \mathrm{VC}^{I}_{i} = \sqrt{p}\, \frac{w_{i} (\mathbf{\Sigma}_{M} \boldsymbol{w})_{i}}{\sigma_{P}}\,, \\ \mathrm{PV}_{i} &= \frac{w_{i} (\mathbf{\Sigma}_{M} \boldsymbol{w})_{i}}{\sigma_{P}^{2}}\,, \\ \mathrm{MC}^{S}_{i} &= p\, w_{i} (\mathbf{B} \boldsymbol{\mu}_{f})_{i}\,, \\ \mathrm{MC}^{I}_{i} &= p\, w_{i} b_{i}\,, \\ \mathrm{MC}_{i} &= \mathrm{MC}^{S}_{i} + \mathrm{MC}^{I}_{i}\,, \\ \mu_{i} &= p \left( (\mathbf{B} \boldsymbol{\mu}_{f})_{i} + b_{i} \right)\,, \\ \mathrm{vol}_{i} &= \sqrt{p\, (\mathbf{\Sigma}_{M})_{ii}}\,, \\ \rho_{i} &= \frac{(\mathbf{\Sigma}_{M} \boldsymbol{w})_{i}}{\sqrt{(\mathbf{\Sigma}_{M})_{ii}}\, \sigma_{P}}\,. \end{align}\]
For each asset $i$ and factor $k$:
\[\begin{align} \mathrm{VC}_{ik} &= \sqrt{p}\, \frac{w_{i} B_{ik} (\mathbf{F} \boldsymbol{g})_{k}}{\sigma_{P}}\,, \\ \mathrm{MC}_{ik} &= p\, w_{i} B_{ik} \mu_{f,k}\,. \end{align}\]
Where:
- $\mathbf{\Sigma}_{M}$: Model covariance, $N \times N$.
- $\mathrm{VC}$, $\mathrm{PV}$, $\mathrm{MC}$, $\mathrm{vol}$, $\rho$: Volatility contribution, variance share, mean return contribution, volatility and correlation with the portfolio. A superscript $S$ or $I$ names the systematic or the idiosyncratic part.
- $\mu_{i}$: Expected return of asset $i$ under the model, scaled by $p$.
- $w_{i}$, $b_{i}$, $B_{ik}$, $\mu_{f,k}$: Entries of $\boldsymbol{w}$, $\boldsymbol{b}$, $\mathbf{B}$ and $\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.
Summed over the assets, $\mathrm{VC}^{S}_{i}$ gives $\sqrt{p}\, \boldsymbol{g}^{\intercal} \mathbf{F} \boldsymbol{g} / \sigma_{P}$, the systematic volatility contribution, and $\mathrm{VC}^{I}_{i}$ gives $\sqrt{p}\, \boldsymbol{w}^{\intercal} \mathbf{D} \boldsymbol{w} / \sigma_{P}$, the idiosyncratic one. Summed over the assets, $\mathrm{VC}_{ik}$ and $\mathrm{MC}_{ik}$ give the row of factor $k$ of the factor axis. Summed over the factors, they give $\mathrm{VC}^{S}_{i}$ and $\mathrm{MC}^{S}_{i}$. The volatility and the correlation of an asset read the model covariance, while $\sigma_{P}$ reads the covariance of the prior result. So $\rho_{i}$ is the correlation of asset $i$ with the portfolio under the model only when $\boldsymbol{w}^{\intercal} \mathbf{\Sigma}_{M} \boldsymbol{w} = \sigma_{P}^{2}$, which is when the unattributed variance is zero.
Arguments
assets: Whether to compute the two answers at all.w: Portfolio weights.mdl: The factor model: the loadingsM, the factor covarianceF, the expected factor returnsmu_f, the idiosyncratic covarianceDand the factor-orthogonal expected returnbp, after the rule for an unknown entry, and the loadingsMr, factor-orthogonal expected returnbprand idiosyncratic covarianceerthat the standalone numbers read.Fb: The product of the factor covariance and the portfolio exposure.sigma_p: Portfolio volatility.sc: The two annualisation factors.
Returns
abd::Option{<:AssetAttributionBreakdown}: The asset axis, ornothing.afc::Option{<:AssetFactorContribution}: The asset-by-factor matrices, ornothing.
Related