Relativistic X at Risk: private API

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::RelativisticValueatRisk,
    pr::AbstractPriorResult
) -> RelativisticValueatRisk
resolve_deferred_quantities(
    x::RelativisticValueatRisk,
    pr::AbstractPriorResult,
    slv
) -> RelativisticValueatRisk

Resolve the significance level alpha and the deformation parameter kappa of a RelativisticValueatRisk against prior result pr.

alpha and kappa are a Travelling Pair. A rule in the kappa slot, such as EntropyBudget, can read the significance level of the alpha slot, so alpha resolves first. A stated number, a plain function and a rule that reads no sibling ignore the context, so the order changes nothing for them.

Algorithm

  1. Select the observation weights ws with sel(x.w, pr.w).
  2. Select the solver sv with sel(x.slv, slv). Both rules receive it, so a rule can call RRM.
  3. Read the series marker s with calibration_series. The measure prices the returns, which is also the default of the context.
  4. Resolve the alpha slot, giving alpha.
  5. Resolve the kappa slot with a CalibrationContext that holds alpha and s, giving kappa.
  6. Rebuild the measure with rebuild_with_slots. Its positional call runs the inner constructor, which checks the range of both calibrated numbers again.

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::RelativisticValueatRiskRange,
    pr::AbstractPriorResult
) -> RelativisticValueatRiskRange
resolve_deferred_quantities(
    x::RelativisticValueatRiskRange,
    pr::AbstractPriorResult,
    slv
) -> RelativisticValueatRiskRange

Resolve the two significance levels and the two deformation parameters of a RelativisticValueatRiskRange against prior result pr.

Each end has its own Travelling Pair: kappa_a reads alpha, and kappa_b reads beta. The gain-side pair defaults to the loss-side pair, beta to alpha and kappa_b to kappa_a, so a pair stated on the loss side alone reaches both ends. Neither end reads the number of the other end. range_tails and the functor use the same pairing.

The four slots have four different bounds, so the constructor refuses a rule of the wrong end or of the wrong family. Both ends price the returns, so one series marker goes into the context of both kappa slots, while each end has its own significance level.

Algorithm

  1. Select the observation weights ws with sel(x.w, pr.w).
  2. Select the solver sv with sel(x.slv, slv). All four rules receive it.
  3. Read the series marker s with calibration_series.
  4. Resolve the alpha slot, giving alpha.
  5. Resolve the kappa_a slot with a CalibrationContext that holds alpha and s, giving kappa_a.
  6. Resolve the beta slot, giving beta.
  7. Resolve the kappa_b slot with a CalibrationContext that holds beta as its significance level and s, giving kappa_b.
  8. Rebuild the measure with rebuild_with_slots, which checks the range of all four calibrated numbers again.

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::RelativisticDrawdownatRisk,
    pr::AbstractPriorResult
) -> RelativisticDrawdownatRisk
resolve_deferred_quantities(
    x::RelativisticDrawdownatRisk,
    pr::AbstractPriorResult,
    slv
) -> RelativisticDrawdownatRisk

Resolve the significance level alpha and the deformation parameter kappa of a RelativisticDrawdownatRisk against prior result pr.

The order is the one that RelativisticValueatRisk uses: alpha resolves first, and it reaches the kappa slot in its CalibrationContext. The drawdown series has one entry per row of the sample, so a rule reads the same sample size as it does for the value-at-risk measure.

The series differs from that of RelativisticValueatRisk. This measure prices the absolute drawdown series of the portfolio, so calibration_series states AbsoluteDrawdownSeries, and the context carries that marker beside alpha. A rule that reads the shape of a series then reads the drawdown series of each column of the sample, not the columns, and alpha is the level of that drawdown series. The key :kappa names this slot and the slot of RelativisticValueatRisk alike, so the marker is the only thing that tells the rule which series it reads.

