Log-wealth regret: private API

PortfolioOptimisers.regret_series — Function
regret_series(pred::PredictionResult)
regret_series(pred::MultiPeriodPredictionResult)

The realised return series and the timestamps a prediction result was scored on, as log_wealth_regret reads them.

The series is the one performance_summary reads: the portfolio returns that predict stored, net of the fee the fold settled, and drifted where a Weight Drift ran. A prediction whose optimiser gives many portfolios, such as a frontier sweep, holds one series for each member, and the reader gives all of them. A multi-period result gives its stacked returns and timestamps. All the members share the timestamps.

Arguments

  • pred: The prediction result.

Returns

  • ret::VecNum_VecVecNum: The realised return series, or one series for each member.
  • ts::Option{<:AbstractVector}: The timestamps of the rows, or nothing when the fold carried none.

Related

source
PortfolioOptimisers.regret_benchmark — Function
regret_benchmark(pred::PredictionResult)
regret_benchmark(pred::MultiPeriodPredictionResult)

The benchmark series of the rows a prediction result was scored on, as log_wealth_regret reads it when no comparator is given.

Each fold keeps the benchmark of its test rows as one series: a benchmark series as it was given, and a benchmark matrix collapsed by the fold's weights, as collapse_benchmark states. A multi-period result stacks the series of its folds. The series shares the rows of regret_series, because PredictionReturnsResult checks the length of B against X and ts. It also has the shape of the series: one series for each member when the prediction holds many members, because each member collapses a benchmark matrix by its own weights.

Arguments

  • pred: The prediction result.

Returns

  • B::Option{<:VecNum_VecVecNum}: The benchmark series, one series for each member, or nothing when the returns data carried no benchmark.

Related

source
PortfolioOptimisers.member_vector — Function
member_vector(x::Nothing, j::Integer)
member_vector(x::VecNum, j::Integer)
member_vector(x::VecVecNum, j::Integer)

The vector of member j: a weight vector of a fold, a return series or a benchmark series.

A prediction whose optimiser gives many portfolios carries one vector for each member, and member j reads entry j. A single vector belongs to the one member of its prediction, so it is the answer for every j. An absent benchmark stays nothing.

Arguments

  • x: The vector of each member, one vector, or nothing.
  • j: The index of the member.

Returns

  • x::Option{<:VecNum}: The vector of member j, or nothing.

Related

source
PortfolioOptimisers.stacked_fold_weights — Function
stacked_fold_weights(pred::MultiPeriodPredictionResult, read) -> MatNum

One weight vector per fold, read by read and embedded by asset name on the union of the folds' universes.

The folds of a multi-period result need not share a universe. A Pipeline with an Asset Selector fits each fold on the assets it selected, so the fold of a top-1 selector carries one name and one weight. A path over the folds is stated on one axis, so each fold's weights go into the columns of its own names on the union axis, and every other entry of its row is zero. The row of a fold that failed to solve with no weights to hold is NaN at every name, as weights_by_name states.

Algorithm

  1. Read each fold's weights through read, giving ws.
  2. Embed ws on the union of the folds' rd.nx with weights_by_name, and keep the matrix W.

Arguments

Validation

  • Every fold's weights have one entry per name of its rd.nx. A DimensionMismatch is thrown otherwise, because the embedding would misplace them.

Returns

  • W::MatNum: folds × assets weights on the union universe, one row per fold in split order.

Related

source
PortfolioOptimisers.weights_by_name — Function
weights_by_name(ws::AbstractVector, nxs::AbstractVector) -> (names, W)

Embed weight vectors that sit on different asset names on the union of their names.

Each vector ws[i] holds one weight for each name of nxs[i]. The union axis holds every name once, in the order of first appearance. A vector puts each weight in the column of its name, and every other entry of its row is zero. stacked_fold_weights embeds the folds of a path with this function, and prediction_weights embeds the paths of a population.

A vector whose every weight is NaN is a failed portfolio. A fold that failed to solve holds such a vector, and so does a path or a population mean that reads one. Under a Weight Drift, a failed fold that the fold loop handed the previous weights holds those weights, as fold_target states, so its vector is finite and its row is not failed. Its row is NaN at every name of the union. A zero at a name that the vector does not hold would read as a book with no position in that asset, and the failed portfolio holds no book. A vector with no weight is not a failed portfolio.

