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
- Read the slots
xdeclares withdeferred_slots, givingslots. - Read the resolved calibration slots with
resolve_calibration_slots, givingcalibrated. - Return
xunchanged when both are empty. A type with neither kind of slot needs no method of its own. - Resolve every entry of
slotswithresolve_deferred_quantities, threadingprandslvto each, givingresolved. 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,nothingor a Deferred Quantity that the enclosing type resolves itself. - Refuse a slot the recursion left unresolved with
assert_declared_slot_resolver. - Hand
merge(calibrated, resolved)torebuild_with_slots, which returnsxitself when no entry moved and a rebuilt copy when one did.
Returns
xitself when no slot moved, and a rebuilt copy ofxwhen one did.
Related
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
- Select the observation weights
wswithsel(x.w, pr.w). - Select the solver
svwithsel(x.slv, slv). Both rules receive it, so a rule can callRRM. - Read the series marker
swithcalibration_series. The measure prices the returns, which is also the default of the context. - Resolve the
alphaslot, givingalpha. - Resolve the
kappaslot with aCalibrationContextthat holdsalphaands, givingkappa. - Rebuild the measure with
rebuild_with_slots. Its positional call runs the inner constructor, which checks the range of both calibrated numbers again.
Related
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
- Read the slots
xdeclares withdeferred_slots, givingslots. - Read the resolved calibration slots with
resolve_calibration_slots, givingcalibrated. - Return
xunchanged when both are empty. A type with neither kind of slot needs no method of its own. - Resolve every entry of
slotswithresolve_deferred_quantities, threadingprandslvto each, givingresolved. 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,nothingor a Deferred Quantity that the enclosing type resolves itself. - Refuse a slot the recursion left unresolved with
assert_declared_slot_resolver. - Hand
merge(calibrated, resolved)torebuild_with_slots, which returnsxitself when no entry moved and a rebuilt copy when one did.
Returns
xitself when no slot moved, and a rebuilt copy ofxwhen one did.
Related
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
- Select the observation weights
wswithsel(x.w, pr.w). - Select the solver
svwithsel(x.slv, slv). All four rules receive it. - Read the series marker
swithcalibration_series. - Resolve the
alphaslot, givingalpha. - Resolve the
kappa_aslot with aCalibrationContextthat holdsalphaands, givingkappa_a. - Resolve the
betaslot, givingbeta. - Resolve the
kappa_bslot with aCalibrationContextthat holdsbetaas its significance level ands, givingkappa_b. - Rebuild the measure with
rebuild_with_slots, which checks the range of all four calibrated numbers again.
Related
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
- Read the slots
xdeclares withdeferred_slots, givingslots. - Read the resolved calibration slots with
resolve_calibration_slots, givingcalibrated. - Return
xunchanged when both are empty. A type with neither kind of slot needs no method of its own. - Resolve every entry of
slotswithresolve_deferred_quantities, threadingprandslvto each, givingresolved. 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,nothingor a Deferred Quantity that the enclosing type resolves itself. - Refuse a slot the recursion left unresolved with
assert_declared_slot_resolver. - Hand
merge(calibrated, resolved)torebuild_with_slots, which returnsxitself when no entry moved and a rebuilt copy when one did.
Returns
xitself when no slot moved, and a rebuilt copy ofxwhen one did.
Related
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
- Select the observation weights
wswithsel(x.w, pr.w). - Select the solver
svwithsel(x.slv, slv). - Read the series marker
s, which isAbsoluteDrawdownSeries. - Resolve the
alphaslot, givingalpha. - Resolve the
kappaslot with aCalibrationContextthat holdsalphaands, givingkappa. - Rebuild the measure with
rebuild_with_slots, which checks the range of both calibrated numbers again.
Related
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
- Read the slots
xdeclares withdeferred_slots, givingslots. - Read the resolved calibration slots with
resolve_calibration_slots, givingcalibrated. - Return
xunchanged when both are empty. A type with neither kind of slot needs no method of its own. - Resolve every entry of
slotswithresolve_deferred_quantities, threadingprandslvto each, givingresolved. 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,nothingor a Deferred Quantity that the enclosing type resolves itself. - Refuse a slot the recursion left unresolved with
assert_declared_slot_resolver. - Hand
merge(calibrated, resolved)torebuild_with_slots, which returnsxitself when no entry moved and a rebuilt copy when one did.
Returns
xitself when no slot moved, and a rebuilt copy ofxwhen one did.
Related
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
- Select the observation weights
wswithsel(x.w, pr.w). - Select the solver
svwithsel(x.slv, slv). - Read the series marker
s, which isRelativeDrawdownSeries. - Resolve the
alphaslot, givingalpha. - Resolve the
kappaslot with aCalibrationContextthat holdsalphaands, givingkappa. - Rebuild the measure with
rebuild_with_slots, which checks the range of both calibrated numbers again.
Related
PortfolioOptimisers.RRM — Function
RRM(x::VecNum, slv::Option{<:Slv_VecSlv}, alpha::Number = 0.05, kappa::Number = 0.3,
w::Option{<:ObsWeights} = nothing) -> NumberCompute 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
- Check
wagainstxwithchecked_observation_weights. - Check that
slvis a solver, and not empty when it is a vector, withchecked_kernel_solver. - Build and solve the primal programme, or the dual programme when no solver solves the primal one, with
RRM_model. - 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, ornothingfor equal weights.
Validation
wpasseschecked_observation_weightsagainstx. Otherwise that function raises its error.slvis notnothing, elseIsNothingError, and ifslvis aVecSlv:!isempty(slv), elseIsEmptyError. Seechecked_kernel_solver.
Returns
- The Relativistic Value-at-Risk of
x, orNaNwhen no solver ofslvsolves either programme.
Related
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
- Check
wagainstxwithchecked_observation_weights. - Check that
slvis a solver, and not empty when it is a vector, withchecked_kernel_solver. - Build and solve the programmes with
RRM_model. When no solver solves it, returnnothing. - When the solved model is the primal one, negate the dual of each row of
rrm_loss. When the solver gives no dual, returnnothing. - When the solved model is the dual one, take the value of its variable
z. - Expand the result to
Tentries withexpand_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, ornothingfor equal weights.
Validation
wpasseschecked_observation_weightsagainstx. Otherwise that function raises its error.slvis notnothing, elseIsNothingError, and ifslvis aVecSlv:!isempty(slv), elseIsEmptyError. Seechecked_kernel_solver.
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 ofslvsolves either programme, or the solver of the primal programme gives no dual.
Related
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
- Find
rows, the indices of the observations of positive weight, andN, their number. Withoutw,rowsholds every observation. - When
wis stated, divide its entries inrowsby the sum ofw, givingwi. - Compute
ln_k, the Kaniadakis logarithm of $1/(\alpha T)$. - Build the primal programme in a new model, and solve it with the solvers of
slvin turn. When a solver solves it, return the model withprimal = true. - Otherwise, build the dual programme in a new model, and solve it with the solvers of
slvin turn. When a solver solves it, return the model withprimal = false. - 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 maximisesrisk. 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, ornothingfor 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 ofslvsolves either programme.
Related