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, ornothingwhen the fold carried none.
Related
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, ornothingwhen the returns data carried no benchmark.
Related
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, ornothing.j: The index of the member.
Returns
x::Option{<:VecNum}: The vector of memberj, ornothing.
Related
PortfolioOptimisers.stacked_fold_weights — Function
stacked_fold_weights(pred::MultiPeriodPredictionResult, read) -> MatNumOne 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
- Read each fold's weights through
read, givingws. - Embed
wson the union of the folds'rd.nxwithweights_by_name, and keep the matrixW.
Arguments
pred: The multi-period prediction result.read: The per-fold reader,fold_targetorfold_held.
Validation
- Every fold's weights have one entry per name of its
rd.nx. ADimensionMismatchis thrown otherwise, because the embedding would misplace them.
Returns
W::MatNum:folds × assetsweights on the union universe, one row per fold in split order.
Related
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
- Take the union of the names of
nxsin order of first appearance, givingnames, and map each name to its column, givingpos. - Promote the element types of
ws, givingTf, and allocateW, avectors × assetsmatrix of zeros of typeTf. - For each vector
i, check the length ofws[i]againstnxs[i]. Whenws[i]is not empty and every weight isNaN, fill rowiofWwithNaN. Otherwise write each weight into rowiofW, at the column thatposgives its name.
Arguments
ws: The weight vectors.nxs: The asset names of each weight vector.
Validation
length(ws[i]) == length(nxs[i])for eachi. Otherwise the function raises aDimensionMismatch, because the embedding would misplace the weights.
Returns
names::Vector: The union of the names.W::MatNum:vectors × assetsweights on the union axis, one row for each vector ofws.
Related
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
NaNat every asset, so the path length isNaN. - $T$: Number of folds.
Algorithm
- Read the target of member
jon each fold throughfold_target, and embed the targets on one axis throughstacked_fold_weights, givingW, one row per fold. - When
Whas fewer than two rows, returnNaNof typeTf. - Sum the Euclidean norms of the differences of consecutive rows of
W.
Arguments
b: The comparator's prediction result, ornothingfor the benchmark.j: The index of the member ofb.Tf: Number type of the answer when the comparator has no path.
Returns
P::Number: The path length, orNaN.
Related
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, ornothingfor the benchmark.
Validation
- When both sides hold many members, they hold the same count. A
DimensionMismatchthat 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
member_regret(ra::VecNum, rb::VecNum, mt::AbstractMeanTestEstimator,
b::Union{Nothing, PredRes_MultiPredRes}, j::Integer = 1) -> LogWealthRegretResultThe 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
- Check that the two series have the same length, and that no return is below $-1$.
- Take the log growth of each series, giving
laandlb, and their differenced. - Sum
dcumulatively, givingcumulative. Its last entry isregret, andregret / Tismd. - Test the mean of
dagainst zero throughloss_difference_testundermt, with every row scored. - Read the path length of member
jof the comparator throughcomparator_path_length.
Arguments
ra: Realised return series of the strategy.rb: Realised return series of the comparator, on the rows ofra.mt: The Mean Test of the per-row difference.b: The comparator's prediction result, ornothingfor the benchmark.j: The index of the member ofbthatrbbelongs to. A single comparator series is member1.
Validation
raandrbhave the same length. AnArgumentErroris thrown otherwise, because two series over different rows compare nothing.- No return of either series is below $-1$. A
DomainErroris thrown otherwise.
Returns
reg::LogWealthRegretResult: The regret and its test, aslog_wealth_regretreturns it.
Related
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 atm.
Related
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 theT × Nallocations, one row per period. Every entry outsidemskis fixed at zero withJuMP.fix, which sets the variable's bounds and adds no row.z: read. It is theTlog-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: TheT × Nallocation variables, one row per period.z: TheTlog-wealth variables, one per period.X: TheT × Nprice relatives, finite wheremskholds.msk: TheT × NInvestable 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
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 theT × Nallocation 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: TheT × Nallocation variables, one row per period.L: The path-length budget.p: The norm order.
Returns
nothing.
Related
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
IsEmptyErrorthat names the row is thrown otherwise, throughrow_universe_error. Any other error ofcoverage_maskpasses through as it is.
Returns
msk::Option{BitVector}: The row's mask, one entry per asset, ornothingwhen the row covers every asset.
Related
PortfolioOptimisers.row_universe_error — Function
row_universe_error(err::IsEmptyError, t::Integer) -> IsEmptyError
row_universe_error(err::Exception, t::Integer) -> ExceptionThe error that row_coverage_mask throws for row t.
The IsEmptyError of an empty Coverage Universe is restated to name the row. Any other error is returned as it is.
Related
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
- Start from
msk, arows × assetsmatrix oftrue. - For each row
t, derive the row's Coverage Universe throughrow_coverage_mask, givingcm, and write it into rowtofmskwhen it is notnothing. - Return
nothingwhen every entry ofmskistrue, andmskotherwise.
Arguments
rd: The returns result to use.
Validation
- Every row has at least one asset in its Coverage Universe. An
IsEmptyErrornaming the row is thrown otherwise, because the row's budget of one cannot be met.
Returns
msk::Option{BitMatrix}: The masks,rows × assets, ornothing.
Related
PortfolioOptimisers.assert_path_rows — Function
assert_path_rows(res::BudgetedHindsightPathResult, rd::ReturnsResult)Refuse a returns result that is not the panel a budgeted path was solved over: the names, the clock and the row count must be the fit's, because the path is bound to its rows. An ArgumentError is thrown otherwise.
Related
PortfolioOptimisers.path_row_fold — Function
path_row_fold(res::BudgetedHindsightPathResult, rd::ReturnsResult, t::Integer) -> PredictionResultOne 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