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 ArgumentError naming the type.
  • A CrossSectionalFactorModel whose esigma is nothing raises an IsNothingError.

Returns

  • esigma::VecNum_MatNum: The idiosyncratic variances, or the idiosyncratic covariance. A Regression that carries none answers a vector of zeros.

Related

source
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 ArgumentError naming the type.
  • A CrossSectionalFactorModel whose csr is nothing raises an IsNothingError.
  • A Regression on a prior result whose o_X is nothing raises an IsNothingError, because such a prior result reconstructed nothing and the difference is zero at every observation.

Returns

  • eps::MatNum: The idiosyncratic returns, observations × assets.

Related

source
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 ArgumentError naming the type.
  • A CrossSectionalFactorModel whose csr is nothing raises an IsNothingError, with or without a family re-basis.
  • A re-based CrossSectionalFactorModel whose fr is nothing raises an IsNothingError. A block the prior fits carries it.

Returns

  • f::MatNum: The factor returns, observations × factors.

Related

source
PortfolioOptimisers.attribution_observed_count — Function
attribution_observed_count(rr::AbstractLoadingsRegressionResult) -> Int
attribution_observed_count(rr::CrossSectionalFactorModel) -> Int

Return 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

source
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 ArgumentError naming the type.

Returns

  • Ms::Union{MatNum, Arr3Num}: The exposure history assets × factors × observations, or the static loadings assets × factors.

Related

source
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 ArgumentError naming the type.

Returns

  • lag::Int: The exposure lag, as a count.

Related

source
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, or nothing.
  • ts: ts: The timestamp of each row, or nothing.

Related

source
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 position idx of each block row, or nothing, and the timestamp ts of each block row, or nothing.

Related

source
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, or nothing.

Related

source
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, or nothing.

Related

source
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

source
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 history observations × assets, or nothing.

Related

source
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 history observations × assets, or nothing.

Related

source
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

  • x is not nothing, else an IsNothingError naming the field is raised.

Returns

  • x: The field's value, unchanged.

Related

source
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

  • x is not nothing, else an IsNothingError naming the field is raised.

Returns

  • x: The field's value, unchanged.

Related

source
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, or nothing.

Returns

  • A::Option{<:AbstractArray}: The array, with every non-finite entry replaced by zero, or nothing.

Related

source
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

  1. Refuse weights that do not hold one entry for each asset of pr through assert_attribution_assets, so the mask is never read at an index it lacks.
  2. Read the investable mask imsk off pr. An absent mask means that every asset is investable, and the verb returns.
  3. Find the non-investable assets that carry a non-zero weight, in the vector or at any observation of the history, giving held.
  4. When held is not empty, warn naming it and stating note, or raise under strict, through strict_diagnostic.

Arguments

  • w: The constant weights, or the weight history.
  • pr: The prior result.
  • imsk: The assets the model states, or nothing when 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

  • w holds one entry for each asset of pr, else a DimensionMismatch is raised.
  • Every weight at a non-investable asset is zero, else a warning naming the assets is emitted, or an ArgumentError naming them is raised under strict.

Returns

  • Nothing is returned.

Related

source
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 N assets, else a DimensionMismatch naming both counts is raised.

Returns

  • Nothing is returned.

Related

source
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

Returns

The tuple (rr, fpr):

  • rr::AbstractLoadingsRegressionResult: The factor model block.
  • fpr::LowOrderPrior: The factor distribution.

Related

source
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 a DomainError is raised.

Returns

  • sc::AnnualisationScale: The factor s1 a mean or a variance takes, ppy itself, and the factor s2 a volatility takes, in the type of ppy * one(x) or wider.

Related

source
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

source
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, or NaN.

Related

source
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

  1. Convert each label of fam to a String, remove the duplicates and sort the rest, giving labels.
  2. For each entry of labels, find the positions of fam that carry it, giving one entry of idx.

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

source
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

  1. Index the families with attribution_family_index, giving the sorted labels and the raw factors of each.
  2. Sum each of the four additive fields of fbd over the raw factors of each family.
  3. Build the family axis from the labels, the four sums, exposure_std and mu_se, with nothing for vol, corr and mu.

