X at Risk

PortfolioOptimisers.ValueatRiskFormulation Type

abstract type ValueatRiskFormulation <: AbstractAlgorithm

Abstract supertype for all Value-at-Risk formulation algorithms in PortfolioOptimisers.jl.

All concrete and/or abstract types representing the formulation for computing Value-at-Risk (e.g., mixed-integer programming, distribution-based) should be subtypes of ValueatRiskFormulation.

Related

• AbstractAlgorithm

• MIPValueatRisk

• DistributionValueatRisk

• ValueatRisk

• ValueatRiskRange

source

PortfolioOptimisers.factory Method

factory(
    alg::ValueatRiskFormulation,
    args...;
    kwargs...
) -> DistributionValueatRisk{_A, _B, _C, <:Distributions.Distribution{F, S}} where {_A, _B, _C, F<:Distributions.VariateForm, S<:Distributions.ValueSupport}

Return the Value-at-Risk formulation alg unchanged.

Identity pass-through for formulation types that do not depend on prior results.

Related

• ValueatRiskFormulation

• factory

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(r, args...)

Get a view or subset of a Value-at-Risk formulation for slicing.

Returns the formulation unchanged (for non-distribution types) or sliced (for distribution-based types). Used internally in hierarchical optimisation.

Arguments

• r: Value-at-Risk formulation.

• args...: Additional arguments (index, etc.).

Returns

• Sliced or unchanged formulation.

Related

• ValueatRiskFormulation

• DistributionValueatRisk

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(x, i, args...; kwargs...) -> nothing_scalar_array_view(x, i)

Sub-select an estimator, result, or algorithm to the asset/observation index i.

port_opt_view is the index-selection counterpart of factory: where factory threads runtime values down a composed struct tree, port_opt_view threads an index selection — restricting every data-bearing field and composed child to the subset i. It is the mechanism that makes meta-optimisers (NestedClustered, SubsetResampling) and cross-validation variants operate on subproblems with identical struct shapes.

Callers do not normally call port_opt_view directly; it is driven by meta-optimisers and cross-validation internals. It is public (not exported) because extension authors who implement a new composed estimator may need to define a method. Use @vprop on data-bearing fields to have the method generated automatically.

This universal fallback handles leaf values: arrays are sliced via nothing_scalar_array_view; scalars, nothing, estimators without data fields, and algorithms pass through unchanged. Composed structs that recurse into children define their own (more specific) method — emitted by @vprop or hand-written.

The threaded tail args... (typically the returns matrix X for the JuMP families) and any kwargs are accepted and dropped here, so a macro-threaded port_opt_view(child, i, X) never MethodErrors on a leaf field.

Related

• factory

• @vprop

• nothing_scalar_array_view

source

port_opt_view(r, args...)

Get a view or subset of a Value-at-Risk formulation for slicing.

Returns the formulation unchanged (for non-distribution types) or sliced (for distribution-based types). Used internally in hierarchical optimisation.

Arguments

• r: Value-at-Risk formulation.

• args...: Additional arguments (index, etc.).

Returns

• Sliced or unchanged formulation.

Related

• ValueatRiskFormulation

• DistributionValueatRisk

source

PortfolioOptimisers.MIPValueatRisk Type

struct MIPValueatRisk{__T_b, __T_s} <: ValueatRiskFormulation

Mixed-integer programming (MIP) formulation for Value-at-Risk.

MIPValueatRisk specifies bounds used in the binary variable formulation of Value-at-Risk within a JuMP optimisation model.

Fields

• b: Big-M upper bound for MIP formulations.

• s: Small-M lower bound for MIP formulations.

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.

• If s is not nothing: s > 0.

• If both are not nothing: b > s.

Examples

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

Related

• ValueatRiskFormulation

• DistributionValueatRisk

• ValueatRisk

• Option

source

PortfolioOptimisers.DistributionValueatRisk Type

struct DistributionValueatRisk{__T_mu, __T_sigma, __T_chol, __T_dist} <: ValueatRiskFormulation

