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

  1. Read fin, the mask of the finite scores, and n, the number of finite scores. Return a mask of falses when k is not positive, and fin when k is at least n. The second case is the saturation of the count.
  2. Select the comparison ahead. It is > when tail and bib agree that a larger score is further into the tail, and < otherwise.
  3. Sort the finite scores s under ahead with sortperm into perm. Read cut, the score at position k of that order.
  4. Count the finite scores strictly ahead of cut into n_ahead, and the finite scores equal to cut into n_eq.
  5. Set keep_ties to n_ahead + n_eq == k. The tied block at the cut fits in k only then. cut is at position k, so n_ahead + n_eq >= k is always true.
  6. Return the mask that is true for every finite score strictly ahead of cut, and for a score equal to cut when keep_ties is true.

Arguments

  • scores: The score vector assets × 1, with one score for each asset.
  • k: The number of assets to take from the tail end.
  • bib: The bigger_is_better flag of the score.
  • tail: The end to take from, :best or :worst.

Returns

  • keep::BitVector: The mask assets × 1. It is true for every asset in the tail, and false at every non-finite score. It holds k assets or fewer, and fewer when a tied block crosses the cut.

Related

source
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

  1. Start from a mask of length(scores) falses.
  2. When best is not nothing, take the :best tail of size best with tail_mask, and add it to the mask with a union.
  3. When worst is not nothing, take the :worst tail of size worst with tail_mask, and add it to the mask with a union.
  4. Return the mask when action is :keep. When action is :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, or nothing.
  • worst: The number of assets to take from the worst end, or nothing.
  • action: :keep returns the union, and :drop returns its complement among the finite scores.
  • scores: The score vector assets × 1, with one score for each asset.
  • bib: The bigger_is_better flag of the score.

Returns

  • keep::BitVector: The mask assets × 1. It is true for every asset that the rule admits, and false at every non-finite score.

Related

source
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

  1. Start from a keep-mask of length(scores) falses.
  2. Take the next group g of groups. Read fin, the members of g with a finite score. Skip the group when fin is empty.
  3. Set best to the member of fin with the largest score when bib is true, and with the smallest score otherwise.
  4. Count the members of fin whose score is equal to scores[best]. Set the mask at best only when that count is one, so a group with a tied best keeps no asset.
  5. 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: true when 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

source
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

  1. Read n, the number of rows of rho, and set parent[i] to i for every asset. Each asset starts as its own component.
  2. Take the next entry of the strict lower triangle of rho, which holds each pair one time.
  3. When that entry is at least t, find the root of each member of the pair with find. Point the larger root at the smaller one. find compresses the path that it reads, so a later lookup on that chain takes one step.
  4. Do steps 2 and 3 for each of the other pairs.
  5. Group the assets by their last root into groups, with that root as the key.
  6. 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 matrix assets × 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 a Dict, so their order is not defined. groups_argbest reads them as a set, and does not depend on the order.

Related

source
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 vector assets × 1, with one score for each asset.
  • bib: The bigger_is_better flag of the score that gave scores.

Returns

  • d::VecNum: The drop score vector assets × 1. Of two assets, the algorithm drops the one with the higher number.

Related

source
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

Returns

  • nothing.

Related

source
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

  1. Evaluate score on a view of each live column, into live_scores.
  2. Check that every entry of live_scores is finite.
  3. Fill a vector with NaN in the element type of live_scores, one entry for each column of X.
  4. Write live_scores at the positions live, and return the vector.

Arguments

  • score: The risk measure to evaluate on each live column.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • live: The positions of the live columns of X, in increasing order.

Validation

  • Every score of a live column is finite. Otherwise the function throws a DomainError that names the columns with a non-finite score.

Returns

  • scores::VecNum: The score vector assets × 1. It holds the score of each live column and NaN at every other column, in the element type of the scores.

Related

source
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

  1. Return nothing for a tail of nothing.
  2. Return tail.val for a CountOf.
  3. Return round(Int, tail.val * n, RoundNearestTiesUp) for a FractionOf. An exact half rounds up.

Arguments

  • tail: The best or the worst field of the rule.
  • n: The number of assets with a finite score.

Returns

  • k::Option{<:Integer}: The number of assets that the tail takes, or nothing.

Examples

julia> PortfolioOptimisers.rule_tail_count(FractionOf(0.625), 4)3julia> PortfolioOptimisers.rule_tail_count(CountOf(50), 30)50

Related

source
PortfolioOptimisers.assert_selection_action — Function
assert_selection_action(action::Symbol)

Check the action field of an ordinal selection rule.

Arguments

  • action: The action field of an ordinal selection rule.

Validation

  • action in (:keep, :drop). Otherwise the function throws an ArgumentError that names the value of action.

Returns

  • nothing.

Related

source

Types