Threshold constraint generation

PortfolioOptimisers.ThresholdEstimator — Type
struct ThresholdEstimator{__T_val, __T_key, __T_dval} <: AbstractConstraintEstimator

Resolves a minimum-holding threshold written in asset or group names against a universe.

threshold_constraints resolves it to a Threshold. The function finds the indices of each name in the universe that key selects, and gives dval to each unnamed asset. The default dval gives no threshold. A threshold can also be a scalar, a vector, or an algorithmic rule such as UniformValues.

The universe key is a field of this estimator, and estimator_to_val uses sets.xkey when the key is nothing. RiskBudgetEstimator has the same shape, but its function takes the key as a positional argument.

A dval of nothing goes unchanged to estimator_to_val, which uses zero(datatype). An unnamed asset has no threshold. The nothing default of a risk budget is different, because it becomes the uniform share of its axis.

Fields

  • val: Minimum-holding thresholds, as a map from asset or group names to values, a scalar, a vector or an algorithmic rule.
  • key: Key of the universe in sets.dict that names resolve against. If nothing, the caller reads the key from sets.xkey, or from the key of another declared axis when the caller is written against that axis.
  • dval: Default value of each entry that val does not name.

Constructors

ThresholdEstimator(;    val::VectorEstValType,    key::Option{<:AbstractString} = nothing,    dval::Option{<:Number} = nothing) -> ThresholdEstimator

Keywords correspond to the struct's fields.

Validation

  • assert_nonempty_nonneg_finite_val checks val and dval, so a threshold must be non-empty, non-negative and finite.
  • If key is not nothing, it must be a non-empty string.

View parameters

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

port_opt_view slices only a vector val. A scalar, a Dict, a Pair or an algorithmic rule has no asset index. The view keeps such a val unchanged, and the estimator resolves it against the universe of the view.

Examples

julia> ThresholdEstimator(; val = Dict("A" => 0.05, "B" => 0.1))ThresholdEstimator   val ┼ Dict{String, Float64}: Dict("B" => 0.1, "A" => 0.05)   key ┼ nothing  dval ┴ nothingjulia> ThresholdEstimator(; val = "A" => 0.05)ThresholdEstimator   val ┼ Pair{String, Float64}: "A" => 0.05   key ┼ nothing  dval ┴ nothingjulia> ThresholdEstimator(; val = 0.05)ThresholdEstimator   val ┼ Float64: 0.05   key ┼ nothing  dval ┴ nothingjulia> ThresholdEstimator(; val = [0.05])ThresholdEstimator   val ┼ Vector{Float64}: [0.05]   key ┼ nothing  dval ┴ nothingjulia> ThresholdEstimator(; val = UniformValues())ThresholdEstimator   val ┼ UniformValues()   key ┼ nothing  dval ┴ nothing

Related

References

  • [150] T.-J. Chang, N. Meade, J. E. Beasley and Y. M. Sharaiha. Heuristics for cardinality constrained portfolio optimisation. Computers & Operations Research 27, 1271–1302 (2000). Section 2.4, Equation 12.
source
PortfolioOptimisers.Threshold — Type
struct Threshold{__T_val} <: AbstractConstraintResult

Makes each held position reach a minimum size, and sets each smaller position to zero.

The threshold is one scalar for every asset, or a vector with one value for each asset. It stops a mixed-integer model from returning many positions that are too small to trade. The original source writes the bound over the position, as this library does, so no reference portfolio enters it. [12] also writes a buy-in threshold over the positive and negative trades against a reference portfolio. This library does not make that threshold.

No upper bound applies to a threshold. A threshold above the largest weight that the budget lets an asset hold excludes that asset. On a three-asset long-only variance model with a cardinality cap of three, Threshold(0.15) held all three assets. Threshold(0.5) held two assets at exactly 0.5 each. Threshold(1.5) returned an OptimisationFailure with the solver status INFEASIBLE, because the budget row needs a sum of one and no asset can be held.

A vector threshold above one on a single asset excludes only that asset. On a 20-asset variance model, an asset held at 0.37 without a threshold went to zero under a threshold of 1.5, and the weights still summed to one.

Mathematical definition

The threshold is the lower half of a buy-in constraint on the held binary:

