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 a DimensionMismatch.

Returns

  • nothing.

Related

source
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, val is a matrix and size(val, 1) == size(val, 2), else a DimensionMismatch.

Returns

  • nothing.

Related

source
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

  1. When p is infinite, return one(p), because the dual of the infinity norm is the one norm.
  2. Otherwise return p / (p - 1). At p = 1 the division is by zero and returns Inf, the dual of the one norm, and at p = 2 it returns 2, which is its own dual.

Arguments

  • p::Number: Norm order, p >= 1.

Returns

  • q::Number: Dual norm order.

Related

source
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

  1. When diagonal is true, return LinearAlgebra.Diagonal(sqrt.(LinearAlgebra.diag(cov))), the square root of the diagonal shape. The result is stored as a Diagonal, not as a dense matrix. A NormalUncertaintySet hands it a diagonal shape already, built under its dc by diagonal_sigma_shape, so the diagonal is the one that rule states.
  2. Otherwise return matrix_square_root(mtx_sqrt, cov), which satisfies $\mathbf{L}\mathbf{L}^{\intercal} = \mathbf{S}$ and is the map the converter constructor of NormBallUncertaintySet builds.

Arguments

  • diagonal: Whether to discard the off-diagonal entries of cov before the factorisation.
  • cov: Asymptotic covariance of the statistic.
  • mtx_sqrt: Square-root algorithm of cov, the mtx_sqrt of the NormBallUncertaintySetAlgorithm, or nothing for the plain Cholesky factor.

Validation

  • When diagonal is false, cov has a square root under mtx_sqrt, as matrix_square_root states. Raises a LinearAlgebra.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 with pdm = nothing the plain Cholesky factor refuses it, and the default eigen square root reads it.

Returns

  • L::MatNum: Geometry map, square.

Related

source
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

  1. When diagonal is true, return LinearAlgebra.Diagonal(sqrt.(vec(Statistics.var(X; dims = 1)))), the square root of the entrywise variances. It is $m \times m$ and of full rank.
  2. Otherwise subtract the column means from X, transpose the result, and divide by sqrt(size(X, 1) - 1). The map needs at least two rows, because a sample of one row divides by zero. ARCHUncertaintySet refuses n_sim < 2 for 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$ under diagonal = false and $m \times m$ under diagonal = true.

Related

source
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

  1. On a triangular map, and on a map that is not square, return L \ transpose(X).
  2. On a diagonal map with no zero entry, return L \ transpose(X). Otherwise divide each row of transpose(X) by its entry, and give a zero coordinate where the entry is zero, which is the pseudo-inverse of a diagonal map.
  3. 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 which matrix_square_root reads a negative eigenvalue of EigenFallbackSquareRoot as round-off of zero.
  4. 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 of X. Under step 3 it has $r$ rows.

Related

source
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

  1. Build the map with norm_ball_factor under alg.diagonal and alg.mtx_sqrt, giving L.
  2. Fit the radius with k_norm_ball on alg.method, passing ucs_dimension(class, alg.diagonal, size(L, 1)) as the degrees of freedom.
  3. Build a NormBallUncertaintySet from alg.p, L, the radius, class and val.

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 container alg.method reads. An algorithm that runs no simulation absorbs it.
  • cov: Asymptotic covariance of the statistic. It has a square root under alg.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

source
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

  1. Build the map with norm_ball_deviation_factor under alg.diagonal, giving L.
  2. Fit the radius with k_norm_ball on alg.method, passing LinearAlgebra.rank(L) as the degrees of freedom, because the map is rank deficient whenever the sample is.
  3. Build a NormBallUncertaintySet from alg.p, L, the radius, class and val.

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

source
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

  1. Allocate a zero frame of length(imsk) rows and size(set.L, 2) columns, and write set.L at the rows the mask keeps, giving L.
  2. Rebuild the set from L, with pr.mu as val, with rebuild_struct. kappa, p and class do 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

source
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

  1. Take the positions the investable pairs occupy in the vectorised covariance with coverage_pair_index, which orders them as fourth_moment_index_generator does.
  2. Allocate a zero frame of length(imsk)^2 rows and size(set.L, 2) columns, and write set.L at those rows.
  3. Rebuild the set from the frame, with pr.sigma as val, with rebuild_struct. kappa, p and class do 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

source