Turnover

The turnover measures the absolute change of each weight from a set of reference weights, such as the weights before a rebalance. You can use it to compute fees or as a constraint. It is also a risk measure, which the turnover risk measure page describes.

PortfolioOptimisers.TurnoverEstimator — Type
struct TurnoverEstimator{__T_w, __T_val, __T_dval, __T_fixed} <: AbstractEstimator

Turnover bounds before turnover_constraints aligns them to a universe. The bounds can name assets or groups.

val can be a number, a vector, a pair, a dictionary, a vector of pairs, or a VectorAbstractEstimatorValueAlgorithm. A pair, a dictionary and a vector of pairs use asset or group names as keys, and dval is the bound of every asset that the keys do not name. turnover_constraints resolves the names against a UniverseSets and returns a Turnover whose val holds one bound per asset.

The w field holds the reference weights, not the candidate weights, as on Turnover.

Fields

  • 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.
  • val: Turnover bound. A number is one bound for every asset, and a vector holds one bound per asset. A TurnoverEstimator can also name the bounds by asset or by group, and turnover_constraints resolves the names to one bound per asset. A Fees reads the val of its Turnover as a fee rate per asset, not as a bound.
  • dval: Default value of each entry that val does not name.
  • fixed: If true, factory keeps the reference weights w and ignores the new weights. If false, factory replaces w with the new weights.

Constructors

TurnoverEstimator(;    w::VecNum,    val::VectorEstValType,    dval::Option{<:Number} = nothing,    fixed::Bool = false) -> TurnoverEstimator

Keywords correspond to the struct's fields.

Validation

  • w, through assert_nonempty_finite_val: !isempty(w) and all(isfinite, w).

  • val, through assert_nonempty_nonneg_finite_val:

    • AbstractDict: !isempty(val), all(isfinite, values(val)) and all(x -> x >= 0, values(val)).
    • Vector of pairs: !isempty(val), all(isfinite, getindex.(val, 2)) and all(x -> x[2] >= 0, val).
    • Pair: isfinite(val[2]) and val[2] >= 0.
    • AbstractVector of numbers: !isempty(val), all(isfinite, val) and all(x -> x >= 0, val).
    • Number: isfinite(val) and val >= 0.
    • VectorAbstractEstimatorValueAlgorithm: no rule.
  • dval, through assert_nonneg: if not nothing, dval >= 0. This rule admits +Inf, which the rules of val refuse. dval is the bound of every asset that val does not name, and dval = +Inf leaves these assets with no bound. dval = nothing gives them a bound of zero, which freezes their weights.

View parameters

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

Examples

julia> TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2), dval = 0.0)TurnoverEstimator      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1)   dval ┼ Float64: 0.0  fixed ┴ Bool: false

Related

source
PortfolioOptimisers.Turnover — Type
struct Turnover{__T_w, __T_val, __T_fixed} <: AbstractResult

Bound on the weight change of each asset from a reference portfolio.

Warning

The w field holds the reference weights, not the candidate weights. The candidate weights are the weight variable of the optimiser, and no field holds them. factory(tn, w) replaces the reference weights with w. Give it the weights of the last rebalance, and they become the reference of the next rebalance.

val is the bound. A Fees holds the same type and reads val as a fee rate per asset. The type that holds the Turnover thus gives the meaning of val.

Mathematical definition

\[\begin{align} \boldsymbol{Tn}(\boldsymbol{w}) &\coloneqq \lvert \boldsymbol{w} - \boldsymbol{w}_{0} \rvert\,, \\ \boldsymbol{Tn}(\boldsymbol{w}) &\leq \boldsymbol{\delta}\,. \end{align}\]

Where:

  • $\boldsymbol{Tn}(\boldsymbol{w})$: N × 1 turnover vector.
  • $\boldsymbol{w}$: N × 1 vector of candidate portfolio weights.
  • $\boldsymbol{w}_{0}$: Reference portfolio weights vector $N \times 1$, the weights from which the turnover is measured.
  • $\boldsymbol{\delta}$: N × 1 vector of maximum turnover, the val field. A scalar val broadcasts to every asset.
  • $\lvert \cdot \rvert$: Element-wise absolute value.