Algorithm

  1. Select the observation weights ws with sel(x.w, pr.w).
  2. Select the solver sv with sel(x.slv, slv).
  3. Read the series marker s, which is AbsoluteDrawdownSeries.
  4. Resolve the alpha slot, giving alpha.
  5. Resolve the kappa slot with a CalibrationContext that holds alpha and s, giving kappa.
  6. Rebuild the measure with rebuild_with_slots, which checks the range of both calibrated numbers again.

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::RelativeRelativisticDrawdownatRisk,
    pr::AbstractPriorResult
) -> RelativeRelativisticDrawdownatRisk
resolve_deferred_quantities(
    x::RelativeRelativisticDrawdownatRisk,
    pr::AbstractPriorResult,
    slv
) -> RelativeRelativisticDrawdownatRisk

Resolve the significance level alpha and the deformation parameter kappa of a RelativeRelativisticDrawdownatRisk against prior result pr.

The measure is hierarchical, so it reaches no JuMP model, and factory is the only route that resolves it. The Travelling Pair resolves in the order that RelativisticDrawdownatRisk uses.

This measure compounds the path, so calibration_series states RelativeDrawdownSeries, and the context carries that marker. The two drawdown measures name two different series of the same column, and a rule that reads the shape of a series gives a different answer on each.

Algorithm

  1. Select the observation weights ws with sel(x.w, pr.w).
  2. Select the solver sv with sel(x.slv, slv).
  3. Read the series marker s, which is RelativeDrawdownSeries.
  4. Resolve the alpha slot, giving alpha.
  5. Resolve the kappa slot with a CalibrationContext that holds alpha and s, giving kappa.
  6. Rebuild the measure with rebuild_with_slots, which checks the range of both calibrated numbers again.

Related

source
PortfolioOptimisers.RRM — Function
RRM(x::VecNum, slv::Option{<:Slv_VecSlv}, alpha::Number = 0.05, kappa::Number = 0.3,
    w::Option{<:ObsWeights} = nothing) -> Number

Compute the Relativistic Value-at-Risk of the returns x with a power-cone programme.

RelativisticValueatRisk states the measure, its Kaniadakis ball and its primal programme. Every call builds a new JuMP model. The primal and the dual programmes have the same optimal value, but a solver can stall on one of them and solve the other, so the dual programme is the fallback of the primal one.

Both models hold the variables and the rows of the observations of positive weight only. An observation of weight zero has $q_i = 0$ in the ball, so it does not change the optimum, but its rows make the programme harder to solve. The sample size $T$ still counts every observation.

Algorithm

  1. Check w against x with checked_observation_weights.
  2. Check that slv is a solver, and not empty when it is a vector, with checked_kernel_solver.
  3. Build and solve the primal programme, or the dual programme when no solver solves the primal one, with RRM_model.
  4. When a solver solves one of them, return its objective value. Otherwise, return NaN.

Arguments

  • x: Vector of portfolio returns.
  • slv: Solver or vector of solvers.
  • alpha: Significance level, $\alpha \in (0, 1)$.
  • kappa: Kaniadakis deformation parameter, $\kappa \in (0, 1)$.
  • w: Observation weights, or nothing for equal weights.

Validation

Returns

  • The Relativistic Value-at-Risk of x, or NaN when no solver of slv solves either programme.

Related

source
PortfolioOptimisers.RRM_worst_case — Function
RRM_worst_case(x::VecNum, slv::Option{<:Slv_VecSlv}, alpha::Number = 0.05, kappa::Number = 0.3,
               w::Option{<:ObsWeights} = nothing) -> Option{<:VecNum}

Compute the Worst-Case Distribution of the Relativistic Value-at-Risk of the returns x, from the programmes of RRM_model.

