GitHub

Threshold Constraints

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 turns it into a Threshold: every name is mapped to its indices in the universe key selects, and an unnamed asset takes dval, which defaults to no threshold. A threshold may also be a scalar, a vector, or an algorithmic rule such as UniformValues.

Fields

  • val: Asset-specific minimum-holding threshold value(s).
  • key: Key to specify the universe in sets.dict that names resolve against. If nothing, the key is taken from sets.xkey — or, where the caller is written against another declared axis, from that axis' key.
  • dval: Default value for assets not specified in val.

Constructors

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

Keywords correspond to the struct's fields.

Validation

  • val and dval are both validated with assert_nonempty_nonneg_finite_val, so a threshold is non-empty, non-negative and finite.
  • If key is not nothing, it is a non-empty string.

View parameters

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

Only a vector val is sliced. A val that is a scalar, a Dict, a Pair or an algorithmic rule is not indexed by asset, so a view passes it through untouched and it resolves against the viewed universe when the estimator runs.

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

  • [4] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.4.
source
PortfolioOptimisers.Threshold — Type
struct Threshold{__T_val} <: AbstractConstraintResult

Forces every held position to reach a minimum size, and drives anything smaller to zero.

The threshold is a scalar shared by every asset or a vector of one value per asset. It exists to keep a mixed-integer model from answering with a long tail of positions too small to trade.

Mathematical definition

The threshold is the lower half of a buy-in constraint, stated against 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 carries both halves. Where $z_i = 0$ the two bounds collapse to $w_i = 0$; where $z_i = 1$ the position must reach $\ell_i$. A long and a short threshold are separate objects, each bound to its own side's binary.

The threshold binds the held weight, not the trade. The source writes the same constraint over positive and negative trades against a reference portfolio; this library writes it over the position, so no reference portfolio enters it. On a six-asset conditional-value-at-risk model at Threshold(0.15) every held weight came back at or above 0.15, with the smallest exactly 0.15.

Fields

  • val: Minimum-holding threshold(s) on the portfolio weights. A held position must reach its threshold; a position below it is driven to zero. The threshold binds the held weight, never the trade, so a reference portfolio does not enter it.

Constructors

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

Keywords correspond to the struct's fields.

Validation

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

  • [4] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.4.
source
PortfolioOptimisers.threshold_constraints — Function
threshold_constraints(t::Option{<:Threshold}, args...; kwargs...)

Propagate or pass through buy-in threshold portfolio constraints.

threshold_constraints returns the input Threshold object or nothing unchanged. This method is used to propagate already constructed buy-in threshold constraints, enabling composability and uniform interface handling in constraint generation workflows.

Arguments

  • t: An existing Threshold object or nothing.
  • args...: Additional positional arguments (ignored).
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • bt::Option{<:Threshold}: The input constraint object, 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)

Generate buy-in threshold portfolio constraints from a ThresholdEstimator and asset set.

threshold_constraints constructs a Threshold object representing minimum allocation thresholds for the assets in sets, using the specifications in t. Supports scalar, vector, dictionary, pair, or custom threshold types for flexible assignment and validation.

Arguments

  • t: ThresholdEstimator specifying asset-specific threshold values.
  • sets: UniverseSets containing asset names or indices.
  • datatype: Output data type for thresholds.
  • strict: If true, a name in t.val that sets does not resolve throws; if false, it issues a warning and is skipped.

Returns

  • bt::Threshold: Object containing threshold values aligned with sets.

Details

  • Thresholds are extracted and mapped to assets by estimator_to_val, against the universe t.key selects.
  • An asset that t.val does not name takes t.dval. The default dval = nothing gives it zero(datatype), which is no threshold.
  • strict governs unresolvable names, not unnamed assets. An unnamed asset always takes the default and never throws.

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.

Provides a uniform interface for processing multiple constraint estimators simultaneously.

source

References

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