Fields

  • 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.
  • val: Turnover bound. A number is one bound for every asset, and a vector holds one bound per asset. A TurnoverEstimator can also name the bounds by asset or by group, and turnover_constraints resolves the names to one bound per asset. A Fees reads the val of its Turnover as a fee rate per asset, not as a bound.
  • fixed: If true, factory keeps the reference weights w and ignores the new weights. If false, factory replaces w with the new weights.

Constructors

Turnover(;    w::VecNum,    val::Num_VecNum = 0.0,    fixed::Bool = false) -> Turnover

Keywords correspond to the struct's fields.

Validation

The constructor checks the rules in the order of this list, so its error names the first rule that a value breaks.

  • w, through assert_nonempty_finite_val: !isempty(w) and all(isfinite, w).

  • val, through assert_nonempty and assert_nonneg:

    • AbstractVector: !isempty(val) and all(x -> x >= 0, val).
    • Number: val >= 0.

    A bound of +Inf leaves an asset with no bound, so the constructor does not check that val is finite. It refuses NaN and -Inf, because neither is >= 0.

  • length(w) == length(val) if val is an AbstractVector. The constructor raises a DimensionMismatch if this rule breaks.

View parameters

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

Examples

julia> Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0])Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: falsejulia> Turnover(; w = [0.2, 0.3, 0.5], val = 0.02, fixed = true)Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Float64: 0.02  fixed ┴ Bool: true

Related

References

  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.1, Equations 9.10 and 9.11. 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(tn::Turnover, w::VecNum)

Replace the reference weights of a Turnover, unless its fixed field is true.

The fixed field selects the weight vector that the result holds. A fixed constraint keeps the reference weights that it was built with, so the function ignores w and returns tn.

Algorithm

  1. If tn.fixed is true, return tn unchanged. The result holds the reference weights tn.w, and the argument w has no effect.
  2. If tn.fixed is false, build a new Turnover whose w is the argument w, and whose val and fixed are those of tn. The result holds the argument w.

Arguments

  • tn: The constraint to update. It gives the turnover bounds and the fixed flag.
  • w: New reference weight vector.

Validation

  • Step 2 builds a Turnover, so its constructor checks w. Step 1 checks nothing.

Returns

  • tn::Turnover: tn if tn.fixed is true. Otherwise, a new constraint with w as its reference weights.

Examples

julia> tn = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0])Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: falsejulia> factory(tn, [0.0, 0.2, 0.8])Turnover      w ┼ Vector{Float64}: [0.0, 0.2, 0.8]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: falsejulia> tn = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0], fixed = true)Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: truejulia> factory(tn, [0.0, 0.2, 0.8])Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: true

Related

source
PortfolioOptimisers.factory — Method
factory(tn::TurnoverEstimator, w::VecNum)

Replace the reference weights of a TurnoverEstimator, unless its fixed field is true.

The fixed field selects the weight vector that the result holds. A fixed estimator keeps the reference weights that it was built with, so the function ignores w and returns tn.

Algorithm

  1. If tn.fixed is true, return tn unchanged. The result holds the reference weights tn.w, and the argument w has no effect.
  2. If tn.fixed is false, build a new TurnoverEstimator whose w is the argument w, and whose val, dval and fixed are those of tn. The result holds the argument w.

Arguments

  • tn: The estimator to update. It gives the turnover bounds, the default bound and the fixed flag.
  • w: New reference weight vector.

Validation

  • Step 2 builds a TurnoverEstimator, so its constructor checks w. Step 1 checks nothing.

Returns

  • tn::TurnoverEstimator: tn if tn.fixed is true. Otherwise, a new estimator with w as its reference weights.

Examples

julia> tn = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2),                              dval = 0.0)TurnoverEstimator      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1)   dval ┼ Float64: 0.0  fixed ┴ Bool: falsejulia> factory(tn, [0.1, 0.4, 0.5])TurnoverEstimator      w ┼ Vector{Float64}: [0.1, 0.4, 0.5]    val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1)   dval ┼ Float64: 0.0  fixed ┴ Bool: falsejulia> tn = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2),                              dval = 0.0, fixed = true)TurnoverEstimator      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1)   dval ┼ Float64: 0.0  fixed ┴ Bool: truejulia> factory(tn, [0.1, 0.4, 0.5])TurnoverEstimator      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1)   dval ┼ Float64: 0.0  fixed ┴ Bool: true

