Tracking

PortfolioOptimisers.AbstractTrackingAlgorithm — Type
abstract type AbstractTrackingAlgorithm <: AbstractAlgorithm

Abstract 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).

PriorFormVector BMatrix BStatus
rawa plain risk measureX * wX * wabsolute risk
excessa plain risk measureX * w - B * s(X - B) * wactive risk
rawWeightsTrackingX * (w - w_b)X * (w - w_b)valid
excessWeightsTrackingX * (w - w_b) - B * (s - s_b)(X - B) * (w - w_b)valid
rawReturnsTrackingX * w - bX * w - bvalid
excessReturnsTrackingX * w - B * s - b(X - B) * w - bvalid if b is excess
rawDataBenchmarkTrackingX * w - B(X - B) * wvalid
excessDataBenchmarkTrackingX * w - B * (s + 1)(X - 2B) * wrefused

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 matrix X.
  • factory(tr::AbstractTrackingAlgorithm, w::VecNum) -> AbstractTrackingAlgorithm: Returns a tracking algorithm that holds the new weights w.
  • port_opt_view(tr::AbstractTrackingAlgorithm, i) -> AbstractTrackingAlgorithm: Returns the tracking algorithm of the assets at the indices i.

Arguments

  • tr: The tracking algorithm.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • w: The new portfolio weights.
  • i: The index or the indices of the assets in the view.

Returns

  • b::VecNum: The benchmark series that tracking_benchmark returns.
  • tr::AbstractTrackingAlgorithm: The tracking algorithm that factory or port_opt_view returns.

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.035

Related

source
PortfolioOptimisers.IndependentVariableTracking — Type
struct IndependentVariableTracking <: VariableTracking

Applies 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() -> IndependentVariableTracking

Examples

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.
source
PortfolioOptimisers.DependentVariableTracking — Type
struct DependentVariableTracking <: VariableTracking

Applies 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 RiskTrackingRiskMeasure with settings.ub, or in a RiskTrackingError, it is the ceiling $R(\boldsymbol{w}) \leq R(\boldsymbol{w}_{b}) + \varepsilon$. Here $\varepsilon$ is the err of the tracking error or the settings.ub of the measure. The model evaluates $R(\boldsymbol{w}_{b})$ on the prior of the optimisation, and a WeightsTracking benchmark that is not fixed takes the previous weights. So the ceiling changes with the data and with the benchmark. A fixed settings.ub on the measure cannot do this.
  • In the objective, it penalises only the risk above the benchmark risk. The semidefinite Variance is 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 a SemiDefinitePhylogeny and $s$ is the tracking scale. $s_v$ is the scale of a variance that the objective minimises on the same weights, and it is 0 when 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() -> DependentVariableTracking

Examples

julia> DependentVariableTracking()DependentVariableTracking()

Related

source
PortfolioOptimisers.WeightsTracking — Type
struct WeightsTracking{__T_fees, __T_w, __T_fixed} <: AbstractTrackingAlgorithm

Builds 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 × 1 benchmark return vector.
  • $\mathbf{X}$: T × N asset return matrix.
  • $\boldsymbol{w}_{b}$: N × 1 benchmark weight vector, the w field.
  • $\boldsymbol{F}(\boldsymbol{w}_{b})$: The fee that each period charges on the benchmark, from the fees field. It is zero when fees is nothing. See calc_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: If true, factory keeps the reference weights w and ignores the new weights. If false, factory replaces w with the new weights.

Constructors

WeightsTracking(;    fees::Option{<:Fees} = nothing,    w::VecNum,    fixed::Bool = false) -> WeightsTracking

Keywords correspond to the struct's fields.

