Follow the leader: private API
PortfolioOptimisers.pattern_candidates — Function
pattern_candidates(
window::Integer,
X::AbstractMatrix
) -> Union{Nothing, Tuple{Any, Any, Any}}
Forms the candidate periods of a pattern-matching selector, their flattened windows and the flattened latest window.
A window flattens column by column, so the entries of one asset stay together.
Arguments
window: The number of rows in each window.X: The price relatives,T × N, in time order.
Returns
nothingwhenT <= window, because no candidate exists.(rows, cands, latest)otherwise.rowsis(window + 1):T. The entry ofcandsfor the candidate rowiisvec(X[(i - window):(i - 1), :]).latestisvec(X[(T - window + 1):T, :]).
Related
PortfolioOptimisers.assert_pattern_window — Function
assert_pattern_window(window::Integer)
Checks that the window of a pattern-matching selector holds at least one row.
Arguments
window: The number of rows in each window.
Validation
window >= 1. ADomainErroris thrown otherwise.
Returns
nothing.
Related
PortfolioOptimisers.histogram_cell — Function
histogram_cell(
edges::AbstractVector,
v::AbstractVector
) -> Any
Returns the histogram cell of a flattened window, the bin index of each of its entries.
Arguments
edges: The cell edges, increasing.v: The flattened window.
Returns
cell::AbstractVector{<:Integer}: Entryjis the number ofedgesat or belowv[j].
Related
PortfolioOptimisers.neighbour_count — Function
neighbour_count(neighbours::CountOf, n::Integer)
neighbour_count(neighbours::FractionOf, n::Integer)Returns the number of neighbours that a nearest-neighbour selector keeps out of n candidates.
Arguments
neighbours: TheCountOfor theFractionOfof the candidates.n: The number of candidates.
Returns
l::Integer:min(neighbours.val, n)for a count, andfloor(Int, neighbours.val * n)for a fraction.
Related
PortfolioOptimisers.LeaderOptimiser — Type
const LeaderOptimiser = Union{BestConstantRebalancedPortfolio, JuMPOptimisationEstimator}Groups the optimisation estimators that a follow-the-leader rule can re-solve under the head's Allocation Set.
A leader of a FollowTheLeader rule must honour the set. The solver-free BestConstantRebalancedPortfolio takes a bounded set on its own wb and sets slots. A JuMP estimator takes any set as a second block of its entry, the keyword blocks of resolve_jump_optimiser. No other estimator has a slot or an entry for the set, so the alias excludes it. Each member of the fallback chain of the held estimator is a member of the alias too, see assert_leader_chain.
Related
PortfolioOptimisers.assert_leader_budget — Function
assert_leader_budget(opt::BestConstantRebalancedPortfolio)
assert_leader_budget(opt::JuMPOptimisationEstimator)Assert that the budgets of the held estimator of a FollowTheLeader rule admit the budget of one that the online head owns.
The head owns the budget: Σw = 1 holds on every Allocation Set, and cash is an asset with price relative one. The re-solve keeps that budget as the row Σw = k in the leader's model. It sets the net budget of the held optimiser, and of each member of its fallback chain, to one, see leader_chain. A budget that excludes one would then lose its effect with no message, and before the re-solve took the set as a block it left an empty feasible set, so that every step was a Held Step. The configuration alone decides it, so the constructor refuses it.
The solver-free estimator states no budget, because its fixed point lies on the simplex. A JuMP estimator is checked through the budgets of its JuMPOptimiser with leader_budget_admits_one. Each entry and the explicit default of a TimeDependent schedule in bgt, sbgt, gbgt or wb are checked with the other fields at their static values, through assert_time_dependent_substitution. A function schedule has a value only at a fold, so the check reads it only through its default. The fold loop resolves the schedule and rebuilds the rule through its constructor, see update_time_dependent_estimator, so a value that excludes one raises at that fold.
Algorithm
The JuMP method:
- Collect
args, thebgt,sbgt,gbgtandwbofjo, theJuMPOptimiserofopt. - Check the values in
argswithleader_budget_admits_one. A schedule passes this step. - Check each entry and the explicit
defaultof each schedule inargswithleader_budget_admits_one, throughassert_time_dependent_substitution. The other fields take their static values, andjump_optimiser_td_defaultsgives the static defaults.
Arguments
opt: The held estimator.
Validation
- The rules of
leader_budget_admits_onefor the budgets of a JuMP estimator.
Returns
nothing.
Related
PortfolioOptimisers.leader_budget_admits_one — Function
leader_budget_admits_one(; bgt, sbgt, gbgt, wb)
Assert that the static budgets of a held optimiser admit the budget of one of the online head.
The net budget goes through assert_net_budget_admits_one. The short and the gross budgets go through assert_gross_budget_admissible with the net budget of one in the place of bgt, as a ProgrammeAllocationSet checks its own. The head fixes the net exposure at one. So a number in sbgt and any gbgt over-determine the gross exposure, and a gross budget below one leaves no feasible weights.
Arguments
bgt: The net budget of the held optimiser.sbgt: The short budget of the held optimiser.gbgt: The gross budget of the held optimiser.wb: The weight bounds of the held optimiser.
Validation
- The rules of
assert_net_budget_admits_oneforbgt. - The rules of
assert_gross_budget_admissiblefor1,sbgt,gbgtandwb.
Related
PortfolioOptimisers.assert_net_budget_admits_one — Function
assert_net_budget_admits_one(bgt::Number)
assert_net_budget_admits_one(bgt::BudgetRange)
assert_net_budget_admits_one(bgt::BudgetCostEstimator)
assert_net_budget_admits_one(bgt::Option{<:UnresolvedValue})Assert that the net budget bgt of the held optimiser of a FollowTheLeader rule admits the budget of one.
The re-solve sets bgt to one, so the leader's model holds the head's row Σw = k in the place of the rows of bgt, see leader_chain. A number writes Σw = k · bgt, so the replacement keeps its feasible set only when it is one. A BudgetRange writes k · lb ≤ Σw ≤ k · ub, so the replacement narrows it to the budget of one only when its interval holds one. nothing writes no row, and the head's row fixes the budget.
A BudgetCostEstimator is refused in every form. It charges its cost against the budget, Σw + c(w) ∈ k · [lb, ub], with c(w) ≥ 0 the cost of the move from its reference w. The head's row Σw = k turns this into c(w) ∈ k · [lb − 1, ub − 1], a band on the cost that the wealth recursion of the head never pays, and the replacement of bgt with one would drop the cost with no message. factory sets the reference to the Price-Adjusted Allocation of the step, or keeps the caller's vector when fixed is true. A budget of one pins the leader to that reference, so the leader never trades, a budget below one leaves no feasible weights, and a budget above one bounds the cost of the move from the reference. None of these is a cost charged against the budget. A cost that the series pays is the fees of the head. A cost that the leader weighs is the fees of the held JuMPOptimiser, which factory measures from the Price-Adjusted Allocation of the step, and a ceiling on the trade is a Turnover on tn.
nothing, a TimeDependent schedule and any other BudgetEstimator pass: each is nothing or an Unresolved Value. assert_leader_budget checks the entries of a schedule. Any other type is a MethodError, because the check has no rule for it.
Arguments
bgt: The net budget of the held optimiser.
Validation
- A number is one. A
DomainErroris thrown otherwise. - The interval of a
BudgetRangeholds one. ADomainErroris thrown otherwise. bgtis not aBudgetCostEstimator. AnArgumentErroris thrown otherwise.bgtis a number,nothingor an Unresolved Value. AMethodErroris thrown otherwise.
Returns
nothing.
Related
PortfolioOptimisers.leader_min_rows — Function
leader_min_rows(opt::LeaderOptimiser)Returns the fewest sample rows on which the held estimator can re-solve.
An estimator whose tree holds a second moment needs two rows, because the covariance of one observation does not exist. Any estimator in the tree can state a larger floor through fit_min_rows.
Arguments
opt: The held estimator.
Returns
n::Integer: The larger of2for a tree that holds a second moment,1otherwise, andfit_min_rows(opt).
Related
PortfolioOptimisers.assert_leader_chain — Function
assert_leader_chain(opt::LeaderOptimiser, fb::Nothing)
assert_leader_chain(opt::JuMPOptimisationEstimator, fb::JuMPOptimisationEstimator)
assert_leader_chain(opt::BestConstantRebalancedPortfolio, fb::BestConstantRebalancedPortfolio)
assert_leader_chain(opt::LeaderOptimiser, fb)Assert that each member of the fallback chain of the held estimator of a FollowTheLeader rule can take the head's Allocation Set.
optimise runs the fallback fb of a member that fails, and it passes its keyword arguments to each member. So the second block that leader_allocation passes to a JuMP estimator reaches each member of its chain, and the leader of each member honours the set. A member of another kind does not read the block, and a precomputed result has nothing to solve, so either one answers outside the set. The solver-free estimator takes a bounded set through its own bounds and passes no block. So each member of its chain is solver-free too, and leader_chain gives each one the bounds of the set. The rule is that each member has the kind of the held estimator.
Algorithm
- When
fbisnothing, return. - When
fbhas the kind ofopt, check the budgets of a JuMP member withassert_leader_budget, and check the chain offb. - Otherwise, throw.
Arguments
opt: The held estimator, or the member of the chain beforefb.fb: The fallback ofopt.
Validation
fbisnothingor has the kind ofopt. AnArgumentErroris thrown otherwise.- The rules of
assert_leader_budgetfor a JuMP member.
Returns
nothing.
Related
PortfolioOptimisers.leader_chain — Function
leader_chain(opt::Nothing, set::AbstractAllocationSet, k::Number)
leader_chain(opt::JuMPOptimisationEstimator, set::AbstractAllocationSet, k::Number)
leader_chain(opt::BestConstantRebalancedPortfolio, set::BoundedAllocationSet, k::Number)Gives the held estimator of a FollowTheLeader rule, and each member of its fallback chain, the parts of the head's Allocation Set that do not reach it as a block.
The online head owns the budget of one, and the block of the set carries no budget row. So the function sets the net budget bgt of each JuMP member to k, and the leader's model holds the row Σw = k. assert_leader_budget admits only a budget that holds one, so the replacement changes no feasible set that the constructor admits. Without the replacement, bgt = nothing would solve away from the budget of one, and the wealth recursion would read weights that do not sum to one. The solver-free estimator has no model and takes no block. So each member of its chain takes the bounds wb and the sets of the bounded set.
Arguments
opt: The held estimator afterfactory(opt, w), a member of its chain, ornothingat the end of the chain.set: The head's Allocation Set, resolved once per fold.k: The budget of one,one(eltype(w))for the Price-Adjusted Allocationwof the step.
Returns
opt':optand its chain, with the budget or the bounds of the set, ornothingat the end of the chain.
Related
PortfolioOptimisers.leader_block — Function
leader_block(set::ProgrammeAllocationSet, opt::JuMPOptimisationEstimator, w::AbstractVector, X::ReturnsResult)
leader_block(set::BoundedAllocationSet, opt::JuMPOptimisationEstimator, w::AbstractVector, X::ReturnsResult)Gives the entry of the head's Allocation Set in the keyword blocks of the entry of a held JuMP estimator.
The entry is (set, X), as fit_allocation_set_block states: the set after stage 1 and after factory(set, w), and the rows that the head holds. So the block of the set reads its own prior on the rows of the head, and its turnover ceilings and its tracking errors read the Price-Adjusted Allocation of the step. The entry is an argument of one solve, so no estimator holds a Result. A BoundedAllocationSet holds no block. Its feasible set is the budget of one and its bounds, so the function puts its bounds wb and its sets into a ProgrammeAllocationSet whose block holds those two slots alone. That set takes the solver of the held estimator. Its block reads no rows and resolves no Calibration Rule, so no reader reads the solver, and the set fits no prior.
Arguments
set: The head's Allocation Set, resolved once per fold.opt: The held estimator.w: The Price-Adjusted Allocation of the step.X: Every row that the head holds, as aReturnsResult.
Returns
(set', X)::Tuple: The entry.
Related
PortfolioOptimisers.leader_allocation — Function
leader_allocation(opt::BestConstantRebalancedPortfolio, rd::ReturnsResult, w::AbstractVector, set::BoundedAllocationSet, X)
leader_allocation(opt::JuMPOptimisationEstimator, rd::ReturnsResult, w::AbstractVector, set::AbstractAllocationSet, X::ReturnsResult)Re-solves the held estimator on the sample under the head's Allocation Set, and returns the leader, or nothing on a Held Step.
The estimator runs the batch path that it runs on any ReturnsResult. An estimator with no prior reduces to the Coverage Universe of the sample, an estimator with a prior reduces to the Investable Mask of its prior, and both return a zero at every asset outside it. A JuMP estimator takes the set as a second block of its entry, so the one refusal branch of the entry covers the readers of the set, and an asset that the prior of the set cannot price departs with a warning, as in a batch fit with two blocks. A leader that stopped short of its certificate still trades, so the solver-free method warns and plays the fixed point.
Algorithm
The solver-free method:
- Give
optand each member of its chain the bounds and thesetsofsetwithleader_chain. - Optimise the result of
factorywithwonrd, givingres. - When the fixed point stopped at
itersbefore its certificate mettol, warn once and name the certificate. - Return
res.w.
The JuMP method:
- Pass
wintooptwithfactory. - Set the net budget of
optand of each member of its chain to one withleader_chain. - Optimise on
rdwith the entry of the set,leader_block, as the keywordblocks, givingres. When its retcode is anOptimisationSuccess, returnres.w. - Otherwise record a Held Step through
record_held_step!with the trials of the solver, and returnnothing.
Arguments
opt: The held estimator.rd: The rows that the head holds, as aReturnsResult, viewed at the sample. It holds the returns as they are,NaNwhere no return exists, under the pinned names and the Asset Panel of the buffer.w: The Price-Adjusted Allocation of the step.set: The resolved Allocation Set of the head, aBoundedAllocationSetfor the solver-free method.X: Every row that the head holds, as aReturnsResult. The JuMP method gives it to the block of the set, and the solver-free method does not read it.
Returns
w::Union{Nothing, AbstractVector}: The leader, ornothingon a Held Step.
Related
PortfolioOptimisers.loss_control_programme — Function
loss_control_programme(
gamma::Real,
slv::Union{Solver, AbstractVector{<:Solver}},
pe::AbstractPriorEstimator,
sc::Number,
so::Number
) -> MeanRisk{__T_opt, __T_r, MinimumRisk, Nothing, Nothing} where {__T_opt, __T_r}
Builds the programme of the short-term portfolio optimisation with loss control.
The programme is MeanRisk under MinimumRisk over WorstRealisation plus Variance scaled by gamma under QuadRiskExpr. Its prior states its own source. The method is typed on the solver and the prior, so the optimiser that it builds is concrete for them.
Arguments
gamma: The weight of the variance.slv: The solver of the programme.pe: The prior estimator of the programme.sc: Constraint scale factor.so: Objective scale factor.
Returns
opt::MeanRisk: The programme.
Related
PortfolioOptimisers.ensemble_programme — Function
ensemble_programme(
gamma::Real,
fees::Fees,
slv::Union{Solver, AbstractVector{<:Solver}},
pe::AbstractPriorEstimator,
sc::Number,
so::Number
) -> MeanRisk{JuMPOptimiser{__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache}, Variance{RiskMeasureSettings{Float64, Nothing, Bool}, Nothing, Nothing, Nothing, QuadRiskExpr, EigenFallbackSquareRoot, SquareRootRatio, Nothing}, MaximumUtility{var"#s185"}, Nothing, Nothing} where {__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache, var"#s185"<:Real}
Builds the programme of the online low-dimension ensemble method.
The programme is MeanRisk under MaximumUtility at the risk aversion gamma over Variance under QuadRiskExpr, and it charges fees. Its prior states its own source. The method is typed on the solver and the prior, so the optimiser that it builds is concrete for them.
Arguments
gamma: The risk aversion over the predictive variance.fees: The fees of the programme, aTurnoverfee for the rule.slv: The solver of the programme.pe: The prior estimator of the programme.sc: Constraint scale factor.so: Objective scale factor.
Returns
opt::MeanRisk: The programme.
Related
PortfolioOptimisers.FollowTheLeadingHistoryState — Type
struct FollowTheLeadingHistoryState{__T_n, __T_st, __T_h, __T_p, __T_born} <: AbstractPartialFitStateHolds the live experts of a follow-the-leading-history rule, with their Rule States, start periods and weights.
It is the state of FollowTheLeadingHistory: what the rule keeps from one update to the next. The rule refuses a merge of two such states, because the head's allocation depends on the order of the rows.
Fields
n: Number of observations folded into the state.
st: The state of each live expert,nothingwhen the base rule keeps nothing.
h: The allocation that each live expert holds during the current period.
p: The weight over the live experts during the current period.
born: The start period of each live expert, from which its lifetime counts.
Related
PortfolioOptimisers.expert_alive — Function
expert_alive(born::Integer, t::Integer) -> Any
Checks whether the copy started at period born is alive at period t, under the lifetime of follow the leading history.
The lifetime is that of [283]. The function reads t >= born as given.
Mathematical definition
\[\begin{align} k &= r\, 2^{j}\,, \quad r \text{ odd}\,, \\ k &\in S_t \iff k \leq t \leq k + 2^{j + 2} + 1\,. \end{align}\]
Where:
- $k$: Start period of the copy,
born. - $r$, $j$: Odd part of $k$ and the exponent of the largest power of two that divides $k$.
- $S_t$: Working set of period $t$.
- $t$: Period index, counted from one.
Hazan and Seshadhri [283] call $2^{j + 2} + 1$ the lifetime of $k$, so the copy is alive in $2^{j + 2} + 2$ periods.
Arguments
born: The start period of the copy.t: The period.
Returns
alive::Bool:t <= born + 2^(j + 2) + 1, withjthe number of trailing zeros ofborn.
Related
FollowTheLeadingHistory: the rule whose pruning reads the lifetime.
References
- [283] E. Hazan and C. Seshadhri. Efficient learning algorithms for changing environments. In: Proceedings of the 26th International Conference on Machine Learning, 393–400 (2009). Section 3.1 and Appendix A.
References
- [283]
- E. Hazan and C. Seshadhri. Efficient learning algorithms for changing environments. In: Proceedings of the 26th International Conference on Machine Learning (2009); pp. 393–400.