Distribution-based formulation for Value-at-Risk.

DistributionValueatRisk specifies a parametric distribution for computing Value-at-Risk analytically. The distribution parameters can be overridden by prior results during optimisation.

Fields

• mu: Optional mean for centering.

• sigma: Covariance matrix features × features.

• chol: Cholesky factorisation of the covariance matrix.

• dist: Probability distribution.

Constructors

DistributionValueatRisk(;
    mu::Option{<:VecNum} = nothing,
    sigma::Option{<:MatNum} = nothing,
    chol::Option{<:MatNum} = nothing,
    dist::Distributions.Distribution = Distributions.Normal()
) -> DistributionValueatRisk

Keywords correspond to the struct's fields.

Validation

• If mu is not nothing: !isempty(mu).

• If sigma is not nothing: !isempty(sigma) and size(sigma, 1) == size(sigma, 2).

• If chol is not nothing: !isempty(chol).

Examples

julia> DistributionValueatRisk()
DistributionValueatRisk
     mu ┼ nothing
  sigma ┼ nothing
   chol ┼ nothing
   dist ┴ Distributions.Normal{Float64}: Distributions.Normal{Float64}(μ=0.0, σ=1.0)

Related

• ValueatRiskFormulation

• MIPValueatRisk

• ValueatRisk

• Option

source

PortfolioOptimisers.ValueatRisk Type

struct ValueatRisk{__T_settings, __T_alpha, __T_w, __T_alg} <: RiskMeasure

Represents the Value-at-Risk (VaR) risk measure.

ValueatRisk quantifies the maximum expected loss at a given confidence level alpha over a specified time horizon. It can be computed using empirical quantiles (weighted or unweighted) or via a parametric distribution.

Mathematical definition

Let $\mathit{x}=(x_1,\dots ,x_T{)}^{⊺}$ be the portfolio returns vector and $x_{(k)}$ the $k$-th order statistic ($k$-th smallest value). The empirical VaR at significance level $\alpha$ is:

$$\begin{array}{rl}{\mathrm{VaR}}_{\alpha }(\mathit{x})& =-x_{(\lceil \alpha T\rceil )}.\end{array}$$

Where:

• ${\mathrm{VaR}}_{\alpha }(\mathit{x})$: Value-at-Risk at significance level $\alpha$.

• $\mathit{x}=(x_1,\dots ,x_T{)}^{⊺}$: Portfolio returns vector.

• $x_{(k)}$: $k$-th order statistic ($k$-th smallest value) of $\mathit{x}$.

• $\alpha$: Significance level (e.g., $\alpha =0.05$ for 95% VaR).

• $T$: Number of observations.

For observation-weighted samples with weight vector $\mathit{w}$ summing to $S_w$, VaR is the $\alpha S_w$-quantile of the weighted empirical distribution.

Fields

• settings: Risk measure settings.

• alpha: Quantile level for the lower tail.

• 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::Number = 0.05,
    w::Option{<:ObsWeights} = nothing,
    alg::ValueatRiskFormulation = MIPValueatRisk()
) -> ValueatRisk

Keywords correspond to the struct's fields.

Validation

• 0 < alpha < 1.

• If w is not nothing: !isempty(w).

Functor

(r::ValueatRisk)(x::VecNum)

Computes the Value-at-Risk of a portfolio returns vector x.

Arguments

• x::VecNum: Portfolio returns 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

• RiskMeasure

• RiskMeasureSettings

• MIPValueatRisk

• DistributionValueatRisk

• ConditionalValueatRisk

• ValueatRiskRange

source

PortfolioOptimisers.ValueatRiskRange Type

struct ValueatRiskRange{__T_settings, __T_alpha, __T_beta, __T_w, __T_alg} <: RiskMeasure

Represents the Value-at-Risk Range risk measure.

ValueatRiskRange computes the difference between the lower-tail Value-at-Risk (at level alpha) and the upper-tail Value-at-Risk (at level beta), measuring the spread between downside and upside tail risks.

Mathematical definition