\[\begin{align} \underset{\boldsymbol{w}}{\mathrm{opt}}\quad & \phi(\boldsymbol{w})\\ \textrm{s.t.}\quad & \ell_i z_i \leq w_i \leq u_i z_i\,,\quad \forall i = 1,\ldots,N\,,\\ & \boldsymbol{z} \in \{0, 1\}^{N}\,,\quad \boldsymbol{w} \in \mathcal{W}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{z}$: Held binary, one entry per asset.
  • $\ell_i$: Minimum-holding threshold for asset $i$, the val field.
  • $u_i$: Upper weight bound for asset $i$, from WeightBounds.
  • $N$: Number of assets.
  • $\phi$: Objective function of the optimiser.
  • $\mathcal{W}$: Rest of the feasible set.

The binary controls both bounds. If $z_i = 0$, the two bounds give $w_i = 0$. If $z_i = 1$, the position must reach $\ell_i$. A long threshold and a short threshold are separate objects, and each one uses the binary of its own side.

A threshold above the matching $u_i$ permits only $z_i = 0$, because $\ell_i z_i \leq w_i \leq u_i z_i$ is infeasible for $z_i = 1$. The pair of bounds states the exclusion and the minimum, so no separate row is necessary.

Fields

  • val: Minimum-holding thresholds of the portfolio weights, as one scalar for every asset or one value for each asset. A position is zero, or it is at least its threshold. The threshold bounds the held weight and not the trade, so no reference portfolio enters it.

Constructors

Threshold(    val::Num_VecNum) -> ThresholdThreshold(;    val::Num_VecNum) -> Threshold

Keywords correspond to the struct's fields.

Validation

  • assert_nonempty_nonneg_finite_val checks val, so a threshold must be non-empty, non-negative and finite. No check sets an upper bound, and the constructor accepts a value above one.

Both constructors run the same check, because the positional form is the inner constructor and the keyword form calls it.

View parameters

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

Examples

julia> Threshold(0.05)Threshold  val ┴ Float64: 0.05julia> Threshold([0.05, 0.1, 0.0])Threshold  val ┴ Vector{Float64}: [0.05, 0.1, 0.0]

Related

References

  • [150] T.-J. Chang, N. Meade, J. E. Beasley and Y. M. Sharaiha. Heuristics for cardinality constrained portfolio optimisation. Computers & Operations Research 27, 1271–1302 (2000). Section 2.4, Equation 12.
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.4, Equation 9.31. It adds the threshold over trades.
source
PortfolioOptimisers.threshold_constraints — Function
threshold_constraints(t::Option{<:Threshold}, args...; kwargs...)

Returns a resolved threshold or nothing unchanged.

This method lets a caller give a Threshold wherever threshold_constraints also accepts a ThresholdEstimator.

The method makes no new object and allocates no memory, so threshold_constraints(t) === t holds. Because it accepts nothing, the broadcast over a VecOptBtE_Bt keeps an empty block as nothing.

Algorithm

  1. Return t. The method reads none of its other arguments and none of its keywords.

Arguments

  • t: A Threshold or nothing.
  • args...: More positional arguments, which the method ignores.
  • kwargs...: More keyword arguments, which the method ignores.

Returns

  • bt::Option{<:Threshold}: The input t, unchanged.

Examples

julia> threshold_constraints(Threshold(0.05))Threshold  val ┴ Float64: 0.05julia> threshold_constraints(nothing)

Related

source
threshold_constraints(t::ThresholdEstimator, sets::UniverseSets;
                      datatype::DataType = Float64, strict::Bool = false)

Resolves a ThresholdEstimator against a universe.

The method resolves the names of t.val against sets, and returns a Threshold with one value for each asset. t.val can be a dictionary, a pair, a vector of pairs, a scalar, a vector or an algorithmic rule.

This method does not normalise the resolved vector, unlike the estimator method of risk_budget_constraints. A threshold bounds one weight and is not a share of a total, so a scaled vector gives a different model.

Algorithm

  1. Resolve t.val with estimator_to_val against the universe that t.key selects in sets. If t.key is nothing, use the universe of sets.xkey. The fill value of an asset that t.val does not name is t.dval. If t.dval is nothing, the fill value is zero(datatype), which is no threshold.
  2. Wrap the resolved vector in a Threshold, which checks that it is non-empty, non-negative and finite.

Arguments

  • t: ThresholdEstimator that states the threshold of each asset.
  • sets: UniverseSets that holds the asset names and the groups.
  • datatype: Number type of the fill value when t.dval is nothing, and of the range that UniformValues resolves to.
  • strict: If true, a name in t.val that sets does not resolve raises ArgumentError. If false, the method logs a warning and skips the name.

Validation

  • strict applies to a name that does not resolve, not to an unnamed asset. A name in t.val that names neither an asset nor a group raises ArgumentError when strict is true. Otherwise the method logs a warning. An unnamed asset always takes the fill value of step 1, and never raises an error.
  • The Threshold constructor of step 2 checks the resolved vector with assert_nonempty_nonneg_finite_val.

Returns

  • bt::Threshold: A Threshold with one value for each asset of the selected universe.

Examples

julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> t = ThresholdEstimator(Dict("A" => 0.05, "B" => 0.1));julia> threshold_constraints(t, sets)Threshold  val ┴ Vector{Float64}: [0.05, 0.1, 0.0]

Related

source
threshold_constraints(t::VecOptBtE_Bt, sets::UniverseSets;
                      kwargs...)

Broadcasts threshold_constraints over the vector.

The method of each entry follows from the type of that entry. An estimator resolves, a Threshold stays unchanged, and nothing stays nothing. The result is a VecOptBt with the same length and the same order. A scenario-block target needs this, because entry i belongs to block i. An empty block stays in the list as nothing.

risk_budget_constraints has no vector method. The threshold targets :slt, :sst, :sglt and :sgst are routing targets that accumulate, and each holds a positional list. The risk budget target :rkb is not. RkbE_Rkb states the same decision for the risk budget.

Algorithm

  1. For each entry ti of t, in order, call threshold_constraints(ti, sets; kwargs...).
  2. Collect the results into a vector of the same length.

Arguments

  • t: A VecOptBtE_Bt, with one entry for each scenario or group block. An entry is a ThresholdEstimator, a Threshold or nothing.
  • sets: UniverseSets that holds the asset names and the groups.
  • kwargs...: More keyword arguments, which the method gives to the method of each entry.

Returns

  • bt::VecOptBt: One resolved Threshold or nothing for each entry of t, in the order of t.

Examples

julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> t = Union{Nothing, PortfolioOptimisers.BtE_Bt}[nothing, Threshold(0.05),                                                      ThresholdEstimator(; val = Dict("A" => 0.1))];julia> bt = threshold_constraints(t, sets);julia> length(bt), isnothing(bt[1]), bt[2].val, bt[3].val(3, true, 0.05, [0.1, 0.0, 0.0])

Related

source

References

[12]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
[150]
T.-J. Chang, N. Meade, J. E. Beasley and Y. M. Sharaiha. Heuristics for Cardinality Constrained Portfolio Optimisation. Computers & Operations Research 27, 1271–1302 (2000).