Threshold constraint generation
PortfolioOptimisers.ThresholdEstimator — Type
struct ThresholdEstimator{__T_val, __T_key, __T_dval} <: AbstractConstraintEstimatorResolves 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 insets.dictthat names resolve against. Ifnothing, the caller reads the key fromsets.xkey, or from the key of another declared axis when the caller is written against that axis.
dval: Default value of each entry thatvaldoes not name.
Constructors
ThresholdEstimator(; val::VectorEstValType, key::Option{<:AbstractString} = nothing, dval::Option{<:Number} = nothing) -> ThresholdEstimatorKeywords correspond to the struct's fields.
Validation
assert_nonempty_nonneg_finite_valchecksvalanddval, so a threshold must be non-empty, non-negative and finite.- If
keyis notnothing, it must be a non-empty string.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
val: Sliced to the selected indices throughport_opt_view.
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 ┴ nothingRelated
ThresholdVectorEstValTypethreshold_constraintsAbstractConstraintEstimatorUniverseSetsport_opt_viewRiskBudgetEstimator: has the same shape, and its function takes the universe key as a positional argument.
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.
PortfolioOptimisers.Threshold — Type
struct Threshold{__T_val} <: AbstractConstraintResultMakes 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
valfield. - $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) -> ThresholdKeywords correspond to the struct's fields.
Validation
assert_nonempty_nonneg_finite_valchecksval, 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:
val: Sliced to the selected indices throughport_opt_view.
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
short_mip_threshold_constraintsmip_constraintsset_mip_constraints!ThresholdEstimatorthreshold_constraintsAbstractConstraintResultWeightBoundsport_opt_view
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.
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
- Return
t. The method reads none of its other arguments and none of its keywords.
Arguments
t: AThresholdornothing.args...: More positional arguments, which the method ignores.kwargs...: More keyword arguments, which the method ignores.
Returns
bt::Option{<:Threshold}: The inputt, unchanged.
Examples
julia> threshold_constraints(Threshold(0.05))Threshold val ┴ Float64: 0.05julia> threshold_constraints(nothing)Related
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
- Resolve
t.valwithestimator_to_valagainst the universe thatt.keyselects insets. Ift.keyisnothing, use the universe ofsets.xkey. The fill value of an asset thatt.valdoes not name ist.dval. Ift.dvalisnothing, the fill value iszero(datatype), which is no threshold. - Wrap the resolved vector in a
Threshold, which checks that it is non-empty, non-negative and finite.
Arguments
t:ThresholdEstimatorthat states the threshold of each asset.sets:UniverseSetsthat holds the asset names and the groups.datatype: Number type of the fill value whent.dvalisnothing, and of the range thatUniformValuesresolves to.strict: Iftrue, a name int.valthatsetsdoes not resolve raisesArgumentError. Iffalse, the method logs a warning and skips the name.
Validation
strictapplies to a name that does not resolve, not to an unnamed asset. A name int.valthat names neither an asset nor a group raisesArgumentErrorwhenstrictistrue. Otherwise the method logs a warning. An unnamed asset always takes the fill value of step 1, and never raises an error.- The
Thresholdconstructor of step 2 checks the resolved vector withassert_nonempty_nonneg_finite_val.
Returns
bt::Threshold: AThresholdwith 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
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
- For each entry
tioft, in order, callthreshold_constraints(ti, sets; kwargs...). - Collect the results into a vector of the same length.
Arguments
t: AVecOptBtE_Bt, with one entry for each scenario or group block. An entry is aThresholdEstimator, aThresholdornothing.sets:UniverseSetsthat 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 resolvedThresholdornothingfor each entry oft, in the order oft.
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
VecOptBtE_BtVecOptBtThresholdThresholdEstimatorthreshold_constraintsRkbE_Rkb: the alias of the risk budget family, which has no vector type for the same reason.
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).