Algorithm

  1. Take the union of the names of nxs in order of first appearance, giving names, and map each name to its column, giving pos.
  2. Promote the element types of ws, giving Tf, and allocate W, a vectors × assets matrix of zeros of type Tf.
  3. For each vector i, check the length of ws[i] against nxs[i]. When ws[i] is not empty and every weight is NaN, fill row i of W with NaN. Otherwise write each weight into row i of W, at the column that pos gives its name.

Arguments

  • ws: The weight vectors.
  • nxs: The asset names of each weight vector.

Validation

  • length(ws[i]) == length(nxs[i]) for each i. Otherwise the function raises a DimensionMismatch, because the embedding would misplace the weights.

Returns

  • names::Vector: The union of the names.
  • W::MatNum: vectors × assets weights on the union axis, one row for each vector of ws.

Related

source
PortfolioOptimisers.comparator_path_length — Function
comparator_path_length(b::Nothing, j::Integer, ::Type{Tf})
comparator_path_length(b::PredictionResult, j::Integer, ::Type{Tf})
comparator_path_length(b::MultiPeriodPredictionResult, j::Integer, ::Type{Tf})

The path length of the targets of member j of a comparator, as log_wealth_regret reports it.

A multi-period result has one target per fold, so the path is over the folds. At test_size = 1 a fold is a row, and $\boldsymbol{u}_t$ is the comparator's target on row $t$. A comparator whose optimiser gives many portfolios has one path for each member, and j names the member. A single prediction result holds one target and no path, and so does a multi-period result of one fold. A benchmark comparator, nothing, is a series with no weights, so it has no path either. All three answer NaN, in the number type Tf of the regret.

Mathematical definition

\[\begin{align} P_T &= \sum_{t=2}^{T} \lVert \boldsymbol{u}_t - \boldsymbol{u}_{t-1} \rVert_2\,. \end{align}\]

Where:

  • $P_T = \sum_{t=2}^{T} \lVert \boldsymbol{u}_t - \boldsymbol{u}_{t-1} \rVert_2$: Path length of a comparator sequence $\boldsymbol{u}_1, \ldots, \boldsymbol{u}_T$ in the feasible set.
  • $\boldsymbol{u}_t$: Comparator's target on fold $t$, embedded by asset name on the union of the folds' universes, with a zero at every asset outside the fold's own universe. A fold that failed to solve with no weights to hold is NaN at every asset, so the path length is NaN.
  • $T$: Number of folds.

Algorithm

  1. Read the target of member j on each fold through fold_target, and embed the targets on one axis through stacked_fold_weights, giving W, one row per fold.
  2. When W has fewer than two rows, return NaN of type Tf.
  3. Sum the Euclidean norms of the differences of consecutive rows of W.

Arguments

  • b: The comparator's prediction result, or nothing for the benchmark.
  • j: The index of the member of b.
  • Tf: Number type of the answer when the comparator has no path.

Returns

  • P::Number: The path length, or NaN.

Related

source
PortfolioOptimisers.member_regret — Function
member_regret(ra::VecVecNum, rb::VecNum, mt::AbstractMeanTestEstimator, b)
member_regret(ra::VecNum, rb::VecVecNum, mt::AbstractMeanTestEstimator, b)
member_regret(ra::VecVecNum, rb::VecVecNum, mt::AbstractMeanTestEstimator, b)

The log-wealth regret of each member of the strategy against its member of the comparator, as log_wealth_regret pairs them.

A side with one series pairs with every member of the other side. Two sides with many members pair by index. The pair of two single series gives one LogWealthRegretResult, through the method of two series below, and every other pair gives a vector with one entry for each pair. Thus the shape of the answer follows the types of ra and rb, and the method is type-stable. Each entry reads the path length of the member of b that it pairs with, through comparator_path_length. A single comparator series is member 1 of b.

Arguments

  • ra: The series of the strategy, or one series for each member.
  • rb: The series of the comparator, or one series for each member.
  • mt: The Mean Test of the per-row difference.
  • b: The comparator's prediction result, or nothing for the benchmark.

Validation

  • When both sides hold many members, they hold the same count. A DimensionMismatch that names both counts is thrown otherwise.

Returns

  • reg::LogWealthRegretResult: When both sides hold one series.
  • reg::Vector{<:LogWealthRegretResult}: When a side holds many members, one entry for each pair in the order of the members.

Related

