Asset scorers: private API

The test windows of a fold risk scorer

A FoldRiskScorer reads each distinct test window once. In each window it scores only the assets that the window covers, the assets whose return is finite and active at every row of the window. An asset that too few windows cover has no score, and its entry is NaN. A vector of risk measures gives each asset one oriented value on each window, and a reduction of nothing gives the sum.

PortfolioOptimisers.distinct_test_windows — Function
distinct_test_windows(test_idx::VecVecInt) -> VecVecInt
distinct_test_windows(test_idx::VecVecVecInt) -> VecVecInt

Return each distinct test window of a cross-validation split once.

A CombinatorialCrossValidation split holds a vector of test blocks, and one block is in many splits. The method on a VecVecVecInt flattens the blocks of every split, and keeps each block once. The method on a VecVecInt keeps each window once. An aggregation over the windows then weighs each window once.

Arguments

  • test_idx: The test indices of a split result, one window for each split, or one vector of blocks for each split.

Returns

  • windows::VecVecInt: The distinct test windows, in the order of their first appearance.

Related

source
PortfolioOptimisers.WindowStatistics — Type
struct WindowStatistics{__T_pos, __T_v}

Holds the statistic of each covered asset on one test window of a FoldRiskScorer, with the position of each asset in those statistics.

This type is an implementation detail and is not intended for direct use. window_statistic makes one for each test window, and the asset_scores method of the scorer collects them and reads them by field. The value travels in a collection, so a record names its two fields.

Fields

  • pos: pos: The entry of v of each asset, assets × 1, or zero at an asset that the window does not cover.
  • v: v: One statistic for each covered asset.

Related

source
PortfolioOptimisers.window_statistic — Function
window_statistic(
    s::FoldRiskScorer,
    rd::AbstractReturnsResult,
    T::AbstractVector{<:Integer},
    bib::Bool
) -> WindowStatistics

Return the statistic of each covered asset on one test window, with the position of each asset in that window.

Algorithm

  1. Find the positions live of the assets in the Coverage Universe of the rows T with cv_live_assets.
  2. Evaluate the risk measure of s on the covered columns of the window with window_values.
  3. Turn the values into statistics with fold_statistic.
  4. Write the position of each covered asset in the statistics into pos, and zero at each other asset.

Arguments

  • s: The fold risk scorer.
  • rd: The returns result to use.
  • T: The rows of the test window.
  • bib: The orientation of the values on a test window, from window_bigger_is_better: the bigger_is_better flag of one risk measure, or true for a vector, whose values are oriented.

Returns

  • ws::WindowStatistics: pos is assets × 1, and holds the entry of v of each covered asset, or zero. v holds one statistic for each covered asset.

Related

source
PortfolioOptimisers.min_folds_scores — Function
min_folds_scores(
    score_of,
    counts::AbstractVector{<:Integer},
    min_folds::Integer,
    _::Type{T}
) -> Any

Return the score of each asset that at least min_folds folds scored, and NaN at every other asset.

An Asset Scorer scores an asset only on a fold that offers it. A fold does not offer an asset outside the Coverage Universe of its window, or outside the asset subset that a MultipleRandomised split drew. So the number of folds can differ from asset to asset, and a score from two folds is not as reliable as a score from twenty. An asset with fewer than min_folds folds has no score, and the default min_folds = 1 marks an asset that no fold scored.

A NaN score is outside every selection rule and every redundancy algorithm, so the asset leaves the selection and the run does not stop. rule_keep states that rule.

Algorithm

  1. Find ok, the positions of the assets whose count is at least min_folds.
  2. Evaluate score_of at each position of ok into v. The function calls score_of at no other position, so an aggregation never reads an empty set of folds.
  3. Read the number type S of v, or T when v is empty.
  4. Return the vector of that type that holds v at ok, and NaN at every other position.

Arguments

  • score_of: The function that returns the score of the asset at a position.
  • counts: The number of folds that scored each asset, assets × 1.
  • min_folds: The smallest number of folds that must score an asset.
  • T: The number type of the returns data. The function reads it only when no asset has enough folds.

