Cross-Sectional Weights
Types
PortfolioOptimisers.AbstractCrossSectionalWeightsAlgorithm — Type
abstract type AbstractCrossSectionalWeightsAlgorithm <: AbstractAlgorithmAbstract supertype for all cross-sectional regression weight policy types.
A member says what weight an asset carries in the cross-sectional fit of an observation, and whether that weight is decided once or twice. A one-pass member reads the cross-section alone. A two-pass member reads the residuals of a first fit, so the caller runs the regression again with the weights the member returns.
All concrete and/or abstract types representing cross-sectional weight policies should be subtypes of AbstractCrossSectionalWeightsAlgorithm.
Interfaces
In order to implement a new concrete type that works seamlessly with the library, subtype AbstractCrossSectionalWeightsAlgorithm and implement the following methods:
cs_weights_initial
cs_weights_initial(alg::AbstractCrossSectionalWeightsAlgorithm, mcap::Option{<:MatNum}, mask::AbstractMatrix{Bool}): Returns the weights of the first pass.
Arguments
alg: The concrete subtype instance.mcap: Market capitalisation matrixobservations × assets, ornothing.mask: Eligibility maskobservations × assets.
Returns
W0::Matrix{<:Number}: First-pass weightsobservations × assets, zero outsidemask.
cs_weights_refine
cs_weights_refine(alg::AbstractCrossSectionalWeightsAlgorithm, W0::MatNum, eps::MatNum, ve::AbstractCovarianceEstimator, mask::AbstractMatrix{Bool}; kwargs...): Returns the weights of the second pass. A member whoseneeds_second_passisfalseneeds no method, because the caller never calls it.
Arguments
alg: The concrete subtype instance.W0: First-pass weightsobservations × assets.eps: First-pass residual matrixobservations × assets.ve: Variance estimator.mask: Eligibility maskobservations × assets.
Returns
W1::Matrix{<:Number}: Second-pass weightsobservations × assets, zero outsidemask.
needs_second_pass
needs_second_pass(alg::AbstractCrossSectionalWeightsAlgorithm): Returnstruewhen the caller must fit twice. The root answersfalse, so a one-pass member needs no method.
Arguments
alg: The concrete subtype instance.
Returns
val::Bool:truewhencs_weights_refineis called,falseotherwise.
Examples
A one-pass member that gives every eligible asset the same weight needs one method:
julia> struct MyWeights <: PortfolioOptimisers.AbstractCrossSectionalWeightsAlgorithm endjulia> function PortfolioOptimisers.cs_weights_initial(::MyWeights, mcap, mask::AbstractMatrix{Bool}) return Matrix{Float64}(mask) endjulia> PortfolioOptimisers.cs_weights_initial(MyWeights(), nothing, [true false true])1×3 Matrix{Float64}: 1.0 0.0 1.0julia> PortfolioOptimisers.needs_second_pass(MyWeights())falseRelated
PortfolioOptimisers.MarketCapWeights — Type
struct MarketCapWeights{__T_p} <: AbstractCrossSectionalWeightsAlgorithmWeights an asset by a power of its market capitalisation, in one pass.
The power sets how concentrated the cross-section is. 0 gives every eligible asset the same weight, 1 gives the capitalisation itself, and a value between the two shrinks the share of the largest assets.
The default p = 1/2 is the weight of the weighted least squares of [79]. That work assumes that the variance of the specific return of an asset is inversely proportional to the square root of its capitalisation, so the weight is the square root.
Mathematical definition
\[\begin{align} w_{t,i} &= \begin{cases} m_{t,i}^{p} & \text{if } (t, i) \in \mathcal{M} \\ 0 & \text{otherwise} \end{cases}\,. \end{align}\]
Where:
- $w_{t,i}$: Cross-sectional regression weight of asset $i$ at observation $t$.
- $m_{t,i}$: Market capitalisation of asset $i$ at observation $t$.
- $p$: Market capitalisation power.
- $\mathcal{M}$: Eligibility mask, the set of pairs $(t, i)$ that enter the fit.
The weights do not sum to one. A weighted least squares gives the same fit for every positive multiple of its weights.
Fields
p: Exponent applied to the market capitalisation. A value of0needs no capitalisation matrix, because every eligible asset then takes the same weight.
Constructors
MarketCapWeights(; p::Real = 0.5) -> MarketCapWeightsKeywords correspond to the struct's fields.
Validation
isfinite(p).p >= 0.
Examples
julia> MarketCapWeights()MarketCapWeights p ┴ Float64: 0.5Related
AbstractCrossSectionalWeightsAlgorithmBlendedInverseVarianceWeightscs_weights_initialcross_sectional_cap_weights
References
- [79] J. Menchero, D. J. Orr and J. Wang. The Barra US Equity Model (USE4): Methodology Notes. Model Insight, MSCI (2011). Section 3.1, Page 13. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.BlendedInverseVarianceWeights — Type
struct BlendedInverseVarianceWeights{__T_p, __T_lambda, __T_ratio, __T_wins} <: AbstractCrossSectionalWeightsAlgorithmBlends market capitalisation weights with inverse idiosyncratic variance weights, in two passes.
A first fit under the capitalisation weights gives the residuals. A variance estimated from those residuals gives the second component, and the caller fits again. The variance paired with observation t reads the residuals up to t - 1 only, so a weight never reads the return it multiplies.
The inverse variance is the weight of the generalised least squares of [82] when the specific returns are uncorrelated. So at $\lambda = 1$, with neither bound reached, the second pass is a two-step feasible generalised least squares. The two bounds are not part of that estimator. They keep the share of an asset with a very small estimated variance finite.
Mathematical definition
\[\begin{align} c_{t,i} &= \mathrm{clip}\left(\frac{1}{v_{t-1,i}},\, q_{t}^{\mathrm{lo}},\, q_{t}^{\mathrm{hi}}\right) \\ u_{t,i} &= \begin{cases} \min\left(c_{t,i},\, \rho \, \underset{j \in \mathcal{V}_{t}}{\mathrm{med}}\, c_{t,j}\right) & \text{if } i \in \mathcal{V}_{t} \\ 0 & \text{otherwise} \end{cases} \\ w_{t,i} &= \begin{cases} \lambda \dfrac{u_{t,i}}{\sum_{j \in \mathcal{V}_{t}} u_{t,j}} + \left(1 - \lambda\right) \dfrac{m_{t,i}^{p}}{\sum_{j \in \mathcal{M}_{t}} m_{t,j}^{p}} & \text{if } (t, i) \in \mathcal{M} \\ 0 & \text{otherwise} \end{cases}\,. \end{align}\]
Where:
- $w_{t,i}$: Cross-sectional regression weight of asset $i$ at observation $t$.
- $v_{ti}$: Idiosyncratic variance of asset $i$ that the fit estimated from the observations up to $t$, so it is the forecast for observation $t + 1$.
- $\mathcal{M}$: Eligibility mask, the set of pairs $(t, i)$ that enter the fit.
- $\mathcal{M}_{t}$: Eligible assets of observation $t$, those with $(t, i) \in \mathcal{M}$.
- $\mathcal{V}_{t}$: Assets of $\mathcal{M}_{t}$ that carry a variance estimate $v_{t-1,i}$.
- $\mathcal{E}_{t}$: Estimation universe of observation $t$, the assets of $\mathcal{V}_{t}$ with $m_{t,i}^{p} > 0$.
- $q_{t}^{\mathrm{lo}}$, $q_{t}^{\mathrm{hi}}$: Quantiles at the levels
winsof the inverse variances of the assets of $\mathcal{E}_{t}$. - $\rho$: Median ratio cap.
- $\lambda$: Blend coefficient.
- $m_{t,i}$: Market capitalisation of asset $i$ at observation $t$.
- $p$: Market capitalisation power.
Both components sum to one over $\mathcal{M}_{t}$, so the share of the inverse variance component in $w_{t,i}$ is $\lambda$. An observation with an empty $\mathcal{E}_{t}$ has no quantiles. It takes $u_{t,i} = m_{t,i}^{p} / \sum_{j \in \mathcal{M}_{t}} m_{t,j}^{p}$, so its weights are the capitalisation weights alone.
An inverse variance is infinite where its variance is zero. The bounds then take the limit as those variances go to zero together, as cross_sectional_winsorise! and cross_sectional_median_cap! state.
Fields
p: Exponent applied to the market capitalisation. A value of0needs no capitalisation matrix, because every eligible asset then takes the same weight. It sets the capitalisation component of the blend and the first-pass weights.
lambda: Blend coefficient. It is the share of the inverse variance component in the second-pass weights, so0gives the capitalisation weights.1drops them on every observation that carries a variance estimate, and an observation with no estimate keeps them.
ratio: Largest multiple of the cross-sectional median an inverse variance weight may take. It caps the influence of an asset whose estimated variance is very small.
wins: Lower and upper quantile levels of the cross-sectional winsorisation of the inverse variances, applied before the median cap.
Constructors
BlendedInverseVarianceWeights(; p::Real = 0.5, lambda::Real, ratio::Real = 20.0, wins::Tuple{Real, Real} = (0.025, 0.975)) -> BlendedInverseVarianceWeightsKeywords correspond to the struct's fields. lambda takes no default, because naming this member is the request for the second pass. A caller that wants one pass writes MarketCapWeights instead.
Validation
isfinite(p)andp >= 0.0 <= lambda <= 1.isfinite(ratio)andratio > 0.0 <= wins[1] < wins[2] <= 1.
Examples
julia> BlendedInverseVarianceWeights(; lambda = 0.5)BlendedInverseVarianceWeights p ┼ Float64: 0.5 lambda ┼ Float64: 0.5 ratio ┼ Float64: 20.0 wins ┴ Tuple{Float64, Float64}: (0.025, 0.975)Related
AbstractCrossSectionalWeightsAlgorithmMarketCapWeightscs_weights_initialcs_weights_refinevariance_series
References
- [82] A. C. Aitken. On least squares and linear combination of observations. Proceedings of the Royal Society of Edinburgh 55, 42–48 (1935). Section 3, Page 45.
Functions
PortfolioOptimisers.cs_weights_initial — Function
cs_weights_initial(alg::Union{MarketCapWeights, BlendedInverseVarianceWeights},
mcap::Option{<:MatNum}, mask::AbstractMatrix{Bool}) -> Matrix{<:Number}Return the first-pass cross-sectional regression weights of a weight policy.
Both members read the capitalisation the same way, so both call cross_sectional_cap_weights. They differ in what the caller does next. needs_second_pass is false for MarketCapWeights and true for BlendedInverseVarianceWeights.
Arguments
alg: Cross-sectional weight policy.mcap::Option{<:MatNum}: Market capitalisation matrixobservations × assets, ornothingwhen the policy'spis zero.mask::AbstractMatrix{Bool}: Eligibility maskobservations × assets.
Validation
- The rules of
cross_sectional_cap_weights.
Returns
W0::Matrix{<:Number}: First-pass weightsobservations × assets, zero outsidemask.
Examples
julia> PortfolioOptimisers.cs_weights_initial(MarketCapWeights(; p = 1.0), [2.0 3.0 5.0], [true true false])1×3 Matrix{Float64}: 2.0 3.0 0.0Related
PortfolioOptimisers.cs_weights_refine — Function
cs_weights_refine(alg::BlendedInverseVarianceWeights, W0::MatNum, eps::MatNum,
ve::AbstractCovarianceEstimator, mask::AbstractMatrix{Bool};
kwargs...) -> Matrix{<:Number}Return the second-pass cross-sectional regression weights of a weight policy.
The verb takes the first-pass weights and residuals as arguments rather than reading them off the policy, because a weight policy is configuration and holds no fitted data. A caller runs it only when needs_second_pass answers true. An observation whose eligible first-pass weights sum to zero returns NaN for every eligible pair, because both components are normalised. When alg.p is not zero, cs_weights_initial builds such a row from a row whose eligible capitalisations are all zero. A single zero capitalisation leaves the row finite. Its pair takes no part in the quantiles, and its capitalisation component is zero.
Algorithm
- Take the lagged inverse variances through
cross_sectional_lagged_inverse_variance. - Blend them with the first-pass weights through
cs_weights_blend.
Arguments
alg: Cross-sectional weight policy.W0::MatNum: First-pass weightsobservations × assets.eps::MatNum: First-pass residual matrixobservations × assets.ve: Variance estimator.mask::AbstractMatrix{Bool}: Eligibility maskobservations × assets.kwargs...: Additional keyword arguments passed tovariance_series.
Validation
size(W0) == size(eps).all(isfinite, W0)andall(x -> x >= 0, W0).- The rules of
cross_sectional_lagged_inverse_variance, which holdepsagainstmask.
Returns
W1::Matrix{<:Number}: Second-pass weightsobservations × assets, zero outsidemask.
Examples
julia> eps = [1.0 2.0; 3.0 6.0; 2.0 4.0];julia> alg = BlendedInverseVarianceWeights(; p = 0.0, lambda = 1.0);julia> W0 = PortfolioOptimisers.cs_weights_initial(alg, nothing, trues(3, 2));julia> PortfolioOptimisers.cs_weights_refine(alg, W0, eps, SimpleVariance(), trues(3, 2))3×2 Matrix{Float64}: 0.5 0.5 0.5 0.5 0.785 0.215Related
PortfolioOptimisers.needs_second_pass — Function
needs_second_pass(alg::AbstractCrossSectionalWeightsAlgorithm) -> BoolReturn whether a weight policy asks the caller to fit the cross-sectional regression twice.
The trait keeps the fit loop in the caller, which reads top to bottom, so the weight family and the regression family never name each other's types. It follows needs_previous_weights, which the tracking family uses the same way.
Arguments
alg: Cross-sectional weight policy.
Returns
val::Bool:truewhen the caller must runcs_weights_refineand fit again,falsewhen the first-pass weights are the answer.
Examples
julia> PortfolioOptimisers.needs_second_pass(MarketCapWeights())falsejulia> PortfolioOptimisers.needs_second_pass(BlendedInverseVarianceWeights(; lambda = 0.5))trueRelated
References
- [79]
- J. Menchero, D. J. Orr and J. Wang. The Barra US Equity Model (USE4): Methodology Notes (MSCI, 2011).
- [82]
- A. C. Aitken. On Least Squares and Linear Combination of Observations. Proceedings of the Royal Society of Edinburgh 55, 42–48 (1935).