X at Risk: private API

PortfolioOptimisers.ValueatRiskFormulation — Type
abstract type ValueatRiskFormulation <: AbstractAlgorithm

Selects whether a Value-at-Risk measure computes its quantile from the sample or from a parametric distribution.

The formulation selects the estimand, not only the encoding. MIPValueatRisk reports the empirical quantile of the sample, and DistributionValueatRisk reports the quantile of a parametric distribution fitted to the prior's moments. The two are different numbers on the same data. A measure that holds one formulation reports that number in its optimisation model and in its functor alike.

All concrete subtypes should subtype ValueatRiskFormulation.

Related

source
PortfolioOptimisers.CholRM — Type
const CholRM = Union{Variance, StandardDeviation, DistributionValueatRisk}

Groups the types that hold an optional covariance matrix sigma and its optional factor chol.

The group exists so that one method of chol_sigma_selector serves all three. The JuMP model of each type reads a factor of the covariance, and that method selects it. It takes chol when the caller states it, a factor of sigma when the caller states only sigma, and the factor of the prior otherwise. DistributionValueatRisk is a formulation, not a risk measure, but it holds the same two fields.

Related

source
PortfolioOptimisers.compute_value_at_risk_z — Function
compute_value_at_risk_z(
    dist::Distributions.Normal,
    alpha::Number
) -> Any

Compute the loss-tail z-score of the parametric Value-at-Risk at significance level alpha.

The z-score is the $1 - \alpha$ quantile of the distribution, the standardised loss that the portfolio exceeds with probability $\alpha$.

Mathematical definition

\[\begin{align} z_{\alpha} &= F^{-1}(1 - \alpha)\,. \end{align}\]

Each method reads $F$ from its own distribution:

  • Normal: $F$ is the cumulative distribution function of dist as given, so the default Normal() is standardised. A mean $m$ adds $m$ to $z_{\alpha}$, and a standard deviation $s$ multiplies its quantile term by $s$.
  • TDist: $F$ is the Student-t distribution with $\nu$ degrees of freedom, scaled to unit variance, so $z_{\alpha} = t_{\nu}^{-1}(1 - \alpha) \sqrt{(\nu - 2)/\nu}$.
  • Laplace: $F$ is the Laplace distribution with zero mean and unit variance, whatever the parameters of dist. Its closed form is below.

\[\begin{align} z_{\alpha} &= \begin{cases} -\dfrac{\ln(2 \alpha)}{\sqrt{2}}\,, & \alpha \leq \dfrac{1}{2}\,,\\ \dfrac{\ln(2 (1 - \alpha))}{\sqrt{2}}\,, & \alpha > \dfrac{1}{2}\,. \end{cases} \end{align}\]

Where:

  • $z_{\alpha}$: Loss-tail z-score.
  • $F$: Cumulative distribution function of the standardised loss.
  • $t_{\nu}$: Cumulative distribution function of the Student-t distribution with $\nu$ degrees of freedom.
  • $\nu$: Degrees of freedom of dist.
  • $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.

$z_{\alpha}$ is positive for $\alpha < 1/2$ on each of the three distributions.

Arguments

  • dist: Distribution of the standardised loss, a Normal, a TDist or a Laplace.
  • alpha::Number: Significance level.

Validation

  • TDist: the degrees of freedom are greater than 2, so that the variance is finite. Otherwise a DomainError is thrown.

Returns

  • z::Number: Loss-tail z-score.

Related

source
PortfolioOptimisers.compute_value_at_risk_cz — Function
compute_value_at_risk_cz(
    dist::Distributions.Normal,
    alpha::Number
) -> Any

Compute the gain-tail z-score of the parametric Value-at-Risk at significance level alpha.

The z-score is the $\alpha$ quantile of the distribution. The gain tail of ValueatRiskRange reads it.

Mathematical definition

\[\begin{align} z^{c}_{\alpha} &= F^{-1}(\alpha)\,. \end{align}\]

Each method reads $F$ from the same distribution as compute_value_at_risk_z. For a distribution that is symmetric about zero, $z^{c}_{\alpha} = -z_{\alpha}$. The Laplace method returns that value, and so do the TDist method and the Normal method for a zero mean. A Normal with a mean $m$ gives $z^{c}_{\alpha} = -z_{\alpha} + 2 m$.