Returns

  • scores::VecNum: The score vector assets × 1. It is NaN at each asset with fewer than min_folds folds.

Related

source
PortfolioOptimisers.window_bigger_is_better — Function
window_bigger_is_better(r::AbstractBaseRiskMeasure) -> Bool
window_bigger_is_better(r::VecBaseRM) -> Bool

State whether a bigger value of a FoldRiskScorer on a test window is better.

One measure keeps its raw value, so the method returns its bigger_is_better flag. A vector gives an oriented value, in which a bigger value is better, so the method returns true. It never reads bigger_is_better of the vector, which throws when the members disagree on orientation.

Arguments

  • r: One risk measure, or a vector of them.

Returns

  • bib::Bool: true when a bigger value is better.

Related

source
PortfolioOptimisers.window_values — Function
window_values(sca::Option{<:Sca_VecToScaM}, r::AbstractBaseRiskMeasure, X::MatNum)
    -> VecNum
window_values(sca::Option{<:Sca_VecToScaM}, r::VecBaseRM, X::MatNum) -> VecNum

Evaluate the risk measure of a FoldRiskScorer on each column of one test window.

The method on one measure returns the raw value of each column through asset_scores, and ignores sca. The method on a vector returns the oriented score of each column under sca, through oriented_score on the series of the column, so a bigger value is better.

Arguments

  • sca: The reduction of a vector, the field sca of the scorer. nothing gives the sum.
  • r: One risk measure, or a vector of them.
  • X: The returns of the covered assets at the rows of the window, observations × assets. Every column is in the Coverage Universe of the window.

Validation

  • Every value is finite. Otherwise the function throws a DomainError that names the columns with a non-finite value, as asset_scores does for one measure.

Returns

  • v::VecNum: One value for each column of X.

Related

source

The splits of a weight mass scorer

A WeightMassScorer builds one candidate for each point of its grid, finds the prediction of each split once, and maps the weights of each split to the assets of the returns data by name.

PortfolioOptimisers.weight_mass_grid — Function
weight_mass_grid(opt, p) -> Tuple
weight_mass_grid(opt::Pipeline, p) -> Tuple

Expand the grid p of a WeightMassScorer into its lenses and its values.

The method on an estimator calls lens_val_grid, and the method on a Pipeline calls pipeline_lens_val_grid. search_cross_validation calls the same two functions, so the scorer and the search read one grid syntax.

Arguments

  • opt: The optimisation estimator or the pipeline.
  • p: The grid of configurations.

Returns

  • (lenses, vals)::Tuple: One vector of lenses and one tuple of values for each candidate.

Related

source
PortfolioOptimisers.weight_mass_candidates — Function
weight_mass_candidates(opt::Union{OptE_TD, Pipeline}, p::Nothing) -> AbstractVector
weight_mass_candidates(opt::Union{OptE_TD, Pipeline}, p::MultiGSCVValType_VecMultiGSCVValType) -> AbstractVector

Return the candidates that a WeightMassScorer runs, one for each point of its grid.

With no grid the candidate is opt alone. Otherwise the function sets each lens of a point to its value with search_candidate.

Arguments

  • opt: The optimisation estimator or the pipeline of the scorer.
  • p: The grid of configurations, or nothing.

Returns

  • cands::AbstractVector: The candidates, in the order of the grid.

Related

source
PortfolioOptimisers.split_assets — Function
split_assets(cvr::MultipleRandomisedResult, k::Integer, N::Integer) -> VecInt
split_assets(cvr::CrossValidationResult, k::Integer, N::Integer) -> VecInt

Return the asset positions that split k gives its optimiser.

A MultipleRandomised split gives the subset that it drew. Every other split gives all N assets.

Arguments

  • cvr: The split result.
  • k: The index of the split.
  • N: The number of assets of the returns data.

Returns

  • cols::VecInt: The asset positions of the split.

Related

source
PortfolioOptimisers.split_offered — Function
split_offered(
    rd::AbstractReturnsResult,
    cvr::CrossValidationResult,
    k::Integer
) -> Any

Return the mask of the assets that split k offers its optimiser.