Arguments

  • fam: The family label of each raw factor, or nothing.
  • fbd: The factor axis.
  • exposure_std: The standard deviation of the per-observation family exposure, or nothing.
  • mu_se: The standard error of the family mean return contribution, or nothing.

Returns

  • fmbd::Option{<:AttributionBreakdown}: The family axis, or nothing when the block names no family.

Related

source
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, or nothing.
  • vs: vs: The idiosyncratic variance history, observations × assets, or nothing.
  • fcb: fcb: The family re-basis the regression was written in, or nothing.
  • 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, or nothing.
  • h1: h1: The leverage-one mask, observations × assets, or nothing.
  • dc: dc: The dropped-column mask of the fit, observations × estimated factors, or nothing.

Related

source
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)
    -> AttributionBlock

Return 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 first lag observations, as an exposure history with the same lag does. A static matrix reads every observation otherwise.
  • rw: Regression weight history, or nothing.
  • vs: Idiosyncratic variance history, 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.
  • fam: Family label of each factor, or nothing.

Validation

  • lag >= 0, else a DomainError is 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. Its lag is zero for a static matrix unless trim = true.

Related

source
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, or nothing.
  • mu: mu: The expected asset returns the total mean reads, or nothing.
  • fam: fam: The family label of each factor, or nothing.
  • lev: lev: The assets whose variance split the model does not identify, or nothing.

Related

source
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) -> AttributionModel

Return 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, 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.
  • mu: Expected asset returns the total mean reads, or nothing.
  • fam: Family label of each factor, or nothing.

Returns

  • mdl::AttributionModel: The model, with zeros for an absent mean.

Related

source
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

Returns

  • imsk::Option{BitVector}: true at every decomposable asset, or nothing when every asset is decomposable.

Related

source
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

source
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, or nothing.
  • 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 loadings M, the factor covariance F, the idiosyncratic covariance D, the expected factor returns mu_f and the factor-orthogonal mean bp.

Returns

  • tv::PredictedTotal: The total total and the unattributed part gap.

Related

source
PortfolioOptimisers.predicted_attribution — Function
predicted_attribution(w::VecNum, mdl::AttributionModel; assets::Bool = false,
                      ppy::Number = 1, strict::Bool = false,
                      unknown::AbstractUnknownEntryRule = EntrywiseUnknown())
    -> FactorAttributionResult

Decompose 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

  1. Refuse weights over another universe through assert_attribution_assets. Find the decomposable assets imsk with attribution_array_mask, and report a holding outside them through attribution_investable_diagnostic, with the sentence of attribution_unknown_note.
  2. Find the assets keep whose unknown entries stay unknown with attribution_unknown_keep. Zero every other non-finite entry of the loadings M, the orthogonal mean bp and the idiosyncratic covariance D.
  3. Form the portfolio exposure bexp, its product Fb with the factor covariance, and the systematic and idiosyncratic variances and means.
  4. Take the totals and the two gaps from the anchors with attribution_predicted_total. A total that reads an unknown entry is NaN, and so is every number divided by the portfolio volatility.
  5. Build the four components, the factor axis, the family axis and, when assets = true, the asset axis, each scaled by ppy.

Arguments

  • w: Portfolio weights.
  • mdl: The factor model, from attribution_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 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

  • The factor covariance and the expected factor returns are finite, else an IsNonFiniteError is raised.
  • w holds one entry for each row of the loadings, else a DimensionMismatch is raised.
  • Every weight at an asset the model does not state is zero, else a warning names the assets, or an ArgumentError names them under strict.
  • The portfolio variance is positive or NaN, and ppy > 0, else a DomainError is raised. The variance is NaN when it reads an unknown entry.

Returns

  • fa::FactorAttributionResult: The attribution.

Related

source
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 loadings M, the factor covariance F, the expected factor returns mu_f, the idiosyncratic covariance D and the factor-orthogonal expected return bp, after the rule for an unknown entry, and the loadings Mr, factor-orthogonal expected return bpr and idiosyncratic covariance er that 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, or nothing.
  • afc::Option{<:AssetFactorContribution}: The asset-by-factor matrices, or nothing.

Related

source