Base Online Portfolio Selection: private API

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

  1. When isapprox(sum(wn), 1) holds, return wn. The default tolerance of isapprox is a relative error of sqrt(eps) of the element type, 1.49e-8 for Float64.
  2. Otherwise, record a Held Step on the current ProjectionStep with record_held_step!. Its reason names the set, the geometry and the sum, and it has no solver trials.
  3. Return a copy of w, as a failed projection programme of project does.

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, or w copied on a Held Step.

Related

source
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

  1. Refuse a non-finite q with assert_finite_raw_step, bounds that no allocation on the budget satisfies with assert_feasible_bounds, and a negative or NaN entry of h.
  2. When every entry of h is positive, return the projection at the budget one with budget_root_projection. Stop.
  3. When no entry of h is positive, return the projection at unit weights and the budget one with budget_root_projection. Stop.
  4. Otherwise, split the assets into pos, where h is positive, and zer, where it is zero. Clip q[pos] to its bounds, and form r, the budget that the clipped entries leave.
  5. When r is above the sum of the upper bounds of zer, hold zer at those bounds, and project q[pos] at the budget that they leave with budget_root_projection. Do the same with the lower bounds when r is below their sum.
  6. Otherwise, keep the clipped q[pos], and project q[zer] at unit weights and the budget r with budget_root_projection.
  7. 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). A DomainError is thrown otherwise.
  • Σ lb ≤ 1 ≤ Σ ub over the resolved bounds. An ArgumentError is thrown otherwise.
  • all(>= 0, h). A DomainError is thrown otherwise.

Returns

  • w'::Vector: The projected allocation, a new vector.

Related

source
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 of q.
  • h: The diagonal of the norm, positive.
  • c: The budget.

Returns

  • w'::Vector: The projected vector, a new vector.

Related

source
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

  1. Drop the non-finite kinks and sort the rest, giving x. When no kink is left, use the one kink 0.
  2. Search the indices of x by bisection for lo, the last kink at which f is at least c, and hi = lo + 1. The index 0 stands for the linear tail below the first kink, and the index length(x) + 1 for the tail above the last kink.
  3. Take the segment (a, b) that holds the root with breakpoint_segment.
  4. When f(a) == f(b), return a. Otherwise, return the point at which the line through (a, f(a)) and (b, f(b)) crosses c.

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 that f crosses.

Returns

  • r: The scalar at which f crosses c.

Related

source
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

  1. When lo == 0, return (x[1] - max(1, abs(x[1])), x[1]).
  2. When hi > length(x), return (x[end], x[end] + max(1, abs(x[end]))).
  3. Otherwise, return (x[lo], x[hi]).

Related

source
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

  1. Take the midpoint mid = lo / 2 + hi / 2. Stop when mid equals lo or hi, because the bracket then holds two adjacent values.
  2. Set lo = mid when f(mid) >= 1, and hi = mid otherwise.
  3. Repeat steps 1 and 2, at most bisection_cap times.
  4. Return lo / 2 + hi / 2.

Arguments

  • f: The budget as a function of the scalar, non-increasing.
  • lo, hi: A bracket with f(lo) ≥ 1 ≥ f(hi).

Returns

  • x: The scalar at which f crosses one.

Related

source
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) and floatmin(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

source
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

  1. Sum v, giving s. When every entry of v is non-negative and abs(s - 1) is at most budget_rounding, return v ./ s.
  2. Sort v in decreasing order, giving u.
  3. For each j, add u[j] to the running sum css and take t = (css - 1) / j. When u[j] - t > 0, set rho = j and theta = t.
  4. 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.
source
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

source
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, and nothing outside a fold.
  • reason: The projection of the row that the step held, and the reason.
  • trials: The solver trials of the failed programme, the trials of a JuMPResult, or nothing when the projection built no programme.

Related

source
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, a ReturnsResult of the rows as they arrived, or nothing.
  • ts: The timestamp of the row, or the index of the row in the fold.
  • strict: The head's strict flag. 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.
  • held: The Held Steps recorded during this row, in the order in which their projections failed.

Related

source
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_src is not ExcessSource, or rows carries a benchmark. An ArgumentError is thrown otherwise, through benchmark_relative_returns.
  • rows holds returns, which the rows of the head always do. A TypeError is thrown otherwise.

Related

source
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

source
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

source
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:

  1. Return alg unchanged when is_time_dependent is false for it.
  2. Read the names fns of the fields of the rule tree with rule_tree_fields.
  3. Resolve the value of each field in fns at ctx with update_time_dependent_estimator.
  4. Rebuild alg with the resolved values through rebuild_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

Validation

Returns

  • flag::Bool: true when 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

source
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

Related

source
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

source
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

source
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} <: AbstractPartialFitState

Holds 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 is nothing for a rule that keeps nothing.
  • X: The rows of returns that any rule of the tree reads, a ReturnsBufferState of the rows as they arrived, of their active masks, and of every other field of the Returns Result. rows_needed caps it. It is nothing when 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 states ExcessSource, see group_source, or nothing. A head whose group reads no benchmark pins none.
  • pnl: The static AssetPanel of the universe, pinned by the first step, or nothing. 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, or nothing under a static panel.
  • ts: Timestamps of the folded observations, in order and with no cap, or nothing when the rows hold none.
  • hold: The HeldStep record of the last folded row when the step held a projection of that row, or nothing when 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) -> OnlinePortfolioSelectionState

Keywords correspond to the struct's fields.

Validation

  • n >= 0. A DomainError is thrown otherwise.
  • length(nx) == length(w) when nx is given, and length(amsk) == length(w) when amsk is given. A DimensionMismatch is thrown otherwise.
  • pnl is static when it is not nothing. An ArgumentError is 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.
  • w is sliced and renormalised through renormalised_view, as a copy. The recursion keeps the full w.
  • st goes to the view of the state of the rule through rule_state_view.
  • X, nx, pnl and amsk are sliced along the asset axis.
  • nb is 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, ts and hold pass through, and ts is copied.

Related

source
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

source
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

source

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.