Related

source
PortfolioOptimisers.factory — Method
factory(tn::VecTnE_Tn, w::VecNum)

Replace the reference weights of each entry of a vector of turnover constraints or estimators.

The method does what the generic vector method of factory does, and then calls concrete_typed_array_if_abstract. The element type of a vector that holds a Turnover and a TurnoverEstimator is then a Union of the two types, not an abstract type.

Algorithm

  1. For each entry tni of tn, in the order of tn, call factory on tni with w. A fixed entry returns itself with its own reference weights, so the result can hold entries of both kinds.
  2. Pass the vector of step 1 through concrete_typed_array_if_abstract. The two turnover types have no common concrete type, so step 1 can give the vector an abstract element type. This step narrows it to a Union of the element types.

Arguments

  • tn: Vector of turnover constraints or estimators.
  • w: New reference weight vector.

Returns

  • res::VecTnE_Tn: One updated entry per entry of tn, in the order of tn.

Examples

julia> tn1 = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0]);julia> tn2 = Turnover(; w = [0.2, 0.3, 0.5], val = [0.05, 0.1, 0.0]);julia> factory([tn1, tn2], [0.1, 0.4, 0.5])2-element Vector{Turnover{Vector{Float64}, Vector{Float64}, Bool}}: Turnover      w ┼ Vector{Float64}: [0.1, 0.4, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: false Turnover      w ┼ Vector{Float64}: [0.1, 0.4, 0.5]    val ┼ Vector{Float64}: [0.05, 0.1, 0.0]  fixed ┴ Bool: false

Related

source
PortfolioOptimisers.turnover_constraints — Function
turnover_constraints(tn::TurnoverEstimator, sets::UniverseSets; datatype::DataType = Float64,
                     strict::Bool = false)

Resolve the names of a TurnoverEstimator against a universe, and return a Turnover.

The result holds the reference weights of tn and one turnover bound per asset of sets. TurnoverEstimator lists the shapes that tn.val can take.

Algorithm

  1. Resolve tn.val against the universe of sets with estimator_to_val. The result is one turnover bound per asset, in the order of the universe and not in the order of the keys of tn.val. Every asset that the keys do not name takes tn.dval, or zero(datatype) if tn.dval is nothing. A key that names neither an asset nor a group raises an error if strict is true, and logs a warning if strict is false.
  2. Build a Turnover from tn.w, the bounds of step 1 and tn.fixed.

Arguments

  • tn: The estimator to resolve. It gives the reference weights, the turnover bounds and the default bound.
  • sets: UniverseSets that holds the asset names of the universe and the groups.
  • datatype: Element type of the bounds if tn.dval is nothing. It has no effect if tn.dval is a number.
  • strict: If true, a key that names no asset and no group raises an error. If false, it logs a warning.

Returns

  • tn::Turnover: The reference weights of tn, with one turnover bound per asset of sets.

Examples

julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> tn = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2));julia> turnover_constraints(tn, sets)Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: false

Related

source
turnover_constraints(tn::Option{<:Turnover}, args...; kwargs...)
turnover_constraints(tns::AbstractVector{<:Turnover}, ::Nothing, args...; kwargs...)

Return a resolved turnover constraint, a vector of them, or nothing, unchanged.

A Turnover holds one bound per asset, so it needs no universe. A vector of them with no universe also returns unchanged, as a vector of LinearConstraint does. The constructors of JuMPOptimiser and of ProgrammeAllocationSet refuse a vector that holds a TurnoverEstimator when they have no universe, so such a vector never reaches this method.

Algorithm

  1. Return the first argument unchanged. The method reads no other argument and no keyword.

Arguments

  • tn: A Turnover, or nothing.
  • tns: A vector of Turnover.
  • args...: More positional arguments. The method ignores them.
  • kwargs...: Keyword arguments. The method ignores them.

