Skip to content
13

Tracking

Public

PortfolioOptimisers.L2Tracking Type
julia
struct L2Tracking{__T_ddof} <: NormTracking

Second-order cone (SOC) norm-based tracking formulation.

L2Tracking implements a norm-based tracking error formulation using the Euclidean (L2) norm, scaled by the square root of the number of assets minus the degrees of freedom (ddof). This is commonly used for tracking error constraints and objectives in portfolio optimisation.

Mathematical definition

TEL2(a,b)=ab2Td.

Where:

  • TEL2(a,b): L2-norm tracking error.

  • a: Portfolio weight or return vector T×1.

  • b: Benchmark vector T×1.

  • T: Number of observations.

  • d: Degrees of freedom, ddof. When T is not provided the denominator is 1.

Fields

  • ddof: Degrees-of-freedom correction.

Constructors

julia
L2Tracking(;
    ddof::Integer = 1
) -> L2Tracking

Validation

  • 0 <= ddof.

Examples

julia
julia> L2Tracking()
L2Tracking
  ddof ┴ Int64: 1

Related

source
PortfolioOptimisers.SquaredL2Tracking Type
julia
struct SquaredL2Tracking{__T_ddof} <: NormTracking

Second-order cone (SOC) squared norm-based tracking formulation.

SquaredL2Tracking implements a norm-based tracking error formulation using the squared Euclidean (L2) norm, scaled by the number of assets minus the degrees of freedom (ddof). This is commonly used for tracking error constraints and objectives in portfolio optimisation where squared error is preferred.

Mathematical definition

TEL22(a,b)=ab22Td.

Where:

  • TEL22(a,b): Squared L2-norm tracking error.

  • a: Portfolio weight or return vector T×1.

  • b: Benchmark vector T×1.

  • T: Number of observations.

  • d: Degrees of freedom, ddof. When T is not provided the denominator is 1.

Fields

  • ddof: Degrees-of-freedom correction.

Constructors

julia
SquaredL2Tracking(;
    ddof::Integer = 1,
) -> SquaredL2Tracking

Validation

  • 0 <= ddof.

Examples

julia
julia> SquaredL2Tracking()
SquaredL2Tracking
  ddof ┴ Int64: 1

Related

source
PortfolioOptimisers.L1Tracking Type
julia
struct L1Tracking <: NormTracking

Norm-one (NOC) tracking formulation.

L1Tracking implements a norm-based tracking error formulation using the L1 (norm-one) distance between portfolio and benchmark weights. This is commonly used for tracking error constraints and objectives in portfolio optimisation where sparsity or absolute deviations are preferred.

Mathematical definition

TEL1(a,b)=ab1T.

Where:

  • TEL1(a,b): L1-norm tracking error.

  • a: Portfolio weight or return vector T×1.

  • b: Benchmark vector T×1.

  • T: Number of observations. When T is not provided the denominator is 1.

Constructors

julia
L1Tracking() -> L1Tracking

Examples

julia
julia> L1Tracking()
L1Tracking()

Related

source
PortfolioOptimisers.LpTracking Type
julia
struct LpTracking{__T_p, __T_ddof} <: NormTracking

L-p norm tracking error estimator.

Computes the Lp-norm of the difference between portfolio and benchmark returns: |Xwb|p.

Mathematical definition

TELp(a,b)=abp(Td)1/p.

Where:

  • TELp(a,b): Lp-norm tracking error.

  • a: Portfolio weight or return vector T×1.

  • b: Benchmark vector T×1.

  • T: Number of observations.

  • d: Degrees of freedom, ddof. When T is not provided the denominator is 1.

  • p: Norm order.

Fields

  • p: Power or order parameter.

  • ddof: Degrees-of-freedom correction.

Constructors

julia
LpTracking(; p::Number = 3, ddof::Integer = 0) -> LpTracking

Keywords correspond to the struct's fields.

Validation

  • 0 <= ddof.

Examples

julia
julia> LpTracking()
LpTracking
     p ┼ Int64: 3
  ddof ┴ Int64: 0

Related

source
PortfolioOptimisers.LInfTracking Type
julia
struct LInfTracking{__T_ddof, __T_pos} <: NormTracking

L-infinity norm (maximum absolute deviation) tracking error estimator.

Computes the L∞-norm (maximum absolute deviation) of the difference between portfolio and benchmark returns.

Mathematical definition

TEL(a,b)=abTd.

Where:

  • TEL(a,b): L∞-norm tracking error. pos = true uses +, pos = false uses .

  • a: Portfolio weight or return vector T×1.

  • b: Benchmark vector T×1.

  • T: Number of observations.

  • d: Degrees of freedom, ddof. When T is not provided the denominator is 1.

