X at Risk

PortfolioOptimisers.MIPValueatRisk — Type
struct MIPValueatRisk{__T_b, __T_s} <: ValueatRiskFormulation

Computes 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 ValueatRisk and $-d_{t}$ for DrawdownatRisk.
  • $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 b field.
  • $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. If nothing, the model derives the smallest exact constant from the data and the weight bounds with mip_big_m, and uses 1000 where 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) * T without observation weights, so it absorbs the rounding error of alpha times the total weight. The functor selects its order statistic with the same slack. If nothing, the model and the functor use 1e-9.

Constructors

MIPValueatRisk(;    b::Option{<:Number} = nothing,    s::Option{<:Number} = nothing) -> MIPValueatRisk

Keywords correspond to the struct's fields.

Validation

  • If b is not nothing: b > 0 and finite.
  • If s is not nothing: s > 0 and finite.
  • If both b and s are not nothing: b > s.

Examples

julia> MIPValueatRisk()MIPValueatRisk  b ┼ nothing  s ┴ nothing

Related

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.
source
PortfolioOptimisers.DistributionValueatRisk — Type
struct DistributionValueatRisk{__T_mu, __T_sigma, __T_chol, __T_pe, __T_dist, __T_mtx_sqrt} <: ValueatRiskFormulation

Computes 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 dist at $\alpha$, from compute_value_at_risk_z.
  • $z^{c}_{\beta}$: Gain-tail z-score of dist at $\beta$, from compute_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.

Note

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 vector assets × 1, the location of dist. Also admits a Deferred Quantity — an expected returns estimator or a prior estimator that computes the vector against the optimisation's own prior, at factory time (see MuSlot and resolve_deferred_quantities). If nothing, the prior supplies it.
  • sigma: Optional covariance matrix assets × assets. Also admits a Deferred Quantity — a covariance estimator or a prior estimator that computes the matrix against the optimisation's own prior, at factory time (see SigmaSlot and resolve_deferred_quantities). If nothing, the prior supplies it.
  • chol: Optional Cholesky factorisation of the covariance matrix. Derived from sigma, so it never defers: it arrives as one pair with whatever sigma resolves to. Give it with a matrix sigma and with neither otherwise — stating it without sigma, or while sigma holds a Deferred Quantity, is refused at construction (see assert_derived_slot_has_source). If nothing, the prior supplies the pair, or the kernel derives the factorisation from a stated sigma.
  • pe: Optional prior estimator that fills every prior-derived slot the measure leaves unstated, from a single fit. A stated slot wins. See resolve_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 a pe whose x_src is not nothing, see assert_returns_source.
  • dist: Probability distribution.
  • mtx_sqrt: Square-root algorithm of the covariance matrix that the cone of the parametric quantile reads when no chol is at hand, or nothing for the plain Cholesky factor, which raises a LinearAlgebra.PosDefException on a matrix that is not positive definite. The default takes the square root of the eigendecomposition of a singular positive semidefinite matrix. matrix_square_root states 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()) -> DistributionValueatRisk

Keywords correspond to the struct's fields.

Validation

  • If mu is not nothing: !isempty(mu).
  • If sigma is an estimator, it is not an AbstractVarianceEstimator. A variance estimator has no cov, so assert_covariance_estimator raises an ArgumentError that names sigma.
  • If sigma is not nothing: !isempty(sigma) and size(sigma, 1) == size(sigma, 2).
  • If chol is not nothing: !isempty(chol), and sigma is a matrix rather than nothing or a Deferred Quantity.
Warning

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 mu to the selected assets. A Deferred Quantity passes through unsliced, and resolves on the subset later.
  • The method slices a stated sigma on both axes. A Deferred Quantity passes through unsliced, and resolves on the subset later.
  • The method slices chol on its columns alone. Its rows index the factorisation, and the asset selection does not address them.
  • pe, dist and mtx_sqrt pass through unchanged. dist describes 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

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.
source
PortfolioOptimisers.ValueatRisk — Type
struct ValueatRisk{__T_settings, __T_alpha, __T_w, __T_alg} <: RiskMeasure

Measures 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 s field of MIPValueatRisk.
  • $\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:

  1. Read the slack s with mip_var_bounds, which gives the default when alg.s is nothing.
  2. Read the observation weights w with get_observation_weights.
  3. Return empirical_value_at_risk of x at alpha and s. Without weights the kernel reorders its input, so it receives a copy of x.

Fields

  • settings: Risk measure settings.
  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, 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()) -> ValueatRisk

Keywords correspond to the struct's fields.

Validation

Propagated parameters

factory passes its arguments on to these @fprop fields:

View parameters

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

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

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

