Asset selection: private API
Functions
PortfolioOptimisers.tail_mask — Function
tail_mask(
scores::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
k::Integer,
bib::Bool,
tail::Symbol
) -> BitVector
Return the mask of the k assets that are furthest into the tail end of the order of the scores.
tail is :best or :worst. bib, the bigger_is_better flag of the score, sets which raw direction each end is. The count saturates at the number of finite scores.
The function orders only the finite scores. A non-finite score is in neither tail, so the mask is false at every NaN and at every infinite score. An unscored asset is then never in a selection, and it takes no slot of the count.
The mask includes the assets tied with the score at position k only when the whole tied block fits in k. Otherwise the block crosses the cut, and the mask excludes it. This is the tie policy of the library, and it is the reason that the mask can hold fewer than k assets. RankRule states the admitted set in closed form.
Algorithm
- Read
fin, the mask of the finite scores, andn, the number of finite scores. Return a mask of falses whenkis not positive, andfinwhenkis at leastn. The second case is the saturation of the count. - Select the comparison
ahead. It is>whentailandbibagree that a larger score is further into the tail, and<otherwise. - Sort the finite scores
sunderaheadwithsortpermintoperm. Readcut, the score at positionkof that order. - Count the finite scores strictly
aheadofcutinton_ahead, and the finite scores equal tocutinton_eq. - Set
keep_tieston_ahead + n_eq == k. The tied block at the cut fits inkonly then.cutis at positionk, son_ahead + n_eq >= kis always true. - Return the mask that is
truefor every finite score strictlyaheadofcut, and for a score equal tocutwhenkeep_tiesistrue.
Arguments
scores: The score vectorassets × 1, with one score for each asset.k: The number of assets to take from thetailend.bib: Thebigger_is_betterflag of the score.tail: The end to take from,:bestor:worst.
Returns
keep::BitVector: The maskassets × 1. It istruefor every asset in the tail, andfalseat every non-finite score. It holdskassets or fewer, and fewer when a tied block crosses the cut.
Related
PortfolioOptimisers.tail_action_mask — Function
tail_action_mask(
best::Union{Nothing, Integer},
worst::Union{Nothing, Integer},
action::Symbol,
scores::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
bib::Bool
) -> BitVector
Make the union of the two tail masks, and apply the action of the rule.
Algorithm
- Start from a mask of
length(scores)falses. - When
bestis notnothing, take the:besttail of sizebestwithtail_mask, and add it to the mask with a union. - When
worstis notnothing, take the:worsttail of sizeworstwithtail_mask, and add it to the mask with a union. - Return the mask when
actionis:keep. Whenactionis:drop, return its complement among the finite scores.
A non-finite score is in neither tail, so step 4 does not admit it under :drop either. The mask is false at every non-finite score under both actions.
Arguments
best: The number of assets to take from the best end, ornothing.worst: The number of assets to take from the worst end, ornothing.action::keepreturns the union, and:dropreturns its complement among the finite scores.scores: The score vectorassets × 1, with one score for each asset.bib: Thebigger_is_betterflag of the score.
Returns
keep::BitVector: The maskassets × 1. It istruefor every asset that the rule admits, andfalseat every non-finite score.
Related
PortfolioOptimisers.groups_argbest — Function
groups_argbest(
groups,
scores::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
bib::Bool
) -> BitVector
Keep the member with the best score in each redundancy group.
A group whose best score is tied keeps no asset. This is the tie policy of the library: if the library cannot tell two assets apart, it keeps neither of them. find_uncorrelated_indices does the same with a correlated pair whose drop scores are equal. A group with one member has no tie, so its member survives when its score is finite.
A member with a non-finite score is not a candidate. The function skips it, and the best finite member of the group survives. A group with no finite score keeps no asset, so an asset with no score never survives.
Algorithm
- Start from a keep-mask of
length(scores)falses. - Take the next group
gofgroups. Readfin, the members ofgwith a finite score. Skip the group whenfinis empty. - Set
bestto the member offinwith the largest score whenbibistrue, and with the smallest score otherwise. - Count the members of
finwhose score is equal toscores[best]. Set the mask atbestonly when that count is one, so a group with a tied best keeps no asset. - Do steps 2 to 4 for each of the other groups, then return the mask.
Arguments
groups: The vector of index vectors that partition the assets.scores: The score vector, with one score for each asset.bib:truewhen a larger score is better.
Returns
keep::BitVector: The keep-mask, with one survivor for each group whose best finite score is not tied.
Related
PortfolioOptimisers.correlation_components — Function
correlation_components(
rho::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
t::Number
) -> Vector{Vector{Int64}}
Return the connected components of the graph whose edges are the pairs of rho at or above t.
The function does one union-find pass over the strict lower triangle. The components are transitive, and every asset is in exactly one of them. An asset with no partner at or above t is a component of one.
Algorithm
- Read
n, the number of rows ofrho, and setparent[i]toifor every asset. Each asset starts as its own component. - Take the next entry of the strict lower triangle of
rho, which holds each pair one time. - When that entry is at least
t, find the root of each member of the pair withfind. Point the larger root at the smaller one.findcompresses the path that it reads, so a later lookup on that chain takes one step. - Do steps 2 and 3 for each of the other pairs.
- Group the assets by their last root into
groups, with that root as the key. - Return the values of
groups.
The function compares the threshold with rho as the caller gives it. A caller that wants the absolute value takes it before this call.
Arguments
rho: The correlation matrixassets × assets.t: Threshold value.
Returns
groups::Vector{Vector{Int}}: The components. Each is a vector of asset indices in ascending order. The components come from aDict, so their order is not defined.groups_argbestreads them as a set, and does not depend on the order.
Related
PortfolioOptimisers.drop_scores — Function
drop_scores(
scores::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
bib::Bool
) -> Any
Convert the scores of the assets into drop scores. Of two assets, the algorithm drops the one with the higher drop score.
When bib is false, a lower score is better, and the score is already a drop score. When bib is true, the function negates the score. After this call a lower number is always better, whatever the orientation of the measure.
Mathematical definition
\[\begin{align} d_{i} &= \begin{cases} -s_{i} & \text{a larger score is better} \\ s_{i} & \text{otherwise} \end{cases}\,. \end{align}\]
Where:
- $d_{i}$: The drop score of asset $i$. Of two assets, the algorithm drops the one with the higher drop score.
- $s_{i}$: The score of asset $i$. It is the value of the risk measure on the return series of asset $i$ alone.
The map reverses the order in the first case, and keeps it in the second. It never changes which of two assets is better. It changes only the direction of the order.
Arguments
scores: The score vectorassets × 1, with one score for each asset.bib: Thebigger_is_betterflag of the score that gavescores.
Returns
d::VecNum: The drop score vectorassets × 1. Of two assets, the algorithm drops the one with the higher number.
Related
PortfolioOptimisers.assert_scoreable — Function
assert_scoreable(score::AbstractBaseRiskMeasure)
Check that score can take the return series of one asset.
The score of asset i is score(X[:, i]). This is the route of a precomputed return vector, and supports_precomputed_returns controls it. A WeightsInput measure, such as Variance or StandardDeviation, takes portfolio weights in place of a return vector. It cannot score an asset.
The method on an AbstractAssetScorer checks nothing and returns nothing. A scorer that holds a risk measure checks that measure in its own constructor. The method on a vector of risk measures checks each member, for a FoldRiskScorer that holds a vector.
Arguments
score: The risk measure, the vector of risk measures, or the Asset Scorer that a selector uses to score its assets.
Validation
supports_precomputed_returns(score). Otherwise the function throws anArgumentErrorthat names the measure. When the measure is aVarianceor aStandardDeviation, the message also namesSCM(), which computes the same quantity from a return series. When it is aSkewness, the message namesThirdCentralMoment, and when it is aKurtosis, it namesHighOrderMomentandLowOrderMoment.- Every slot that
functor_slotsdeclares for the measure, or for a child measure that it holds, holds a value. Otherwiseassert_resolved_slotsthrows anIsNothingErrorthat names the slot. AnEntropicValueatRiskwith no solverslvis such a measure, and so is aGenericValueatRiskRangeor aRiskRatiothat holds one: a selector has no optimiser to give it a solver, so it states the solver on the measure.
Returns
nothing.
Related
PortfolioOptimisers.live_asset_scores — Function
live_asset_scores(
score::AbstractBaseRiskMeasure,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
live::AbstractVector{<:Integer}
) -> Any
Evaluate score on the live columns of X, and write NaN at every other column.
Algorithm
- Evaluate
scoreon a view of each live column, intolive_scores. - Check that every entry of
live_scoresis finite. - Fill a vector with
NaNin the element type oflive_scores, one entry for each column ofX. - Write
live_scoresat the positionslive, and return the vector.
Arguments
score: The risk measure to evaluate on each live column.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.live: The positions of the live columns ofX, in increasing order.
Validation
- Every score of a live column is finite. Otherwise the function throws a
DomainErrorthat names the columns with a non-finite score.
Returns
scores::VecNum: The score vectorassets × 1. It holds the score of each live column andNaNat every other column, in the element type of the scores.
Related
PortfolioOptimisers.rule_tail_count — Function
rule_tail_count(tail::Nothing, n::Integer)
rule_tail_count(tail::CountOf, n::Integer)
rule_tail_count(tail::FractionOf, n::Integer)Convert one tail of a RankRule to the number of assets that it takes from its end.
n is the number of assets with a finite score, so an asset with no score does not count in the size of the universe. tail_mask saturates the count at n.
Algorithm
- Return
nothingfor a tail ofnothing. - Return
tail.valfor aCountOf. - Return
round(Int, tail.val * n, RoundNearestTiesUp)for aFractionOf. An exact half rounds up.
Arguments
tail: Thebestor theworstfield of the rule.n: The number of assets with a finite score.
Returns
k::Option{<:Integer}: The number of assets that the tail takes, ornothing.
Examples
julia> PortfolioOptimisers.rule_tail_count(FractionOf(0.625), 4)3julia> PortfolioOptimisers.rule_tail_count(CountOf(50), 30)50Related
PortfolioOptimisers.assert_selection_action — Function
assert_selection_action(action::Symbol)
Check the action field of an ordinal selection rule.
Arguments
action: Theactionfield of an ordinal selection rule.
Validation
action in (:keep, :drop). Otherwise the function throws anArgumentErrorthat names the value ofaction.
Returns
nothing.
Related
PortfolioOptimisers.assert_correlation_threshold — Function
assert_correlation_threshold(t::Number)
Check a correlation threshold.
Arguments
t: Threshold value.
Validation
-1 <= t <= 1. Otherwise the function throws aDomainError. The bound is the range of a correlation coefficient. A correlation never gets to a threshold above the range, and it is always at or above a threshold below the range.
Returns
nothing.
Related
Types
PortfolioOptimisers.BaseRM_AsSc — Type
const BaseRM_AsSc = Union{AbstractBaseRiskMeasure, AbstractAssetScorer}The score of a ScoreSelector and of a RedundancySelector. A risk measure scores each asset on the training window, and an Asset Scorer reads the whole returns data. The two families share no supertype, but asset_scores and bigger_is_better take both, so a selector reads either one in the same way.
Related