Fields

  • ddof: Degrees-of-freedom correction.

  • pos: Whether to consider only positive deviations.

Constructors

julia
LInfTracking(; ddof::Integer = 0, pos::Bool = true) -> LInfTracking

Keywords correspond to the struct's fields.

Validation

  • 0 <= ddof.

Examples

julia
julia> LInfTracking()
LInfTracking
  ddof ┼ Int64: 0
   pos ┴ Bool: true

Related

source
PortfolioOptimisers.IndependentVariableTracking Type
julia
struct IndependentVariableTracking <: VariableTracking

Independent variable-based tracking formulation.

IndependentVariableTracking tracks the independent variables of a measurement.

Constructors

julia
IndependentVariableTracking() -> IndependentVariableTracking

Examples

julia
julia> IndependentVariableTracking()
IndependentVariableTracking()

Related

source
PortfolioOptimisers.DependentVariableTracking Type
julia
struct DependentVariableTracking <: VariableTracking

Dependent variable-based tracking formulation.

DependentVariableTracking tracks the measurement.

Constructors

julia
DependentVariableTracking() -> DependentVariableTracking

Examples

julia
julia> DependentVariableTracking()
DependentVariableTracking()

Related

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

Asset weights-based tracking algorithm.

WeightsTracking represents a tracking algorithm that operates directly on portfolio weights, optionally incorporating transaction fees. This is used for tracking error measurement and constraint generation where the comparison is made between portfolio weights and benchmark weights, with optional adjustment for fees.

Fields

  • fees: Fees estimator or result.

  • w: Current portfolio weights vector.

  • fixed: Whether the estimator is fixed and does not update with new weights.

Constructors

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

Validation

  • !isempty(w).

View parameters

When port_opt_view is called on this type, the following @vprop-tagged fields are automatically subset to the selected indices:

Examples

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

Related

source
PortfolioOptimisers.ReturnsTracking Type
julia
struct ReturnsTracking{__T_w} <: AbstractTrackingAlgorithm

Returns-based tracking algorithm.

ReturnsTracking represents a tracking algorithm that operates directly on portfolio returns, rather than asset weights. This is used for tracking error measurement and constraint generation where the comparison is made between portfolio returns and benchmark returns.

Fields

  • w: Benchmark portfolio returns vector.

Constructors

julia
ReturnsTracking(;
    w::VecNum
) -> ReturnsTracking

Validation

  • !isempty(w).

Examples

julia
julia> ReturnsTracking(; w = [0.01, 0.02, 0.03])
ReturnsTracking
  w ┴ Vector{Float64}: [0.01, 0.02, 0.03]

Related

source
PortfolioOptimisers.TrackingError Type
julia
struct TrackingError{__T_tr, __T_err, __T_alg} <: AbstractTracking

Tracking error result type.

TrackingError represents the result of a tracking error computation, including the tracking algorithm used, the computed error value, and the tracking formulation algorithm. This type is used to store and propagate tracking error results in portfolio analytics and optimisation workflows.

Fields

  • tr: Tracking error constraint estimator.

  • err: Tracking error tolerance.

  • alg: Tracking formulation algorithm.

Constructors

julia
TrackingError(;
    tr::AbstractTrackingAlgorithm,
    err::Number = 0.0,
    alg::NormTracking = L2Tracking()
) -> TrackingError

Validation

  • isfinite(err) and err >= 0.

Propagated parameters

When factory is called on this type, the following @fprop-tagged fields are automatically propagated:

  • tr: Recursively updated via factory.

View parameters

When port_opt_view is called on this type, the following @vprop-tagged fields are automatically subset to the selected indices:

Examples

julia
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 ┼ L2Tracking
      │   ddof ┴ Int64: 1

Related

source
PortfolioOptimisers.TrackingFormulation Type
julia
abstract type TrackingFormulation <: AbstractAlgorithm

Abstract supertype for all tracking formulation algorithm types in PortfolioOptimisers.jl.

All concrete and/or abstract types representing tracking formulation algorithms (such as norm-based or variable-based tracking) should be subtypes of TrackingFormulation.

Related

source

Private

PortfolioOptimisers.AbstractTracking Type
julia
abstract type AbstractTracking <: AbstractResult

Abstract supertype for all tracking result types in PortfolioOptimisers.jl.

All concrete and/or abstract types representing tracking error or tracking constraint results should be subtypes of AbstractTracking.

Related

source
PortfolioOptimisers.AbstractTrackingAlgorithm Type
julia
abstract type AbstractTrackingAlgorithm <: AbstractAlgorithm

Abstract supertype for all tracking algorithm types in PortfolioOptimisers.jl.

All concrete and/or abstract types representing tracking algorithms (such as weights or returns tracking) should be subtypes of AbstractTrackingAlgorithm.

