Variance: private API
PortfolioOptimisers.NSkeQuadFormulations — Type
const NSkeQuadFormulations = Union{QuadRiskExpr, SquaredSOCRiskExpr}Groups the two encodings under which NegativeSkewness reports the quadratic form of its skewness matrix rather than its square root.
The functor of NegativeSkewness dispatches on the group. It returns $\boldsymbol{w}^\intercal \mathbf{V} \boldsymbol{w}$, with $\mathbf{V}$ the field V of the measure, under these two encodings, and the square root under SOCRiskExpr, so the functor reports the units of the model.
Related
PortfolioOptimisers.QuadSecondMomentFormulations — Type
const QuadSecondMomentFormulations = Union{NSkeQuadFormulations, RSOCRiskExpr}Groups the three encodings that report the second moment itself rather than its square root.
The value level of SecondMoment dispatches on the group. It returns the variance of the deviations under these three encodings, and the standard deviation under SOCRiskExpr, so the functor reports the units of the model.
Related
PortfolioOptimisers.SecondMomentFormulation — Type
abstract type SecondMomentFormulation <: AbstractAlgorithmAbstract supertype for the JuMP encodings of a second moment.
A second-moment risk measure gives the encoding a deviation vector and a correction factor, and the encoding selects the quadratic form or the cone that holds the sum of squares. SOCRiskExpr reports the square root of the second moment, and the other three encodings report the second moment itself. The functor of the measure reports the units of its model, and the measure reads a bound in settings.ub in the same units.
The encoding sets the risk expression alone. Every consumer also adds a second-order cone variable that bounds the square root of the second moment. The bound in settings.ub and the MaximumRatio objective act on that variable, because each needs an expression of degree one in the weights. The cone encodings bound the sum of squares from above, so they are tight when the objective minimises the risk or when a bound holds it.
All concrete types implementing a second-moment JuMP encoding should subtype SecondMomentFormulation.
Related
PortfolioOptimisers.VarianceFormulation — Type
abstract type VarianceFormulation <: SecondMomentFormulationAbstract supertype for the second-moment encodings that state the risk as an explicit square.
Variance accepts these two and no others. Both report the variance itself. QuadRiskExpr states it as a quadratic form in the weights, and SquaredSOCRiskExpr states it as the square of a second-order cone variable.
Related
PortfolioOptimisers.assert_lift_corner — Function
assert_lift_corner(corner::Option{<:Number})Check the corner of a variance that states its objective term on a lifted weight matrix.
nothing asks the model to derive the corner, so it passes. A number is the constant corner of SquareRootRatio. It must be finite and above zero, because the bordered matrix of the lift then states $c\,\mathbf{W}_c \succeq \boldsymbol{y}\boldsymbol{y}^\intercal$. A corner of zero forces $\boldsymbol{y} = \mathbf{0}$.
Validation
- If
corneris a number:isfinite(corner)andcorner > 0. Otherwise the function raises aDomainError.
Returns
nothing.
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(
r::Variance,
pr::AbstractPriorResult
) -> Variance
resolve_deferred_quantities(
r::Variance,
pr::AbstractPriorResult,
) -> Variance
Resolve a Deferred Quantity in the sigma slot of a Variance against prior result pr.
sigma and chol are one pair, so both come from the same fit. The method never meets a stated chol, because assert_derived_slot_has_source refuses one beside a deferred sigma at construction. A covariance estimator gives no factorisation, so chol becomes nothing and the model derives it from the resolved sigma. A prior estimator gives both, so the sparse factorisation of a factor prior reaches the slot unchanged. A measure whose sigma is not a Deferred Quantity returns unchanged.
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(
r::StandardDeviation,
pr::AbstractPriorResult
) -> StandardDeviation
resolve_deferred_quantities(
r::StandardDeviation,
pr::AbstractPriorResult,
) -> StandardDeviation
Resolve a Deferred Quantity in the sigma slot of a StandardDeviation against prior result pr.
sigma and chol come from the same fit, by the rule that resolve_deferred_quantities(r::Variance, pr::AbstractPriorResult) states. A measure whose sigma is not a Deferred Quantity returns unchanged.
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(
r::UncertaintySetVariance,
pr::AbstractPriorResult
) -> UncertaintySetVariance
resolve_deferred_quantities(
r::UncertaintySetVariance,
pr::AbstractPriorResult,
) -> UncertaintySetVariance
Resolve a Deferred Quantity in the sigma slot of an UncertaintySetVariance against prior result pr.
The measure has one slot that the prior supplies, and no derived slot, so resolve_slot fills sigma alone. A measure whose sigma is not a Deferred Quantity returns unchanged.
Related
PortfolioOptimisers.ucs_risk_measure — Function
ucs_risk_measure(r, rd::ReturnsResult)Fit the uncertainty set of an UncertaintySetVariance on the returns data rd, so that the set becomes an AbstractUncertaintySetResult.
near_optimal_centering_setup calls it once, so that the risk targets of the barrier, the sub-problem solves and the model of NearOptimalCentering read one fitted set. The functor of a measure with a fitted set gives ucs_variance, so the targets agree with the risk expression of the model.
Three inputs return unchanged. A measure of another type returns unchanged. A set that is already a result passes through sigma_ucs unchanged. An estimator that reads a prior result, one for which reads_prior_result is true, returns unchanged too. Such an estimator is an AbstractPriorUncertaintySetEstimator, or an estimator of returns data with pe = nothing. It is fitted on the prior of the optimisation, and no prior exists when this method runs, so each solve fits it later from its own prior. A vector of measures is fitted element by element.
The set reads the returns of rd under the source that its own pe states, see sigma_ucs. A set whose prior states x_src = ExcessSource() fits on X - B, whatever the source of the prior of the optimiser is.
Related
PortfolioOptimisers.ucs_variance — Function
ucs_variance(ucs::AbstractUncertaintySetResult, sigma::MatNum, w::VecNum,
mtx_sqrt::Option{<:AbstractMatrixSquareRootAlgorithm} = EigenFallbackSquareRoot())Compute the worst-case portfolio variance of the weights w over a fitted uncertainty set.
It is the value level of the risk expression that set_ucs_variance_risk! builds, at $\mathbf{W} = \boldsymbol{w} \boldsymbol{w}^\intercal$. The functor of UncertaintySetVariance calls it when ucs holds a fitted set. The compact value equals the optimum of the model expression. The box value fixes $\mathbf{W} = \boldsymbol{w} \boldsymbol{w}^\intercal$, which the model lets rise in the order of positive semidefinite matrices, and the ellipsoid and the norm-ball values take the dual matrix $\mathbf{E} = 0$, so each lies at or above the optimum of its model expression.
Mathematical definition
\[\begin{align} R_{\mathrm{box}}(\boldsymbol{w}) &= \langle \mathbf{\Sigma}_u, (\boldsymbol{w} \boldsymbol{w}^\intercal)_{+} \rangle - \langle \mathbf{\Sigma}_l, (-\boldsymbol{w} \boldsymbol{w}^\intercal)_{+} \rangle\,,\\ R_{\mathrm{ell}}(\boldsymbol{w}) &= \boldsymbol{w}^\intercal \hat{\mathbf{\Sigma}} \boldsymbol{w} + k_{e} \lVert \mathbf{G}_{\Omega} \, \mathrm{vec}(\boldsymbol{w} \boldsymbol{w}^\intercal) \rVert_{2}\,,\\ R_{\mathrm{nb}}(\boldsymbol{w}) &= \boldsymbol{w}^\intercal \hat{\mathbf{\Sigma}} \boldsymbol{w} + \kappa_{b} \lVert \mathbf{L}^\intercal \mathrm{vec}(\boldsymbol{w} \boldsymbol{w}^\intercal) \rVert_{p^{*}}\,,\\ R_{\mathrm{cpt}}(\boldsymbol{w}) &= \boldsymbol{w}^\intercal \hat{\mathbf{\Sigma}} \boldsymbol{w} + \kappa \underset{\boldsymbol{z}}{\min} \left( \lVert \mathbf{C} \boldsymbol{w} - \mathbf{Q} \boldsymbol{z} \rVert_{2}^{2} + \lVert \mathbf{R} \boldsymbol{z} \rVert_{2}^{2} \right)\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $R_{\mathrm{box}}$, $R_{\mathrm{ell}}$, $R_{\mathrm{nb}}$, $R_{\mathrm{cpt}}$: Value for a
BoxUncertaintySet, anEllipsoidalUncertaintySet, a covarianceNormBallUncertaintySetand aCompactCovarianceUncertaintySet. - $\mathbf{\Sigma}_l$, $\mathbf{\Sigma}_u$: Lower and upper bounds of the box,
lbandub. - $(\cdot)_{+}$: Positive part, entry by entry.
- $\hat{\mathbf{\Sigma}}$: Centre of the set, the
valof the set when it states one andsigmaotherwise. - $k_{e}$, $\mathbf{G}_{\Omega}$: Radius of the ellipsoid,
k, and the transpose of the square root of its matrix $\mathbf{\Omega}$,sigma, thatmatrix_square_roottakes undermtx_sqrt, so $\mathbf{G}_{\Omega}^\intercal \mathbf{G}_{\Omega} = \mathbf{\Omega}$. - $\kappa_{b}$, $\mathbf{L}$, $p^{*}$: Radius of the norm ball, its map, and the dual order of its norm. A map with no column adds nothing.
- $\mathbf{C}$, $\mathbf{Q}$, $\mathbf{R}$, $\boldsymbol{z}$: Diagonal metric of the compact set, its basis, the factor of the rows a view dropped from the basis, and the free coefficients of the basis. A fitted set has no row in $\mathbf{R}$. A basis with no column leaves $\lVert \mathbf{C} \boldsymbol{w} \rVert_{2}^{2}$.
- $\kappa \geq 0$: Radius of the compact covariance set, the multiplier of its penalty.
- $\langle \mathbf{X}, \mathbf{Y} \rangle = \mathrm{Tr}(\mathbf{X}^\intercal \mathbf{Y})$: Inner product of two matrices.
The least-squares problem of the compact line projects onto the span of $\mathbf{Q}$ whether or not the columns of $\mathbf{Q}$ are orthonormal.
Arguments
ucs: Fitted uncertainty set.sigma::MatNum: Fallback centre of the set. Thevalof the set wins over it, and the box reads neither.w::VecNum: Asset weights.mtx_sqrt: Square-root algorithm of the matrix of an ellipsoid, ornothingfor the plain Cholesky factor. The other sets ignore it, because the value level of the compact set takes no square root.
Validation
- Ellipsoid:
ucs.sigmahas a square root undermtx_sqrt, asmatrix_square_rootstates. Raises aLinearAlgebra.PosDefException.
Returns
risk::Number: Worst-case portfolio variance.
Related
UncertaintySetVarianceBoxUncertaintySetEllipsoidalUncertaintySetNormBallUncertaintySetCompactCovarianceUncertaintySetset_ucs_variance_risk!: The model expression, whose optimum is at or below this value.
PortfolioOptimisers.reader_frames — Method
reader_frames(r::UncertaintySetVariance, path::AbstractString, refit::Bool)Return the frames that the uncertainty set of an UncertaintySetVariance adds to the group of the optimiser that holds the measure.
The measure holds its reader in ucs, so the walk passes through to the set at the path "<path>.ucs", and the set passes through to its own prior. A built set, nothing and a set that reads the Prior Result add no frames.
Arguments
r: The risk measure.path: The path of the value from the head, for example"pe","cle"or"r[2].pe". A warning names a reader by its path.refit:truewhen a regression reader atx_src = nothingin the group fits its regression on the raw returns data.refits_regressionfinds the value.
Returns
fr::ReturnsFrames: The frames of the uncertainty set of the measure.
Related