Returns

  • tn::Option{<:Turnover}: The input constraint, unchanged.
  • tns::AbstractVector{<:Turnover}: The input vector, unchanged.

Examples

julia> tn = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0]);julia> turnover_constraints(tn)Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: false

Related

source
turnover_constraints(tn::VecTnE_Tn, sets::UniverseSets; datatype::DataType = Float64,
                     strict::Bool = false)

Apply turnover_constraints to each entry of a vector of turnover constraints or estimators.

Algorithm

  1. For each entry tni of tn, in the order of tn, call turnover_constraints on tni with sets, datatype and strict. An entry that is already a Turnover passes through.
  2. Collect the results into a vector that preserves the order of tn.

Arguments

  • tn: Vector of turnover constraints or estimators.
  • sets: UniverseSets that holds the asset names of the universe and the groups.
  • datatype: Element type of the bounds of an estimator whose dval is nothing.
  • strict: If true, a key that names no asset and no group raises an error. If false, it logs a warning.

Returns

  • res::VecTn: One resolved turnover constraint per entry of tn, in the order of tn.

Examples

julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> tn1 = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2));julia> tn2 = TurnoverEstimator(; w = [0.1, 0.4, 0.5], val = Dict("B" => 0.15, "C" => 0.3));julia> turnover_constraints([tn1, tn2], sets)2-element Vector{Turnover{Vector{Float64}, Vector{Float64}, Bool}}: Turnover      w ┼ Vector{Float64}: [0.2, 0.3, 0.5]    val ┼ Vector{Float64}: [0.1, 0.2, 0.0]  fixed ┴ Bool: false Turnover      w ┼ Vector{Float64}: [0.1, 0.4, 0.5]    val ┼ Vector{Float64}: [0.0, 0.15, 0.3]  fixed ┴ Bool: false

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(tn::VecTnE_Tn, i, args...)

View each entry of a vector of turnover constraints or estimators at a subset of the assets.

The method does what the generic vector method of port_opt_view does, and then calls concrete_typed_array_if_abstract, for the reason that factory(tn::VecTnE_Tn, w::VecNum) gives.

Algorithm

  1. For each entry tni of tn, in the order of tn, call port_opt_view on tni with i and args.... The @vprop tags of each type select the fields to slice. w and a vector val become views at i, and a number or a dictionary val stays unchanged.
  2. Pass the vector of step 1 through concrete_typed_array_if_abstract.

Arguments

  • tn: Vector of turnover constraints or estimators.
  • i: Index or indices of the subset of assets.
  • args...: More arguments, which the method gives unchanged to the port_opt_view of each entry.

Returns

  • res::VecTnE_Tn: One view per entry of tn, in the order of tn.

Examples

julia> tn1 = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0], fixed = true);julia> tn2 = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2),                               dval = 0.0, fixed = true);julia> PortfolioOptimisers.port_opt_view(concrete_typed_array([tn1, tn2]), 1:2)2-element Vector{Union{Turnover{SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Bool}, TurnoverEstimator{SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Dict{String, Float64}, Float64, Bool}}}: Turnover      w ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.2, 0.3]    val ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.1, 0.2]  fixed ┴ Bool: true TurnoverEstimator      w ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.2, 0.3]    val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1)   dval ┼ Float64: 0.0  fixed ┴ Bool: true

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(tn::TnE_Tn) -> Bool
needs_previous_weights(tn::VecTnE_Tn) -> Bool

Tell whether a turnover constraint or estimator needs the previous portfolio weights.

A fixed entry keeps its own reference weights, so it needs no previous weights, and the method for one entry returns !tn.fixed. The vector method reduces with any, not with all. So one entry that is not fixed makes the whole vector need the previous weights.

Algorithm

  1. On a single TnE_Tn, return !tn.fixed.
  2. On a VecTnE_Tn, apply step 1 to every entry and reduce with any.

Arguments

  • tn: One turnover constraint or estimator, or a vector of them.

Returns

  • Bool: true if tn needs the previous weights, else false.

Related

source

References

[12]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).