X at Risk
PortfolioOptimisers.MIPValueatRisk — Type
struct MIPValueatRisk{__T_b, __T_s} <: ValueatRiskFormulationComputes the Value-at-Risk as the empirical quantile of the sample, through a mixed-integer programme.
The programme has one binary indicator per observation. The functor of the measure that holds this formulation computes the same order statistic directly, so the model and the functor report one number.
A solver accepts an indicator that is within its integrality tolerance $\varepsilon$ of zero as zero. The exceedance row of that observation then holds for a risk as low as $\ell_{t} - b \varepsilon$. So the risk that the model reports can be smaller than the order statistic of the weights that it returns, by up to $b \varepsilon$, and those weights need not be optimal. A constant $b = 1000$ and a tolerance of $10^{-6}$ give a gap of up to $10^{-3}$, which is large next to the scale of daily returns. So the default b = nothing derives the smallest exact constant from the data, with mip_big_m. It is the largest spread of the losses of one asset times a bound on the gross exposure of the weights, about $10^{-1}$ for a long-only portfolio of daily returns. Where the model admits no such bound, for example under MaximumRatio, the default is $b = 1000$, and a tighter integrality tolerance of the solver makes the gap smaller.
Mathematical definition
Each indicator exempts one observation from the bound on the risk, and the cardinality row caps the weight of the exempt observations. The programme minimises $r$, so $r$ falls to the largest loss that no indicator exempts:
\[\begin{align} \underset{r,\, \boldsymbol{z}}{\min} \quad & r\\ \text{s.t.} \quad & r \geq \ell_{t} - b z_{t}\,, \quad t = 1,\ldots,T\\ \quad & \sum_{t=1}^{T} w_{t} z_{t} \leq \left(\alpha + s\right) W_{T}\\ \quad & z_{t} \in \left\{0,\, 1\right\}\,. \end{align}\]
Where:
- $r$: Value-at-Risk variable.
- $\ell_{t}$: Loss of observation $t$. It is $-x_{t}$ for
ValueatRiskand $-d_{t}$ forDrawdownatRisk. - $z_{t}$: Exceedance indicator of observation $t$. It is one when the bound on $r$ does not apply to the observation.
- $b$: Big-M constant, the
bfield. - $s$: Cardinality slack of the mixed-integer quantile programme, $s > 0$. It absorbs the rounding error of $\alpha W_{T}$.
- $w_{t}$: Observation weight of observation $t$. Every $w_{t}$ is one when no observation weights are set.
- $W_{T} = \sum_{t=1}^{T} w_{t}$: Total observation weight.
- $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
- $T$: Number of observations.
The minimum is the $k$-th largest loss, the order statistic that ValueatRisk defines. The programme exempts the largest losses first, and it can exempt them while their cumulative weight stays within $(\alpha + s) W_{T}$. So the exempt weight reaches $\alpha W_{T}$ and does not pass it. The slack only absorbs the rounding error of $\alpha W_{T}$.
The programme is exact when $b$ is at least the largest loss minus the minimum, which the derived default is. The slack must stay small. When $s W_{T}$ reaches the gap from $\alpha W_{T}$ up to the next cumulative weight, the programme exempts one more observation.
The order statistic is the upper quantile of Definition 3.3 of [196]. Equation 7.51 of [12] subtracts its slack, so when $\alpha W_{T}$ is an integer it selects the next larger loss, and not the order statistic of its own Equation 7.50. This programme adds the slack, so that it selects the order statistic of the definition. Section 7.2.2.3 of [12] builds its programme on an older mixed-integer formulation of the Value-at-Risk. No copy of the work that first states that formulation was found.
Fields
b: Big-M constant of the MIP formulation. It relaxes the bound on an observation that the model flags as an exceedance. Ifnothing, the model derives the smallest exact constant from the data and the weight bounds withmip_big_m, and uses1000where the model admits no bound on the gross exposure.
s: Cardinality slack of the MIP formulation. It caps the weight of the flagged observations at(alpha + s)times the total weight, which is(alpha + s) * Twithout observation weights, so it absorbs the rounding error ofalphatimes the total weight. The functor selects its order statistic with the same slack. Ifnothing, the model and the functor use1e-9.
Constructors
MIPValueatRisk(; b::Option{<:Number} = nothing, s::Option{<:Number} = nothing) -> MIPValueatRiskKeywords correspond to the struct's fields.
Validation
- If
bis notnothing:b > 0and finite. - If
sis notnothing:s > 0and finite. - If both
bandsare notnothing:b > s.
Examples
julia> MIPValueatRisk()MIPValueatRisk b ┼ nothing s ┴ nothingRelated
ValueatRiskFormulationDistributionValueatRiskValueatRiskDrawdownatRisk: builds the same programme over the drawdowns.Option
References
- [196] P. Artzner, F. Delbaen, J.-M. Eber and D. Heath. Coherent measures of risk. Mathematical Finance 9, 203–228 (1999). Section 3.3, Definition 3.3.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 7.2.2.3, Equations 7.50 and 7.51. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.DistributionValueatRisk — Type
struct DistributionValueatRisk{__T_mu, __T_sigma, __T_chol, __T_pe, __T_dist, __T_mtx_sqrt} <: ValueatRiskFormulationComputes the Value-at-Risk as a quantile of a parametric distribution, from the mean and the covariance of the asset returns.
This is a different estimand from the empirical quantile that MIPValueatRisk reports. The risk measure that holds it reports the parametric value in the optimisation model and in the functor alike. mu and sigma fall back to the prior's own, so factory fills them before either the model or the functor reads them.
The optimisation model bounds the standard deviation from above with a second-order cone, so the model is convex only while the coefficient of the standard deviation is not negative. For a law that is symmetric about zero, that is $\alpha \leq 1/2$ for ValueatRisk, and $\alpha + \beta \leq 1$ for ValueatRiskRange. A Normal with a mean $m$ adds $m$ to $z_{\alpha}$, so a negative $m$ can make the coefficient of ValueatRisk negative at $\alpha \leq 1/2$. The coefficient of ValueatRiskRange, $z_{\alpha} - z^{c}_{\beta}$, does not depend on $m$. Two tails of a GenericValueatRiskRange that both hold this algorithm and read the same covariance matrix share one cone, whatever expected returns each tail reads, so the condition is that of ValueatRiskRange. Any other tail of a GenericValueatRiskRange has a cone of its own, so its coefficient must not be negative. The coefficient of a gain tail is $-z^{c}_{\beta}$, which a positive $m$ makes smaller. Past that level a minimisation of the risk has no finite solution.
Mathematical definition
\[\begin{align} \mathrm{VaR}_{\alpha}(\boldsymbol{w}) &= -\boldsymbol{\mu}^\intercal \boldsymbol{w} + z_{\alpha} \sqrt{\boldsymbol{w}^\intercal \mathbf{\Sigma} \boldsymbol{w}}\,,\\ \mathrm{VaRRange}_{\alpha, \beta}(\boldsymbol{w}) &= \left(z_{\alpha} - z^{c}_{\beta}\right) \sqrt{\boldsymbol{w}^\intercal \mathbf{\Sigma} \boldsymbol{w}}\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $\boldsymbol{\mu}$: Expected returns vector $N \times 1$.
- $\mathbf{\Sigma}$: Covariance matrix of the asset returns, $N \times N$.
- $z_{\alpha}$: Loss-tail z-score of
distat $\alpha$, fromcompute_value_at_risk_z. - $z^{c}_{\beta}$: Gain-tail z-score of
distat $\beta$, fromcompute_value_at_risk_cz. - $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
- $\beta$: Significance level of the gain tail, $\beta \in (0, 1)$.
The range is the Value-at-Risk of the returns plus the Value-at-Risk of the negated returns, and the two mean terms cancel.
dist is the law of the standardised loss $\varepsilon$ of the portfolio, so the loss is $-\boldsymbol{\mu}^\intercal \boldsymbol{w} + \sqrt{\boldsymbol{w}^\intercal \mathbf{\Sigma} \boldsymbol{w}}\, \varepsilon$. A Normal with a mean $m \neq 0$ is not symmetric about zero. It moves the loss tail up by $m \sqrt{\boldsymbol{w}^\intercal \mathbf{\Sigma} \boldsymbol{w}}$ and the gain tail down by the same amount. A GenericValueatRiskRange evaluates the gain tail of a ValueatRisk on $-\boldsymbol{w}$, and the standardised loss of $-\boldsymbol{w}$ is $-\varepsilon$. So it reads the law that gain_tail_distribution gives, and its value equals that of a ValueatRiskRange with the same dist.
The two estimands agree only when the returns follow dist. On a large sample drawn from dist, the parametric quantile of the sample moments is close to the empirical quantile. On a sample whose loss tail is heavier than that of dist, the parametric quantile at a small $\alpha$ is below the empirical quantile, so it understates the loss. On a sample whose loss tail is lighter, it is above the empirical quantile. At a larger $\alpha$ the order can reverse.
Sections 1.2 and 4.5.2.2 of [197] state the Value-at-Risk of normal returns. Section 2.6 of [198] states its bound as a second-order cone for a confidence of at least one half, which is the condition $\alpha \leq 1/2$ above. Equation 11.5 of [12] states the quantiles of the Student-t law, scaled to unit variance, and of the Laplace law. No copy of the work that first states those two forms was found. Equation 7.52 of [12] calls $z_{\alpha}$ the $\alpha$ quantile of the normal law, but the definition needs the $1 - \alpha$ quantile, which its Equation 11.5 states.
Fields
mu: Optional expected returns vectorassets × 1, the location ofdist. Also admits a Deferred Quantity — an expected returns estimator or a prior estimator that computes the vector against the optimisation's own prior, atfactorytime (seeMuSlotandresolve_deferred_quantities). Ifnothing, the prior supplies it.
sigma: Optional covariance matrixassets × assets. Also admits a Deferred Quantity — a covariance estimator or a prior estimator that computes the matrix against the optimisation's own prior, atfactorytime (seeSigmaSlotandresolve_deferred_quantities). Ifnothing, the prior supplies it.
chol: Optional Cholesky factorisation of the covariance matrix. Derived fromsigma, so it never defers: it arrives as one pair with whateversigmaresolves to. Give it with a matrixsigmaand with neither otherwise — stating it withoutsigma, or whilesigmaholds a Deferred Quantity, is refused at construction (seeassert_derived_slot_has_source). Ifnothing, the prior supplies the pair, or the kernel derives the factorisation from a statedsigma.
pe: Optional prior estimator that fills every prior-derived slot the measure leaves unstated, from a single fit. A stated slot wins. Seeresolve_deferred_quantities. It fits on the returns of the Prior Result that the measure receives, so it states no source of its own, and the constructor refuses apewhosex_srcis notnothing, seeassert_returns_source.
dist: Probability distribution.
mtx_sqrt: Square-root algorithm of the covariance matrix that the cone of the parametric quantile reads when nocholis at hand, ornothingfor the plain Cholesky factor, which raises aLinearAlgebra.PosDefExceptionon a matrix that is not positive definite. The default takes the square root of the eigendecomposition of a singular positive semidefinite matrix.matrix_square_rootstates each algorithm.
Constructors
DistributionValueatRisk(; mu::Option{<:MuSlot} = nothing, sigma::Option{<:SigmaSlot} = nothing, chol::Option{<:MatNum} = nothing, pe::Option{<:AbstractPriorEstimator} = nothing, dist::Distributions.Distribution = Distributions.Normal(), mtx_sqrt::Option{<:AbstractMatrixSquareRootAlgorithm} = EigenFallbackSquareRoot()) -> DistributionValueatRiskKeywords correspond to the struct's fields.
Validation
- If
muis notnothing:!isempty(mu). - If
sigmais an estimator, it is not anAbstractVarianceEstimator. A variance estimator has nocov, soassert_covariance_estimatorraises anArgumentErrorthat namessigma. - If
sigmais notnothing:!isempty(sigma)andsize(sigma, 1) == size(sigma, 2). - If
cholis notnothing:!isempty(chol), andsigmais a matrix rather thannothingor a Deferred Quantity.
The caller states mu, sigma and chol independently, and nothing makes them agree with each other. A caller who wants one consistent set gives pe alone, and one fit of pe fills all three. A caller who states them by hand must make sure that they agree.
View parameters
DistributionValueatRisk defines its own port_opt_view method rather than deriving one from field tags.
- The method slices
muto the selected assets. A Deferred Quantity passes through unsliced, and resolves on the subset later. - The method slices a stated
sigmaon both axes. A Deferred Quantity passes through unsliced, and resolves on the subset later. - The method slices
cholon its columns alone. Its rows index the factorisation, and the asset selection does not address them. pe,distandmtx_sqrtpass through unchanged.distdescribes the standardised loss, so it has no asset axis.
Examples
julia> DistributionValueatRisk()DistributionValueatRisk mu ┼ nothing sigma ┼ nothing chol ┼ nothing pe ┼ nothing dist ┼ Distributions.Normal{Float64}: Normal(0.0, 1.0) mtx_sqrt ┴ EigenFallbackSquareRoot()Related
ValueatRiskFormulationMIPValueatRiskValueatRiskgain_tail_distributionMuSlotSigmaSlotresolve_deferred_quantitiesOptionport_opt_view
References
- [197] J.P. Morgan and Reuters. RiskMetrics technical document. Fourth edition, J.P. Morgan/Reuters (1996). Section 1.2, Equation 1.5, and Section 4.5.2.2, Equation 4.43.
- [198] M. S. Lobo, L. Vandenberghe, S. Boyd and H. Lebret. Applications of second-order cone programming. Linear Algebra and its Applications 284, 193–228 (1998). Section 2.6, Equation 13.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 11.2, Equation 11.5. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.ValueatRisk — Type
struct ValueatRisk{__T_settings, __T_alpha, __T_w, __T_alg} <: RiskMeasureMeasures the Value-at-Risk (VaR), the loss that the portfolio exceeds with probability alpha.
alg selects the estimand. MIPValueatRisk, the default, gives the empirical quantile of the sample, which the definition below states. DistributionValueatRisk gives the quantile of a parametric distribution, which that type states. The measure is not convex, so its empirical model is a mixed-integer programme.
Mathematical definition
\[\begin{align} \mathrm{VaR}_{\alpha}(\boldsymbol{x}) &= -x_{(k)}\,. \end{align}\]
Where:
- $\mathrm{VaR}_{\alpha}(\boldsymbol{x})$: Value-at-Risk at level $\alpha$.
- $\boldsymbol{x}$: Portfolio returns vector $T \times 1$.
- $x_{(k)}$: $k$-th smallest entry of the series, and $w_{(k)}$ its observation weight.
- $k = \min\{k : W_{k} > (\alpha + s) W_{T}\}$: Quantile index, the position of the order statistic that the mixed-integer quantile programme selects.
- $W_{k} = \sum_{j=1}^{k} w_{(j)}$: Cumulative weight of the $k$ smallest entries, with $W_{0} = 0$.
- $w_{t}$: Observation weight of observation $t$. Every $w_{t}$ is one when no observation weights are set.
- $s$: Cardinality slack of the mixed-integer quantile programme, $s > 0$. It absorbs the rounding error of $\alpha W_{T}$. It is the
sfield ofMIPValueatRisk. - $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
- $T$: Number of observations.
$-x_{(k)}$ is the minimum of the programme of MIPValueatRisk over the losses $-x_{t}$. Without observation weights $k = \lfloor (\alpha + s) T \rfloor + 1$. This is $\lfloor \alpha T \rfloor + 1$, the index of the upper $\alpha$-quantile, while $s T$ is smaller than $\lfloor \alpha T \rfloor + 1 - \alpha T$. The slack absorbs the rounding error of $\alpha T$. For example, at $\alpha = 0.29$ and $T = 100$ the product rounds to 28.999999999999996, and $k$ is 30.
$-x_{(k)}$ is the definition $-\inf\{x : F(x) > \alpha\}$ of Definition 3.3 of [196], with $F$ the weighted distribution function of the returns. Equation 7.50 of [12] states it too. It is the smallest loss that the portfolio exceeds with a probability of $\alpha$ or less. Equation 7.51 of [12], the programme, subtracts its slack, and it selects $\lceil \alpha T \rceil$, which is one position higher when $\alpha T$ is an integer. At $\alpha T = 1$ that position is the largest loss.
Algorithm
The functor of the empirical estimand:
- Read the slack
swithmip_var_bounds, which gives the default whenalg.sisnothing. - Read the observation weights
wwithget_observation_weights. - Return
empirical_value_at_riskofxatalphaands. Without weights the kernel reorders its input, so it receives a copy ofx.
Fields
settings: Risk measure settings.
alpha: Quantile level for the lower tail. The bound isNum_SigCal, so the slot takes the level itself, anAbstractSignificanceCalibrationAlgorithmthat computes it from the prior result, or a plain function of the same five arguments.
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
alg: Risk measure optimisation formulation algorithm.
Constructors
ValueatRisk(; settings::RiskMeasureSettings = RiskMeasureSettings(), alpha::Num_SigCal = 0.05, w::Option{<:ObsWeights} = nothing, alg::ValueatRiskFormulation = MIPValueatRisk()) -> ValueatRiskKeywords correspond to the struct's fields.
Validation
- If
alphais a number:0 < alpha < 1. - If
wis aStatsBase.AbstractWeights, it is not empty, each entry is finite and>= 0, andsum(w) > 0, throughassert_observation_weights. ADynamicAbstractWeightsholds no weights until it reads the data, sochecked_observation_weightschecks it at evaluation, and also checks there that the weights have one entry for each observation.
Propagated parameters
factory passes its arguments on to these @fprop fields:
w: Replaced with the incomingObsWeights.alg: Recursively updated throughfactory.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
alg: Recursively viewed throughport_opt_view.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.alg: Recursively indexed throughobs_weights_view.
Functor
(r::ValueatRisk)(x::VecNum)(r::ValueatRisk{<:Any, <:Any, <:Any, <:DistributionValueatRisk})(w::VecNum, X, fees)alg selects the quantity, and each method reports the value that its own JuMP model builds. The first computes the empirical quantile of a portfolio returns vector, weighted by w when the measure states observation weights, and leaves x unchanged. The second computes the parametric quantile from the moments that DistributionValueatRisk holds, so it takes the asset weights instead. It does not read X and fees, because the terms of the model are the prior's moments and no return series enters them.
Arguments
x::VecNum: Portfolio returns vector.w::VecNum: Asset weights vector.
Examples
julia> ValueatRisk()ValueatRisk settings ┼ RiskMeasureSettings │ scale ┼ Float64: 1.0 │ ub ┼ nothing │ rke ┴ Bool: true alpha ┼ Float64: 0.05 w ┼ nothing alg ┼ MIPValueatRisk │ b ┼ nothing │ s ┴ nothingRelated
RiskMeasureRiskMeasureSettingsMIPValueatRiskDistributionValueatRiskConditionalValueatRiskValueatRiskRangefactoryport_opt_viewobs_weights_view
References
- [196] P. Artzner, F. Delbaen, J.-M. Eber and D. Heath. Coherent measures of risk. Mathematical Finance 9, 203–228 (1999). Section 3.3, Definition 3.3.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 7.2.2.3, Equations 7.50 and 7.51.
PortfolioOptimisers.ValueatRiskRange — Type
struct ValueatRiskRange{__T_settings, __T_alpha, __T_beta, __T_w, __T_alg} <: RangeRiskMeasureMeasures the Value-at-Risk Range, the spread between the loss quantile at alpha and the gain quantile at beta.
The range sums the ValueatRisk of the portfolio returns and the Value-at-Risk of the negated returns. alg selects the estimand of both tails, as it does for ValueatRisk.
Mathematical definition
\[\begin{align} \mathrm{VaRRange}_{\alpha,\beta}(\boldsymbol{x}) &= \mathrm{VaR}_{\alpha}(\boldsymbol{x}) + \mathrm{VaR}_{\beta}(-\boldsymbol{x})\,. \end{align}\]
Where:
- $\mathrm{VaRRange}_{\alpha,\beta}(\boldsymbol{x})$: Value-at-Risk Range.
- $\mathrm{VaR}_{\alpha}(\boldsymbol{x})$: Value-at-Risk of the returns at level $\alpha$, the loss quantile that
ValueatRiskdefines. - $\mathrm{VaR}_{\beta}(-\boldsymbol{x})$: Value-at-Risk of the negated returns at level $\beta$, which is minus the gain quantile.
- $\boldsymbol{x}$: Portfolio returns vector $T \times 1$.
- $\alpha$: Significance level of the loss tail, $\alpha \in (0, 1)$.
- $\beta$: Significance level of the gain tail, $\beta \in (0, 1)$.
The upper tail is the base measure applied to the negated returns $-\boldsymbol{x}$, so both tails are reported on the same sign convention and the range is their sum, not their difference.
The two tails select their order statistics with the same slack $s$. The gain tail is the $k$-th largest return, with $k$ the index of ValueatRisk at $\beta$.
Let $k_{\alpha}$ be the index of the loss tail and $k_{\beta}$ the index of the gain tail, so that the range is $x_{(T + 1 - k_{\beta})} - x_{(k_{\alpha})}$. The range is not negative when $k_{\alpha} + k_{\beta} \leq T + 1$. Without observation weights this holds when $\lfloor (\alpha + s) T \rfloor + \lfloor (\beta + s) T \rfloor \leq T - 1$, which is about $\alpha + \beta < 1$. When the two levels overlap past that point, the loss order statistic is above the gain order statistic, and the range is zero or negative. For example, at $T = 10$ and $\alpha = \beta = 0.5$ the range is $x_{(5)} - x_{(6)}$. The constructor does not refuse such levels, and the model and the functor report the same number.
Section 7.2.3 of [12] defines the ranges of the Conditional Value-at-Risk and of other tail measures, and names [199] as their source. No copy of that work was found. [12] defines no range of the Value-at-Risk, so this measure is the library's analogue of that family.
Algorithm
The functor of the empirical estimand:
- Read the slack
swithmip_var_bounds, which gives the default whenalg.sisnothing. - Read the observation weights
wwithget_observation_weights. - Compute
loss,empirical_value_at_riskofxatalphaands. Without weights the kernel reorders its input, so it receives a copy ofx. - Compute
gain,empirical_value_at_riskof-xatbetaands. - Return
loss + gain.
Fields
settings: Risk measure settings.
alpha: Quantile level for the lower tail. The bound isNum_SigCal, so the slot takes the level itself, anAbstractSignificanceCalibrationAlgorithmthat computes it from the prior result, or a plain function of the same five arguments.
beta: Quantile level for the upper tail. The bound isNum_SigCal, so the slot takes the level itself, anAbstractSignificanceCalibrationAlgorithmthat computes it from the prior result, or a plain function of the same five arguments.
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
alg: Risk measure optimisation formulation algorithm.
Constructors
ValueatRiskRange(; settings::RiskMeasureSettings = RiskMeasureSettings(), alpha::Num_SigCal = 0.05, beta::Num_SigCal = alpha, w::Option{<:ObsWeights} = nothing, alg::ValueatRiskFormulation = MIPValueatRisk()) -> ValueatRiskRangeKeywords correspond to the struct's fields.
Validation
- If
alphais a number:0 < alpha < 1. - If
betais a number:0 < beta < 1. - If
wis aStatsBase.AbstractWeights, it is not empty, each entry is finite and>= 0, andsum(w) > 0, throughassert_observation_weights. ADynamicAbstractWeightsholds no weights until it reads the data, sochecked_observation_weightschecks it at evaluation, and also checks there that the weights have one entry for each observation.
Propagated parameters
factory passes its arguments on to these @fprop fields:
w: Replaced with the incomingObsWeights.alg: Recursively updated throughfactory.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
alg: Recursively viewed throughport_opt_view.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.alg: Recursively indexed throughobs_weights_view.
Functor
(r::ValueatRiskRange)(x::VecNum)(r::ValueatRiskRange{<:Any, <:Any, <:Any, <:Any, <:DistributionValueatRisk})(w::VecNum, X, fees)alg selects the quantity, as it does for ValueatRisk. The first method computes the sum of the two empirical tail quantiles of a portfolio returns vector, and leaves x unchanged. The second computes the parametric range that DistributionValueatRisk states. It does not read X and fees.
Arguments
x::VecNum: Portfolio returns vector.w::VecNum: Asset weights vector.
Examples
julia> ValueatRiskRange()ValueatRiskRange settings ┼ RiskMeasureSettings │ scale ┼ Float64: 1.0 │ ub ┼ nothing │ rke ┴ Bool: true alpha ┼ Float64: 0.05 beta ┼ Float64: 0.05 w ┼ nothing alg ┼ MIPValueatRisk │ b ┼ nothing │ s ┴ nothingRelated
RiskMeasureRiskMeasureSettingsValueatRiskConditionalValueatRiskRangefactoryport_opt_viewobs_weights_view
References
- [196] P. Artzner, F. Delbaen, J.-M. Eber and D. Heath. Coherent measures of risk. Mathematical Finance 9, 203–228 (1999). Section 3.3, Definition 3.3.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 7.2.3. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
- [199] D. Cajas. OWA portfolio optimization: A disciplined convex programming framework. Available at SSRN 3988927 (2021).
PortfolioOptimisers.DrawdownatRisk — Type
struct DrawdownatRisk{__T_settings, __T_alpha, __T_w, __T_b, __T_s} <: RiskMeasureMeasures the Drawdown-at-Risk (DaR), the uncompounded drawdown that the portfolio exceeds with probability alpha.
It is the ValueatRisk of the drawdown series in place of the returns. Its optimisation model is the mixed-integer programme of MIPValueatRisk over the drawdowns, so b and s have the same meaning here as they have there. The measure is not convex.
Mathematical definition
\[\begin{align} c_t &= \sum_{s=1}^{t} x_s\,, \quad c_0 = 0\,, \\ d_t &= c_t - \max_{0 \leq s \leq t} c_s\,, \\ \mathrm{DaR}_{\alpha}(\boldsymbol{x}) &= -d_{(k)}\,. \end{align}\]
Where:
- $\mathrm{DaR}_{\alpha}(\boldsymbol{x})$: Drawdown-at-Risk at level $\alpha$.
- $\boldsymbol{x}$: Portfolio returns vector $T \times 1$.
- $c_t$: Cumulative simple portfolio return at period $t$.
- $d_t \leq 0$: Absolute drawdown at period $t$.
- $d_{(k)}$: $k$-th smallest drawdown, the $k$-th deepest, and $w_{(k)}$ its observation weight.
- $k = \min\{k : W_{k} > (\alpha + s) W_{T}\}$: Quantile index, the position of the order statistic that the mixed-integer quantile programme selects.
- $W_{k} = \sum_{j=1}^{k} w_{(j)}$: Cumulative weight of the $k$ smallest entries, with $W_{0} = 0$.
- $w_{t}$: Observation weight of observation $t$. Every $w_{t}$ is one when no observation weights are set.
- $s$: Cardinality slack of the mixed-integer quantile programme, $s > 0$. It absorbs the rounding error of $\alpha W_{T}$. It is the
sfield. - $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
- $T$: Number of observations.
The running peak starts at $c_0 = 0$, so a series that falls from its first period is in drawdown from the start. $-d_{(k)}$ is the minimum of the programme of MIPValueatRisk over the losses $-d_{t}$, and $k$ follows the rules that ValueatRisk states.
Equation 3.2 of [200] defines the drawdown of the uncompounded cumulative return, with the peak taken from $c_0$. Its Equations 3.6 and 3.8 take the quantile of the drawdowns as the threshold of its conditional measure, and do not name it as a measure. Equation 7.90 of [12] names that quantile the Drawdown-at-Risk.
Algorithm
- Read the slack
swithmip_var_bounds, which gives the default when thesfield isnothing. - Compute the drawdown series with
absolute_drawdown_vec. - Read the observation weights with
get_observation_weights. - Return
empirical_value_at_riskof the drawdown series atalphaands.
Fields
settings: Risk measure settings.
alpha: Quantile level for the lower tail. The bound isNum_SigCal, so the slot takes the level itself, anAbstractSignificanceCalibrationAlgorithmthat computes it from the prior result, or a plain function of the same five arguments.
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
b: Big-M constant of the MIP formulation. It relaxes the bound on an observation that the model flags as an exceedance. Ifnothing, the model derives the smallest exact constant from the data and the weight bounds withmip_big_m, and uses1000where the model admits no bound on the gross exposure.
s: Cardinality slack of the MIP formulation. It caps the weight of the flagged observations at(alpha + s)times the total weight, which is(alpha + s) * Twithout observation weights, so it absorbs the rounding error ofalphatimes the total weight. The functor selects its order statistic with the same slack. Ifnothing, the model and the functor use1e-9.
Constructors
DrawdownatRisk(; settings::RiskMeasureSettings = RiskMeasureSettings(), alpha::Num_SigCal = 0.05, w::Option{<:ObsWeights} = nothing, b::Option{<:Number} = nothing, s::Option{<:Number} = nothing) -> DrawdownatRiskKeywords correspond to the struct's fields.
Validation
- If
alphais a number:0 < alpha < 1. - If
wis aStatsBase.AbstractWeights, it is not empty, each entry is finite and>= 0, andsum(w) > 0, throughassert_observation_weights. ADynamicAbstractWeightsholds no weights until it reads the data, sochecked_observation_weightschecks it at evaluation, and also checks there that the weights have one entry for each observation. - If
bis notnothing:b > 0and finite. - If
sis notnothing:s > 0and finite. - If both
bandsare notnothing:b > s.
Propagated parameters
factory passes its arguments on to these @fprop fields:
w: Replaced with the incomingObsWeights.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
Functor
(r::DrawdownatRisk)(x::VecNum)Computes the Drawdown-at-Risk of a portfolio returns vector x, and leaves x unchanged.
Arguments
x::VecNum: Portfolio returns vector.
Examples
julia> DrawdownatRisk()DrawdownatRisk settings ┼ RiskMeasureSettings │ scale ┼ Float64: 1.0 │ ub ┼ nothing │ rke ┴ Bool: true alpha ┼ Float64: 0.05 w ┼ nothing b ┼ nothing s ┴ nothingRelated
RiskMeasureRiskMeasureSettingsConditionalDrawdownatRiskRelativeDrawdownatRiskMIPValueatRiskempirical_value_at_riskfactoryobs_weights_view
References
- [200] A. Chekhlov, S. Uryasev and M. Zabarankin. Drawdown measure in portfolio optimization. International Journal of Theoretical and Applied Finance 8, 13–58 (2005). Section 3, Equations 3.2, 3.6 and 3.8.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 7.2.4.3, Equation 7.90.
PortfolioOptimisers.RelativeDrawdownatRisk — Type
struct RelativeDrawdownatRisk{__T_settings, __T_alpha, __T_w} <: HierarchicalRiskMeasureMeasures the Relative Drawdown-at-Risk, the compounded drawdown that the portfolio exceeds with probability alpha.
It is the ValueatRisk of the relative drawdown series. The compounded wealth is a product of linear functions of the weights, so the library states no JuMP formulation of the measure, and it is a HierarchicalRiskMeasure.
Mathematical definition
\[\begin{align} C_t &= \prod_{s=1}^{t} (1 + x_s)\,, \quad C_0 = 1\,, \\ rd_t &= \frac{C_t}{\max_{0 \leq s \leq t} C_s} - 1\,, \\ \mathrm{RDaR}_{\alpha}(\boldsymbol{x}) &= -rd_{(k)}\,. \end{align}\]
Where:
- $\mathrm{RDaR}_{\alpha}(\boldsymbol{x})$: Relative Drawdown-at-Risk at level $\alpha$.
- $\boldsymbol{x}$: Portfolio returns vector $T \times 1$.
- $C_t$: Compound wealth process at period $t$.
- $rd_t \leq 0$: Relative drawdown at period $t$.
- $rd_{(k)}$: $k$-th smallest relative drawdown, the $k$-th deepest, and $w_{(k)}$ its observation weight.
- $k = \min\{k : W_{k} > (\alpha + s) W_{T}\}$: Quantile index, the position of the order statistic that the mixed-integer quantile programme selects.
- $W_{k} = \sum_{j=1}^{k} w_{(j)}$: Cumulative weight of the $k$ smallest entries, with $W_{0} = 0$.
- $w_{t}$: Observation weight of observation $t$. Every $w_{t}$ is one when no observation weights are set.
- $s$: Cardinality slack of the mixed-integer quantile programme, $s > 0$. It absorbs the rounding error of $\alpha W_{T}$. The measure has no
sfield, so it takes the default ofmip_var_bounds. - $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
- $T$: Number of observations.
The running peak starts at $C_0 = 1$, so the peak is never below the initial portfolio value. The index $k$ is the one of DrawdownatRisk, so the two measures select the same position in their series.
Section 3 of [200] defines the drawdown of the uncompounded cumulative return only. It names the relative drawdown and states that it lacks the properties of the absolute drawdown, but it defines no measure on it. The relative drawdown series above, and its quantile, are the library's extension of that work.
Algorithm
- Read the default slack
swithmip_var_bounds. - Compute the relative drawdown series with
relative_drawdown_vec. - Read the observation weights with
get_observation_weights. - Return
empirical_value_at_riskof the relative drawdown series atalphaands.
Fields
settings: Risk measure settings.
alpha: Quantile level for the lower tail. The bound isNum_SigCal, so the slot takes the level itself, anAbstractSignificanceCalibrationAlgorithmthat computes it from the prior result, or a plain function of the same five arguments.
w: Optional observation weights vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
Constructors
RelativeDrawdownatRisk(; settings::HierarchicalRiskMeasureSettings = HierarchicalRiskMeasureSettings(), alpha::Num_SigCal = 0.05, w::Option{<:ObsWeights} = nothing) -> RelativeDrawdownatRiskKeywords correspond to the struct's fields.
Validation
- If
alphais a number:0 < alpha < 1. - If
wis aStatsBase.AbstractWeights, it is not empty, each entry is finite and>= 0, andsum(w) > 0, throughassert_observation_weights. ADynamicAbstractWeightsholds no weights until it reads the data, sochecked_observation_weightschecks it at evaluation, and also checks there that the weights have one entry for each observation.
Propagated parameters
factory passes its arguments on to these @fprop fields:
w: Replaced with the incomingObsWeights.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.
Functor
(r::RelativeDrawdownatRisk)(x::VecNum)Computes the Relative Drawdown-at-Risk of a portfolio returns vector x, and leaves x unchanged.
Arguments
x::VecNum: Portfolio returns vector.
Examples
julia> RelativeDrawdownatRisk()RelativeDrawdownatRisk settings ┼ HierarchicalRiskMeasureSettings │ scale ┴ Float64: 1.0 alpha ┼ Float64: 0.05 w ┴ nothingRelated
HierarchicalRiskMeasureHierarchicalRiskMeasureSettingsDrawdownatRiskRelativeConditionalDrawdownatRiskempirical_value_at_riskfactoryobs_weights_view
References
- [200] A. Chekhlov, S. Uryasev and M. Zabarankin. Drawdown measure in portfolio optimization. International Journal of Theoretical and Applied Finance 8, 13–58 (2005). Section 3, Equation 3.2.
PortfolioOptimisers.port_opt_view — Method
port_opt_view(r::ValueatRiskFormulation, i, args...) -> ValueatRiskFormulationReturn the Value-at-Risk formulation r unchanged for the asset selection i.
A formulation that holds no per-asset data has nothing to slice. DistributionValueatRisk holds the moments of each asset, and it has its own method, which slices them.
Arguments
r: Value-at-Risk formulation.i: Asset selection, which this method does not read.args...: More arguments, which this method does not read.
Returns
r, unchanged.
Related
PortfolioOptimisers.port_opt_view — Method
port_opt_view(x, i, args...; kwargs...) -> nothing_scalar_array_view(x, i)Select the assets i of an estimator, a result or an algorithm.
port_opt_view is the index-selection counterpart of factory. factory passes runtime values down a tree of composed structs, and port_opt_view passes an index selection down the same tree. It restricts every field that holds data, and every composed child, to the subset i. The meta-optimisers, such as NestedClustered and SubsetResampling, and the cross-validation variants use it to solve sub-problems with structs of the same shape.
A caller does not usually call port_opt_view. The meta-optimisers and the cross-validation internals call it. It is public and not exported, because the author of a new composed estimator can need to define a method. Tag each field that holds data with @vprop, and @propagatable makes the method.
This universal fallback handles leaf values. It views an array through nothing_scalar_array_view. It returns a scalar, nothing, an estimator with no data fields and an algorithm with no change. A composed struct that recurses into its children has its own, more specific method, which @propagatable makes from the @vprop tags or which the author writes by hand.
This method accepts and drops the threaded tail args... and all kwargs. The tail is usually the returns matrix X of the JuMP families. With this method, a call port_opt_view(child, i, X) that a macro makes never raises a MethodError on a leaf field.
Algorithm
- Drop
args...andkwargs.... This method is the leaf of the recursion, so it passes nothing further. - Return
nothing_scalar_array_viewofxati. The algorithm of that function gives the rule for each leaf type.
Related
port_opt_view(r::ValueatRiskFormulation, i, args...) -> ValueatRiskFormulationReturn the Value-at-Risk formulation r unchanged for the asset selection i.
A formulation that holds no per-asset data has nothing to slice. DistributionValueatRisk holds the moments of each asset, and it has its own method, which slices them.
Arguments
r: Value-at-Risk formulation.i: Asset selection, which this method does not read.args...: More arguments, which this method does not read.
Returns
r, unchanged.
Related
PortfolioOptimisers.factory — Method
factory(
alg::DistributionValueatRisk,
pr::AbstractPriorResult,
args...;
kwargs...
) -> DistributionValueatRisk{_A, _B, _C, Nothing, <:Distributions.Distribution{F, S}} where {_A, _B, _C, F<:Distributions.VariateForm, S<:Distributions.ValueSupport}
Create an instance of DistributionValueatRisk by resolving its Deferred Quantities, then falling back to the prior result for whatever is still unstated.
sigma_chol_selector selects sigma and chol as a pair, not field by field. A stated sigma with no factor must not take the factor of the prior, which is a factor of a different matrix.
Algorithm
- Resolve the Deferred Quantities with
resolve_deferred_quantities. - Select
sigmaandcholas a pair withsigma_chol_selector. - Take
mufrom the formulation, or fromprwhen the formulation states none. - Build the formulation with the three values,
pe = nothingand the samedistandmtx_sqrt.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [196]
- P. Artzner, F. Delbaen, J.-M. Eber and D. Heath. Coherent measures of risk. Mathematical Finance 9, 203–228 (1999).
- [197]
- J.P. Morgan and Reuters. RiskMetrics Technical Document (J.P. Morgan/Reuters, 1996).
- [198]
- M. S. Lobo, L. Vandenberghe, S. Boyd and H. Lebret. Applications of Second-Order Cone Programming. Linear Algebra and its Applications 284, 193–228 (1998).
- [199]
- D. Cajas. OWA portfolio optimization: A disciplined convex programming framework. Available at SSRN 3988927 (2021).
- [200]
- A. Chekhlov, S. Uryasev and M. Zabarankin. Drawdown measure in portfolio optimization. International Journal of Theoretical and Applied Finance 8, 13–58 (2005).