Base Online Portfolio Selection: private API
PortfolioOptimisers.simplex_bounds — Function
simplex_bounds(wb::WeightBounds) -> Bool
Checks whether a resolved bound is (0, 1) at every asset. The bound is then the simplex, and the projection is a sort or a normalisation, not a root.
Related
PortfolioOptimisers.assert_feasible_bounds — Function
assert_feasible_bounds(wb::WeightBounds)
Refuses a resolved bound that no allocation on the budget satisfies.
Validation
sum(wb.lb) <= 1 <= sum(wb.ub). AnArgumentErroris thrown otherwise.
Related
PortfolioOptimisers.assert_finite_raw_step — Function
assert_finite_raw_step(q::AbstractVector)
Refuses a raw step with a non-finite entry, because no projection of an infinite or undefined step lies on the budget.
Validation
all(isfinite, q). ADomainErroris thrown otherwise.
Related
PortfolioOptimisers.budget_or_held_step — Function
budget_or_held_step(
wn::AbstractVector,
w::AbstractVector,
proj::AbstractProjectionGeometry,
set::AbstractAllocationSet
) -> Any
Returns the projected allocation wn when it meets the budget, and the Held Step otherwise.
A root found from the kinks is exact on every input whose kinks floating point can hold. The root of a barrier geometry can lose its budget to cancellation, when a base is far larger than the step it restores. This function catches that loss, so no allocation off the budget reaches the rule.
Algorithm
- When
isapprox(sum(wn), 1)holds, returnwn. The default tolerance ofisapproxis a relative error ofsqrt(eps)of the element type,1.49e-8forFloat64. - Otherwise, record a Held Step on the current
ProjectionStepwithrecord_held_step!. Its reason names the set, the geometry and the sum, and it has no solver trials. - Return a copy of
w, as a failed projection programme ofprojectdoes.
Arguments
wn: The projected allocation.w: The Price-Adjusted Allocation the step trades from.proj: The geometry, named in the record.set: The set, named in the record.
Returns
w'::Vector:wn, orwcopied on a Held Step.
Related
PortfolioOptimisers.bounded_quadratic_projection — Function
bounded_quadratic_projection(
q::AbstractVector,
wb::WeightBounds
) -> Any
bounded_quadratic_projection(
q::AbstractVector,
wb::WeightBounds,
h::AbstractVector
) -> Any
Projects a raw step onto a bounded set in the norm of a non-negative diagonal h, at the exact root of the budget.
At h = 1, the default, it is the Euclidean arm of project off the simplex bounds. With the gradient mass of AdaptiveSubgradient in h, it is the DiagonalProjection on every bound.
Mathematical definition
\[\begin{align} \boldsymbol{w}^{+} &= \underset{\boldsymbol{w} \in \mathcal{W}}{\arg\min} \; \tfrac{1}{2} \sum_i h_i (w_i - q_i)^2\,, \\ w_i(\theta) &= \min\left(\max\left(q_i - \theta / h_i,\, l_i\right),\, u_i\right)\,. \end{align}\]
Where:
- $\boldsymbol{w}^{+}$: Projected allocation, the answer of the projection onto the Allocation Set.
- $\mathcal{W}$: Allocation Set.
- $\boldsymbol{h}$: Non-negative diagonal of the norm, one entry for each asset.
- $\boldsymbol{q}$: Raw step, the vector the rule's unconstrained step gives before the projection onto the Allocation Set.
- $l_i$, $u_i$: Lower and upper bounds of asset $i$ on a
BoundedAllocationSet. - $\theta$: Budget multiplier, the root of $\sum_i w_i(\theta) = 1$.
When every $h_i$ is positive, the projection is $\boldsymbol{w}(\theta)$ at the root. The budget $\sum_i w_i(\theta)$ does not increase in $\theta$, and it is linear between the kinks at $h_i (q_i - u_i)$ and $h_i (q_i - l_i)$, so the line through the two kinks that bracket the root gives the root exactly.
When some $h_i$ is zero, the norm is a seminorm. Let $P = \{i : h_i > 0\}$ and $Z = \{i : h_i = 0\}$. The objective is strictly convex in $\boldsymbol{w}_P$, so every minimiser has the same $\boldsymbol{w}_P$, and only $\boldsymbol{w}_Z$ is free. The function returns the limit of the projection in $\mathrm{diag}(\boldsymbol{h} + \delta \boldsymbol{1})$ as $\delta \to 0^{+}$. That limit is the minimiser nearest $\boldsymbol{q}$ in the Euclidean norm. Let $r = 1 - \sum_{i \in P} \min(\max(q_i, l_i), u_i)$. Then:
- If $\sum_{i \in Z} l_i \leq r \leq \sum_{i \in Z} u_i$, each $w_i$ with $i \in P$ is $\min(\max(q_i, l_i), u_i)$, and $\boldsymbol{w}_Z$ is the Euclidean projection of $\boldsymbol{q}_Z$ onto its bounds at the budget $r$.
- If $r > \sum_{i \in Z} u_i$, each $w_i$ with $i \in Z$ is $u_i$, and $\boldsymbol{w}_P$ is the projection of $\boldsymbol{q}_P$ in $\mathrm{diag}(\boldsymbol{h}_P)$ at the budget $1 - \sum_{i \in Z} u_i$.
- If $r < \sum_{i \in Z} l_i$, the same holds with $l_i$ in place of $u_i$.
With no positive $h_i$, $P$ is empty and the projection is the Euclidean one.
Algorithm
- Refuse a non-finite
qwithassert_finite_raw_step, bounds that no allocation on the budget satisfies withassert_feasible_bounds, and a negative orNaNentry ofh. - When every entry of
his positive, return the projection at the budget one withbudget_root_projection. Stop. - When no entry of
his positive, return the projection at unit weights and the budget one withbudget_root_projection. Stop. - Otherwise, split the assets into
pos, wherehis positive, andzer, where it is zero. Clipq[pos]to its bounds, and formr, the budget that the clipped entries leave. - When
ris above the sum of the upper bounds ofzer, holdzerat those bounds, and projectq[pos]at the budget that they leave withbudget_root_projection. Do the same with the lower bounds whenris below their sum. - Otherwise, keep the clipped
q[pos], and projectq[zer]at unit weights and the budgetrwithbudget_root_projection. - Return the two parts as one vector.
Arguments
q: The raw step.wb: The resolved bounds.h: The diagonal of the norm, non-negative.
Validation
all(isfinite, q). ADomainErroris thrown otherwise.Σ lb ≤ 1 ≤ Σ ubover the resolved bounds. AnArgumentErroris thrown otherwise.all(>= 0, h). ADomainErroris thrown otherwise.
Returns
w'::Vector: The projected allocation, a new vector.
Related
PortfolioOptimisers.budget_root_projection — Function
budget_root_projection(
q::AbstractVector,
lb::AbstractVector,
ub::AbstractVector,
h::AbstractVector,
c::Real
) -> Any
Projects q onto its bounds at the budget c, in the norm of a positive diagonal h.
This is the scalar root of bounded_quadratic_projection. The function finds the root θ of $\sum_i \min(\max(q_i - \theta / h_i, l_i), u_i) = c$ with breakpoint_root, over the kinks $h_i (q_i - u_i)$ and $h_i (q_i - l_i)$, and returns the clipped step at that root. It does not check that the bounds reach c. The caller passes a budget that they reach.
Arguments
q: The raw step.lb,ub: The lower and upper bounds, one entry for each entry ofq.h: The diagonal of the norm, positive.c: The budget.
Returns
w'::Vector: The projected vector, a new vector.
Related
PortfolioOptimisers.breakpoint_root — Function
breakpoint_root(f, x::AbstractVector) -> Any
breakpoint_root(f, x::AbstractVector, c::Real) -> Any
Finds, from its kinks x, the point at which a non-increasing, piecewise linear budget function f crosses the budget c, one by default.
The Euclidean, diagonal and entropic projections onto a bounded set each clip the raw step at one scalar. The budget is linear in that scalar between the kinks at which an asset reaches a bound, so the line through the two kinks that bracket the root gives the root exactly. The search reads the kinks and not the width of a bracket, so a raw step whose entries span hundreds of binades is as exact as a step near the simplex. A kink at an infinite bound is not a kink, and the budget is linear past the last finite kink.
Algorithm
- Drop the non-finite kinks and sort the rest, giving
x. When no kink is left, use the one kink0. - Search the indices of
xby bisection forlo, the last kink at whichfis at leastc, andhi = lo + 1. The index0stands for the linear tail below the first kink, and the indexlength(x) + 1for the tail above the last kink. - Take the segment
(a, b)that holds the root withbreakpoint_segment. - When
f(a) == f(b), returna. Otherwise, return the point at which the line through(a, f(a))and(b, f(b))crossesc.
Arguments
f: The budget as a function of the scalar, non-increasing and linear between kinks.x: The kinks. The non-finite ones are dropped.c: The budget thatfcrosses.
Returns
r: The scalar at whichfcrossesc.
Related
PortfolioOptimisers.breakpoint_segment — Function
breakpoint_segment(
x::AbstractVector,
lo::Integer,
hi::Integer
) -> Tuple{Any, Any}
Returns the segment of the budget of breakpoint_root that holds the root, from the kinks x[lo] and x[hi].
An index past either end of x stands for a linear tail. The second point on a tail lies beyond the outer kink by the magnitude of that kink, and by at least one.
Algorithm
- When
lo == 0, return(x[1] - max(1, abs(x[1])), x[1]). - When
hi > length(x), return(x[end], x[end] + max(1, abs(x[end]))). - Otherwise, return
(x[lo], x[hi]).
Related
PortfolioOptimisers.bounded_root — Function
bounded_root(f, lo, hi) -> Any
Finds the point on [lo, hi] at which a non-increasing budget function f crosses one, by bisection until the bracket collapses to adjacent floating-point values.
The projection of a barrier geometry onto a bounded set clips the raw step at one scalar. The budget is monotone in that scalar but not linear, so the function bisects it. bisection_cap of the type of the bracket caps the number of halvings. The cap is not less than the number of halvings in which a bracket over the whole range of the type collapses, so no bracket stops before it reaches its resolution. The midpoint is lo / 2 + hi / 2, which does not overflow on a bracket near floatmax.
Algorithm
- Take the midpoint
mid = lo / 2 + hi / 2. Stop whenmidequalsloorhi, because the bracket then holds two adjacent values. - Set
lo = midwhenf(mid) >= 1, andhi = midotherwise. - Repeat steps 1 and 2, at most
bisection_captimes. - Return
lo / 2 + hi / 2.
Arguments
f: The budget as a function of the scalar, non-increasing.lo,hi: A bracket withf(lo) ≥ 1 ≥ f(hi).
Returns
x: The scalar at whichfcrosses one.
Related
PortfolioOptimisers.bisection_cap — Function
bisection_cap(::Type{T}) where {T <: AbstractFloat}
bisection_cap(::Type)Returns a number of halvings that is enough for any bisection bracket of type T to collapse to adjacent values of T.
Mathematical definition
\[\begin{align} c(T) &= e_{\max}(T) - e_{\min}(T) + 2 p(T)\,. \end{align}\]
Where:
- $c(T)$: Cap on the halvings for the type $T$.
- $e_{\max}(T)$, $e_{\min}(T)$: Exponents of
floatmax(T)andfloatmin(T). Their difference counts the normal binades of $T$. - $p(T)$: Precision of $T$ in bits. Twice the precision covers the significand and the subnormal binades below
floatmin(T).
The cap is 2151 for Float64, 301 for Float32 and 51 for Float16. The widest bracket, [-floatmax(T), floatmax(T)], collapses at the smallest subnormal after 2099, 278 and 41 halvings, so the cap is an upper bound and not the exact count.
The cap only guards bounded_root. On a floating-point type the collapse check stops the loop first. Any other type takes the cap of Float64, and the loop does not need a tight cap there. An AD dual and a quantity with units compare by their values, so the collapse check still stops the loop. A Rational bracket never collapses, so no cap comes from it, and a Rational{Int} bracket overflows its integers after about sixty halvings.
Related
PortfolioOptimisers.project_simplex — Function
project_simplex(v::AbstractVector) -> Any
Projects a vector onto the probability simplex in Euclidean distance, by a sort of its entries.
The sort is the algorithm of Duchi et al. [248].
Mathematical definition
\[\begin{align} \boldsymbol{w}^{+} &= \underset{\boldsymbol{w} \in \Delta_N}{\arg\min} \; \tfrac{1}{2} \lVert \boldsymbol{w} - \boldsymbol{v} \rVert_2^2\,, \\ w^{+}_i &= \max(v_i - \theta, 0)\,, \\ \rho &= \max \left\lbrace j : u_j - \frac{1}{j} \left( \sum_{k \leq j} u_k - 1 \right) > 0 \right\rbrace\,, \\ \theta &= \frac{1}{\rho} \left( \sum_{k \leq \rho} u_k - 1 \right)\,. \end{align}\]
Where:
- $\boldsymbol{w}^{+}$: Projected allocation, the answer of the projection onto the Allocation Set.
- $\Delta_N$: Probability simplex over the $N$ assets.
- $\boldsymbol{v}$: Vector to project.
- $\theta$: Budget multiplier, the root of $\sum_i w_i(\theta) = 1$.
- $\rho$: Number of positive entries of the projection.
- $\boldsymbol{u}$: Entries of $\boldsymbol{v}$ in decreasing order.
The entries of $\boldsymbol{v}$ below $\theta$ become exactly zero. That is the sparsity of every rule under the Euclidean geometry.
A non-negative $\boldsymbol{v}$ whose sum misses one by rounding alone is on the simplex already, and the projection renormalises it:
\[\begin{align} \boldsymbol{w}^{+} &= \frac{\boldsymbol{v}}{s} \quad \text{if } \boldsymbol{v} \geq 0 \text{ and } \lvert s - 1 \rvert \leq (N + 1) \varepsilon\,,\quad s = \boldsymbol{1}^\intercal \boldsymbol{v}\,. \end{align}\]
Where:
- $s$: Sum of the entries of $\boldsymbol{v}$.
- $\varepsilon$: Machine epsilon of the element type, twice its unit roundoff $u$.
The bound $(N + 1) \varepsilon$ is budget_rounding.
The exact projection of such a vector lifts every zero entry by $(1 - s) / N$ when $s < 1$, and a later step compounds that residue as a real holding. The quotient keeps a zero exactly zero. It differs from the exact projection by at most $\lVert \boldsymbol{v} - \boldsymbol{v} / s \rVert$, because a projection is non-expansive and $\boldsymbol{v} / s$ is its own projection. That distance is within the rounding of $\boldsymbol{v}$ itself.
Algorithm
- Sum
v, givings. When every entry ofvis non-negative andabs(s - 1)is at mostbudget_rounding, returnv ./ s. - Sort
vin decreasing order, givingu. - For each
j, addu[j]to the running sumcssand taket = (css - 1) / j. Whenu[j] - t > 0, setrho = jandtheta = t. - Return
max.(v .- theta, 0).
Arguments
v: The vector to project.
Returns
w::Vector: The projection, a new vector summing to one.
Related
References
- [248] J. Duchi, S. Shalev-Shwartz, Y. Singer and T. Chandra. Efficient projections onto the l1-ball for learning in high dimensions. In: Proceedings of the 25th International Conference on Machine Learning, 272–279 (2008). Section 3, Equations 3 to 6 and Figure 1.
PortfolioOptimisers.budget_rounding — Function
budget_rounding(::Type{T}, n::Integer) where {T <: Union{Integer, Rational}}
budget_rounding(::Type{T}, n::Integer)Returns the rounding bound on the sum of an n-vector of type T that sums to one in exact arithmetic.
Mathematical definition
\[\begin{align} b(T, n) &= (n + 1) \varepsilon\,. \end{align}\]
Where:
- $b(T, n)$: Bound on $\lvert \boldsymbol{1}^\intercal \boldsymbol{v} - 1 \rvert$ for a computed $\boldsymbol{v}$ of $n$ entries of type $T$.
- $\varepsilon$: Machine epsilon of the element type, twice its unit roundoff $u$.
The bound is deterministic, to first order in $u$. The Price-Adjusted Allocation w .* x ./ ⟨w, x⟩ sums to one in exact arithmetic whatever Σ w is. Each of its entries carries a relative error of at most $(n + 2) u$: one rounding in the product, one in the quotient, and $n$ in the dot product. The pairwise sum adds at most $\lceil \log_2 n \rceil u$. The total, $(n + 2 + \lceil \log_2 n \rceil) u$, is at most $2 (n + 1) u = b(T, n)$ for every $n \geq 1$.
The probabilistic bound $\sqrt{n} \varepsilon$ holds at one step with high probability, but not at every step of a long recursion. One miss leaves a residue that later steps compound. An integer or Rational type takes zero, because its sums carry no rounding. An AD dual takes the bound of its value type, through its own eps.
Related
PortfolioOptimisers.gram_geometry — Function
gram_geometry(proj::AbstractProjectionGeometry, A::AbstractMatrix)
gram_geometry(proj::GramProjection, A::AbstractMatrix)Returns the geometry in which a rule with a Gram matrix projects at this step.
For a GramProjection it is a new geometry with the same solver and with the rule's current matrix A in its A field. Every other geometry comes back unchanged.
Related
PortfolioOptimisers.HeldStep — Type
struct HeldStep{__T_ts, __T_reason, __T_trials}Records a Held Step, a projection of one row that did not give an allocation on the budget, so the step traded nothing.
A projection onto a ProgrammeAllocationSet, or in a GramProjection, is a programme, and a programme can fail. It is infeasible on a day when a turnover ceiling and a cap cannot both hold. It can also time out, stop a MIP at its limit, or meet a covariance cone with no finite data on its first rows. A closed-form root can also miss the budget in floating point, as budget_or_held_step states. The step then returns the Price-Adjusted Allocation that it got, the book that the fund already holds, so the fund trades nothing. The state of the rule still takes in the row. The head warns once with the timestamp of the row. Its Recursion Result carries the record of the last folded row inside an OptimisationSuccess, so a fallback chain never runs on a hold. A step never throws on a failed solve, and never falls back to a weaker set, because a constraint that the step drops on the day it binds does not constrain.
Fields
ts: The timestamp of the row whose projection the step held. It is the index of the row in the fold when the rows have no timestamps, andnothingoutside a fold.
reason: The projection of the row that the step held, and the reason.
trials: The solver trials of the failed programme, thetrialsof aJuMPResult, ornothingwhen the projection built no programme.
Related
PortfolioOptimisers.ProjectionStep — Type
struct ProjectionStep{__T_rows, __T_ts, __T_x_src}Holds the context of one row for every projection of that row: the rows that the head holds, the timestamp of the row, the head's flags and the Held Steps recorded so far.
The projection of the Online Update is project(proj, set, q, w), with four arguments and no more. Two things must reach it outside that signature. The covariance cone and the tracking error of a programme set read the head's rows, and the head must see the record of a Held Step. Both go on the task-scoped PROJECTION_STEP. The source of the head's step, its x_src, goes on the step too, because the readers of the rows inside a rule, such as the refit of a forecaster or the row selector of a leader, take the rows through the signature of the Online Update, and that signature has no source. head_frame_returns reads it. The head opens one step for each row through with_projection_step, around the whole Online Update. So every projection of that row, those of a mixture's experts and that of its blend, reads one set of rows and writes one log. The rows are the ones that the update gets, a ReturnsResult of the rows as they arrived, under the pinned names and the Asset Panel of the buffer. So a programme set fits its prior through buffer_returns_result, as a batch head does. Outside a step, a projection reads no rows and reports a hold as a warning.
Fields
rows: The rows that the head holds through the period, aReturnsResultof the rows as they arrived, ornothing.
ts: The timestamp of the row, or the index of the row in the fold.
strict: The head'sstrictflag. A programme set reads it when it resolves its rows, so it refuses a name that an exposure row states and the universe does not carry, as the head refuses one.
x_src: The source of the head's step,nothingor anAbstractReturnsSource. A rule that reads the returns of the rows reads them in excess of the benchmark when it isExcessSource, throughhead_frame_returns.
held: The Held Steps recorded during this row, in the order in which their projections failed.
Related
PortfolioOptimisers.PROJECTION_STEP — Constant
const PROJECTION_STEPHolds the task-scoped ProjectionStep that a projection reads. It is nothing outside a step.
Related
PortfolioOptimisers.with_projection_step — Function
with_projection_step(
f,
rows::Union{Nothing, ReturnsResult},
ts;
strict,
x_src
) -> Tuple{Any, Vector{HeldStep}}
Runs f() inside a ProjectionStep over the rows rows at ts, with the head's strict flag and the source x_src of its step.
It returns (f(), held), the result of the update and the Held Steps that its projections recorded. held is empty when every projection met the budget.
Related
PortfolioOptimisers.record_held_step! — Function
record_held_step!(reason::AbstractString, trials)
Records a Held Step on the current ProjectionStep. Outside a step, it warns at once and records nothing.
Related
PortfolioOptimisers.projection_step_rows — Function
projection_step_rows() -> Any
Returns the rows that the current ProjectionStep holds, or nothing outside a step.
Related
PortfolioOptimisers.projection_step_strict — Function
projection_step_strict() -> Bool
Returns the head's strict flag that the current ProjectionStep carries, or false outside a step.
Related
PortfolioOptimisers.head_frame_returns — Function
head_frame_returns(rows::ReturnsResult)Returns the returns of the rows that a rule reads, in the frame of the head: in excess of the benchmark when the head's x_src is ExcessSource, and as they arrived otherwise.
The head's x_src comes from the current ProjectionStep, and it is nothing outside a step. The rows themselves stay raw, so a prior or a leader that reads them reads its own source. The function never builds a ReturnsResult: it gives the matrix of benchmark_relative_returns.
Validation
- The head's
x_srcis notExcessSource, orrowscarries a benchmark. AnArgumentErroris thrown otherwise, throughbenchmark_relative_returns. rowsholds returns, which the rows of the head always do. ATypeErroris thrown otherwise.
Related
PortfolioOptimisers.assert_rule_admits_set — Function
assert_rule_admits_set(alg::AbstractOnlinePortfolioSelectionAlgorithm, set::AbstractAllocationSet)Refuses, when the head is built, a rule and an Allocation Set that cannot work together.
The default admits every pair. A rule that holds an optimisation estimator with no model for a programme set, such as FollowTheLeader, refuses that set by name. A FollowTheLeader whose held estimator, or a member of its fallback chain, is a FactorRiskContribution refuses a programme set with a semidefinite phylogeny. A rule over other rules sends the check to each of them.
Related
PortfolioOptimisers.rows_needed_max — Function
rows_needed_max(a, b)Returns the larger of two row needs. nothing stands for every row, so it is larger than any number.
Related
PortfolioOptimisers.rule_tree_fields — Function
rule_tree_fields(alg::AbstractOnlinePortfolioSelectionAlgorithm)Returns the names of the fields of a rule whose type can hold a rule, a vector of rules or an optimisation estimator.
These fields are the rule tree that a schedule can reach. A schedule stands only in an optimiser, and a rule holds an optimiser only as the leader of a FollowTheLeader. A rule over rules, such as an ExpertMixture or a FollowTheLeadingHistory, holds a leader through its sub-rules. A generated function computes the tuple once for each type of rule, from the field types, as time_dependent_candidate_fields does. So a rule that holds no optimiser and no rule gives an empty tuple at compile time, and the walks of is_time_dependent and update_time_dependent_estimator read none of its fields.
Related
PortfolioOptimisers.is_time_dependent — Method
is_time_dependent(alg::AbstractOnlinePortfolioSelectionAlgorithm)
is_time_dependent(v::AbstractVector{<:AbstractOnlinePortfolioSelectionAlgorithm})
assert_time_dependent_fold_count(alg::AbstractOnlinePortfolioSelectionAlgorithm, n::Integer, all_binds::Bool = true)
assert_time_dependent_fold_count(v::AbstractVector{<:AbstractOnlinePortfolioSelectionAlgorithm}, n::Integer, all_binds::Bool = true)
update_time_dependent_estimator(alg::AbstractOnlinePortfolioSelectionAlgorithm, ctx::TimeDependentContext, all_binds::Bool = true)
update_time_dependent_estimator(v::AbstractVector{<:AbstractOnlinePortfolioSelectionAlgorithm}, ctx::TimeDependentContext, all_binds::Bool = true)Walks the rule tree for the schedules in the optimisers that the rules hold.
A rule is static, but the leader of a FollowTheLeader is an optimiser, and a field of the leader can hold a TimeDependent. The leader solves at each step of the head, and its optimise resets every schedule to its fold-less value first. So the fold loop of the head must resolve these schedules at the fold, before the step reads the leader. The OnlinePortfolioSelection methods of the three verbs call these methods on alg, as a JuMP head calls them on its inner JuMPOptimiser.
The walk reads the fields of rule_tree_fields. A field that holds a rule or a vector of rules recurses, and a field that holds an optimiser takes the method of the optimiser. A rule that holds no schedule answers false, checks nothing, and comes back as the same object, so the head is not rebuilt for it. The leader has no inner fold loop, so the head's loop is the nearest loop of each schedule in it, and the walk passes all_binds on unchanged. The fold-less value needs no walk, because each leader resets its own schedules in its own optimise.
Algorithm
The update of a rule:
- Return
algunchanged whenis_time_dependentisfalsefor it. - Read the names
fnsof the fields of the rule tree withrule_tree_fields. - Resolve the value of each field in
fnsatctxwithupdate_time_dependent_estimator. - Rebuild
algwith the resolved values throughrebuild_struct.
The update of a vector of rules returns v unchanged when no rule in it holds a schedule. Otherwise it maps the update of a rule over v.
Arguments
alg: The rule.v: A vector of rules, such as the experts of anExpertMixture.n: The number of folds.ctx: The context of the fold.all_binds: Asupdate_time_dependent_estimatortakes it.
Validation
- Each vector schedule in the tree has
nentries, else aDimensionMismatchthat names the field is thrown, throughassert_time_dependent_fold_count.
Returns
flag::Bool:truewhen an optimiser in the tree holds a schedule.alg: The rule, with each schedule in its tree resolved at the fold. A vector of rules gives a vector.
Related
PortfolioOptimisers.rule_state_view — Function
rule_state_view(st::Nothing, i, args...)
rule_state_view(st::AbstractPartialFitState, i, args...)
rule_state_view(st, i, args...)Slices the state of a rule to the selected assets.
A nothing state stays nothing. A state that subtypes AbstractPartialFitState goes to its own port_opt_view. The function refuses any other state.
Validation
stisnothingor anAbstractPartialFitState. AnArgumentErroris thrown otherwise.
Related
PortfolioOptimisers.price_adjusted_allocation — Function
price_adjusted_allocation(
w::AbstractVector,
x::AbstractVector
) -> Any
Returns the Price-Adjusted Allocation, the book that the fund holds at the end of a period before it trades.
It is one row of the self-financing Weight Drift at budget one. Every trade of the family starts from it. The update of BuyAndHold returns this vector, a turnover ceiling on a ProgrammeAllocationSet bounds the distance from it, and every projection gets it as its w argument.
Mathematical definition
\[\begin{align} \hat{\boldsymbol{w}}_t &= \frac{\boldsymbol{w}_t \odot \boldsymbol{x}_t}{\boldsymbol{w}_t^\intercal \boldsymbol{x}_t}\,. \end{align}\]
Where:
- $\hat{\boldsymbol{w}}_t = \boldsymbol{w}_t \odot \boldsymbol{x}_t / \langle \boldsymbol{w}_t, \boldsymbol{x}_t \rangle$: Price-Adjusted Allocation, the wealth held in each asset at the end of period $t$.
- $\boldsymbol{w}_t$: Iterate of the rule at period $t$, the allocation its update reads.
- $\boldsymbol{x}_t$: Price relative vector of period $t$, each asset's price over its price one period earlier.
- $\odot$: Elementwise product.
Arguments
w: The allocation held during the period.x: The price relative of the period.
Returns
ŵ::Vector: The price-adjusted allocation, a new vector.
Related
PortfolioOptimisers.project_start — Function
project_start(
proj::AbstractProjectionGeometry,
set::Union{Nothing, AbstractAllocationSet},
w::AbstractVector
) -> Any
Projects a start allocation w once onto the Allocation Set set in the geometry proj, with w as its own reference.
The head projects its Start Allocation with this function, and so does each expert of an ExpertMixture or a FollowTheLeadingHistory. So the allocation held during the first period lies in the set. When set is nothing, or when it reads the head's rows and so has no constraints before the first row, the function returns w as it is, and the first Online Update projects it.
Related
PortfolioOptimisers.OnlinePortfolioSelectionState — Type
struct OnlinePortfolioSelectionState{__T_n, __T_w, __T_st, __T_X, __T_nx, __T_nb, __T_pnl, __T_amsk, __T_ts, __T_hold} <: AbstractPartialFitStateHolds the Partial Fit State of an online portfolio selection head: the Rule State, the rows, the Fold Context and every folded timestamp.
The pair (st, w) is the Rule State, the unit over which the family recurses. The state holds once the rows that any rule of the tree reads, as a ReturnsBufferState that owns the returns. The buffer keeps the rows of the Returns Result as they arrived, with NaN where there was no return, and under a time-varying panel it keeps the active mask of each row beside it. It keeps every other field of the Returns Result too, such as the benchmark and the factor returns, so the rows that a rule reads drop no field. rows_needed of the rule tree caps the buffer, and the buffer is nothing for a tree that reads no rows. At every row the head reads the buffer out as a ReturnsResult through buffer_returns_result, so a statistic over the rows reduces to its Coverage Universe as a batch fit over the same window does. No cap applies to the timestamps, so Resume works for a rule with no state. The active mask of the last folded row is the Investable Mask on which optimise(opt) with no data reduces the allocation, and it is nothing under a static panel. The recursion keeps the full w and never carries a forced zero.
Fields
n: Number of observations folded into the state.
w: The allocation held during the current period. It covers the full pinned universe and sums to one.
st: The state of the rule: what the rule keeps from one update to the next. It isnothingfor a rule that keeps nothing.
X: The rows of returns that any rule of the tree reads, aReturnsBufferStateof the rows as they arrived, of their active masks, and of every other field of the Returns Result.rows_neededcaps it. It isnothingwhen the tree reads no rows.
nx: Names of the asset columns, pinned by the first step.
nb: Names of the benchmark columns, pinned by the first step when a reader of the head's group statesExcessSource, seegroup_source, ornothing. A head whose group reads no benchmark pins none.
pnl: The staticAssetPanelof the universe, pinned by the first step, ornothing. The state never holds a time-varying panel here.
amsk: The active mask of the last folded row under a time-varying panel, which is the Investable Mask of the Recursion Result, ornothingunder a static panel.
ts: Timestamps of the folded observations, in order and with no cap, ornothingwhen the rows hold none.
hold: TheHeldSteprecord of the last folded row when the step held a projection of that row, ornothingwhen every projection of it met the budget. The return code of the Recursion Result carries it.
Constructors
OnlinePortfolioSelectionState(; n::Integer = 0, w::AbstractVector, st = nothing, X::Option{<:ReturnsBufferState} = nothing, nx::Option{<:VecStr} = nothing, nb::Option{<:VecStr} = nothing, pnl::Option{<:AssetPanel} = nothing, amsk::Option{<:AbstractVector{<:Bool}} = nothing, ts::Option{<:AbstractVector} = nothing, hold::Option{<:HeldStep} = nothing) -> OnlinePortfolioSelectionStateKeywords correspond to the struct's fields.
Validation
n >= 0. ADomainErroris thrown otherwise.length(nx) == length(w)whennxis given, andlength(amsk) == length(w)whenamskis given. ADimensionMismatchis thrown otherwise.pnlis static when it is notnothing. AnArgumentErroris thrown otherwise, because the buffer holds the masks of a time-varying panel with the rows.
View parameters
OnlinePortfolioSelectionState defines its own port_opt_view method rather than deriving one from field tags.
- The method passes
args...to the view of the state of the rule and to the view of the rows buffer. wis sliced and renormalised throughrenormalised_view, as a copy. The recursion keeps the fullw.stgoes to the view of the state of the rule throughrule_state_view.X,nx,pnlandamskare sliced along the asset axis.nbis sliced along the asset axis when it holds one name per asset, which is the names of a matrix benchmark. A single name is that of a vector benchmark, which every asset shares, so it is copied.n,tsandholdpass through, andtsis copied.
Related
Base.copy — Method
copy(
x::OnlinePortfolioSelectionState
) -> OnlinePortfolioSelectionState{var"#s185", <:AbstractVector{T}} where {var"#s185"<:Integer, T}
Copies an OnlinePortfolioSelectionState so that the copy shares no array with the original.
The method calls copy on w, st, X, nx, nb, amsk and ts. The state of the rule and the rows buffer copy their own arrays through their Base.copy methods. n, pnl and hold pass through unchanged.
Related
PortfolioOptimisers.renormalised_view — Function
renormalised_view(w::Nothing, i)
renormalised_view(w::AbstractVector, i)Slices an allocation to the selected assets and renormalises it to sum to one, as a copy. A nothing allocation stays nothing.
The function spreads the mass that the selection leaves out over the kept assets in proportion. Every per-asset view of an allocation in the family reads it this way, the Recursion Result under a time-varying panel and the view of a rule's own allocation among them. A selection that keeps none of the mass, such as a view of a one-hot allocation to the other assets, has no proportion. It returns the uniform allocation over the kept assets, the Start Allocation of the family.
Mathematical definition
\[\begin{align} v_i &= \begin{cases} w_i \big/ \sum_{j \in I} w_j & \text{if } \sum_{j \in I} w_j \neq 0\,, \\ 1 / \lvert I \rvert & \text{otherwise}\,, \end{cases} \quad i \in I\,. \end{align}\]
Where:
- $v_i$: Entry of the view for the kept asset $i$.
- $w_i$: Entry of the allocation for asset $i$.
- $I$: Set of the kept assets.
Related
PortfolioOptimisers.statistic_before_rate — Function
statistic_before_rate(eta, s, w::AbstractVector, x::AbstractVector)Returns the statistic from which the rule reads the rate of the period. This is the first of the two points at which a rule writes the row of its schedule.
The row goes in here when reads_period_row returns true. Otherwise the call returns s unchanged. statistic_after_step is the other point. A rule makes both calls, and the schedule decides which one writes.
Related
PortfolioOptimisers.statistic_after_step — Function
statistic_after_step(eta, s, w::AbstractVector, x::AbstractVector)Returns the statistic that the state of the rule keeps after the step. This is the second of the two points at which a rule writes the row of its schedule.
The row goes in here when reads_period_row returns false, the default. Otherwise the call returns s unchanged. statistic_before_rate is the other point.
Related
References
- [248]
- J. Duchi, S. Shalev-Shwartz, Y. Singer and T. Chandra. Efficient projections onto the l1-ball for learning in high dimensions. In: Proceedings of the 25th International Conference on Machine Learning (2008); pp. 272–279.