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)

Universal fallback for port_opt_view. Any value that has no more specific port_opt_view method is treated as leaf data: it is delegated to nothing_scalar_array_view, which slices arrays/VecScalars and passes scalars, nothing, estimators, and algorithms through unchanged. Composed structs that need to recurse into children define their own (more specific) method — emitted by the @vprop tag 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

• nothing_scalar_array_view

• @vprop

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.factory Method

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

Create an instance of DistributionValueatRisk by selecting distribution parameters from the formulation or falling back to the prior result.

Related

• DistributionValueatRisk

• factory

• nothing_scalar_array_selector

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.factory Method

factory(
    r::ValueatRisk,
    pr::AbstractPriorResult,
    args...;
    kwargs...
) -> ValueatRisk{RiskMeasureSettings{__T_scale, __T_ub, __T_rke}, var"#s179", _A, <:ValueatRiskFormulation} where {__T_scale, __T_ub, __T_rke, var"#s179"<:Number, _A}

Create an instance of ValueatRisk by selecting observation weights and formulation from the risk-measure instance or falling back to the prior result.

Related

• ValueatRisk

• factory

• nothing_scalar_array_selector

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.factory Method

factory(
    r::ValueatRiskRange,
    pr::AbstractPriorResult,
    args...;
    kwargs...
) -> ValueatRiskRange{RiskMeasureSettings{__T_scale, __T_ub, __T_rke}, var"#s179", var"#s1791", _A, <:ValueatRiskFormulation} where {__T_scale, __T_ub, __T_rke, var"#s179"<:Number, var"#s1791"<:Number, _A}

Create an instance of ValueatRiskRange by selecting observation weights and formulation from the risk-measure instance or falling back to the prior result.

Related

• ValueatRiskRange

• factory

• nothing_scalar_array_selector

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.factory Method

factory(
    r::DrawdownatRisk,
    pr::AbstractPriorResult,
    args...;
    kwargs...
) -> DrawdownatRisk

Create an instance of DrawdownatRisk by selecting observation weights from the risk-measure instance or falling back to the prior result.

Related

• DrawdownatRisk

• factory

• nothing_scalar_array_selector

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.factory Method

factory(
    r::RelativeDrawdownatRisk,
    pr::AbstractPriorResult,
    args...;
    kwargs...
) -> RelativeDrawdownatRisk{HierarchicalRiskMeasureSettings{__T_scale}, <:Number} where __T_scale

Create an instance of RelativeDrawdownatRisk by selecting observation weights from the risk-measure instance or falling back to the prior result.

Related

• RelativeDrawdownatRisk

• factory

• nothing_scalar_array_selector

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

Arguments

• x::VecNum: Return series vector (modified in place temporarily, then restored).

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.

Arguments

• x: Vector of portfolio returns.

Returns

• Relative drawdown vector.

Related

• absolute_drawdown_vec

• relative_drawdown_arr

source