source
member_regret(ra::VecNum, rb::VecNum, mt::AbstractMeanTestEstimator,
              b::Union{Nothing, PredRes_MultiPredRes}, j::Integer = 1) -> LogWealthRegretResult

The log-wealth regret of the return series ra against the return series rb, which share their rows. The methods of member_regret on many members pair the series of both methods of log_wealth_regret and pass each pair here, and that verb's docstring states the mathematics.

Algorithm

  1. Check that the two series have the same length, and that no return is below $-1$.
  2. Take the log growth of each series, giving la and lb, and their difference d.
  3. Sum d cumulatively, giving cumulative. Its last entry is regret, and regret / T is md.
  4. Test the mean of d against zero through loss_difference_test under mt, with every row scored.
  5. Read the path length of member j of the comparator through comparator_path_length.

Arguments

  • ra: Realised return series of the strategy.
  • rb: Realised return series of the comparator, on the rows of ra.
  • mt: The Mean Test of the per-row difference.
  • b: The comparator's prediction result, or nothing for the benchmark.
  • j: The index of the member of b that rb belongs to. A single comparator series is member 1.

Validation

  • ra and rb have the same length. An ArgumentError is thrown otherwise, because two series over different rows compare nothing.
  • No return of either series is below $-1$. A DomainError is thrown otherwise.

Returns

  • reg::LogWealthRegretResult: The regret and its test, as log_wealth_regret returns it.

Related

source
PortfolioOptimisers.row_bound_view — Function
row_bound_view(b::Number, m::AbstractVector{Bool})
row_bound_view(b::VecNum, m::AbstractVector{Bool})

One side of a resolved weight bound on the investable assets of a row.

A scalar bound applies to every asset, so it passes through. A vector bound is viewed at the row's mask.

Arguments

  • b: One side of the resolved bound, a number or one entry per asset.
  • m: The row's Investable Mask.

Returns

  • b: The scalar bound, or the view of the vector bound at m.

Related

source
PortfolioOptimisers.path_row_constraints! — Function
path_row_constraints!(model::JuMP.Model, u, z, X, msk::AbstractMatrix{Bool}, wb::WeightBounds)

Writes the rows of every period of the budgeted path programme on each period's investable assets.

The budget, the finite bounds and the log wealth of period $t$ read the assets that row $t$ of msk keeps. The allocation of every other asset is fixed at zero, because a row with no price relative for an asset cannot hold it. Each kind of row is one JuMP container over the periods, the form that the JuMP manual recommends for an indexed family of rows.

JuMP formulation

Variables

  • u: read. It is the T × N allocations, one row per period. Every entry outside msk is fixed at zero with JuMP.fix, which sets the variable's bounds and adds no row.
  • z: read. It is the T log-wealth variables, one per period.

Constraints

Every row is registered under no name, and the row of period $t$ reads the assets in $\mathcal{M}_t$ alone.

  • $\sum_{i \in \mathcal{M}_t} u_{t,i} = 1$, for $t = 1, \ldots, T$.
  • $u_{t,i} - l_i \geq 0$ for each $i \in \mathcal{M}_t$, for $t = 1, \ldots, T$, when an entry of $\boldsymbol{l}$ is finite.
  • $u_{t,i} - h_i \leq 0$ for each $i \in \mathcal{M}_t$, for $t = 1, \ldots, T$, when an entry of $\boldsymbol{h}$ is finite.
  • The exponential cone rows $\left(z_t, 1, \sum_{i \in \mathcal{M}_t} x_{t,i} u_{t,i}\right) \in \mathcal{K}_{\exp}$, for $t = 1, \ldots, T$, which hold when $z_t \leq \log \sum_{i \in \mathcal{M}_t} x_{t,i} u_{t,i}$.

Where:

  • $u_{t,i}$: Allocation of asset $i$ in period $t$.
  • $z_t$: Log-wealth variable of period $t$.
  • $x_{t,i}$: Price relative of asset $i$ in period $t$, one plus its return.
  • $\mathcal{M}_t$: Set of the assets in the Investable Mask of period $t$.
  • $l_i$, $h_i$: Resolved lower and upper weight bounds of asset $i$, the entries of $\boldsymbol{l}$ and $\boldsymbol{h}$.
  • $\mathcal{K}_{\exp} = \mathrm{cl}\,\{(a, b, c) : b\, e^{a / b} \leq c,\, b > 0\}$: Exponential cone.
  • $T$: Number of observations.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • u: The T × N allocation variables, one row per period.
  • z: The T log-wealth variables, one per period.
  • X: The T × N price relatives, finite where msk holds.
  • msk: The T × N Investable Masks, one row per period. Row $t$ is the Coverage Universe of the one-row window of period $t$.
  • wb: Weight bounds.