Interfaces

In order to implement a new tracking algorithm that works seamlessly with the library, subtype AbstractTrackingAlgorithm and implement the following methods:

  • tracking_benchmark(tr::AbstractTrackingAlgorithm, X::MatNum) -> VecNum: Compute benchmark returns from the asset return matrix X.

  • factory(tr::AbstractTrackingAlgorithm, w::VecNum) -> AbstractTrackingAlgorithm: Construct a new instance with updated portfolio weights w.

  • port_opt_view(tr::AbstractTrackingAlgorithm, i) -> AbstractTrackingAlgorithm: Create a view of the tracking algorithm for the subset of assets at indices i.

Arguments

  • tr: The concrete tracking algorithm instance.

  • X: Covariance-like or correlation-like matrix features × features.

  • w: New portfolio weights.

  • i: Index or indices for asset subset.

Returns

  • b::VecNum: Benchmark returns (for tracking_benchmark).

  • tr::AbstractTrackingAlgorithm: Updated or viewed tracking algorithm (for factory, port_opt_view).

Examples

julia
julia> struct MyTracking <: PortfolioOptimisers.AbstractTrackingAlgorithm
           w::Vector{Float64}
       end

julia> function PortfolioOptimisers.tracking_benchmark(tr::MyTracking,
                                                       X::PortfolioOptimisers.MatNum)
           return X * tr.w
       end

julia> 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.VecTr Type
julia
const VecTr = AbstractVector{<:AbstractTracking}

Alias for a vector of tracking result types.

Related

source
PortfolioOptimisers.Tr_VecTr Type
julia
const Tr_VecTr = Union{<:AbstractTracking, <:VecTr}

Union type for a single tracking result or a vector of tracking results.

Related

source
PortfolioOptimisers.NormTracking Type
julia
abstract type NormTracking <: TrackingFormulation

Abstract supertype for all norm-based tracking formulation algorithms in PortfolioOptimisers.jl.

All concrete and/or abstract types representing norm-based tracking algorithms (such as second-order cone or norm-one tracking) should be subtypes of NormTracking.

Related

source
PortfolioOptimisers.VariableTracking Type
julia
abstract type VariableTracking <: TrackingFormulation

Abstract supertype for all variable-based tracking formulation algorithms in PortfolioOptimisers.jl.

All concrete and/or abstract types representing variable-based tracking algorithms (such as independent or dependent variable tracking) should be subtypes of VariableTracking.

Related

source
PortfolioOptimisers.norm_tracking Function
julia
norm_tracking(f::L2Tracking, a, b, T::Option{<:Number} = nothing)
norm_tracking(f::SquaredL2Tracking, a, b, T::Option{<:Number} = nothing)
norm_tracking(::L1Tracking, a, b, T::Option{<:Number} = nothing)
norm_tracking(f::LpTracking, a, b, T::Option{<:Number} = nothing)
norm_tracking(f::LInfTracking, a, b, T::Option{<:Number} = nothing)

Compute the norm-based tracking error between portfolio and benchmark weights.

norm_tracking computes the tracking error using either the Euclidean (L2) norm for L2Tracking, squared Euclidean (L2) norm for SquaredL2Tracking, or the L1 (norm-one) distance for L1Tracking. The error is optionally scaled by the number of assets and degrees of freedom for SOC, or by the number of assets for NOC.

Mathematical definition

TEL2(a,b)=ab2Td,TEL22(a,b)=ab22Td,TEL1(a,b)=ab1T,TELp(a,b)=abp(Td)1/p,TEL(a,b)=abTd.

Where:

  • a: Portfolio weight or return vector T×1.

  • b: Benchmark vector T×1.

  • T: Number of observations.

  • d: Degrees of freedom, ddof.

  • p: Norm order.

Arguments

  • f: Tracking formulation algorithm.

  • a: Portfolio weights.

  • b: Benchmark weights.

  • T: Optional number of observations.

Returns

  • err::Number: Norm-based tracking error.

Details

  • For L2Tracking, computes LinearAlgebra.norm(a - b, 2) / sqrt(T - f.ddof) if T is not nothing, else unscaled.

  • For SquaredL2Tracking, computes LinearAlgebra.norm(a - b, 2)^2 / (T - f.ddof) if T is not nothing, else unscaled.

  • For L1Tracking, computes LinearAlgebra.norm(a - b, 1) / T if T is not nothing, else unscaled.

Examples

julia
julia> PortfolioOptimisers.norm_tracking(L2Tracking(), [0.5, 0.5], [0.6, 0.4], 2)
0.14142135623730948

julia> PortfolioOptimisers.norm_tracking(L1Tracking(), [0.5, 0.5], [0.6, 0.4], 2)
0.09999999999999998