$$\begin{array}{rl}{\mathrm{VaRRange}}_{\alpha ,\beta }(\mathit{x})& ={\mathrm{VaR}}_{\alpha }(\mathit{x})-{\mathrm{VaR}}_{\beta }(-\mathit{x}),.\end{array}$$

Where:

• ${\mathrm{VaRRange}}_{\alpha ,\beta }(\mathit{x})$: Value-at-Risk Range.

• ${\mathrm{VaR}}_{\alpha }(\mathit{x})$: Lower-tail loss quantile.

• ${\mathrm{VaR}}_{\beta }(-\mathit{x})$: Upper-tail gain quantile.

• $\mathit{x}$: Portfolio returns vector.

• $\alpha$: Lower-tail significance level.

• $\beta$: Upper-tail significance level.

Fields

• settings: Risk measure settings.

• alpha: Quantile level for the lower tail.

• beta: Quantile level for the upper tail.

• 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::Number = 0.05,
    beta::Number = 0.05,
    w::Option{<:ObsWeights} = nothing,
    alg::ValueatRiskFormulation = MIPValueatRisk()
) -> ValueatRiskRange

Keywords correspond to the struct's fields.

Validation

• 0 < alpha < 1.

• 0 < beta < 1.

• If w is not nothing: !isempty(w).

Functor

(r::ValueatRiskRange)(x::VecNum)

Computes the VaR Range of a portfolio returns vector x.

Arguments

• x::VecNum: Portfolio returns 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

• RiskMeasure

• RiskMeasureSettings

• ValueatRisk

• ConditionalValueatRiskRange

source

PortfolioOptimisers.DrawdownatRisk Type

struct DrawdownatRisk{__T_settings, __T_alpha, __T_w, __T_b, __T_s} <: RiskMeasure

Represents the Drawdown-at-Risk (DaR) risk measure.

DrawdownatRisk quantifies the maximum drawdown not exceeded at a given confidence level alpha. It operates on absolute drawdowns computed from the portfolio returns series.

Mathematical definition

Define the cumulative wealth process and absolute drawdown at time $t$:

$$\begin{array}{rl}{c}_t& =\sum _{s=1}^t{x}_s,\\ d_t& =c_t-\underset{0\le s\le t}{max}{c}_s\le 0.\end{array}$$

Where:

• $\mathit{x}$: Portfolio returns vector $T\times 1$.

• $c_t$: Cumulative simple portfolio return at period $t$.

• $d_t\le 0$: Absolute drawdown at period $t$.

The Drawdown-at-Risk at level $\alpha$ is the $\lceil \alpha T\rceil$-th smallest (most extreme) drawdown:

$$\begin{array}{rl}{\mathrm{DaR}}_{\alpha }(\mathit{x})& =-d_{(\lceil \alpha T\rceil )}.\end{array}$$

Where:

• ${\mathrm{DaR}}_{\alpha }(\mathit{x})$: Drawdown-at-Risk at level $\alpha$.

• $\alpha$: Significance level (left tail probability), $\alpha \in (0,1)$.

• $T$: Number of observations.

• $d_t\le 0$: Absolute drawdown at period $t$.

• $d_{(k)}$: $k$-th order statistic (sorted ascending) of the drawdown series.

Fields

• settings: Risk measure settings.

• alpha: Quantile level for the lower tail.

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

• b: Big-M upper bound for MIP formulations.

• s: Small-M lower bound for MIP formulations.

Constructors

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

Keywords correspond to the struct's fields.

Validation

• 0 < alpha < 1.

• If w is not nothing: !isempty(w).

• If b is not nothing: b > 0.

• If s is not nothing: s > 0.

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

Functor

(r::DrawdownatRisk)(x::VecNum)

Computes the Drawdown-at-Risk of a portfolio returns vector x.

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

• RiskMeasure

• RiskMeasureSettings

• ConditionalDrawdownatRisk

• RelativeDrawdownatRisk

source

PortfolioOptimisers.RelativeDrawdownatRisk Type