Returns

  • nothing.

Related

source
PortfolioOptimisers.path_budget_constraint! — Function
path_budget_constraint!(model::JuMP.Model, u, L::Number, p::Number)

Writes the path-length budget of the budgeted path programme.

Each step of the path takes one epigraph variable through norm_epigraph!, and the sum of these variables is at most L. The bare programme registers no constraint scale, so the rows take the scale 1. A path of one row has no step, so the function writes nothing.

JuMP formulation

Variables

  • u: read. It is the T × N allocation variables, one row per period.
  • s: created, an anonymous vector of $T - 1$ step lengths.
  • d: created, an anonymous $(T - 1) \times N$ matrix of steps.

Constraints

Every row is registered under no name.

  • $\boldsymbol{d}_{t-1} = \boldsymbol{u}_t - \boldsymbol{u}_{t-1}$, for $t = 2, \ldots, T$, one row per entry.
  • The rows of norm_epigraph! on $s_{t-1} \geq \lVert \boldsymbol{d}_{t-1} \rVert_p$, for $t = 2, \ldots, T$.
  • $\sum_{t=1}^{T-1} s_t \leq L$.

Where:

  • $\boldsymbol{u}_t$: Allocation of period $t$, one entry per asset.
  • $\boldsymbol{d}_t$: Step from period $t$ to period $t + 1$.
  • $s_t$: Length of step $t$ in the norm of order $p$.
  • $L$: Path-length budget.
  • $p$: Norm order.
  • $T$: Number of observations.
  • $N$: Number of assets.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • u: The T × N allocation variables, one row per period.
  • L: The path-length budget.
  • p: The norm order.

Returns

  • nothing.

Related

source
PortfolioOptimisers.row_coverage_mask — Function
row_coverage_mask(rd::ReturnsResult, t::Integer) -> Option{BitVector}

The Coverage Universe of row t of rd alone, through coverage_mask on the one-row view.

Arguments

  • rd: The returns result to use.
  • t: The row.

Validation

  • The row has at least one asset in its Coverage Universe. An IsEmptyError that names the row is thrown otherwise, through row_universe_error. Any other error of coverage_mask passes through as it is.

Returns

  • msk::Option{BitVector}: The row's mask, one entry per asset, or nothing when the row covers every asset.

Related

source
PortfolioOptimisers.path_row_masks — Function
path_row_masks(rd::ReturnsResult) -> Option{BitMatrix}

The Investable Mask of every row of a budgeted path.

Row t is the Coverage Universe of the one-row window t: true at every asset whose return is finite and whose Asset Panel active mask is true on that row. A delisted or unlisted asset is therefore out of the row, as it is out of the fit of a HindsightSplit(; prefix = false) fold.

Algorithm

  1. Start from msk, a rows × assets matrix of true.
  2. For each row t, derive the row's Coverage Universe through row_coverage_mask, giving cm, and write it into row t of msk when it is not nothing.
  3. Return nothing when every entry of msk is true, and msk otherwise.

Arguments

  • rd: The returns result to use.

Validation

  • Every row has at least one asset in its Coverage Universe. An IsEmptyError naming the row is thrown otherwise, because the row's budget of one cannot be met.

Returns

  • msk::Option{BitMatrix}: The masks, rows × assets, or nothing.

Related

source
PortfolioOptimisers.path_row_fold — Function
path_row_fold(res::BudgetedHindsightPathResult, rd::ReturnsResult, t::Integer) -> PredictionResult

One fold of a budgeted path's prediction result: row t's allocation as a NaiveOptimisationResult on the resolved bounds, predicted over row t of rd alone.

The fold is predicted at the test rows t:t, so it records the position t, as a fold of a cross-validation records its test rows. A realised factor_attribution of the path then matches each fold to the row of the factor model block by that position.

A row with a gap carries its Investable Mask, so predict views the row and the weights at the mask and never reads the gap. A row with no gap carries nothing, as a fit on the full universe does.

Related

source