Where:

  • $z^{c}_{\alpha}$: Gain-tail z-score.
  • $z_{\alpha}$: Loss-tail z-score, from compute_value_at_risk_z.
  • $F$: Cumulative distribution function of the standardised loss.
  • $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.

Arguments

  • dist: Distribution of the standardised loss, a Normal, a TDist or a Laplace.
  • alpha::Number: Significance level.

Validation

  • TDist: the degrees of freedom are greater than 2, so that the variance is finite. Otherwise a DomainError is thrown.

Returns

  • z::Number: Gain-tail z-score.

Related

source
PortfolioOptimisers.gain_tail_distribution — Function
gain_tail_distribution(dist::Distributions.Normal) -> Distributions.Normal
gain_tail_distribution(dist::Distributions.Distribution) -> Distributions.Distribution

Return the distribution of the standardised loss of the negated portfolio, which the gain tail of GenericValueatRiskRange reads.

The parametric loss of the portfolio is $-\boldsymbol{\mu}^\intercal \boldsymbol{w} + \sigma_{\boldsymbol{w}} \varepsilon$, where dist is the law of $\varepsilon$. The loss of the negated portfolio is the negated loss, so its standardised loss is $-\varepsilon$. A gain tail that evaluates the loss tail on $-\boldsymbol{w}$ must read the law of $-\varepsilon$. Then its value equals the gain tail of ValueatRiskRange, $\boldsymbol{\mu}^\intercal \boldsymbol{w} - z^{c}_{\alpha} \sigma_{\boldsymbol{w}}$, because $F_{-\varepsilon}^{-1}(1 - \alpha) = -F_{\varepsilon}^{-1}(\alpha)$.

  • Normal: compute_value_at_risk_z reads dist as given, so the method rebuilds it with the negated mean and the same standard deviation. A Normal with a zero mean is returned unchanged.
  • Any other distribution passes through unchanged. compute_value_at_risk_z reads TDist and Laplace as laws with zero mean, which are symmetric about zero, so each is its own reflection.

Arguments

  • dist: Distribution of the standardised loss of the portfolio.

Returns

  • dist: Distribution of the standardised loss of the negated portfolio.

Related

source
PortfolioOptimisers.resolve_deferred_quantities — Method
resolve_deferred_quantities(x, pr::AbstractPriorResult, slv = nothing)

Resolve the children that deferred_slots declared and the slots that calibration_slots declared, and return x itself when none of them changed.

This is the derived half of the resolution rule. A container declares its children once and both entry points follow: factory reaches them through @fprop, and the JuMP builders reach them through this method. Neither needs a forwarding method per container.

A type that resolves a quantity of its own overrides this with its own method, which is more specific. So the derivation carries container recursion alone, and never guesses how a matrix, a tensor or the centre a moment was taken about comes out of a fit.

Both channels end in one rebuild: a measure that carries both kinds of slot must not be rebuilt twice. resolve_calibration_slots states the calibration half and returns its resolved slots rather than a rebuilt object, and the two answers merge here. The deferred half merges last, so it wins a key both channels declare. A container names one child in both, and the child the recursion resolved is the one to keep.

slv is the effective solver, and the recursion threads it to every child. A container states no solver of its own, so it changes none: each child settles the one it was handed against the one it carries.

Algorithm

  1. Read the slots x declares with deferred_slots, giving slots.
  2. Read the resolved calibration slots with resolve_calibration_slots, giving calibrated.
  3. Return x unchanged when both are empty. A type with neither kind of slot needs no method of its own.
  4. Resolve every entry of slots with resolve_deferred_quantities, threading pr and slv to each, giving resolved. A child measure resolves through its own method, a vector of children through the vector method, and any other occupant comes back unchanged through this method, because it declares no slot: a stated value, nothing or a Deferred Quantity that the enclosing type resolves itself.
  5. Refuse a slot the recursion left unresolved with assert_declared_slot_resolver.
  6. Hand merge(calibrated, resolved) to rebuild_with_slots, which returns x itself when no entry moved and a rebuilt copy when one did.

Returns

  • x itself when no slot moved, and a rebuilt copy of x when one did.

Related

source
resolve_deferred_quantities(
    x::ValueatRisk,
    pr::AbstractPriorResult
) -> ValueatRisk
resolve_deferred_quantities(
    x::ValueatRisk,
    pr::AbstractPriorResult,
    slv
) -> ValueatRisk