struct RelativeDrawdownatRisk{__T_settings, __T_alpha, __T_w} <: HierarchicalRiskMeasure

Represents the Relative Drawdown-at-Risk risk measure for hierarchical optimisation.

RelativeDrawdownatRisk quantifies the maximum relative (compounded) drawdown not exceeded at a given confidence level alpha. It operates on relative drawdowns computed from the portfolio returns series.

Mathematical definition

Define the compounded wealth process and relative drawdown at time $t$:

$$\begin{array}{rl}{C}_t& =\prod _{s=1}^t(1+x_s),\\ r{d}_t& =\frac{C_t}{\underset{0\le s\le t}{max}{C}_s}-1\le 0.\end{array}$$

Where:

• $\mathit{x}$: Portfolio returns vector $T\times 1$.

• $C_t$: Compound wealth process at period $t$.

• $r{d}_t\le 0$: Relative drawdown at period $t$.

The Relative Drawdown-at-Risk at level $\alpha$ is:

$$\begin{array}{rl}{\mathrm{RDaR}}_{\alpha }(\mathit{x})& =-r{d}_{(\lceil \alpha T\rceil )}.\end{array}$$

Where:

• ${\mathrm{RDaR}}_{\alpha }(\mathit{x})$: Relative Drawdown-at-Risk at level $\alpha$.

• $\alpha$: Significance level (left tail probability), $\alpha \in (0,1)$.

• $T$: Number of observations.

• $r{d}_t\le 0$: Relative drawdown at period $t$.

• $r{d}_{(k)}$: $k$-th order statistic (sorted ascending) of the relative drawdown series.

Fields

• settings: Risk measure settings.

• alpha: Quantile level for the lower tail.

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

Constructors

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

Keywords correspond to the struct's fields.

Validation

• 0 < alpha < 1.

• If w is not nothing: !isempty(w).

Functor

(r::RelativeDrawdownatRisk)(x::VecNum)

Computes the Relative Drawdown-at-Risk of a portfolio returns vector x.

Arguments

• x::VecNum: Portfolio returns vector.

Examples

julia> RelativeDrawdownatRisk()
RelativeDrawdownatRisk
  settings ┼ HierarchicalRiskMeasureSettings
           │   scale ┴ Float64: 1.0
     alpha ┼ Float64: 0.05
         w ┴ nothing

Related

• HierarchicalRiskMeasure

• HierarchicalRiskMeasureSettings

• DrawdownatRisk

• RelativeConditionalDrawdownatRisk

source

PortfolioOptimisers.CholRM Type

const CholRM = Union{<:Variance, <:StandardDeviation, <:DistributionValueatRisk}

Union of risk measures that support Cholesky-factor-based computation.

Related

• Variance

• StandardDeviation

• DistributionValueatRisk

source

PortfolioOptimisers.absolute_drawdown_vec Function

absolute_drawdown_vec(x::VecNum) -> Vector

Compute the absolute drawdown series for a single-asset return vector.

Each element of the result is the difference between the current cumulative return and its running maximum (always ≤ 0).

The running maximum starts at zero, so the drawdown is measured against the initial portfolio value rather than against the first observation.

x is read, never written: the accumulator and the running peak are carried in scalars, so any AbstractVector works — a column view, a range, an immutable array.

Arguments

• x::VecNum: Return series vector.

Returns

• Vector: Drawdown vector of the same length as x.

Related

• absolute_drawdown_arr

• DrawdownatRisk

source

PortfolioOptimisers.relative_drawdown_vec Method

relative_drawdown_vec(x)

Compute the relative drawdown vector for a vector of portfolio returns.

Returns the relative drawdown at each time step, computed as the current portfolio value relative to its running maximum.

The running maximum starts at one, so the drawdown is measured against the initial portfolio value rather than against the first observation.

x is read, never written: the compounding factor and the running peak are carried in scalars, so any AbstractVector works — a column view, a range, an immutable array.

Arguments

• x: Vector of portfolio returns.

Returns

• Relative drawdown vector.

Related

• absolute_drawdown_vec

• relative_drawdown_arr

source