Related

source
PortfolioOptimisers.tracking_benchmark Function
julia
tracking_benchmark(tr::WeightsTracking, X::MatNum)

Compute the benchmark portfolio returns for a weights-based tracking algorithm.

tracking_benchmark computes the net portfolio returns for the benchmark weights stored in a WeightsTracking object, optionally adjusting for transaction fees if specified. The asset return matrix X is multiplied by the benchmark weights, and fees are deducted if present.

Arguments

  • tr: WeightsTracking tracking algorithm containing benchmark weights and optional fees.

  • X: Asset return matrix (assets × periods).

Returns

  • b::VecNum: Net benchmark portfolio returns.

Details

  • If tr.fees is not nothing, net returns are computed using calc_net_returns.

  • Otherwise, returns are computed as X * tr.w.

Examples

julia
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
julia
tracking_benchmark(tr::ReturnsTracking, args...)

Return the benchmark portfolio returns for a returns-based tracking algorithm.

tracking_benchmark extracts the benchmark portfolio returns stored in a ReturnsTracking object. This is used for tracking error measurement and constraint generation where the comparison is made directly between portfolio returns and benchmark returns.

Arguments

  • tr: ReturnsTracking tracking algorithm containing benchmark returns.

  • args...: For interface compatibility (ignored).

Returns

  • b::VecNum: Benchmark portfolio returns.

Examples

julia
julia> tr = ReturnsTracking(; w = [0.01, 0.02, 0.03]);

julia> PortfolioOptimisers.tracking_benchmark(tr)
3-element Vector{Float64}:
 0.01
 0.02
 0.03

Related

source
PortfolioOptimisers.port_opt_view Method
julia
port_opt_view(tr::VecTr, args...)

Return a vector of tracking views for each element in a vector of tracking results.

This function applies port_opt_view to each element of the input vector of tracking results, passing any additional arguments. It enables efficient subsetting and composability for collections of tracking error or tracking constraint results.

Arguments

  • tr: A vector of tracking result objects (VecTr).

  • args...: Additional arguments to pass to each port_opt_view call.

Returns

  • tres::Vector{<:AbstractTracking}: Vector of tracking view results.

Details

  • Applies port_opt_view to each element in the input vector.

  • Passes all additional arguments to each call.

  • Returns a vector of the results.

Examples

julia
julia> tr = TrackingError(; tr = WeightsTracking(; w = [0.5, 0.5, 0.5]), err = 0.01);

julia> PortfolioOptimisers.port_opt_view([tr], 1:2)
1-element Vector{TrackingError{WeightsTracking{Nothing, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Bool}, Float64, L2Tracking{Int64}}}:
 TrackingError
   tr ┼ WeightsTracking
      │    fees ┼ nothing
      │       w ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.5, 0.5]
      │   fixed ┴ Bool: false
  err ┼ Float64: 0.01
  alg ┼ L2Tracking
      │   ddof ┴ Int64: 1

Related

source
PortfolioOptimisers.factory Method
julia
factory(tr::WeightsTracking, w::VecNum)

Construct a new WeightsTracking object with updated portfolio weights.

This function creates a new WeightsTracking instance by copying the fees from the input tr object and replacing the portfolio weights with w. The fees field is updated using the factory function on the existing fees and weights.

Arguments

Returns

  • tr::WeightsTracking: New tracking algorithm object with updated weights.

Details

  • Copies and updates the fees field using factory(tr.fees, tr.w).

  • Replaces the w field with the provided weights.

Examples

julia
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
        │   kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,)
      w ┼ Vector{Float64}: [0.5, 0.5]
  fixed ┴ Bool: false

julia> PortfolioOptimisers.factory(tr, [0.6, 0.4])
WeightsTracking
   fees ┼ Fees
        │       tn ┼ nothing
        │        l ┼ Float64: 0.002
        │        s ┼ nothing
        │       fl ┼ nothing
        │       fs ┼ nothing
        │   kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,)
      w ┼ Vector{Float64}: [0.6, 0.4]
  fixed ┴ Bool: false

julia> 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
        │   kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,)
      w ┼ Vector{Float64}: [0.5, 0.5]
  fixed ┴ Bool: true

julia> PortfolioOptimisers.factory(tr, [0.1, 0.1])
WeightsTracking
   fees ┼ Fees
        │       tn ┼ nothing
        │        l ┼ Float64: 0.002
        │        s ┼ nothing
        │       fl ┼ nothing
        │       fs ┼ nothing
        │   kwargs ┴ @NamedTuple{atol::Float64}: (atol = 1.0e-8,)
      w ┼ Vector{Float64}: [0.5, 0.5]
  fixed ┴ Bool: true

Related

source