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) -> VecVecIntReturn 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
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 ofvof each asset,assets × 1, or zero at an asset that the window does not cover.
v:v: One statistic for each covered asset.
Related
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
- Find the positions
liveof the assets in the Coverage Universe of the rowsTwithcv_live_assets. - Evaluate the risk measure of
son the covered columns of the window withwindow_values. - Turn the values into statistics with
fold_statistic. - 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, fromwindow_bigger_is_better: thebigger_is_betterflag of one risk measure, ortruefor a vector, whose values are oriented.
Returns
ws::WindowStatistics:posisassets × 1, and holds the entry ofvof each covered asset, or zero.vholds one statistic for each covered asset.
Related
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
- Find
ok, the positions of the assets whose count is at leastmin_folds. - Evaluate
score_ofat each position ofokintov. The function callsscore_ofat no other position, so an aggregation never reads an empty set of folds. - Read the number type
Sofv, orTwhenvis empty. - Return the vector of that type that holds
vatok, andNaNat 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 vectorassets × 1. It isNaNat each asset with fewer thanmin_foldsfolds.
Related
PortfolioOptimisers.window_bigger_is_better — Function
window_bigger_is_better(r::AbstractBaseRiskMeasure) -> Bool
window_bigger_is_better(r::VecBaseRM) -> BoolState 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:truewhen a bigger value is better.
Related
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) -> VecNumEvaluate 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 fieldscaof the scorer.nothinggives 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
DomainErrorthat names the columns with a non-finite value, asasset_scoresdoes for one measure.
Returns
v::VecNum: One value for each column ofX.
Related
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) -> TupleExpand 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
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) -> AbstractVectorReturn 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, ornothing.
Returns
cands::AbstractVector: The candidates, in the order of the grid.
Related
PortfolioOptimisers.split_assets — Function
split_assets(cvr::MultipleRandomisedResult, k::Integer, N::Integer) -> VecInt
split_assets(cvr::CrossValidationResult, k::Integer, N::Integer) -> VecIntReturn 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
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
- Read the asset positions
colsof the split withsplit_assets. - Find the positions of
colsin the Coverage Universe of the training window withcv_live_assets. - Return the mask that is
trueat those positions.
Arguments
rd: The returns result to use.cvr: The split result.k: The index of the split.
Returns
offered::BitVector: The maskassets × 1,trueat each asset that the split offers.
Related
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
mpstarts att. Otherwise the function throws anArgumentError, because the split and the predictions disagree.
Returns
pred::PredictionResult: The prediction of the window.
Related
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) -> PredictionResultReturn 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 ofcross_val_predictover the splitscvr.cvr: The split result.k: The index of the split.
Returns
p::PredictionResult: The prediction that holds the result of splitk.
Related
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.
v:v: The value of each asset, fromweight_mass_value.
Related
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
- Read the weights of the investable assets into
wi:wat the Investable Mask fromresult_investable_mask, or all ofwwhen the mask isnothing. - Write each weight at the position of its asset name in
v, zero at every other asset, and add each named asset tooffered. - Turn
vinto the value of each asset withweight_mass_value.
Arguments
p: The prediction of the split.offered: The mask of the assets that the split offers, fromsplit_offered.idx: The position of each asset name ofrd.tol: The tolerance of the selection frequency, ornothingfor the weight.
Returns
sv::SplitValues:offeredis the maskassets × 1of the offered assets, andvholds the value of each asset.
Related
PortfolioOptimisers.weight_mass_value — Function
weight_mass_value(tol::Nothing, v::VecNum) -> VecNum
weight_mass_value(tol::Real, v::VecNum) -> VecNumReturn 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, ornothing.v: The weights of the split,assets × 1.
Returns
v::VecNum: The value of each asset.
Related