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

  1. When p is zero, return the mask as a matrix with the type of p. Every eligible pair takes the weight one.
  2. Otherwise check mcap against the mask. Write mcap[t, i]^p into every eligible pair, and zero elsewhere. The element type promotes the type of mcap with the type of p.

Arguments

  • p::Real: Exponent applied to the market capitalisation.
  • mcap::Option{<:MatNum}: Market capitalisation matrix observations × assets, or nothing when p is zero.
  • mask::AbstractMatrix{Bool}: Eligibility mask observations × assets.

Validation

  • !isempty(mask).
  • !isnothing(mcap) when p is not zero.
  • size(mcap) == size(mask).
  • Every eligible pair carries a finite, non-negative capitalisation. The DomainError names the observation and the asset.

Returns

  • W0::Matrix{<:Number}: Weights observations × assets, zero outside mask.

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

Related

source
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

  1. Take the variance series of eps through variance_series.
  2. Lag and invert the series through cross_sectional_lagged_inverse.

Arguments

  • ve: Variance estimator.
  • eps::MatNum: First-pass residual matrix observations × assets.
  • mask::AbstractMatrix{Bool}: Eligibility mask observations × assets.
  • kwargs...: Additional keyword arguments passed to variance_series.

Validation

  • !isempty(eps).
  • size(eps) == size(mask).

Returns

  • IV::Matrix{<:Number}: Inverse variances observations × assets, NaN where no estimate exists and outside mask.

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

Related

source
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

  1. Fill the result with NaN, which is what row 1 and every pair outside mask keep. Both blend components then normalise over the same universe.
  2. Write the reciprocal of row t - 1 of the series into every eligible pair of row t, for every later observation.

Arguments

  • V::MatNum: Variance series observations × assets.
  • mask::AbstractMatrix{Bool}: Eligibility mask observations × assets.

Validation

  • size(V) == size(mask).

Returns

  • IV::Matrix{<:Number}: Inverse variances observations × assets, NaN in row 1 and outside mask.

Related

source
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

  1. For each observation, gather the entries in the estimation universe that are not NaN.
  2. Where the set carries a finite entry, take the quantiles wins of 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.quantile gives NaN there, and a NaN bound clamps nothing.
  3. Where every entry of the set is infinite, write an infinity into every entry of the row that is not NaN.
  4. Write an all-NaN row where the set is empty, because no bound exists there.

Arguments

  • IV::Matrix{<:Number}: Inverse variances observations × assets, changed in place.
  • W0::MatNum: First-pass weights observations × 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. IV carries 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.0

Related

source
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

  1. For each observation, record whether the row carries an entry that is not NaN.
  2. Take the median of the entries that are not NaN, and cap the row at ratio times it.
  3. Where no entry is infinite after the cap, divide the row by the sum of its entries that are not NaN.
  4. Where $n$ entries are still infinite, write $1 / n$ into each of them and zero into every finite entry.

Arguments

  • IV::Matrix{<:Number}: Inverse variances observations × assets, changed in place.
  • ratio::Real: Largest multiple of the cross-sectional median an entry may take.

Returns

  • ready::BitVector: One entry per observation, true where the row carries an inverse variance estimate that is not NaN. A row that answers false is 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.6

Related

source
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

  1. Clamp IV to the cross-sectional quantiles through cross_sectional_winsorise!.
  2. Cap and normalise it through cross_sectional_median_cap!, which also names the observations that carry an estimate.
  3. Normalise the first-pass weights over the same universe.
  4. Write zero over every entry that is still NaN, so a missing entry does not contribute.
  5. Write the normalised first-pass weights into every observation that carries no estimate.
  6. Blend the two components by alg.lambda, and write zero outside mask.

Arguments

  • alg: Cross-sectional weight policy.
  • W0::MatNum: First-pass weights observations × assets.
  • IV::Matrix{<:Number}: Lagged inverse variances observations × assets, changed in place.
  • mask::AbstractMatrix{Bool}: Eligibility mask observations × assets.

Validation

  • size(W0) == size(IV).

Returns

  • W1::Matrix{<:Number}: Second-pass weights observations × assets, zero outside mask.

Related

source