Cross-Sectional Weights: private API
Functions
PortfolioOptimisers.cross_sectional_cap_weights — Function
cross_sectional_cap_weights(
p::Real,
mcap::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
mask::AbstractMatrix{Bool}
) -> AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
Return the market capitalisation weights of an eligibility mask, raised to a power.
The two members of the family share this body, so the formula is written once. A power of zero returns before it reads the capitalisation matrix, so a caller with no capitalisation data can pass nothing.
Algorithm
- When
pis zero, return the mask as a matrix with the type ofp. Every eligible pair takes the weight one. - Otherwise check
mcapagainst the mask. Writemcap[t, i]^pinto every eligible pair, and zero elsewhere. The element type promotes the type ofmcapwith the type ofp.
Arguments
p::Real: Exponent applied to the market capitalisation.mcap::Option{<:MatNum}: Market capitalisation matrixobservations × assets, ornothingwhenpis zero.mask::AbstractMatrix{Bool}: Eligibility maskobservations × assets.
Validation
!isempty(mask).!isnothing(mcap)whenpis not zero.size(mcap) == size(mask).- Every eligible pair carries a finite, non-negative capitalisation. The
DomainErrornames the observation and the asset.
Returns
W0::Matrix{<:Number}: Weightsobservations × assets, zero outsidemask.
Examples
julia> mask = [true true false];julia> PortfolioOptimisers.cross_sectional_cap_weights(0.5, [4.0 9.0 1.0], mask)1×3 Matrix{Float64}: 2.0 3.0 0.0julia> PortfolioOptimisers.cross_sectional_cap_weights(0.0, nothing, mask)1×3 Matrix{Float64}: 1.0 1.0 0.0Related
PortfolioOptimisers.cross_sectional_lagged_inverse_variance — Function
cross_sectional_lagged_inverse_variance(
ve::AbstractCovarianceEstimator,
eps::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
mask::AbstractMatrix{Bool};
kwargs...
) -> AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
Return the lagged inverse idiosyncratic variances of a residual matrix.
Row t reads the variance series at row t - 1, so an entry never carries the squared residual of its own observation. Row 1 is NaN, because no residual precedes the first observation.
Algorithm
- Take the variance series of
epsthroughvariance_series. - Lag and invert the series through
cross_sectional_lagged_inverse.
Arguments
ve: Variance estimator.eps::MatNum: First-pass residual matrixobservations × assets.mask::AbstractMatrix{Bool}: Eligibility maskobservations × assets.kwargs...: Additional keyword arguments passed tovariance_series.
Validation
!isempty(eps).size(eps) == size(mask).
Returns
IV::Matrix{<:Number}: Inverse variancesobservations × assets,NaNwhere no estimate exists and outsidemask.
Examples
julia> eps = [1.0 2.0; 3.0 6.0; 2.0 4.0];julia> PortfolioOptimisers.cross_sectional_lagged_inverse_variance(SimpleVariance(), eps, trues(3, 2))3×2 Matrix{Float64}: NaN NaN NaN NaN 0.5 0.125Related
PortfolioOptimisers.cross_sectional_lagged_inverse — Function
cross_sectional_lagged_inverse(
V::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
mask::AbstractMatrix{Bool}
) -> AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
Return the lagged inverse of a variance series.
Row t reads row t - 1 of the series. Row 1 is NaN, because no variance precedes it. cross_sectional_lagged_inverse_variance reads the series of a residual matrix through it. The carry fold of a CrossSectionalFactorPrior reads the series of its folded variance through it, with the last row of the previous step as row 1.
Algorithm
- Fill the result with
NaN, which is what row1and every pair outsidemaskkeep. Both blend components then normalise over the same universe. - Write the reciprocal of row
t - 1of the series into every eligible pair of rowt, for every later observation.
Arguments
V::MatNum: Variance seriesobservations × assets.mask::AbstractMatrix{Bool}: Eligibility maskobservations × assets.
Validation
size(V) == size(mask).
Returns
IV::Matrix{<:Number}: Inverse variancesobservations × assets,NaNin row1and outsidemask.
Related
PortfolioOptimisers.cross_sectional_winsorise! — Function
cross_sectional_winsorise!(
IV::Matrix{<:Number},
W0::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
wins::Tuple{Real, Real}
)
Clamp the inverse variance weights of each observation to two cross-sectional quantiles, in place.
The clamp protects the blend from an asset whose estimated variance is very small, which would otherwise carry almost the whole cross-section. The quantiles come from the estimation universe, which is the set of pairs with a positive first-pass weight. The clamp applies to the whole row, so it holds a pair outside that universe inside the same bounds.
An entry is infinite where its variance is exactly zero. When every entry of the set is infinite, both quantiles are infinite, and the clamp lifts every entry of the row that is not NaN to infinity. That is the limit of the clamp as the variances of the set go to zero together, so cross_sectional_median_cap! then gives those entries equal shares.
Algorithm
- For each observation, gather the entries in the estimation universe that are not
NaN. - Where the set carries a finite entry, take the quantiles
winsof that set, and clamp the whole row between them. A level that lands on an order statistic beside an infinite entry takes that order statistic, which is the limit as those variances go to zero.Statistics.quantilegivesNaNthere, and aNaNbound clamps nothing. - Where every entry of the set is infinite, write an infinity into every entry of the row that is not
NaN. - Write an all-
NaNrow where the set is empty, because no bound exists there.
Arguments
IV::Matrix{<:Number}: Inverse variancesobservations × assets, changed in place.W0::MatNum: First-pass weightsobservations × assets. Only the sign of an entry is read, which names the estimation universe.wins::Tuple{Real, Real}: Lower and upper quantile levels of the clamp.
Validation
size(IV) == size(W0).
Returns
nothing.IVcarries the clamped weights.
Examples
julia> IV = [1.0 3.0 100.0];julia> PortfolioOptimisers.cross_sectional_winsorise!(IV, [1.0 1.0 0.0], (0.0, 1.0))julia> IV1×3 Matrix{Float64}: 1.0 3.0 3.0Related
PortfolioOptimisers.cross_sectional_median_cap! — Function
cross_sectional_median_cap!(
IV::Matrix{<:Number},
ratio::Real
) -> BitVector
Cap the inverse variance weights of each observation at a multiple of their median, then normalise them, in place.
The cap is the second of the two bounds. An asset whose estimated variance is exactly zero has an infinite entry, and the cap lowers it to ratio times the median, so the observation still returns a weight. The normalisation puts the row on the same scale as the capitalisation component, so the blend of the two realises the shrinkage the caller wrote.
When half or more of the entries are infinite, the median is infinite and the cap does not bind. The row then takes the limit of the normalised row as those variances go to zero together: each infinite entry gets an equal share, and each finite entry gets zero. A row whose entries are all infinite gets equal shares the same way.
Algorithm
- For each observation, record whether the row carries an entry that is not
NaN. - Take the median of the entries that are not
NaN, and cap the row atratiotimes it. - Where no entry is infinite after the cap, divide the row by the sum of its entries that are not
NaN. - Where $n$ entries are still infinite, write $1 / n$ into each of them and zero into every finite entry.
Arguments
IV::Matrix{<:Number}: Inverse variancesobservations × assets, changed in place.ratio::Real: Largest multiple of the cross-sectional median an entry may take.
Returns
ready::BitVector: One entry per observation,truewhere the row carries an inverse variance estimate that is notNaN. A row that answersfalseis untouched.
Examples
julia> IV = [1.0 3.0 100.0];julia> PortfolioOptimisers.cross_sectional_median_cap!(IV, 2.0)1-element BitVector: 1julia> IV1×3 Matrix{Float64}: 0.1 0.3 0.6Related
PortfolioOptimisers.cs_weights_blend — Function
cs_weights_blend(
alg::BlendedInverseVarianceWeights,
W0::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
IV::Matrix{<:Number},
mask::AbstractMatrix{Bool}
) -> AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
Blend the first-pass weights with lagged inverse variances into the second-pass weights.
cs_weights_refine runs it on the inverse variances of its residuals. The carry fold of a CrossSectionalFactorPrior runs it on the inverse variances of the new observations, which it reads from its folded variance. Each observation is blended on its own row, so the two calls give the same row.
Algorithm
- Clamp
IVto the cross-sectional quantiles throughcross_sectional_winsorise!. - Cap and normalise it through
cross_sectional_median_cap!, which also names the observations that carry an estimate. - Normalise the first-pass weights over the same universe.
- Write zero over every entry that is still
NaN, so a missing entry does not contribute. - Write the normalised first-pass weights into every observation that carries no estimate.
- Blend the two components by
alg.lambda, and write zero outsidemask.
Arguments
alg: Cross-sectional weight policy.W0::MatNum: First-pass weightsobservations × assets.IV::Matrix{<:Number}: Lagged inverse variancesobservations × assets, changed in place.mask::AbstractMatrix{Bool}: Eligibility maskobservations × assets.
Validation
size(W0) == size(IV).
Returns
W1::Matrix{<:Number}: Second-pass weightsobservations × assets, zero outsidemask.
Related