Resolve the significance level alpha of a ValueatRisk against prior result pr, and resolve the formulation alg beside it.

alpha can hold a Calibration Rule in place of a number, so it resolves here. The rebuild goes through rebuild_with_slots, whose call to the inner constructor checks 0 < alpha < 1 again on the calibrated number. So the check that a number of the caller meets also refuses a rule that returns a value outside the slot.

This method is more specific than the derived recursion, so it takes over the alg slot that deferred_slots declares. It resolves that slot through resolve_deferred_quantities itself, as the derived recursion resolves each slot.

Algorithm

  1. Set ws to the observation weights of the measure, or to those of pr when the measure states none.
  2. Resolve alpha with resolve_calibration_slot, which gives the rule pr, ws and the solver slv. The measure holds no solver of its own.
  3. Resolve alg with resolve_deferred_quantities.
  4. Rebuild the measure with the resolved alpha and alg.

Related

source
PortfolioOptimisers.resolve_deferred_quantities — Method
resolve_deferred_quantities(x, pr::AbstractPriorResult, slv = nothing)

Resolve the children that deferred_slots declared and the slots that calibration_slots declared, and return x itself when none of them changed.

This is the derived half of the resolution rule. A container declares its children once and both entry points follow: factory reaches them through @fprop, and the JuMP builders reach them through this method. Neither needs a forwarding method per container.

A type that resolves a quantity of its own overrides this with its own method, which is more specific. So the derivation carries container recursion alone, and never guesses how a matrix, a tensor or the centre a moment was taken about comes out of a fit.

Both channels end in one rebuild: a measure that carries both kinds of slot must not be rebuilt twice. resolve_calibration_slots states the calibration half and returns its resolved slots rather than a rebuilt object, and the two answers merge here. The deferred half merges last, so it wins a key both channels declare. A container names one child in both, and the child the recursion resolved is the one to keep.

slv is the effective solver, and the recursion threads it to every child. A container states no solver of its own, so it changes none: each child settles the one it was handed against the one it carries.

Algorithm

  1. Read the slots x declares with deferred_slots, giving slots.
  2. Read the resolved calibration slots with resolve_calibration_slots, giving calibrated.
  3. Return x unchanged when both are empty. A type with neither kind of slot needs no method of its own.
  4. Resolve every entry of slots with resolve_deferred_quantities, threading pr and slv to each, giving resolved. A child measure resolves through its own method, a vector of children through the vector method, and any other occupant comes back unchanged through this method, because it declares no slot: a stated value, nothing or a Deferred Quantity that the enclosing type resolves itself.
  5. Refuse a slot the recursion left unresolved with assert_declared_slot_resolver.
  6. Hand merge(calibrated, resolved) to rebuild_with_slots, which returns x itself when no entry moved and a rebuilt copy when one did.

Returns

  • x itself when no slot moved, and a rebuilt copy of x when one did.

Related

source
resolve_deferred_quantities(
    x::ValueatRiskRange,
    pr::AbstractPriorResult
) -> ValueatRiskRange
resolve_deferred_quantities(
    x::ValueatRiskRange,
    pr::AbstractPriorResult,
    slv
) -> ValueatRiskRange

Resolve the two significance levels of a ValueatRiskRange against prior result pr, and resolve the formulation alg beside them.

Each tail has its own slot and its own bound, so a rule for the loss tail and a rule for the gain tail resolve independently. beta defaults to alpha, so a rule stated for the loss tail alone reaches both tails. The rule states the method, and the slot states the tail. The rebuild goes through rebuild_with_slots, whose call to the inner constructor checks both levels again on the calibrated numbers.

This method is more specific than the derived recursion, so it takes over the alg slot that deferred_slots declares, and resolves it through resolve_deferred_quantities itself.

Algorithm

  1. Set ws to the observation weights of the measure, or to those of pr when the measure states none.
  2. Resolve alpha with resolve_calibration_slot, which gives the rule pr, ws and the solver slv.
  3. Resolve beta in the same way.
  4. Resolve alg with resolve_deferred_quantities.
  5. Rebuild the measure with the resolved alpha, beta and alg.

Related

source
PortfolioOptimisers.absolute_drawdown_vec — Function
absolute_drawdown_vec(x::VecNum) -> Vector

Compute the uncompounded drawdown series of one return series.

