Norm-Ball Uncertainty Sets: private API
PortfolioOptimisers.assert_norm_ball_axis — Function
assert_norm_ball_axis(::MuUncertaintySetClass, L::MatNum)
assert_norm_ball_axis(::SigmaUncertaintySetClass, L::MatNum)Check that the rows of L fit the axis the tag names.
The method is a refusal rather than a procedure, so it carries no # Algorithm section. The mean tag accepts any row count, and the covariance tag needs a perfect square, because a set on that axis bounds a vectorised $N \times N$ covariance and port_opt_view recovers $N$ from the row count.
Arguments
class: Axis tag.L: Geometry map.
Validation
- On the covariance tag,
isqrt(size(L, 1))^2 == size(L, 1), else aDimensionMismatch.
Returns
nothing.
Related
PortfolioOptimisers.assert_norm_ball_val — Function
assert_norm_ball_val(::MuUncertaintySetClass, val::ArrNum)
assert_norm_ball_val(::SigmaUncertaintySetClass, val::ArrNum)Check the shape of the carried centre against the axis the tag names.
The method is a refusal rather than a procedure, so it carries no # Algorithm section. The constructor has already matched length(val) to the rows of L, so the mean tag has nothing left to check, and the covariance tag checks that the centre is a square matrix.
Arguments
class: Axis tag.val: Carried centre.
Validation
- On the covariance tag,
valis a matrix andsize(val, 1) == size(val, 2), else aDimensionMismatch.
Returns
nothing.
Related
PortfolioOptimisers.dual_norm_order — Function
dual_norm_order(p::Number) -> Any
Return the dual norm order q of the norm order p, with 1 / p + 1 / q == 1.
Algorithm
- When
pis infinite, returnone(p), because the dual of the infinity norm is the one norm. - Otherwise return
p / (p - 1). Atp = 1the division is by zero and returnsInf, the dual of the one norm, and atp = 2it returns2, which is its own dual.
Arguments
p::Number: Norm order,p >= 1.
Returns
q::Number: Dual norm order.
Related
PortfolioOptimisers.norm_ball_factor — Function
norm_ball_factor(
diagonal::Bool,
cov::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
) -> Any
norm_ball_factor(
diagonal::Bool,
cov::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
mtx_sqrt::Union{Nothing, AbstractMatrixSquareRootAlgorithm}
) -> Any
Factorise an asymptotic covariance into the geometry map of a NormBallUncertaintySet.
The map is square. It is of full column rank when cov reaches this method repaired to positive definiteness, which the pdm of the estimator does. Full rank does not make size(L, 2) the dimension of the set: on a full covariance shape the repair adds $N(N-1)/2$ flat directions that no error fills, so a caller reads its degrees of freedom from ucs_dimension. Its sibling norm_ball_deviation_factor builds the map from a sample instead, and factorises nothing.
Algorithm
- When
diagonalistrue, returnLinearAlgebra.Diagonal(sqrt.(LinearAlgebra.diag(cov))), the square root of the diagonal shape. The result is stored as aDiagonal, not as a dense matrix. ANormalUncertaintySethands it a diagonal shape already, built under itsdcbydiagonal_sigma_shape, so the diagonal is the one that rule states. - Otherwise return
matrix_square_root(mtx_sqrt, cov), which satisfies $\mathbf{L}\mathbf{L}^{\intercal} = \mathbf{S}$ and is the map the converter constructor ofNormBallUncertaintySetbuilds.
Arguments
diagonal: Whether to discard the off-diagonal entries ofcovbefore the factorisation.cov: Asymptotic covariance of the statistic.mtx_sqrt: Square-root algorithm ofcov, themtx_sqrtof theNormBallUncertaintySetAlgorithm, ornothingfor the plain Cholesky factor.
Validation
- When
diagonalisfalse,covhas a square root undermtx_sqrt, asmatrix_square_rootstates. Raises aLinearAlgebra.PosDefException. The asymptotic covariance of a covariance, $T (\mathbf{I} + \mathbf{K}) (\mathbf{\Sigma}_{\mu} \otimes \mathbf{\Sigma}_{\mu})$, has rank $N(N+1)/2$ of $N^{2}$, so withpdm = nothingthe plain Cholesky factor refuses it, and the default eigen square root reads it.
Returns
L::MatNum: Geometry map, square.
Related
PortfolioOptimisers.norm_ball_deviation_factor — Function
norm_ball_deviation_factor(
diagonal::Bool,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
) -> Any
Build the geometry map of a NormBallUncertaintySet from a sample of estimation errors, without forming their covariance.
The map is the sample itself, scaled. It satisfies $\mathbf{L}\mathbf{L}^{\intercal} = \operatorname{Cov}(\mathbf{X})$ exactly, so the set is the one the sample covariance names, and no square matrix of side $N^{2}$ is built and no positive definite repair is applied. Its rank is at most $M - 1$, because the sample is centred, so a caller measures the degrees of freedom with LinearAlgebra.rank rather than reading size(L, 2). Its sibling norm_ball_factor factorises an already-built covariance instead.
Mathematical definition
\[\mathbf{L} = \dfrac{\left(\mathbf{X} - \boldsymbol{1}\bar{\mathbf{x}}^{\intercal}\right)^{\intercal}}{\sqrt{M - 1}}\,, \qquad \mathbf{L}\mathbf{L}^{\intercal} = \operatorname{Cov}(\mathbf{X})\,.\]
Where:
- $\mathbf{L}$: Geometry map, $m \times M$.
- $\mathbf{X}$: Sample of estimation errors, $M \times m$, one row per simulation.
- $\bar{\mathbf{x}}$: Column means of $\mathbf{X}$.
- $M$: Number of simulations.
- $m$: Number of entries of the statistic, $N$ on the mean axis and $N^{2}$ on the covariance axis.
Algorithm
- When
diagonalistrue, returnLinearAlgebra.Diagonal(sqrt.(vec(Statistics.var(X; dims = 1)))), the square root of the entrywise variances. It is $m \times m$ and of full rank. - Otherwise subtract the column means from
X, transpose the result, and divide bysqrt(size(X, 1) - 1). The map needs at least two rows, because a sample of one row divides by zero.ARCHUncertaintySetrefusesn_sim < 2for a norm ball when it is built, so its resample always has two rows.
Arguments
diagonal: Whether to keep only the entrywise variances.X: Sample of estimation errors, one row per simulation.
Returns
L::MatNum: Geometry map, $m \times M$ underdiagonal = falseand $m \times m$ underdiagonal = true.
Related
PortfolioOptimisers.norm_ball_coordinates — Function
norm_ball_coordinates(L::Union{LinearAlgebra.LowerTriangular, LinearAlgebra.UpperTriangular}, X::MatNum)
norm_ball_coordinates(L::LinearAlgebra.Diagonal, X::MatNum)
norm_ball_coordinates(L::MatNum, X::MatNum)Ball coordinates of each sampled error under the pseudo-inverse of a geometry map, one column per error.
Only a map that can be singular pays for a rank decision. A triangular map is a Cholesky factor, and the factorisation that made it found the shape positive definite, so a triangular solve is the pseudo-inverse. A map that is not square is the deviation map of norm_ball_deviation_factor, and Julia solves it with a column-pivoted QR that returns the minimum-norm solution. A square dense map is the eigen square root of EigenFallbackSquareRoot, which the library takes only when the shape has no Cholesky factor, or a square deviation map, whose rank is at most size(L, 1) - 1. A dense square map from a square-root algorithm of the caller takes the same route. On such a map Julia's \ takes an LU factorisation, which raises a LinearAlgebra.SingularException on a zero pivot and divides by a pivot of round-off size. So this method takes the singular value decomposition and drops each direction whose squared singular value is round-off.
Algorithm
- On a triangular map, and on a map that is not square, return
L \ transpose(X). - On a diagonal map with no zero entry, return
L \ transpose(X). Otherwise divide each row oftranspose(X)by its entry, and give a zero coordinate where the entry is zero, which is the pseudo-inverse of a diagonal map. - On any other square map, take the singular value decomposition $\mathbf{L} = \mathbf{U}\mathbf{S}\mathbf{V}^{\intercal}$. Keep the $r$ singular values $s_{i}$ with $s_{i}^{2} > m \epsilon s_{1}^{2}$, where $m$ is
size(L, 1)and $\epsilon$ is the machine epsilon of the singular values. The squares $s_{i}^{2}$ are the eigenvalues of $\mathbf{L}\mathbf{L}^{\intercal}$, so this is the tolerance under whichmatrix_square_rootreads a negative eigenvalue ofEigenFallbackSquareRootas round-off of zero. - Return $\mathbf{S}_{r}^{-1}\mathbf{U}_{r}^{\intercal}\mathbf{X}^{\intercal}$. A column is $\mathbf{L}^{+}\mathbf{x}$ written in the first $r$ right singular vectors, so it has the norm of $\mathbf{L}^{+}\mathbf{x}$ and $r$ entries. The squared column norms are $\mathbf{x}^{\intercal}\left(\mathbf{L}\mathbf{L}^{\intercal}\right)^{+}\mathbf{x}$ under that cut. A zero map keeps no direction, and every coordinate column is empty.
Arguments
L: Geometry map.X: Sample of estimation errors, one row per simulation.
Returns
Z::MatNum: Ball coordinates, one column per row ofX. Under step 3 it has $r$ rows.
Related
PortfolioOptimisers.norm_ball_set — Function
norm_ball_set(
alg::NormBallUncertaintySetAlgorithm,
q::Number,
samples,
cov::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
class::AbstractUncertaintySetClass
) -> Union{NormBallUncertaintySet{var"#s185", <:AbstractMatrix{var"#s166"}, <:Number, MuUncertaintySetClass, Nothing} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}}, NormBallUncertaintySet{var"#s185", <:AbstractMatrix{var"#s166"}, <:Number, SigmaUncertaintySetClass, Nothing} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}}}
norm_ball_set(
alg::NormBallUncertaintySetAlgorithm,
q::Number,
samples,
cov::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
class::AbstractUncertaintySetClass,
val::Union{Nothing, AbstractArray{<:Union{Number, AbstractJuMPScalar}}}
) -> NormBallUncertaintySet
Assemble a NormBallUncertaintySet from an already-computed asymptotic covariance cov.
It is the norm-ball twin of ellipsoidal_set, and it takes the same two steps in the same order: the diagonal is taken before the radius is fitted, so an empirical radius is measured against whichever geometry the set carries. The degrees of freedom are the dimension of the set, which ucs_dimension gives: $N(N+1)/2$ on a full covariance shape, although the repaired map has $N^{2}$ columns. Its sibling norm_ball_deviation_set reads a sample instead of a covariance, and is the route that spares the $N^{2} \times N^{2}$ matrix.
Algorithm
- Build the map with
norm_ball_factorunderalg.diagonalandalg.mtx_sqrt, givingL. - Fit the radius with
k_norm_ballonalg.method, passingucs_dimension(class, alg.diagonal, size(L, 1))as the degrees of freedom. - Build a
NormBallUncertaintySetfromalg.p,L, the radius,classandval.
Arguments
alg: Norm-ball uncertainty set algorithm, which carries the radius algorithm, the diagonal switch and the norm order.q: Significance level.samples: Sampled estimation errors, or whatever containeralg.methodreads. An algorithm that runs no simulation absorbs it.cov: Asymptotic covariance of the statistic. It has a square root underalg.mtx_sqrt.class: Axis tag, which fixes the row count of the map and the index a view applies.val: Quantity the set is a neighbourhood of, the fitted characteristic vector on the mean axis and the fitted covariance on the covariance axis.
Returns
ucs::NormBallUncertaintySet: The assembled set.
Related
PortfolioOptimisers.norm_ball_deviation_set — Function
norm_ball_deviation_set(
alg::NormBallUncertaintySetAlgorithm,
q::Number,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
class::AbstractUncertaintySetClass
) -> NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, Nothing} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass}
norm_ball_deviation_set(
alg::NormBallUncertaintySetAlgorithm,
q::Number,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
class::AbstractUncertaintySetClass,
val::Union{Nothing, AbstractArray{<:Union{Number, AbstractJuMPScalar}}}
) -> Union{NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, Nothing} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass}, NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, <:AbstractArray{var"#s166", N}} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}
Assemble a NormBallUncertaintySet from a sample of estimation errors, without forming their covariance.
This is the one route that never builds a square matrix of the statistic's own size. On the covariance axis the sample is $M \times N^{2}$, so the ellipsoid's shape is $N^{2} \times N^{2}$, and it is rank deficient at every sample size: a vectorised symmetric matrix spans only $N(N+1)/2$ coordinates, so the sample covariance has rank at most $\min(M - 1, N(N+1)/2)$ and the default matrix processing repairs it into a matrix the sample never named. The map this method builds carries the same second moment exactly, at that rank, and no repair is applied. Its sibling norm_ball_set factorises an already-built covariance instead.
Algorithm
- Build the map with
norm_ball_deviation_factorunderalg.diagonal, givingL. - Fit the radius with
k_norm_ballonalg.method, passingLinearAlgebra.rank(L)as the degrees of freedom, because the map is rank deficient whenever the sample is. - Build a
NormBallUncertaintySetfromalg.p,L, the radius,classandval.
Arguments
alg: Norm-ball uncertainty set algorithm, which carries the radius algorithm, the diagonal switch and the norm order.q: Significance level.X: Sample of estimation errors, one row per simulation. It is both the geometry and the sample an empirical radius reads.class: Axis tag, which fixes the row count of the map and the index a view applies.val: Quantity the set is a neighbourhood of, the fitted characteristic vector on the mean axis and the fitted covariance on the covariance axis.
Returns
ucs::NormBallUncertaintySet: The assembled set.
Related
PortfolioOptimisers.expand_investable_ucs — Method
expand_investable_ucs(
set::NormBallUncertaintySet{<:Any, <:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, <:Any, <:MuUncertaintySetClass},
imsk::BitVector,
pr::AbstractPriorResult
) -> Union{NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, Nothing} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass}, NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, <:AbstractArray{var"#s166", N}} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}
Write a mean NormBallUncertaintySet fitted on the Investable Mask back onto the full asset universe.
The expansion is the inverse of port_opt_view: the view drops rows of the map and touches nothing else, so a zero row outside the mask is dropped without a trace and the view recovers the fitted set. A zero row states that the set moves nothing on an asset the prior could not estimate, and the centre is the full pr.mu, NaN frame and all, because the set is a neighbourhood of the prior it was calibrated on and that prior lives on the full universe.
Algorithm
- Allocate a zero frame of
length(imsk)rows andsize(set.L, 2)columns, and writeset.Lat the rows the mask keeps, givingL. - Rebuild the set from
L, withpr.muasval, withrebuild_struct.kappa,pandclassdo not change.
Arguments
set: Mean norm-ball uncertainty set fitted on the reduced prior.imsk: The Investable Mask of the full prior.pr: Prior result.
Returns
set::NormBallUncertaintySet: The set on the full asset universe.
Related
PortfolioOptimisers.expand_investable_ucs — Method
expand_investable_ucs(
set::NormBallUncertaintySet{<:Any, <:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, <:Any, <:SigmaUncertaintySetClass},
imsk::BitVector,
pr::AbstractPriorResult
) -> Union{NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, Nothing} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass}, NormBallUncertaintySet{var"#s185", var"#s1851", var"#s1852", C, <:AbstractArray{var"#s166", N}} where {var"#s185"<:Number, var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s1851"<:AbstractMatrix{var"#s166"}, var"#s1852"<:Number, C<:AbstractUncertaintySetClass, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}
Write a covariance NormBallUncertaintySet fitted on the Investable Mask back onto the full asset universe.
The expansion is the inverse of port_opt_view: the view slices the map at the fourth-moment index of the selected assets and the centre at the plain one, so a zero row written outside the mask is dropped without a trace and the view recovers the fitted set. A zero row states that the set moves nothing on a pair the prior could not estimate, and the map must be finite, so the frame is zero and not NaN. The centre is the full pr.sigma.
Algorithm
- Take the positions the investable pairs occupy in the vectorised covariance with
coverage_pair_index, which orders them asfourth_moment_index_generatordoes. - Allocate a zero frame of
length(imsk)^2rows andsize(set.L, 2)columns, and writeset.Lat those rows. - Rebuild the set from the frame, with
pr.sigmaasval, withrebuild_struct.kappa,pandclassdo not change.
Arguments
set: Covariance norm-ball uncertainty set fitted on the reduced prior.imsk: The Investable Mask of the full prior.pr: Prior result.
Returns
set::NormBallUncertaintySet: The set on the full asset universe.
Related