Tracking
PortfolioOptimisers.AbstractTrackingAlgorithm — Type
abstract type AbstractTrackingAlgorithm <: AbstractAlgorithmAbstract supertype of the tracking algorithms. A tracking algorithm gives the benchmark of a tracking measure.
Every form compares the portfolio series pr.X * w with its benchmark series, so the source of the prior that the measure reads decides the frame of the comparison. A raw prior states x_src = nothing or x_src = DataSource(). An excess prior states x_src = ExcessSource(), and its pr.X is X - B. The table gives the series that each pair tracks, where s = sum(w) and s_b = sum(w_b).
| Prior | Form | Vector B | Matrix B | Status |
|---|---|---|---|---|
| raw | a plain risk measure | X * w | X * w | absolute risk |
| excess | a plain risk measure | X * w - B * s | (X - B) * w | active risk |
| raw | WeightsTracking | X * (w - w_b) | X * (w - w_b) | valid |
| excess | WeightsTracking | X * (w - w_b) - B * (s - s_b) | (X - B) * (w - w_b) | valid |
| raw | ReturnsTracking | X * w - b | X * w - b | valid |
| excess | ReturnsTracking | X * w - B * s - b | (X - B) * w - b | valid if b is excess |
| raw | DataBenchmarkTracking | X * w - B | (X - B) * w | valid |
| excess | DataBenchmarkTracking | X * w - B * (s + 1) | (X - 2B) * w | refused |
The constructor of the holder refuses the last row, because that series subtracts the benchmark two times. No check can see a wrong use of the two rows of WeightsTracking and ReturnsTracking under an excess prior, so their docstrings state the meaning. A raw prior with a data benchmark and an excess prior with a plain measure can track the same series, but they are different models. The excess prior also moves pr.mu, pr.sigma and every other measure of the optimiser, and the raw prior keeps the objective absolute.
Interfaces
To add a tracking algorithm, subtype AbstractTrackingAlgorithm and add these methods:
tracking_benchmark(tr::AbstractTrackingAlgorithm, X::MatNum) -> VecNum: Returns the benchmark series for the asset return matrixX.factory(tr::AbstractTrackingAlgorithm, w::VecNum) -> AbstractTrackingAlgorithm: Returns a tracking algorithm that holds the new weightsw.port_opt_view(tr::AbstractTrackingAlgorithm, i) -> AbstractTrackingAlgorithm: Returns the tracking algorithm of the assets at the indicesi.
Arguments
tr: The tracking algorithm.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.w: The new portfolio weights.i: The index or the indices of the assets in the view.
Returns
b::VecNum: The benchmark series thattracking_benchmarkreturns.tr::AbstractTrackingAlgorithm: The tracking algorithm thatfactoryorport_opt_viewreturns.
Examples
julia> struct MyTracking <: PortfolioOptimisers.AbstractTrackingAlgorithm w::Vector{Float64} endjulia> function PortfolioOptimisers.tracking_benchmark(tr::MyTracking, X::PortfolioOptimisers.MatNum) return X * tr.w endjulia> PortfolioOptimisers.factory(tr::MyTracking, w) = MyTracking(w)julia> PortfolioOptimisers.port_opt_view(tr::MyTracking, i) = MyTracking(tr.w[i])julia> tr = MyTracking([0.5, 0.5]);julia> X = [0.01 0.02; 0.03 0.04];julia> PortfolioOptimisers.tracking_benchmark(tr, X)2-element Vector{Float64}: 0.015 0.035Related
AbstractAlgorithmWeightsTrackingReturnsTrackingDataBenchmarkTrackingTrackingErrorTrackingRiskMeasureExcessSource: The source of an excess prior.
PortfolioOptimisers.IndependentVariableTracking — Type
struct IndependentVariableTracking <: VariableTrackingApplies the risk measure to the difference between the portfolio weights and the benchmark weights.
The weights are the independent variable of a risk measure, so this formulation compares the two portfolios before the risk measure reads them. It reports $R(\boldsymbol{w} - \boldsymbol{w}_{b})$. Under a Variance it is the variance of the tracking error of page 15 of [187], $(\boldsymbol{w} - \boldsymbol{w}_{b})^{\intercal} \mathbf{\Sigma} (\boldsymbol{w} - \boldsymbol{w}_{b})$. Any other risk measure generalises it.
Constructors
IndependentVariableTracking() -> IndependentVariableTrackingExamples
julia> IndependentVariableTracking()IndependentVariableTracking()Related
References
- [187] R. Roll. A mean/variance analysis of tracking error. The Journal of Portfolio Management 18, 13–22 (1992). Page 15.
PortfolioOptimisers.DependentVariableTracking — Type
struct DependentVariableTracking <: VariableTrackingApplies the risk measure to each portfolio, then takes the absolute difference of the two risks.
The risk is the dependent variable of a risk measure, so this formulation compares the two portfolios after the risk measure reads them. It reports $\left\lvert R(\boldsymbol{w}) - R(\boldsymbol{w}_{b}) \right\rvert$.
The functor reports the exact absolute difference. In an optimisation the model states the difference from one side only, because the absolute difference between a convex risk and the benchmark risk, a constant, is not convex. The model reads $R(\boldsymbol{w})$ through the epigraph of the risk measure. The epigraph variable is an upper bound on $R(\boldsymbol{w})$, and the solver can raise it at no cost. So the model states $\max(0,\ R(\boldsymbol{w}) - R(\boldsymbol{w}_{b}))$. It penalises a portfolio with more risk than the benchmark, and it reports zero for a portfolio with less risk. This is true of every measure whose model is an upper bound. Examples are ConditionalValueatRisk, StandardDeviation, LowOrderMoment and a Variance in the semidefinite form, $\mathrm{tr}(\boldsymbol{\Sigma}\mathbf{W}) \geq \boldsymbol{w}^\intercal\boldsymbol{\Sigma}\boldsymbol{w}$. The one-sided difference has two uses:
- In a
RiskTrackingRiskMeasurewithsettings.ub, or in aRiskTrackingError, it is the ceiling $R(\boldsymbol{w}) \leq R(\boldsymbol{w}_{b}) + \varepsilon$. Here $\varepsilon$ is theerrof the tracking error or thesettings.ubof the measure. The model evaluates $R(\boldsymbol{w}_{b})$ on the prior of the optimisation, and aWeightsTrackingbenchmark that is notfixedtakes the previous weights. So the ceiling changes with the data and with the benchmark. A fixedsettings.ubon the measure cannot do this. - In the objective, it penalises only the risk above the benchmark risk. The semidefinite
Varianceis the one exception, because its inner build shares the lifted matrix $\mathbf{W}$ of the head. For this variance, the difference is exact when $p + s_v \Sigma_{ii} \geq s \Sigma_{ii}$ for every $i$. The left side prices the growth of $\mathbf{W}$, and the right side is the tracking term. Here $p$ is the penalty of aSemiDefinitePhylogenyand $s$ is the tracking scale. $s_v$ is the scale of a variance that the objective minimises on the same weights, and it is0when the objective has no such variance.
A Variance outside the semidefinite form is a quadratic expression, and it does not solve in this mode. The variance takes the semidefinite form under a SemiDefinitePhylogeny or under risk-contribution rows. The dependent method of set_risk_constraints! for a RiskTrackingRiskMeasure states the bound in its ## Relaxation.
Constructors
DependentVariableTracking() -> DependentVariableTrackingExamples
julia> DependentVariableTracking()DependentVariableTracking()Related
PortfolioOptimisers.WeightsTracking — Type
struct WeightsTracking{__T_fees, __T_w, __T_fixed} <: AbstractTrackingAlgorithmBuilds the benchmark return series from a vector of benchmark weights, net of the fees of those weights.
The benchmark is a portfolio, not a return series. So tracking_benchmark computes $\mathbf{X}\boldsymbol{w}_{b}$ on the return matrix that the caller gives. Page 15 of [187] states the benchmark as such a portfolio. Equation 1 of [10] states the deviation of the portfolio returns from the benchmark returns. Use it when the benchmark is a known allocation. Use ReturnsTracking when only its realised returns are known.
Under a prior that states x_src = ExcessSource() with a vector benchmark B, the measure tracks X * (w - w_b) - B * (sum(w) - sum(w_b)). It equals the tracking error on the raw returns only when the two budgets are equal. Under a matrix benchmark it tracks (X - B) * (w - w_b). No check can see a difference of budgets, so the table of combinations of AbstractTrackingAlgorithm states the meaning of each pair.
Mathematical definition
\[\begin{align} \boldsymbol{b} &= \mathbf{X}\boldsymbol{w}_{b} - \boldsymbol{F}(\boldsymbol{w}_{b})\,. \end{align}\]
Where:
- $\boldsymbol{b}$:
T × 1benchmark return vector. - $\mathbf{X}$:
T × Nasset return matrix. - $\boldsymbol{w}_{b}$:
N × 1benchmark weight vector, thewfield. - $\boldsymbol{F}(\boldsymbol{w}_{b})$: The fee that each period charges on the benchmark, from the
feesfield. It is zero whenfeesisnothing. Seecalc_net_returns.
The fees field reads no fold, and it needs none. charge_fees charges this fee over the benchmark series that it builds. An AmortisedFees fa spreads the two fixed charges over that series, and a nothing fa charges them on the first observation. The fee does not store the count of observations, so this site needs no fold to set one.
Fields
fees: Fees estimator or result.
w: Reference portfolio weight vector. The deviation of each asset is the difference between the candidate weight and this weight. It is never the candidate weight vector that an optimiser solves for.
fixed: Iftrue,factorykeeps the reference weightswand ignores the new weights. Iffalse,factoryreplaceswwith the new weights.
Constructors
WeightsTracking(; fees::Option{<:Fees} = nothing, w::VecNum, fixed::Bool = false) -> WeightsTrackingKeywords correspond to the struct's fields.
Validation
w, throughassert_nonempty_finite_val:!isempty(w)andall(isfinite, w). Every entry must be finite, so the constructor refuses[0.5, NaN].
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
fees: Recursively viewed throughport_opt_view.w: Sliced to the selected indices throughport_opt_view.
Examples
julia> WeightsTracking(; w = [0.5, 0.5])WeightsTracking fees ┼ nothing w ┼ Vector{Float64}: [0.5, 0.5] fixed ┴ Bool: falseRelated
ReturnsTrackingTrackingErrorAbstractTrackingAlgorithmFeesOptiontracking_benchmarkcalc_net_returnsport_opt_view
References
PortfolioOptimisers.ReturnsTracking — Type
struct ReturnsTracking{__T_w} <: AbstractTrackingAlgorithmHolds the return series of a benchmark whose weights are unknown.
tracking_benchmark returns the w field unchanged. It reads no return matrix and applies no fee. Equation 1 of [10] has this case. Its benchmark is the return series of an index, and the caller has only the published series. Use WeightsTracking when the benchmark allocation is known.
The w field holds T returns, one for each observation, not N weights. Its length must equal the number of rows of the return matrix of the model, and tracking_benchmark refuses a different length. The series is constant, so it cannot follow rows that change. The online step of an optimiser refuses it. The risk ceiling of a ProgrammeAllocationSet and a RiskLoss also refuse it. A batch cross-validation with more than one fold refuses it through assert_folds_track_no_series, because each fold refits on its own rows. DataBenchmarkTracking tracks the benchmark that the returns data carries, and it follows the rows.
The series must be in the frame of the prior that the measure reads. Under a prior that states x_src = ExcessSource(), the portfolio series is (X - B) * w, so the series w must be an excess series too. A series equal to B then subtracts the benchmark two times. No check can see the frame of a series, so the table of combinations of AbstractTrackingAlgorithm states the meaning of each pair.
Fields
w: Benchmark return series. It holdsTreturns, one for each observation, notNweights. Its length must equal the number of rows of the return matrix of the model.
Constructors
ReturnsTracking(; w::VecNum) -> ReturnsTrackingKeywords correspond to the struct's fields.
Validation
w, throughassert_nonempty_finite_val:!isempty(w)andall(isfinite, w). Every entry must be finite, so the constructor refuses[0.01, NaN].
Examples
julia> ReturnsTracking(; w = [0.01, 0.02, 0.03])ReturnsTracking w ┴ Vector{Float64}: [0.01, 0.02, 0.03]Related
References
- [10] M. Rudolf, H.-J. Wolter and H. Zimmermann. A linear model for tracking error minimization. Journal of Banking & Finance 23, 85–103 (1999). Section 2, Equation 1.
PortfolioOptimisers.DataBenchmarkTracking — Type
struct DataBenchmarkTracking{__T_B} <: AbstractTrackingAlgorithmTracks the benchmark that the returns data carries, so the benchmark follows the rows that each reader holds.
A ReturnsTracking series is constant after construction, so it aligns with the rows of one fit only. DataBenchmarkTracking reads the B field of the ReturnsResult instead. Every reader that holds the returns data binds it to the B of its own rows with bind_data_benchmark:
- An optimiser binds it to the rows that it fits on.
- The online step binds it to the rows of its buffer.
- A fold of a cross-validation binds it to the rows of the fold.
- An online portfolio selection head binds it to the rows of its window.
Mathematical definition
\[\begin{align} \boldsymbol{b} &= \begin{cases} \mathbf{B} & \text{a vector benchmark}\,,\\ \mathbf{B}\boldsymbol{w} & \text{a matrix benchmark}\,. \end{cases} \end{align}\]
Where:
- $\boldsymbol{b}$:
T × 1benchmark return series. - $\mathbf{B}$: Benchmark returns of the rows, the
Bfield. A vectorT × 1is one benchmark that every asset shares, and a matrixT × Nholds one benchmark for each asset. - $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
A matrix benchmark gives the portfolio the same weights in the benchmark of each asset, so the tracking error is $\lVert (\mathbf{X} - \mathbf{B})\boldsymbol{w} \rVert$. It is linear in the weights, so every model stays conic. collapse_benchmark applies the same rule to the benchmark of a prediction. The benchmark pays no fee.
A data benchmark refuses a prior that states x_src = ExcessSource(), because the tracking error then subtracts the benchmark two times. The constructor of the optimiser that holds both refuses the pair. See the table of combinations of AbstractTrackingAlgorithm. A reader that holds no returns data leaves the benchmark unbound, and tracking_benchmark refuses it.
Fields
B: Benchmark returns of the rows that a reader holds, from theBfield of theReturnsResultof the reader. A vectorT × 1is the benchmark series. A matrixT × Nholds one benchmark for each asset, and its series isB * w. Every reader that holds the returns data replaces it with theBof its own rows throughbind_data_benchmark. It isnothinguntil a reader binds it.
Constructors
DataBenchmarkTracking(; B::Option{<:VecNum_MatNum} = nothing) -> DataBenchmarkTrackingKeywords correspond to the struct's fields.
View parameters
port_opt_view views the columns of a matrix B at the selected indices. A vector B is a series of rows, so the view keeps it unchanged.
Examples
julia> DataBenchmarkTracking()DataBenchmarkTracking B ┴ nothingjulia> rd = ReturnsResult(; nx = ["A", "B"], X = [0.01 0.03; 0.02 -0.01], nb = ["BM"], B = [0.02, 0.0]);julia> PortfolioOptimisers.bind_data_benchmark(DataBenchmarkTracking(), rd)DataBenchmarkTracking B ┴ Vector{Float64}: [0.02, 0.0]Related
ReturnsTrackingWeightsTrackingTrackingErrorAbstractTrackingAlgorithmbind_data_benchmarktracking_benchmarkReturnsResult
References
- [10] M. Rudolf, H.-J. Wolter and H. Zimmermann. A linear model for tracking error minimization. Journal of Banking & Finance 23, 85–103 (1999). Section 2, Equation 1.
PortfolioOptimisers.TrackingError — Type
struct TrackingError{__T_tr, __T_err, __T_alg} <: AbstractTrackingBounds the deviation of the portfolio return series from a benchmark return series.
err is an upper bound, not a computed value. set_tracking_error_constraints! writes one cone for the norm that alg names, and the cone holds the scaled deviation at or below err. The tr field gives the benchmark, and the alg field names the norm that measures the deviation.
The norms come from [10] and [11]. The docstring of each NormError gives the location of its norm in the source. Those works minimise the tracking error. The bound on the tracking error inside another problem follows Section 9.2 of [12].
Mathematical definition
\[\begin{align} \mathrm{TE}(\boldsymbol{w}) &= \lVert \boldsymbol{r}(\boldsymbol{w}) - \boldsymbol{b} \rVert \cdot c^{-1} \leq \mathrm{err}\,. \end{align}\]
Where:
- $\mathrm{TE}(\boldsymbol{w})$: Tracking error.
- $\boldsymbol{r}(\boldsymbol{w})$:
T × 1net portfolio return series. - $\boldsymbol{b}$:
T × 1benchmark return series, fromtracking_benchmarkon thetrfield. - $\lVert \cdot \rVert$, $c$: The norm and the scaling factor that
algnames.norm_errorcomputes the scaled norm, andnorm_factorgives $c$. - $\mathrm{err}$: The
errfield.
err has the units of alg, and SquaredL2Norm squares the norm. So one number gives two different bounds. TrackingError(; alg = SquaredL2Norm(), err = 5e-6) admits an L2Norm error up to sqrt(5e-6). TrackingError(; alg = L2Norm(), err = 5e-6) admits 5e-6. To change an L2Norm tolerance into a SquaredL2Norm tolerance, square it. Do not use the same number for both. The model, norm_error and set_risk_constraints! read err in the same way.
The conversion does not depend on T. After the conversion, the two norms write the same cone bound. tracking_error_soc_factor computes that bound, and it returns one factor for (SquaredL2Norm(), err^2) and for (L2Norm(), err). So the two models give one weight vector, and the realised deviation of the SquaredL2Norm model is the square of the realised deviation of the L2Norm model. The ddof field of alg changes that bound.
alg selects the keys that the model registers, and each key ends with the index of the constraint. Every branch registers :t_tr_ for the cone variable, :tr_ for the deviation expression $\mathbf{X}\boldsymbol{w} - \boldsymbol{b}k$, and :ctr_ for the row that holds the cone variable at or below the scaled tolerance. The table gives the cone of each branch, the row of the cone, and the rows that a branch adds to those three:
alg | Cone | Cone row | Rows the branch adds |
|---|---|---|---|
L1Norm | JuMP.MOI.NormOneCone | :ctr_noc_ | none |
L2Norm, SquaredL2Norm | JuMP.SecondOrderCone | :ctr_soc_ | none |
LpNorm | JuMP.MOI.PowerCone | :ctr_pnorm_ | :r_tr_, :cstr_ |
LInfNorm | JuMP.MOI.NormInfinityCone | :ctr_infnorm_ | none |
So :ctr_soc_ is the key of the default alg = L2Norm() and of SquaredL2Norm only. The model registers no :tracking_risk_ and no :sq_tracking_risk_. Those two keys belong to TrackingRiskMeasure, which measures a difference of risks, not the deviation of a return series.
Fields
tr: Tracking algorithm that gives the benchmark return series.
err: Tracking error tolerance.
alg: Tracking formulation algorithm.
Constructors
TrackingError(; tr::AbstractTrackingAlgorithm, err::Number = 0.0, alg::NormError = L2Norm()) -> TrackingErrorKeywords correspond to the struct's fields.
Validation
err, throughassert_nonempty_nonneg_finite_val:isfinite(err)anderr >= 0. A failed check throws aDomainErrorthat nameserr. The constructor acceptserr = 0.0, which permits no deviation from the benchmark.
Propagated parameters
factory passes its arguments on to these @fprop fields:
tr: Recursively updated throughfactory.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
tr: Recursively viewed throughport_opt_view.
Examples
julia> tr = WeightsTracking(; w = [0.5, 0.5]);julia> TrackingError(; tr = tr, err = 0.01)TrackingError tr ┼ WeightsTracking │ fees ┼ nothing │ w ┼ Vector{Float64}: [0.5, 0.5] │ fixed ┴ Bool: false err ┼ Float64: 0.01 alg ┼ L2Norm │ ddof ┴ Int64: 1Related
set_tracking_error_constraints!AbstractTrackingWeightsTrackingReturnsTrackingAbstractTrackingAlgorithm: The table of the series that each form tracks under the source of the prior.NormErrorL2NormSquaredL2NormL1Normnorm_errornorm_factortracking_error_soc_factor: Turnserrinto the cone bound. The twoL2norms give the same bound there.TrackingRiskMeasure: The risk-difference measure that owns:tracking_risk_and:sq_tracking_risk_.tracking_benchmarkfactoryport_opt_view
References
- [10] M. Rudolf, H.-J. Wolter and H. Zimmermann. A linear model for tracking error minimization. Journal of Banking & Finance 23, 85–103 (1999). Section 2, Equation 2. Section 3, Equations 5, 6, 7a and 7c.
- [11] J. E. Beasley, N. Meade and T.-J. Chang. An evolutionary heuristic for the index tracking problem. European Journal of Operational Research 148, 621–643 (2003). Section 3.5.1, Equation 9.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.2, Equations 9.19 and 9.20. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.factory — Method
factory(tr::WeightsTracking, w::VecNum)Construct a WeightsTracking that holds the new benchmark weights w.
The fixed flag decides whether the benchmark changes. factory(tn::Turnover, w::VecNum) reads its own fixed flag in the same way. A fixed benchmark is a constant allocation, so the function returns the object unchanged, and === holds. A benchmark that is not fixed takes w as its new reference, and its fees advance one step. The nested Turnover takes the old tr.w as its reference, because the portfolio turns over from that allocation.
Algorithm
- Read
tr.fixed. - When
tr.fixedistrue, returntritself. The function does not readw. - When
tr.fixedisfalse, advance the fees withfactory(tr.fees, tr.w). This gives the old weights to the nested turnover as its reference. - Build a new
WeightsTrackingfrom the advanced fees, the neww, and the unchangedtr.fixed.
Arguments
tr: TheWeightsTrackingto update.w: The new benchmark weights.
Returns
tr::WeightsTracking: A new tracking algorithm that holdsw, ortritself whentr.fixedistrue.
Examples
julia> tr = WeightsTracking(; fees = Fees(; l = 0.002), w = [0.5, 0.5])WeightsTracking fees ┼ Fees │ tn ┼ nothing │ l ┼ Float64: 0.002 │ s ┼ nothing │ fl ┼ nothing │ fs ┼ nothing │ lq ┼ nothing │ flq ┼ nothing │ fa ┼ nothing │ kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,) w ┼ Vector{Float64}: [0.5, 0.5] fixed ┴ Bool: falsejulia> PortfolioOptimisers.factory(tr, [0.6, 0.4])WeightsTracking fees ┼ Fees │ tn ┼ nothing │ l ┼ Float64: 0.002 │ s ┼ nothing │ fl ┼ nothing │ fs ┼ nothing │ lq ┼ nothing │ flq ┼ nothing │ fa ┼ nothing │ kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,) w ┼ Vector{Float64}: [0.6, 0.4] fixed ┴ Bool: falsejulia> tr = WeightsTracking(; fees = Fees(; l = 0.002), w = [0.5, 0.5], fixed = true)WeightsTracking fees ┼ Fees │ tn ┼ nothing │ l ┼ Float64: 0.002 │ s ┼ nothing │ fl ┼ nothing │ fs ┼ nothing │ lq ┼ nothing │ flq ┼ nothing │ fa ┼ nothing │ kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,) w ┼ Vector{Float64}: [0.5, 0.5] fixed ┴ Bool: truejulia> PortfolioOptimisers.factory(tr, [0.1, 0.1])WeightsTracking fees ┼ Fees │ tn ┼ nothing │ l ┼ Float64: 0.002 │ s ┼ nothing │ fl ┼ nothing │ fs ┼ nothing │ lq ┼ nothing │ flq ┼ nothing │ fa ┼ nothing │ kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,) w ┼ Vector{Float64}: [0.5, 0.5] fixed ┴ Bool: trueRelated
WeightsTrackingVecNumfactoryfactory(tn::Turnover, w::VecNum): Reads thefixedflag of the nested turnover in the same way.needs_previous_weights: Reads the same flag to decide whether the optimiser must give a previous weight vector.
PortfolioOptimisers.tracking_benchmark — Function
tracking_benchmark(tr::WeightsTracking, X::MatNum)Compute the net return series of the benchmark weights of a WeightsTracking.
This method states no definition of its own. It is calc_net_returns(tr.w, X, tr.fees), so the fee follows the amortisation that calc_net_returns reads from tr.fees.fa. Take the three-period matrix [0.01 0.02 -0.01 0.03; 0.03 0.04 0.02 -0.02; -0.01 0.005 0.01 0.04] and $\boldsymbol{w}_{b} = [0.3,\, 0.2,\, 0.4,\, 0.1]$. The benchmark is [0.006, 0.023, 0.006] with no fee, and [0.005, 0.022, 0.005] under Fees(; l = 0.001), whose fee is 0.001.
Algorithm
- Forward
tr.w,Xandtr.feestocalc_net_returns. - A
nothingtr.feesreaches theargs...method ofcalc_net_returns, which returnsX * tr.w. It does not reach theFeesmethod, so it charges no fee. - A
Feestr.feesreaches theFeesmethod, which givesX * tr.wtocharge_fees.
Arguments
tr: TheWeightsTrackingthat holds the benchmark weights and the fees.X: Asset return matrixobservations × assets.
Returns
b::VecNum: The net return series of the benchmark, one entry for each row ofX.
Examples
julia> tr = WeightsTracking(; w = [0.5, 0.5]);julia> X = [0.01 0.02; 0.03 0.04];julia> PortfolioOptimisers.tracking_benchmark(tr, X)2-element Vector{Float64}: 0.015 0.035Related
WeightsTrackingMatNumcalc_net_returns: The definition that this method calls.Feestracking_benchmark(tr::ReturnsTracking, X::VecNum_MatNum): The sibling, which reads only the number of rows of the return matrix.
tracking_benchmark(tr::ReturnsTracking)
tracking_benchmark(tr::ReturnsTracking, X::VecNum_MatNum)Return the benchmark return series that a ReturnsTracking holds.
The function reads no return matrix and applies no fee. The form with X reads only the number of rows of X. The series holds one return for each row, so the form refuses a matrix whose number of rows is not length(tr.w). Every reader of a tracking error subtracts the series from a series of the same rows. Without the check, a three-entry w against a seven-row matrix fails inside the reader with a DimensionMismatch. The check cannot see a series of other rows whose length is correct by chance. Such a series gives a tracking error against the wrong rows.
The series is constant after construction, so it does not follow the rows of an online step. The online step of an optimiser refuses it. See partial_fit!. Use DataBenchmarkTracking to track the benchmark that the returns data carries, or WeightsTracking to track a benchmark whose weights are known. Both read the rows that the reader holds.
Algorithm
- Refuse
Xwhen its number of rows is notlength(tr.w). - Return
tr.w.
Arguments
tr: TheReturnsTrackingthat holds the benchmark return series.X: The asset return matrix, or the portfolio return series, that the reader compares with the benchmark. The function reads only its number of rows.
Validation
size(X, 1) == length(tr.w). The function throws anArgumentErrorotherwise.
Returns
b::VecNum: Benchmark portfolio returns. It istr.witself, not a copy, sotracking_benchmark(tr) === tr.w.
Examples
julia> tr = ReturnsTracking(; w = [0.01, 0.02, 0.03]);julia> PortfolioOptimisers.tracking_benchmark(tr)3-element Vector{Float64}: 0.01 0.02 0.03julia> PortfolioOptimisers.tracking_benchmark(tr, zeros(3, 2)) === tr.wtrueRelated
ReturnsTrackingWeightsTrackingtracking_benchmark(tr::WeightsTracking, X::MatNum): The sibling, which reads the return matrix and charges a fee.TrackingError
tracking_benchmark(tr::DataBenchmarkTracking, X::VecNum_MatNum)Return the benchmark returns that a DataBenchmarkTracking holds, after the check that they cover the rows of X.
A vector is the benchmark series. A matrix holds one benchmark for each asset, and the reader forms the series $\mathbf{B}\boldsymbol{w}$ with its own weights. The function applies no fee.
Algorithm
- Refuse an unbound benchmark, whose
Bisnothing. - Refuse
Bwhen its number of rows is not the number of rows ofX. - Refuse a matrix
Bwhen its number of columns is not the number of columns ofX. - Return
tr.B.
Arguments
tr: ADataBenchmarkTrackingbound to the benchmark of the rows.X: The asset return matrix, or the portfolio return series, that the reader compares with the benchmark. The function reads only its size.
Validation
tr.Bis notnothing. The function throws anArgumentErrorotherwise.size(tr.B, 1) == size(X, 1), andsize(tr.B, 2) == size(X, 2)whentr.Bis a matrix. The function throws anArgumentErrorotherwise.
Returns
B::VecNum_MatNum:tr.Bitself.
Examples
julia> tr = DataBenchmarkTracking(; B = [0.01, 0.02]);julia> PortfolioOptimisers.tracking_benchmark(tr, zeros(2, 3)) === tr.BtrueRelated
DataBenchmarkTrackingbind_data_benchmarktracking_benchmark(tr::ReturnsTracking, X::VecNum_MatNum): The sibling, whose series is constant after construction.
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(tr::ReturnsTracking, i) -> ReturnsTrackingReturn the benchmark return series of tr at the observations i.
A ReturnsTracking holds one benchmark return for each observation, as a fixed observation weight vector holds one weight. So a cut of the observations of a fit, such as the drop of a Shared Series gap, drops the benchmark return of each dropped observation with it, see shared_series_estimator. The series is not an observation weight, so factory does not replace it. A TrackingRiskMeasure and a TrackingError reach this method through their tr field.
Arguments
tr: TheReturnsTrackingthat holds the benchmark return series.i: The observations to keep: a mask of the full sample, or their positions.
Validation
- For a mask, the rules of
observed_weights: the series has one entry for each entry of the mask. Raises aDimensionMismatch.
Returns
tr::ReturnsTracking: The series at the kept observations.
Examples
julia> tr = ReturnsTracking(; w = [0.01, 0.02, 0.03]);julia> PortfolioOptimisers.obs_weights_view(tr, [true, false, true]).w2-element Vector{Float64}: 0.01 0.03Related
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(tr::AbstractTrackingAlgorithm) -> Bool
needs_previous_weights(tr::WeightsTracking) -> Bool
needs_previous_weights(tr::TrackingError) -> Bool
needs_previous_weights(tr::VecTr) -> BoolCheck whether a tracking algorithm or tracking result needs the previous portfolio weights.
Only a WeightsTracking that is not fixed needs them, because only it changes its reference allocation when factory runs. A ReturnsTracking and a DataBenchmarkTracking reach the fallback, which returns false. The vector method reduces with any, not all. So one entry that needs the previous weights makes the whole vector need them. A vector with one fixed WeightsTracking and one that is not fixed returns true, where all gives false.
Algorithm
- On any
AbstractTrackingAlgorithmthat no method below claims, returnfalse. - On a
WeightsTracking, return!tr.fixed. - On a
TrackingError, forward to thetr.trfield and return its answer. - On a
VecTr, apply steps 1 to 3 to every entry and reduce withany.
Arguments
tr: One tracking algorithm, one tracking result, or a vector of tracking results.
Returns
Bool:trueiftrneeds the previous weights,falseotherwise.
Related
AbstractTrackingAlgorithmWeightsTrackingReturnsTrackingTrackingErrorVecTrfactory(tr::WeightsTracking, w::VecNum): The verb that reads the samefixedflag.Turnover: Has the samefixedflag and the sameanyrule.
References
- [10]
- M. Rudolf, H.-J. Wolter and H. Zimmermann. A linear model for tracking error minimization. Journal of Banking & Finance 23, 85–103 (1999).
- [11]
- J. E. Beasley, N. Meade and T.-J. Chang. An evolutionary heuristic for the index tracking problem. European Journal of Operational Research 148, 621–643 (2003).
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [187]
- R. Roll. A mean/variance analysis of tracking error. The Journal of Portfolio Management 18, 13–22 (1992).