The Relativistic Value-at-Risk is the largest expected loss over a Kaniadakis ball, and the Worst-Case Distribution $\boldsymbol{q}$ is the distribution in the ball that reaches it. So the expected loss under $\boldsymbol{q}$ equals the value of RRM, to the tolerance of the solver, and $-\boldsymbol{q}$ is the gradient of that value with respect to x. risk_contribution and risk_gradient read it through worst_case_distribution. RRM does not compute it, so a call of expected_risk does not pay for it.

Algorithm

  1. Check w against x with checked_observation_weights.
  2. Check that slv is a solver, and not empty when it is a vector, with checked_kernel_solver.
  3. Build and solve the programmes with RRM_model. When no solver solves it, return nothing.
  4. When the solved model is the primal one, negate the dual of each row of rrm_loss. When the solver gives no dual, return nothing.
  5. When the solved model is the dual one, take the value of its variable z.
  6. Expand the result to T entries with expand_positive_weight_rows.

Arguments

  • x: Vector of portfolio returns.
  • slv: Solver or vector of solvers.
  • alpha: Significance level, $\alpha \in (0, 1)$.
  • kappa: Kaniadakis deformation parameter, $\kappa \in (0, 1)$.
  • w: Observation weights, or nothing for equal weights.

Validation

Returns

  • q::VecNum: The Worst-Case Distribution, one entry for each observation. An observation of weight zero has the entry zero.
  • nothing: When no solver of slv solves either programme, or the solver of the primal programme gives no dual.

Related

source
PortfolioOptimisers.RRM_model — Function
RRM_model(x::VecNum, slv::Slv_VecSlv, alpha::Number, kappa::Number,
          w::Option{<:VecNum}) -> Option{<:Tuple{JuMP.Model, Bool}}

Build the primal programme below in a new model and solve it, and build and solve the dual programme when no solver solves the primal one.

RRM reads the objective value of the solved model, and RRM_worst_case reads the Worst-Case Distribution from it. The callers check w and slv first.

Algorithm

  1. Find rows, the indices of the observations of positive weight, and N, their number. Without w, rows holds every observation.
  2. When w is stated, divide its entries in rows by the sum of w, giving wi.
  3. Compute ln_k, the Kaniadakis logarithm of $1/(\alpha T)$.
  4. Build the primal programme in a new model, and solve it with the solvers of slv in turn. When a solver solves it, return the model with primal = true.
  5. Otherwise, build the dual programme in a new model, and solve it with the solvers of slv in turn. When a solver solves it, return the model with primal = false.
  6. Otherwise, return nothing.

JuMP formulation

Variables

The primal model creates these variables:

  • t: free scalar $t$.
  • z: scalar $z$, bounded below by zero.
  • omega, psi, theta, epsilon: free $N \times 1$ vectors $\boldsymbol{\omega}$, $\boldsymbol{\psi}$, $\boldsymbol{\theta}$ and $\boldsymbol{\epsilon}$, with one entry for each observation in $\mathcal{I}$.

The dual model creates these variables:

  • z, nu, tau: free $N \times 1$ vectors $\boldsymbol{q}$, $\boldsymbol{\nu}$ and $\boldsymbol{\tau}$, with one entry for each observation in $\mathcal{I}$.

Expressions

  • risk, in the primal model: $t + \ln_{\kappa}\!\left(\tfrac{1}{\alpha T}\right) z + T \sum_{i \in \mathcal{I}} p_i (\psi_i + \theta_i)$.
  • risk, in the dual model: $-\sum_{i \in \mathcal{I}} q_i x_i$.

Constraints

No row carries a string name. The primal model registers these rows:

  • $\left(\tfrac{z(1+\kappa)}{2\kappa},\, \tfrac{\psi_i(1+\kappa)}{\kappa},\, \epsilon_i\right) \in \mathcal{K}_{\mathrm{pow}}\!\left(\tfrac{1}{1+\kappa}\right)$, one row for each $i \in \mathcal{I}$.
  • $\left(\tfrac{\omega_i}{1-\kappa},\, \tfrac{\theta_i}{\kappa},\, -\tfrac{z}{2\kappa}\right) \in \mathcal{K}_{\mathrm{pow}}(1-\kappa)$, one row for each $i \in \mathcal{I}$.
  • rrm_loss: $\epsilon_i + \omega_i - x_i - t \leq 0$, one row for each $i \in \mathcal{I}$.