Related

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.
source
PortfolioOptimisers.ValueatRiskRange — Type
struct ValueatRiskRange{__T_settings, __T_alpha, __T_beta, __T_w, __T_alg} <: RangeRiskMeasure

Measures 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 ValueatRisk defines.
  • $\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:

  1. Read the slack s with mip_var_bounds, which gives the default when alg.s is nothing.
  2. Read the observation weights w with get_observation_weights.
  3. Compute loss, empirical_value_at_risk of x at alpha and s. Without weights the kernel reorders its input, so it receives a copy of x.
  4. Compute gain, empirical_value_at_risk of -x at beta and s.
  5. Return loss + gain.

Fields

  • settings: Risk measure settings.
  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, 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()) -> ValueatRiskRange

Keywords correspond to the struct's fields.

Validation

  • If alpha is a number: 0 < alpha < 1.
  • If beta is a number: 0 < beta < 1.
  • If w is a StatsBase.AbstractWeights, it is not empty, each entry is finite and >= 0, and sum(w) > 0, through assert_observation_weights. A DynamicAbstractWeights holds no weights until it reads the data, so checked_observation_weights checks 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:

View parameters

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

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

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

Related

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).
source
PortfolioOptimisers.DrawdownatRisk — Type
struct DrawdownatRisk{__T_settings, __T_alpha, __T_w, __T_b, __T_s} <: RiskMeasure

Measures 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 s field.
  • $\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

  1. Read the slack s with mip_var_bounds, which gives the default when the s field is nothing.
  2. Compute the drawdown series with absolute_drawdown_vec.
  3. Read the observation weights with get_observation_weights.
  4. Return empirical_value_at_risk of the drawdown series at alpha and s.

Fields

  • settings: Risk measure settings.
  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, 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. If nothing, the model derives the smallest exact constant from the data and the weight bounds with mip_big_m, and uses 1000 where 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) * T without observation weights, so it absorbs the rounding error of alpha times the total weight. The functor selects its order statistic with the same slack. If nothing, the model and the functor use 1e-9.

Constructors

DrawdownatRisk(;    settings::RiskMeasureSettings = RiskMeasureSettings(),    alpha::Num_SigCal = 0.05,    w::Option{<:ObsWeights} = nothing,    b::Option{<:Number} = nothing,    s::Option{<:Number} = nothing) -> DrawdownatRisk

Keywords correspond to the struct's fields.

Validation

  • If alpha is a number: 0 < alpha < 1.
  • If w is a StatsBase.AbstractWeights, it is not empty, each entry is finite and >= 0, and sum(w) > 0, through assert_observation_weights. A DynamicAbstractWeights holds no weights until it reads the data, so checked_observation_weights checks it at evaluation, and also checks there that the weights have one entry for each observation.
  • If b is not nothing: b > 0 and finite.
  • If s is not nothing: s > 0 and finite.
  • If both b and s are not nothing: b > s.

Propagated parameters

factory passes its arguments on to these @fprop fields:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

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

Related

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.
source
PortfolioOptimisers.RelativeDrawdownatRisk — Type
struct RelativeDrawdownatRisk{__T_settings, __T_alpha, __T_w} <: HierarchicalRiskMeasure

Measures 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 s field, so it takes the default of mip_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

  1. Read the default slack s with mip_var_bounds.
  2. Compute the relative drawdown series with relative_drawdown_vec.
  3. Read the observation weights with get_observation_weights.
  4. Return empirical_value_at_risk of the relative drawdown series at alpha and s.

Fields

  • settings: Risk measure settings.
  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.

Constructors

RelativeDrawdownatRisk(;    settings::HierarchicalRiskMeasureSettings = HierarchicalRiskMeasureSettings(),    alpha::Num_SigCal = 0.05,    w::Option{<:ObsWeights} = nothing) -> RelativeDrawdownatRisk

Keywords correspond to the struct's fields.

Validation

Propagated parameters

factory passes its arguments on to these @fprop fields:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

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

Related

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.
source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(r::ValueatRiskFormulation, i, args...) -> ValueatRiskFormulation

Return 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

source
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

  1. Drop args... and kwargs.... This method is the leaf of the recursion, so it passes nothing further.
  2. Return nothing_scalar_array_view of x at i. The algorithm of that function gives the rule for each leaf type.

Related

source
port_opt_view(r::ValueatRiskFormulation, i, args...) -> ValueatRiskFormulation

Return 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

source
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

  1. Resolve the Deferred Quantities with resolve_deferred_quantities.
  2. Select sigma and chol as a pair with sigma_chol_selector.
  3. Take mu from the formulation, or from pr when the formulation states none.
  4. Build the formulation with the three values, pe = nothing and the same dist and mtx_sqrt.

Related

source

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