Validation

  • w, through assert_nonempty_finite_val: !isempty(w) and all(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:

Examples

julia> WeightsTracking(; w = [0.5, 0.5])WeightsTracking   fees ┼ nothing      w ┼ Vector{Float64}: [0.5, 0.5]  fixed ┴ Bool: false

Related

References

  • [187] R. Roll. A mean/variance analysis of tracking error. The Journal of Portfolio Management 18, 13–22 (1992). Page 15.
  • [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.
source
PortfolioOptimisers.ReturnsTracking — Type
struct ReturnsTracking{__T_w} <: AbstractTrackingAlgorithm

Holds 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 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.

Constructors

ReturnsTracking(;    w::VecNum) -> ReturnsTracking

Keywords correspond to the struct's fields.

Validation

  • w, through assert_nonempty_finite_val: !isempty(w) and all(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.
source
PortfolioOptimisers.DataBenchmarkTracking — Type
struct DataBenchmarkTracking{__T_B} <: AbstractTrackingAlgorithm

Tracks 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 × 1 benchmark return series.
  • $\mathbf{B}$: Benchmark returns of the rows, the B field. A vector T × 1 is one benchmark that every asset shares, and a matrix T × N holds 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 the B field of the ReturnsResult of the reader. A vector T × 1 is the benchmark series. A matrix T × N holds one benchmark for each asset, and its series is B * w. Every reader that holds the returns data replaces it with the B of its own rows through bind_data_benchmark. It is nothing until a reader binds it.

Constructors

DataBenchmarkTracking(;    B::Option{<:VecNum_MatNum} = nothing) -> DataBenchmarkTracking

Keywords 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

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.
source
PortfolioOptimisers.TrackingError — Type
struct TrackingError{__T_tr, __T_err, __T_alg} <: AbstractTracking

Bounds 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 × 1 net portfolio return series.
  • $\boldsymbol{b}$: T × 1 benchmark return series, from tracking_benchmark on the tr field.
  • $\lVert \cdot \rVert$, $c$: The norm and the scaling factor that alg names. norm_error computes the scaled norm, and norm_factor gives $c$.
  • $\mathrm{err}$: The err field.
Warning

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:

algConeCone rowRows the branch adds
L1NormJuMP.MOI.NormOneCone:ctr_noc_none
L2Norm, SquaredL2NormJuMP.SecondOrderCone:ctr_soc_none
LpNormJuMP.MOI.PowerCone:ctr_pnorm_:r_tr_, :cstr_
LInfNormJuMP.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()) -> TrackingError

Keywords correspond to the struct's fields.

Validation

  • err, through assert_nonempty_nonneg_finite_val: isfinite(err) and err >= 0. A failed check throws a DomainError that names err. The constructor accepts err = 0.0, which permits no deviation from the benchmark.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • tr: Recursively updated through factory.

View parameters

port_opt_view takes the view of these @vprop fields at the selected indices:

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

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

  1. Read tr.fixed.
  2. When tr.fixed is true, return tr itself. The function does not read w.
  3. When tr.fixed is false, advance the fees with factory(tr.fees, tr.w). This gives the old weights to the nested turnover as its reference.
  4. Build a new WeightsTracking from the advanced fees, the new w, and the unchanged tr.fixed.

Arguments

Returns

  • tr::WeightsTracking: A new tracking algorithm that holds w, or tr itself when tr.fixed is true.

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

Related

source
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

  1. Forward tr.w, X and tr.fees to calc_net_returns.
  2. A nothing tr.fees reaches the args... method of calc_net_returns, which returns X * tr.w. It does not reach the Fees method, so it charges no fee.
  3. A Fees tr.fees reaches the Fees method, which gives X * tr.w to charge_fees.

Arguments

  • tr: The WeightsTracking that holds the benchmark weights and the fees.
  • X: Asset return matrix observations × assets.

Returns

  • b::VecNum: The net return series of the benchmark, one entry for each row of X.

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.035

Related

source
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

  1. Refuse X when its number of rows is not length(tr.w).
  2. Return tr.w.

Arguments

  • tr: The ReturnsTracking that 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 an ArgumentError otherwise.

Returns

  • b::VecNum: Benchmark portfolio returns. It is tr.w itself, not a copy, so tracking_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.wtrue

Related

source
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

  1. Refuse an unbound benchmark, whose B is nothing.
  2. Refuse B when its number of rows is not the number of rows of X.
  3. Refuse a matrix B when its number of columns is not the number of columns of X.
  4. Return tr.B.

Arguments

  • tr: A DataBenchmarkTracking bound 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.B is not nothing. The function throws an ArgumentError otherwise.
  • size(tr.B, 1) == size(X, 1), and size(tr.B, 2) == size(X, 2) when tr.B is a matrix. The function throws an ArgumentError otherwise.

Returns

  • B::VecNum_MatNum: tr.B itself.

Examples

julia> tr = DataBenchmarkTracking(; B = [0.01, 0.02]);julia> PortfolioOptimisers.tracking_benchmark(tr, zeros(2, 3)) === tr.Btrue

Related

source
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(tr::ReturnsTracking, i) -> ReturnsTracking

Return 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: The ReturnsTracking that 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 a DimensionMismatch.

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.03

Related

source
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) -> Bool

Check 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

  1. On any AbstractTrackingAlgorithm that no method below claims, return false.
  2. On a WeightsTracking, return !tr.fixed.
  3. On a TrackingError, forward to the tr.tr field and return its answer.
  4. On a VecTr, apply steps 1 to 3 to every entry and reduce with any.

Arguments

  • tr: One tracking algorithm, one tracking result, or a vector of tracking results.

Returns

  • Bool: true if tr needs the previous weights, false otherwise.

Related

source

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).