The dual model registers these rows:

  • $\sum_{i \in \mathcal{I}} q_i - 1 = 0$.
  • $\tfrac{1}{2\kappa} \sum_{i \in \mathcal{I}} (\nu_i - \tau_i) - \ln_{\kappa}\!\left(\tfrac{1}{\alpha T}\right) \leq 0$.
  • $(\nu_i,\, T p_i,\, q_i) \in \mathcal{K}_{\mathrm{pow}}\!\left(\tfrac{1}{1+\kappa}\right)$, one row for each $i \in \mathcal{I}$.
  • $(q_i,\, T p_i,\, \tau_i) \in \mathcal{K}_{\mathrm{pow}}(1-\kappa)$, one row for each $i \in \mathcal{I}$.

The two power-cone rows of the dual model give $\nu_i \geq q_i^{1+\kappa} (T p_i)^{-\kappa}$ and $\tau_i \leq q_i^{1-\kappa} (T p_i)^{\kappa}$. So the second row is the Kaniadakis ball of RelativisticValueatRisk, $\sum_{i} q_i \ln_{\kappa}\!\left(\tfrac{q_i}{p_i T}\right) \leq \ln_{\kappa}\!\left(\tfrac{1}{\alpha T}\right)$.

At the optimum, $\boldsymbol{q}$ is the Worst-Case Distribution of the ball. The dual of the row of observation $i$ in rrm_loss of the primal model is $-q_i$. RRM_worst_case reads it from the model that a solver solves.

Objective

  • The primal model minimises risk, and the dual model maximises risk. The two optimal values are equal.

Where:

  • $\boldsymbol{x}$: Portfolio returns vector $T \times 1$.
  • $T$: Number of observations.
  • $\alpha$: Significance level (left tail probability), $\alpha \in (0, 1)$.
  • $\kappa$: Kaniadakis deformation parameter, $\kappa \in (0, 1)$.
  • $\ln_{\kappa}(u) = \dfrac{u^{\kappa} - u^{-\kappa}}{2 \kappa}$: Kaniadakis logarithm.
  • $p_i$: Probability of observation $i$. It is $1/T$ without observation weights, and the $i$-th observation weight divided by the sum of the weights with them.
  • $\mathcal{I}$: Set of the observations of positive weight. Without observation weights, it holds all $T$ observations.
  • $t$: Shift variable of the primal programme.
  • $z \geq 0$: Scale variable of the primal power-cone programme.
  • $\psi_i$, $\theta_i$, $\epsilon_i$, $\omega_i$: Auxiliary variables of observation $i$ in the primal power-cone programme.
  • $\boldsymbol{q}$: $N \times 1$ probability vector of the dual programme, whose entry for observation $i$ is $q_i$.
  • $\nu_i$, $\tau_i$: Auxiliary variables of observation $i$ in the dual programme.
  • $\mathcal{K}_{\mathrm{pow}}(p) = \{(a,b,c) : a^{p} b^{1-p} \geq |c|,\, a \geq 0,\, b \geq 0\}$: Power cone.

Arguments

  • x: Vector of portfolio returns.
  • slv: Solver or vector of solvers.
  • alpha: Significance level, $\alpha \in (0, 1)$.
  • kappa: Kaniadakis deformation parameter, $\kappa \in (0, 1)$.
  • w: Checked observation weights, or nothing for equal weights.

Returns

  • (model, primal): The solved model, and whether it holds the primal programme, as a plain tuple that each caller takes apart at once.
  • nothing: When no solver of slv solves either programme.

Related

source