The function reads x and does not write it, so any AbstractVector works, for example a column view, a range or an immutable array.

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\,. \end{align}\]

Where:

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

The running peak starts at $c_0 = 0$, so each drawdown is relative to the initial portfolio value, not to the first observation.

Algorithm

  1. Allocate dd, of the same length and element type as x.
  2. Set the cumulative return cs and the running peak peak to zero.
  3. For each observation, add it to cs, raise peak to cs when cs is larger, and store cs - peak in dd.
  4. Return dd.

Arguments

  • x::VecNum: Return series.

Returns

  • dd: Drawdown series of the same length as x, with every entry $\leq 0$.

Related

source
PortfolioOptimisers.relative_drawdown_vec — Method
relative_drawdown_vec(x::VecNum) -> Vector

Compute the compounded drawdown series of one return series.

The function reads x and does not write it, so any AbstractVector works, for example a column view, a range or an immutable array.

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\,. \end{align}\]

Where:

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

The running peak starts at $C_0 = 1$, so each drawdown is relative to the initial portfolio value, not to the first observation.

Algorithm

  1. Allocate dd, of the same length and element type as x.
  2. Set the compounded wealth cp and the running peak peak to one.
  3. For each observation, multiply cp by one plus the return, raise peak to cp when cp is larger, and store cp / peak - 1 in dd.
  4. Return dd.

Arguments

  • x::VecNum: Return series.

Returns

  • dd: Relative drawdown series of the same length as x, with every entry $\leq 0$.

Related

source
PortfolioOptimisers.mip_var_bounds — Function
mip_var_bounds(b, s) -> Tuple

Resolve the cardinality slack s of the empirical quantile programme to a number, and pass the big-M constant b on.

A nothing slack takes the default, s = 1e-9. It exceeds the rounding error of $\alpha W_{T}$ and of a cumulative sum of up to about $10^{6}$ weights, and $s T$ stays below $10^{-3}$ up to $T = 10^{6}$, so it moves no order statistic on a sample of that size. The JuMP builder and the functor read the pair from this one function, so both select the same order statistic. The functor does not read b. A nothing constant stays nothing, and the JuMP builder derives it from the data and the weight bounds with mip_big_m.

Arguments

  • b: Big-M constant, or nothing.
  • s: Cardinality slack, or nothing.

Returns

  • (b, s): b as it is, and the stated s or its default.

Related

source
PortfolioOptimisers.empirical_value_at_risk — Function
empirical_value_at_risk(x::VecNum, alpha::Real, s::Real, ::Nothing) -> Number
empirical_value_at_risk(x::VecNum, alpha::Real, s::Real, w::VecNum) -> Number

Compute the empirical Value-at-Risk of a series, the negated order statistic that the mixed-integer quantile programme selects.

The four empirical measures of the family call this one kernel: ValueatRisk and ValueatRiskRange on the returns, DrawdownatRisk and RelativeDrawdownatRisk on a drawdown series. The method without weights reorders x in place, so a caller passes a copy or a vector that it has just computed.

Mathematical definition

\[\begin{align} \mathrm{VaR}_{\alpha}(\boldsymbol{x}) &= -x_{(k)}\,. \end{align}\]

Where:

  • $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 w is nothing.
  • $s$: Cardinality slack of the mixed-integer quantile programme, $s > 0$. It absorbs the rounding error of $\alpha W_{T}$.
  • $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
  • $T$: Number of observations.

Algorithm

Without observation weights:

  1. Set k to $\lfloor (\alpha + s) T \rfloor + 1$, clamped to the range from 1 to $T$.
  2. Partially sort x, so that its k smallest entries come first, in ascending order.
  3. Return minus the entry at k.

With observation weights:

  1. Sort x with sortperm, giving order, and accumulate the sorted weights, giving cum_w.
  2. Set k to one plus the last position at which cum_w does not exceed (alpha + s) times the total weight, and cap it at $T$.
  3. Return minus the k-th smallest entry of x.

Arguments

  • x::VecNum: Series, for example the portfolio returns or a drawdown series. The method without weights reorders it.
  • alpha::Real: Significance level, 0 < alpha < 1.
  • s::Real: Cardinality slack, from mip_var_bounds.
  • w: Observation weights from get_observation_weights, or nothing.

Returns

  • Number: The Value-at-Risk, positive when the order statistic is a loss.

Related

source