Algorithm

  1. Read the asset positions cols of the split with split_assets.
  2. Find the positions of cols in the Coverage Universe of the training window with cv_live_assets.
  3. Return the mask that is true at those positions.

Arguments

  • rd: The returns result to use.
  • cvr: The split result.
  • k: The index of the split.

Returns

  • offered::BitVector: The mask assets × 1, true at each asset that the split offers.

Related

source
PortfolioOptimisers.prediction_at — Function
prediction_at(
    mp::MultiPeriodPredictionResult,
    t::Integer
) -> Any

Return the prediction of mp whose test window starts at row t.

Arguments

  • mp: One path of predictions.
  • t: The first row of the test window.

Validation

  • One prediction of mp starts at t. Otherwise the function throws an ArgumentError, because the split and the predictions disagree.

Returns

  • pred::PredictionResult: The prediction of the window.

Related

source
PortfolioOptimisers.split_prediction — Function
split_prediction(pred::MultiPeriodPredictionResult, cvr::CrossValidationResult, k::Integer) -> PredictionResult
split_prediction(pred::PopulationPredictionResult, cvr::CombinatorialCrossValidationResult, k::Integer) -> PredictionResult
split_prediction(pred::PopulationPredictionResult, cvr::MultipleRandomisedResult, k::Integer) -> PredictionResult

Return the prediction that holds the result of split k, once for each split.

A sequential or a K-fold scheme gives one prediction for each split. A combinatorial split is in many paths, and every block of the split holds the same result, so the method reads the first block of the split in its path. A randomised split is in one path, and the method reads it there. Each method finds the prediction by the first row of its test window, with prediction_at.

Arguments

  • pred: The output of cross_val_predict over the splits cvr.
  • cvr: The split result.
  • k: The index of the split.

Returns

  • p::PredictionResult: The prediction that holds the result of split k.

Related

source
PortfolioOptimisers.SplitValues — Type
struct SplitValues{__T_offered, __T_v}

Holds the record of one successful split of a WeightMassScorer: the assets that the split offered, and the value of each asset.

This type is an implementation detail and is not intended for direct use. split_weight_record makes one for each split whose optimisation succeeded, and the asset_scores method of the scorer collects them and reads them by field. The value travels in a collection, so a record names its two fields.

Fields

  • offered: offered: The mask of the assets that the split offered, assets × 1.

Related

source
PortfolioOptimisers.split_weight_record — Function
split_weight_record(
    p::PredictionResult,
    offered::BitVector,
    idx::AbstractDict,
    tol::Union{Nothing, Real}
) -> SplitValues{BitVector}

Return the record of one successful split: the assets that it offered, and the value of each.

The weights of a fold are on the universe that its optimiser saw, which a selector or an asset subset can make smaller than rd. The function maps them to the assets of rd by name, through the names of the investable assets of the prediction.

Algorithm

  1. Read the weights of the investable assets into wi: w at the Investable Mask from result_investable_mask, or all of w when the mask is nothing.
  2. Write each weight at the position of its asset name in v, zero at every other asset, and add each named asset to offered.
  3. Turn v into the value of each asset with weight_mass_value.

Arguments

  • p: The prediction of the split.
  • offered: The mask of the assets that the split offers, from split_offered.
  • idx: The position of each asset name of rd.
  • tol: The tolerance of the selection frequency, or nothing for the weight.

Returns

  • sv::SplitValues: offered is the mask assets × 1 of the offered assets, and v holds the value of each asset.

Related

source
PortfolioOptimisers.weight_mass_value — Function
weight_mass_value(tol::Nothing, v::VecNum) -> VecNum
weight_mass_value(tol::Real, v::VecNum) -> VecNum

Return the value that a WeightMassScorer averages for each asset of one split.

With tol = nothing the value is the weight itself. With a number it is one where the absolute weight exceeds tol, and zero otherwise, in the number type of the weights.

Arguments

  • tol: The tolerance of the selection frequency, or nothing.
  • v: The weights of the split, assets × 1.

Returns

  • v::VecNum: The value of each asset.

Related

source