Base Uncertainty Sets

PortfolioOptimisers.AbstractUncertaintySetEstimator — Type
abstract type AbstractUncertaintySetEstimator <: AbstractEstimator

Fits an uncertainty set around a prior statistic, so that a robust model can take the worst case over the set.

Every concrete estimator of an uncertainty set subtypes AbstractUncertaintySetEstimator.

Interfaces

To add an estimator that the library can use, subtype AbstractUncertaintySetEstimator and add the methods below.

mu_ucs

  • mu_ucs(ue::AbstractUncertaintySetEstimator, X::MatNum, F::Option{<:MatNum} = nothing; dims::Int = 1, kwargs...) -> AbstractUncertaintySetResult: Fits the uncertainty set of the mean.

sigma_ucs

  • sigma_ucs(ue::AbstractUncertaintySetEstimator, X::MatNum, F::Option{<:MatNum} = nothing; dims::Int = 1, kwargs...) -> AbstractUncertaintySetResult: Fits the uncertainty set of the covariance. An estimator with no covariance set throws an error here, as CharacteristicUncertaintySet does.

ucs

  • ucs(ue::AbstractUncertaintySetEstimator, X::MatNum, F::Option{<:MatNum} = nothing; dims::Int = 1, kwargs...) -> Tuple: Fits the two sets in one call, so that the estimator computes a shared prior or a shared simulation once.

Arguments

  • ue: The instance of the concrete subtype.
  • X: Matrix of asset returns.
  • F: Optional matrix of factor returns, which a factor prior needs.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments, which the method gives to the prior estimator.

Returns

  • ucs::AbstractUncertaintySetResult: The fitted set. ucs returns a tuple of the mean set and the covariance set.

reads_prior_result

  • reads_prior_result(ue::AbstractUncertaintySetEstimator) -> Bool: States whether the estimator calibrates its set on a Prior Result that the caller gives it, and not on returns data. The root returns false, so a subtype that fits from returns data declares no method. A subtype that reads a Prior Result subtypes AbstractPriorUncertaintySetEstimator instead. Each of the four returns-data families reads a Prior Result when it holds pe = nothing.

Related

source
PortfolioOptimisers.AbstractPriorUncertaintySetEstimator — Type
abstract type AbstractPriorUncertaintySetEstimator <: AbstractUncertaintySetEstimator

Fits an uncertainty set from the Prior Result that the optimisation solves on, and not from returns data.

Every other AbstractUncertaintySetEstimator holds its own prior estimator pe and fits it on the returns that the caller gives it. So the set that it builds does not know the prior of the optimiser. A subtype of this root reads the fitted Prior Result instead. The inputs of its fit are the factor model, the mu and the sigma of that result, and it holds no pe. Both JuMP builders hold the prior beside the returns, so both give it to the set. The three-argument form of the ucs Triple then gives each estimator the argument that it reads.

The root is not exported. A caller writes its name only to declare a subtype, and every consumer gets to it through the ucs Triple.

Interfaces

To add an estimator that the library can use, subtype AbstractPriorUncertaintySetEstimator and add the methods below.

mu_ucs

  • mu_ucs(ue::AbstractPriorUncertaintySetEstimator, pr::AbstractPriorResult; kwargs...) -> AbstractUncertaintySetResult: Fits the uncertainty set of the mean.

sigma_ucs

  • sigma_ucs(ue::AbstractPriorUncertaintySetEstimator, pr::AbstractPriorResult; kwargs...) -> AbstractUncertaintySetResult: Fits the uncertainty set of the covariance.

ucs

  • ucs(ue::AbstractPriorUncertaintySetEstimator, pr::AbstractPriorResult; kwargs...) -> Tuple: Fits the two sets in one call, so that the estimator computes a shared geometry once.

Arguments

  • ue: The instance of the concrete subtype.
  • pr: The Prior Result that the optimisation solves on.
  • kwargs...: More keyword arguments.

Returns

  • ucs::AbstractUncertaintySetResult: The fitted set. ucs returns a tuple of the mean set and the covariance set.

The root returns true from reads_prior_result. So a subtype gets the three-argument methods of the ucs Triple, which drop the returns data and call the two-argument methods above. A subtype needs no method of the returns-data interface of AbstractUncertaintySetEstimator, because no consumer calls that interface through this root. Each of the four returns-data families has the same contract with no subtype when its pe is nothing. DeltaUncertaintySet, NormalUncertaintySet, ARCHUncertaintySet and CharacteristicUncertaintySet each have a method of the ucs Triple over a Prior Result. The optimiser gives such a set the prior that it solves on.

The root has no default fit. It has one method of each of the three verbs, and each method throws an error that names the type of its argument. So a subtype that declares none of the three tells its author which method is missing, and does not fail on the root.

Related

source
PortfolioOptimisers.AbstractUncertaintySetAlgorithm — Type
abstract type AbstractUncertaintySetAlgorithm <: AbstractAlgorithm

Selects the shape of the uncertainty set that an estimator builds, for example a box or an ellipsoid.

Every concrete shape subtypes AbstractUncertaintySetAlgorithm. A subtype holds the parameters of its shape and nothing more. The estimator does the fit.

Interfaces

A subtype is a tag that the estimator dispatches on, so it declares no method. To add a shape, subtype AbstractUncertaintySetAlgorithm. Then add the ucs, mu_ucs and sigma_ucs methods of AbstractUncertaintySetEstimator for the new shape, one set of methods for each estimator that builds it.

Related

source
PortfolioOptimisers.AbstractUncertaintySetResult — Type
abstract type AbstractUncertaintySetResult <: AbstractResult

Holds a fitted uncertainty set, which a robust model reads to build its worst-case expression.

Every concrete set subtypes AbstractUncertaintySetResult. A subtype also holds the statistic that the estimator calibrated its bounds on, so that the consumer bounds that statistic and not a different one.

Interfaces

To add a set that the library can use, subtype AbstractUncertaintySetResult and add the method below.

port_opt_view

  • port_opt_view(risk_ucs::AbstractUncertaintySetResult, i, args...) -> AbstractUncertaintySetResult: Returns the set restricted to the asset indices i. A hierarchical optimiser calls it once for each cluster.

Arguments

  • risk_ucs: The instance of the concrete subtype.
  • i: Asset index of the cluster.
  • args...: More arguments.

Returns

  • risk_ucs::AbstractUncertaintySetResult: The restricted set.

A model that takes the worst case over the new shape also needs its own set_ucs_return_constraints! method, its own set_ucs_variance_risk! method, or both.

Related

source
PortfolioOptimisers.AbstractUncertaintyKAlgorithm — Type
abstract type AbstractUncertaintyKAlgorithm <: AbstractAlgorithm

Computes the radius k of an ellipsoidal uncertainty set, which bounds the distance from the estimate to the true statistic.

Every concrete radius algorithm subtypes AbstractUncertaintyKAlgorithm. A plain number in place of an algorithm is the radius.

Interfaces

To add a radius algorithm that the library can use, subtype AbstractUncertaintyKAlgorithm and add the methods below. An ellipsoid reads k_ucs, and a norm ball reads k_norm_ball.

k_ucs

  • k_ucs(km::AbstractUncertaintyKAlgorithm, q::Number, X, sigma_X::MatNum, df::Integer) -> Number: Returns the radius.

Arguments

  • km: The instance of the concrete subtype.
  • q: Significance level.
  • X: Matrix of sampled estimation errors, with one row for each sample. An algorithm that runs no simulation ignores it.
  • sigma_X: Shape matrix of the ellipsoid.
  • df: Dimension of the set, which ucs_dimension gives. On a full covariance shape, it is less than the first dimension of sigma_X, because a symmetric matrix has $N(N+1)/2$ free entries of its $N^{2}$. An algorithm that reads no dimension ignores it.

Returns

  • k::Number: Radius of the ellipsoid.

k_norm_ball

  • k_norm_ball(km::AbstractUncertaintyKAlgorithm, q::Number, X, L::MatNum, df::Integer) -> Number: Returns the radius of a norm ball.

Arguments

  • km, q, X: The same as for k_ucs.
  • L: Geometry map of the ball, in place of the shape. The shape is L * L'.
  • df: Dimension of the ball. For a map that is a factor of a shape, the caller reads ucs_dimension. For a map of deviations, the caller reads LinearAlgebra.rank(L). An algorithm that reads no dimension ignores it.

Returns

  • k::Number: Radius of the ball.

Related

source
PortfolioOptimisers.AbstractCompactRadiusAlgorithm — Type
abstract type AbstractCompactRadiusAlgorithm <: AbstractAlgorithm

Computes the radius $\kappa$ of a compact covariance uncertainty set from the Prior Result and the geometry of the set.

The radius of a CompactCovarianceUncertaintySet then changes when the sample or the factor span changes. A member goes in the kappa field of an OrthogonalUncertaintySet, whose type bound is Num_CptRad. A plain number in that field is the radius, and k_compact returns it unchanged.

This family is separate from the Calibration Rules, and the two do not mix. A Calibration Rule reads (pr, w, slv, ctx) and nothing more. These four inputs cannot size the compact radius, because its units change with a different field of the same estimator. The penalty is $\kappa \lVert (\mathbf{I} - \mathbf{Q}\mathbf{Q}^{\intercal})\mathbf{C}\boldsymbol{w} \rVert_{2}^{2}$ with $\mathbf{C} = \mathbf{W}^{-1/2}$. Under metric = nothing, $\kappa$ has the units of a variance. Under InverseIdiosyncraticVarianceMetric, it has no units.

A rule that reads only the Prior Result must select one of the two units, and it is wrong under the other. So a rule of this family computes the radius inside the family, which has the metric, the loadings block and the span. The mean radius of the same estimator follows the same pattern through k_norm_ball and the method field. A field that holds a radius also accepts the rule that computes it.

The name of a rule is the name of the method that it runs, and no other part of the library uses either word. ResidualInflation increases the residual variance to a confidence bound. VarianceFraction sets the penalty to a fraction of the nominal variance at a reference portfolio.

Interfaces

k_compact

  • k_compact(alg::AbstractCompactRadiusAlgorithm, q::Number, metric::Option{<:AbstractOrthogonalityMetric}, pr::AbstractPriorResult, rr::AbstractLoadingsRegressionResult, C::VecNum, Q::MatNum, rd) -> Number: Returns the radius, which is finite and >= 0. rd is the returns data of the fit, or nothing. The constructor of the estimator that holds the rule states the range, so a rule needs no range check.

Related

source
PortfolioOptimisers.AbstractUncertaintyEpsAlgorithm — Type
abstract type AbstractUncertaintyEpsAlgorithm <: AbstractAlgorithm

Computes the radius eps of an $\ell_1$ uncertainty set, which sets how many assets the portfolio holds.

The radius bounds the distance from the estimate to the true characteristic vector. Every concrete radius algorithm of the $\ell_1$ family subtypes AbstractUncertaintyEpsAlgorithm. A plain number in place of an algorithm is the radius. The family has the same role for the $\ell_1$ sets as AbstractUncertaintyKAlgorithm has for the ellipsoid.

Interfaces

To add a radius algorithm that the library can use, subtype AbstractUncertaintyEpsAlgorithm and add the method below.

l1_resolve_eps

  • l1_resolve_eps(method::AbstractUncertaintyEpsAlgorithm, mus::VecNum, sds::Option{<:VecNum}, paired::Bool) -> Number: Returns the radius.

Arguments

  • method: The instance of the concrete subtype.
  • mus: Characteristic vector, sorted in non-increasing order.
  • sds: Scale of each asset under the same permutation, or nothing when the set has no scale.
  • paired: Whether to read the paired ladder of the dollar-neutral problem, and not the long-only ladder.

Returns

  • eps::Number: Radius of the set.

Related

source
PortfolioOptimisers.AbstractUncertaintySetClass — Type
abstract type AbstractUncertaintySetClass <: AbstractUncertaintySetResult

Names the axis of an uncertainty set, which sets the row count of its shape matrix or of its geometry map.

The family has two members, and the library exports both. A consumer dispatches on the tag. A mean set and a covariance set are the same struct with a different size of shape matrix or of geometry map. EllipsoidalUncertaintySet and NormBallUncertaintySet both hold a tag. The tag names only the axis, and not the geometry. So a norm ball of order one, which is not an ellipsoid, has the same tag as an ellipsoid on the same axis.

Interfaces

A subtype is a tag. It has no field and declares no method.

Related

source
PortfolioOptimisers.BoxUncertaintySet — Type
struct BoxUncertaintySet{__T_lb, __T_ub, __T_val} <: AbstractUncertaintySetResult

Holds the element-wise lower and upper bounds of a box uncertainty set on a mean vector or on a covariance matrix.

A box is a convex polytope, so it is a polyhedral confidence interval on the entries that it bounds. Section 3.1 of [167] states the worst case on the mean axis, $\hat{\boldsymbol{\mu}}^{\intercal} \boldsymbol{w} - \delta^{\intercal} \lvert \boldsymbol{w} \rvert$ for a box symmetric about $\hat{\boldsymbol{\mu}}$. Section 5.2.6 of the same work states the worst case on the covariance axis as Equation 7. Equation 7 is the dual of the semidefinite programme of Equation 6. Its constraint $\mathbf{Z} + \mathbf{\Lambda}_u - \mathbf{\Lambda}_l = -\boldsymbol{w} \boldsymbol{w}^\intercal$ has the wrong sign: the dual of the worst case needs $\mathbf{\Lambda}_u - \mathbf{\Lambda}_l \succeq \boldsymbol{w} \boldsymbol{w}^\intercal$.

The two axes read the bounds differently, so a set fitted for one axis is not a set for the other. On the mean axis, set_ucs_return_constraints! reads only the half-width $(\boldsymbol{u} - \boldsymbol{\ell}) / 2$ of the bounds, which is the $\delta$ of the definition below. It centres that width on val. So neither lb nor ub is a bound on the mean alone. This is why two estimators can write one set in two ways and agree. ARCHUncertaintySet stores the two quantiles of the bootstrap mean. DeltaUncertaintySet and the normal box write $\boldsymbol{\ell} = \boldsymbol{0}$ and put the full width in $\boldsymbol{u}$.

On the covariance axis, set_ucs_variance_risk! reads $\operatorname{tr}(\mathbf{A}_{u} \mathbf{\Sigma}_{u}) - \operatorname{tr}(\mathbf{A}_{l} \mathbf{\Sigma}_{l})$ under $\mathbf{A}_{u} - \mathbf{A}_{l} = \mathbf{W}$. So each bound binds alone, and the covariance box is absolute. That route has no centre, so it never reads val.

Mathematical definition

\[\begin{align} U^{\text{box}}_{\boldsymbol{\mu}} &= \left\{ \boldsymbol{\mu}\, \vert\, \lvert \boldsymbol{\mu} - \boldsymbol{\hat{\mu}} \rvert \leq \delta \right\} \\ U^{\text{box}}_{\mathbf{\Sigma}} &= \left\{ \mathbf{\Sigma}\, \vert\, \mathbf{\Sigma}_{l} \leq \mathbf{\Sigma} \leq \mathbf{\Sigma}_{u},\, \mathbf{\Sigma} \succeq 0 \right\}\,. \end{align}\]

Where:

  • $U^{\text{box}}_{\boldsymbol{\mu}}$: Box uncertainty set for expected returns.
  • $U^{\text{box}}_{\mathbf{\Sigma}}$: Box uncertainty set for the covariance matrix.
  • $\boldsymbol{\mu}$, $\mathbf{\Sigma}$: Uncertain expected returns and covariance.
  • $\boldsymbol{\hat{\mu}}$: Estimated mean vector, the centre of the box.
  • $\delta$: Element-wise half-width of the box.
  • $\mathbf{\Sigma}_{l}$, $\mathbf{\Sigma}_{u}$: Lower and upper bounds of the covariance matrix.
  • $\mathbf{\Sigma} \succeq 0$: Constraint that the matrix is positive semidefinite.

Fields

  • lb: Lower bound.
  • ub: Upper bound.
  • val: Quantity that the set is a neighbourhood of. It is a vector on the mean axis and a covariance matrix on the covariance axis. nothing lets the consumer use its own quantity. A value has priority over the field of the returns estimator and over the prior.

Constructors

BoxUncertaintySet(;    lb::ArrNum,    ub::ArrNum,    val::Option{<:ArrNum} = nothing) -> BoxUncertaintySet

The keywords are the fields of the struct.

Validation

  • !isempty(lb).
  • !isempty(ub).
  • size(lb) == size(ub).
  • If val is an array, size(val) == size(lb).

Examples

julia> BoxUncertaintySet(; lb = [0.1, 0.2], ub = [0.3, 0.4])BoxUncertaintySet   lb ┼ Vector{Float64}: [0.1, 0.2]   ub ┼ Vector{Float64}: [0.3, 0.4]  val ┴ nothing

Related

References

  • [167] M. Sousa Lobo and S. Boyd. The worst-case risk of a portfolio. Technical report, Stanford University (2000). Sections 3.1, 4 and 5.2.6, Equations 6 and 7.
source
PortfolioOptimisers.BoxUncertaintySetAlgorithm — Type
struct BoxUncertaintySetAlgorithm <: AbstractUncertaintySetAlgorithm

Selects a box uncertainty set, a convex polytope of element-wise bounds, from an estimator that can build either shape.

EllipsoidalUncertaintySetAlgorithm selects the ellipsoid. The box has no correlation between the entries that it bounds. Its worst case is a linear programme or a semidefinite programme, and not a second-order cone programme.

Related

References

  • [167] M. Sousa Lobo and S. Boyd. The worst-case risk of a portfolio. Technical report, Stanford University (2000). Sections 3.1 and 4.
source
PortfolioOptimisers.MuUncertaintySetClass — Type
struct MuUncertaintySetClass <: AbstractUncertaintySetClass

Marks an uncertainty set as a set on the mean axis, where the shape matrix is $N \times N$ and the geometry map has $N$ rows.

The tag applies to EllipsoidalUncertaintySet and NormBallUncertaintySet, and the consumers dispatch on it. port_opt_view slices such a set with the plain asset index. The builder of the robust return refuses a set that has the covariance tag.

Related

source
PortfolioOptimisers.SigmaUncertaintySetClass — Type
struct SigmaUncertaintySetClass <: AbstractUncertaintySetClass

Marks an uncertainty set as a set on the covariance axis, where the shape matrix is $N^{2} \times N^{2}$ and the geometry map has $N^{2}$ rows.

The tag applies to EllipsoidalUncertaintySet and NormBallUncertaintySet, and the consumers dispatch on it. The set bounds a vectorised covariance. So port_opt_view maps the asset index through fourth_moment_index_generator before it slices the shape matrix or the geometry map.

Related

source
PortfolioOptimisers.NormalKUncertaintyAlgorithm — Type
struct NormalKUncertaintyAlgorithm{__T_kwargs} <: AbstractUncertaintyKAlgorithm

Computes the radius k of the ellipsoid from a sample, as the 1 - q quantile of the Mahalanobis distances of the sampled estimation errors.

The algorithm makes no assumption about the distribution. It reads the errors that the estimator sampled, from a parametric draw or from a bootstrap resample. ChiSqKUncertaintyAlgorithm and GeneralKUncertaintyAlgorithm give the radius in closed form.

The sample must be the estimation error, not the estimate. When the errors are normal, the squared Mahalanobis distance of a centred error has a chi-squared distribution. So this algorithm and ChiSqKUncertaintyAlgorithm compute one radius in two ways, and they agree to within the noise of the sample. That radius depends only on the dimension and the significance level. A sample of the raw estimates makes the distance non-central. The radius then increases with the non-centrality $T \hat{\boldsymbol{\mu}}^{\intercal} \hat{\mathbf{\Sigma}}^{-1} \hat{\boldsymbol{\mu}}$, although it must measure only the estimation error.

The algorithm measures the distances against the shape matrix that it gets, not against the first shape of the estimator. ellipsoidal_set replaces the asymptotic covariance with its diagonal before it calls k_ucs. So under the default diagonal = true, the radius is a quantile of the distances against the diagonal shape. The two radii are different, and neither shape always gives the larger radius.

Mathematical definition

\[k = \sqrt{Q_{1-q}\!\left(\left\{ \boldsymbol{\delta}^{(m)\intercal} \mathbf{\Sigma}_{\boldsymbol{\delta}}^{-1} \boldsymbol{\delta}^{(m)} \right\}_{m=1}^{M}\right)}\,.\]

Where:

  • $\boldsymbol{\delta}^{(m)}$: The $m$-th sampled estimation error, a row of the X argument of k_ucs.
  • $\mathbf{\Sigma}_{\boldsymbol{\delta}}$: Shape matrix of the ellipsoid.
  • $Q_{1-q}$: The 1 - q quantile function.
  • $M$: Number of samples.

Fields

  • kwargs: More keyword arguments.

Constructors

NormalKUncertaintyAlgorithm(;    kwargs::NamedTuple = (;))

The keyword is the field above.

Validation

  • kwargs is a NamedTuple.

Examples

julia> NormalKUncertaintyAlgorithm()NormalKUncertaintyAlgorithm  kwargs ┴ @NamedTuple{}: NamedTuple()

Related

References

  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 11.3.2, Listings 11.10 and 11.11. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.GeneralKUncertaintyAlgorithm — Type
struct GeneralKUncertaintyAlgorithm <: AbstractUncertaintyKAlgorithm

Computes the radius k of the ellipsoid as sqrt((1 - q) / q), a closed form that holds for every distribution of the estimation errors.

The radius is the factor $\kappa(\epsilon)$ of Theorem 1 of [168], Equation 8, at $\epsilon = q$. It reads neither the data nor the shape matrix. The theorem bounds the worst-case value at risk over every distribution with a given mean and covariance. The radius comes from the one-sided Chebyshev inequality of Cantelli. So it holds for every distribution of the estimation errors that has the stated second moment. When the errors are normal, use ChiSqKUncertaintyAlgorithm, because its radius is smaller there.

The guarantee is a bound in one direction, not a joint region for the full vector. It covers the scalar that a robust row bounds, which is the worst-case value of $\boldsymbol{w}^{\intercal} \boldsymbol{\mu}$ at the weights that the model selects. It holds with a probability of at least $1 - q$. The chi-squared radius gives a joint confidence region for all entries together.

Mathematical definition

\[k = \sqrt{\dfrac{1 - q}{q}}\,.\]

Where:

  • $q$: Significance level.

The inverse of the form is $\left(1 + k^{2}\right)^{-1} = q$, which is the bound of Cantelli at $k$ standard deviations. So the radius is the smallest radius whose tail bound is $q$ for every distribution with the stated moments.

Related

References

  • [168] L. El Ghaoui, M. Oks and F. Oustry. Worst-Case Value-At-Risk and Robust Portfolio Optimization: A Conic Programming Approach. Operations Research 51, 543–556 (2003). Theorem 1, Equations 7 and 8.
source
PortfolioOptimisers.ChiSqKUncertaintyAlgorithm — Type
struct ChiSqKUncertaintyAlgorithm{__T_ambient} <: AbstractUncertaintyKAlgorithm

Computes the radius k of the ellipsoid as the square root of a chi-squared quantile, a closed form for normal estimation errors.

The degrees of freedom are the dimension of the set, which is the number of free coordinates of the estimation error. On the mean axis, the dimension is $N$. On the covariance axis, the error is a vectorised symmetric $N \times N$ matrix. The entries $(i, j)$ and $(j, i)$ are one number, so the error has $N(N+1)/2$ free coordinates of the $N^{2}$. The shape of the normal method, $\left(\mathbf{I} + \mathbf{K}\right) \left(\mathbf{\Sigma} \otimes \mathbf{\Sigma}\right) / T$, has that rank. Theorem 3.1 (vi) of [169] gives $\mathbf{K}$ the eigenvalue $+1$ with multiplicity $N(N+1)/2$.

The squared Mahalanobis distance of a normal error has a chi-squared distribution at the rank of its shape. So a full covariance shape reads $N(N+1)/2$. A diagonal shape reads $N^{2}$, because its statistic is a sum of $N^{2}$ terms with a mean of one. ucs_dimension states the rule, and the set builders give its value to k_ucs and k_norm_ball.

ambient = true reads the dimension of the ambient space instead. That is the first dimension of the shape matrix or of the geometry map, which is $N^{2}$ on every covariance shape. At $N = 5$ and $q = 0.05$, that radius is $6.136$, and the dimension of the set gives $5.000$. So the set covers $0.999$ of the errors, not $0.95$, and the radius is too large for its level. As $N$ increases, the ratio of the two radii decreases to $1 / \sqrt{2}$. The field keeps that rule available for a comparison with a caller that counts every entry of the vectorised matrix.

The sources state this closed form for the mean axis only. Equation 50 of [170] states that the squared Mahalanobis distance of a normal estimation error has a chi-squared distribution at the dimension of the estimate. That work sizes its sets with an F quantile, because it estimates the variance. Equation 11.23 of [12] sets $\kappa^{2}_{\boldsymbol{\mu}}$ to the chi-squared quantile at $n$ degrees of freedom, where $n$ is the number of assets. It gets $\kappa^{2}_{\mathbf{\Sigma}}$ from a simulation, not in closed form. The form on the covariance axis is an extension that this library makes.

Section 4.1 of [167] bounds the $N(N+1)/2$ distinct entries of the covariance with its ellipsoid, and the dimension of the set reads that count. NormalKUncertaintyAlgorithm on the same errors gives the radius from the sample, and the two radii agree to within the noise of the simulation.

Mathematical definition

\[\begin{align} k &= \sqrt{\chi^{2,\,-1}_{p}(1 - q)}\,. \end{align}\]

Where:

  • $\chi^{2,\,-1}_{p}$: Inverse cumulative distribution function of the chi-squared distribution with $p$ degrees of freedom.
  • $p$: Degrees of freedom, the dimension of the set, or the first dimension of the shape matrix under ambient = true.
  • $q$: Significance level.

Fields

  • ambient: Whether the degrees of freedom are the first dimension of the shape matrix, and not the dimension of the set. The first dimension is $N^{2}$ on every covariance shape. The default is false.

Constructors

ChiSqKUncertaintyAlgorithm(;    ambient::Bool = false)

The keyword is the field above.

Examples

julia> ChiSqKUncertaintyAlgorithm()ChiSqKUncertaintyAlgorithm  ambient ┴ Bool: false

Related

References

  • [170] D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003). Section 5, Equations 50 and 54.
  • [167] M. Sousa Lobo and S. Boyd. The worst-case risk of a portfolio. Technical report, Stanford University (2000). Section 4.1.
  • [169] J. R. Magnus and H. Neudecker. The Commutation Matrix: Some Properties and Applications. The Annals of Statistics 7, 381–394 (1979). Theorem 3.1 (vi).
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equation 11.23. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.EllipsoidalUncertaintySet — Type
struct EllipsoidalUncertaintySet{__T_sigma, __T_k, __T_class, __T_val} <: AbstractUncertaintySetResult

Holds the shape matrix, the radius, and the axis tag of an ellipsoidal uncertainty set on a mean vector or on a covariance matrix.

An ellipsoid is a Mahalanobis ball, so it is a confidence region that holds the correlation between the entries that it bounds. Section 3.2 of [167] states the set and its worst case on the mean axis. Section 4.1 of the same work bounds the distinct entries of the covariance with an ellipsoid. Equation 6.12 of [53] states that set again on $\text{vec}(\mathbf{\Sigma})$, and Equations 6.13 to 6.15 state its worst case. The two worst cases are second-order cones.

class names the axis, and the axis sets the size of sigma and the index that a view applies. A set with MuUncertaintySetClass has an $N \times N$ shape matrix and takes the plain asset index. A set with SigmaUncertaintySetClass has an $N^{2} \times N^{2}$ shape matrix, because it bounds a vectorised covariance. So port_opt_view finds $N$ from the shape matrix, and maps the asset index through fourth_moment_index_generator before it slices. The two consumers also dispatch on the tag, and the builder of the robust return refuses a set with the covariance tag.

A view keeps k unchanged, so it is not the set that the same estimator fits on the subset alone. When the shape is diagonal, the restricted shape matrix is equal to the shape matrix fitted on the subset, entry for entry. The radius is not equal, because two of the three algorithms calibrate it on the dimension or on the sample. Only GeneralKUncertaintyAlgorithm gives the same radius, because it reads neither the data nor the shape. So a view is the conservative choice. A caller who needs the radius of the subset fits the subset.

Mathematical definition

\[\begin{align} U^{\text{ellip}}_{\boldsymbol{\mu}} &= \left\{ \boldsymbol{\mu}\, \vert\, \left( \boldsymbol{\mu} - \boldsymbol{\hat{\mu}} \right)^{\intercal} \mathbf{\Sigma}^{-1}_{\boldsymbol{\mu}} \left( \boldsymbol{\mu} - \boldsymbol{\hat{\mu}} \right) \leq k^{2}_{\boldsymbol{\mu}} \right\} \\ U^{\text{ellip}}_{\mathbf{\Sigma}} &= \left\{ \mathbf{\Sigma}\, \vert\, \left( \text{vec}\left(\mathbf{\Sigma}\right) - \text{vec}\left(\mathbf{\hat{\Sigma}} \right) \right)^{\intercal} \mathbf{\Sigma}^{-1}_{\mathbf{\Sigma}} \left( \text{vec}\left(\mathbf{\Sigma}\right) - \text{vec}\left(\mathbf{\hat{\Sigma}} \right) \right) \leq k^{2}_{\mathbf{\Sigma}},\, \mathbf{\Sigma} \succeq 0 \right\}\,. \end{align}\]

Where:

  • $U^{\text{ellip}}_{\boldsymbol{\mu}}$: Ellipsoidal uncertainty set for expected returns.
  • $U^{\text{ellip}}_{\mathbf{\Sigma}}$: Ellipsoidal uncertainty set for the covariance matrix.
  • $\boldsymbol{\mu}$, $\mathbf{\Sigma}$: Uncertain expected returns and covariance.
  • $\boldsymbol{\hat{\mu}}$, $\mathbf{\hat{\Sigma}}$: Estimated mean and covariance, the centres of the two sets.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Covariance matrix of the estimation error of the mean.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Covariance matrix of the estimation error of the vectorised covariance.
  • $k^{2}_{\boldsymbol{\mu}}$, $k^{2}_{\mathbf{\Sigma}}$: Squared radii of the two ellipsoids.
  • $\text{vec}(\cdot)$: Vectorisation operator, which stacks the columns.
  • $\mathbf{\Sigma} \succeq 0$: Constraint that the matrix is positive semidefinite.

Fields

  • sigma: Shape matrix of the ellipsoid, which the estimator derives from the covariance of the estimation error. It is $N \times N$ on the mean axis and $N^{2} \times N^{2}$ on the covariance axis.
  • k: Radius of the ellipsoid. It must be positive.
  • class: Axis tag of the set, which sets the row count of the shape matrix or of the geometry map.
  • val: Quantity that the set is a neighbourhood of. It is a vector on the mean axis and a covariance matrix on the covariance axis. nothing lets the consumer use its own quantity. A value has priority over the field of the returns estimator and over the prior.

Constructors

EllipsoidalUncertaintySet(;    sigma::MatNum,    k::Number,    class::AbstractUncertaintySetClass,    val::Option{<:ArrNum} = nothing) -> EllipsoidalUncertaintySet

The keywords are the fields of the struct.

Validation

  • !isempty(sigma).
  • size(sigma, 1) == size(sigma, 2).
  • !(k isa Bool), else an ArgumentError. The converter to NormBallUncertaintySet puts k in its radius kappa, which also refuses a Bool.
  • k > 0.
  • If val is an array, length(val) == size(sigma, 1). The rule reads a length and not a size, so it holds on the two axes. On the mean axis, val is a vector of length $N$ beside an $N \times N$ shape matrix. On the covariance axis, it is an $N \times N$ covariance matrix beside an $N^{2} \times N^{2}$ shape matrix.

Examples

julia> EllipsoidalUncertaintySet([1.0 0.2; 0.2 1.0], 2.5, SigmaUncertaintySetClass())EllipsoidalUncertaintySet  sigma ┼ 2×2 Matrix{Float64}      k ┼ Float64: 2.5  class ┼ SigmaUncertaintySetClass()    val ┴ nothing

Related

References

  • [167] M. Sousa Lobo and S. Boyd. The worst-case risk of a portfolio. Technical report, Stanford University (2000). Sections 3.2 and 4.1.
  • [53] Y. Feng and D. P. Palomar. A signal processing perspective of financial engineering. Foundations and Trends in Signal Processing 9, 1–231 (2016). Section 6.1, Equations 6.6, 6.7 and 6.12 to 6.15.
source
PortfolioOptimisers.EllipsoidalUncertaintySetAlgorithm — Type
struct EllipsoidalUncertaintySetAlgorithm{__T_method, __T_diagonal} <: AbstractUncertaintySetAlgorithm

Selects an ellipsoidal uncertainty set, and holds the radius algorithm and the diagonal switch of the set.

BoxUncertaintySetAlgorithm selects the box. The shape matrix of the ellipsoid holds the correlation between the entries that it bounds. diagonal = true removes that correlation, to remove the noise in the off-diagonal estimation errors. Section 11.3.2 of [12] states that practice. Sections 3.2 and 4.1 of [167] state the two ellipsoids.

Fields

  • method: Radius algorithm of the set, or the radius as a Number.
  • diagonal: Whether the shape matrix keeps only its diagonal, which removes the correlation between the estimation errors of different entries.

Constructors

EllipsoidalUncertaintySetAlgorithm(;    method::Num_UcSK = ChiSqKUncertaintyAlgorithm(),    diagonal::Bool = true) -> EllipsoidalUncertaintySetAlgorithm
  • method: The radius algorithm, or the radius as a number.
  • diagonal: Whether the shape matrix keeps only its diagonal.

Examples

julia> EllipsoidalUncertaintySetAlgorithm()EllipsoidalUncertaintySetAlgorithm    method ┼ ChiSqKUncertaintyAlgorithm           │   ambient ┴ Bool: false  diagonal ┴ Bool: true

Related

References

  • [167] M. Sousa Lobo and S. Boyd. The worst-case risk of a portfolio. Technical report, Stanford University (2000). Sections 3.2 and 4.1.
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 11.3.2, Equation 11.24. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.NormBallUncertaintySetAlgorithm — Type
struct NormBallUncertaintySetAlgorithm{__T_method, __T_diagonal, __T_p, __T_mtx_sqrt} <: AbstractUncertaintySetAlgorithm

Selects a norm-ball uncertainty set, and holds the radius algorithm, the diagonal switch and the norm order of the set.

BoxUncertaintySetAlgorithm and EllipsoidalUncertaintySetAlgorithm select the two older shapes. This algorithm selects a NormBallUncertaintySet, which holds a geometry map and not a shape matrix. So an estimator that makes it factorises the shape one time during the fit, or stores its own deviations and makes no shape. diagonal = true removes the correlation between the estimation errors of different entries, as it does on the ellipsoid.

Theorem 2 of [171] states the worst case over a norm ball, which reads the dual norm. That work gives the result to [172]. Equation 14 of [173] defines the Euclidean case, which is an ellipsoid that can be flat.

Fields

  • method: Radius algorithm of the ball, or the radius as a Number. The algorithm reads the geometry map and not a shape matrix, so k_norm_ball computes the radius, and k_ucs does not.
  • diagonal: Whether the shape matrix keeps only its diagonal, which removes the correlation between the estimation errors of different entries.
  • p: Norm order $p \geq 1$ of the ball. Inf is valid. The set gets it unchanged, and the consumer adds the cone of the dual order.
  • mtx_sqrt: Square-root algorithm of the full asymptotic covariance, which gives the geometry map. nothing selects the plain Cholesky factor, which throws a LinearAlgebra.PosDefException on a matrix that is not positive definite. matrix_square_root states each algorithm. The covariance of the covariance is always singular, and only the repair of pdm makes it positive definite. When the repair is off, the default takes the square root from the eigendecomposition. A NormalKUncertaintyAlgorithm radius applies the pseudo-inverse of the map. So it reads the eigen square root of a singular matrix, in the subspace that the cut of norm_ball_coordinates keeps. A ridge gives a map of full rank and a different set, and a diagonal shape reads no square root.

Constructors

NormBallUncertaintySetAlgorithm(;    method::Num_UcSK = ChiSqKUncertaintyAlgorithm(),    diagonal::Bool = true,    p::Number = 2,    mtx_sqrt::Option{<:AbstractMatrixSquareRootAlgorithm} = EigenFallbackSquareRoot()) -> NormBallUncertaintySetAlgorithm

The keywords are the fields of the struct.

Validation

  • !isnan(p) and p >= 1. Inf is valid.

Examples

julia> NormBallUncertaintySetAlgorithm()NormBallUncertaintySetAlgorithm    method ┼ ChiSqKUncertaintyAlgorithm           │   ambient ┴ Bool: false  diagonal ┼ Bool: true         p ┼ Int64: 2  mtx_sqrt ┴ EigenFallbackSquareRoot()

Related

References

  • [171] D. Bertsimas, D. B. Brown and C. Caramanis. Theory and Applications of Robust Optimization. SIAM Review 53, 464–501 (2011). Section 2.2, Theorem 2. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
  • [172] D. Bertsimas, D. Pachamanova and M. Sim. Robust linear optimization under general norms. Operations Research Letters 32, 510–516 (2004).
  • [173] A. Ben-Tal and A. Nemirovski. Robust Convex Optimization. Mathematics of Operations Research 23, 769–805 (1998). Section 3, Equation 14.
source
PortfolioOptimisers.ucs — Method
ucs(uc::Option{<:Tuple{Option{<:AbstractUncertaintySetResult},
                       Option{<:AbstractUncertaintySetResult}}}, args...; kwargs...)

Returns a pair of built uncertainty sets unchanged, so that a consumer can call ucs on an estimator or on a result.

The method is a passthrough. It does no procedure, so it has no # Algorithm section. The method that takes an AbstractUncertaintySetEstimator does the fit.

Arguments

  • uc: Tuple of uncertainty sets, or nothing.
  • args...: More positional arguments, which the method ignores.
  • kwargs...: More keyword arguments, which the method ignores.

Returns

  • uc::Option{<:Tuple{Option{<:AbstractUncertaintySetResult}, Option{<:AbstractUncertaintySetResult}}}: The input, unchanged.

Related

source
PortfolioOptimisers.ucs — Method
ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult; dims::Int = 1)

Fits the two uncertainty sets in one call from an estimator and a ReturnsResult.

The method reads the fields of the container and calls the matrix method. The matrix method fits the two axes together, and an estimator that shares a prior or a simulation between them computes it once. The only keyword is dims, and the method ignores it, as prior does on a ReturnsResult. The container holds every input of the fit, and the prior of the set states the source of the returns. So an unknown keyword causes a MethodError, and the method does not ignore it.

Algorithm

  1. Check that rd.X is not nothing. If it is, throw an error.
  2. If needs_factor_returns returns true for uc.pe, check that rd.F is not nothing. If it is, throw an error. A factor leaf at any position in the estimator tree reads the factor returns, and no other prior reads them.
  3. Read the source x_src that uc.pe states, with returns_source. The set holds no source of its own. It gives the returns to its prior, and the prior states the source. A set with pe = nothing reads rd.X.
  4. Remove the observations of a Shared Series gap from the data and from the observation weights of uc, with shared_series_fit. These are the gaps of a vector benchmark under x_src = ExcessSource(), and the gaps of the factor returns when reads_factor_returns returns true for uc.pe.
  5. Read the asset returns X with benchmark_relative_returns under x_src. X is rd.X, or rd.X - rd.B under ExcessSource().
  6. Call ucs(uc, X, rd.F; iv = rd.iv, ivpa = rd.ivpa, dims = 1), and return the pair of fitted sets. The method gives the implied volatility fields with the returns, because a prior that reads them takes them by keyword. dims = 1 states that a ReturnsResult holds its observations in the rows.

Arguments

  • uc: Estimator of the two uncertainty sets.
  • rd: ReturnsResult that holds the returns data and its metadata.
  • dims: Accepted and ignored. A ReturnsResult holds its observations along the rows, so the call passes dims = 1. The method takes no other keyword that it does not list: an unknown keyword raises the MethodError of the language, and no estimator swallows it.

Validation

  • !isnothing(rd.X), else an IsNothingError.
  • The rules of benchmark_relative_returns.
  • If needs_factor_returns(uc.pe) === true, then !isnothing(rd.F), else an IsNothingError.

Returns

  • uc::Tuple{AbstractUncertaintySetResult, AbstractUncertaintySetResult}: The uncertainty sets of the mean and of the covariance.

Related

source
PortfolioOptimisers.ucs — Method
ucs(ue::AbstractPriorUncertaintySetEstimator, ::AbstractPriorResult; kwargs...)
mu_ucs(ue::AbstractPriorUncertaintySetEstimator, ::AbstractPriorResult; kwargs...)
sigma_ucs(ue::AbstractPriorUncertaintySetEstimator, ::AbstractPriorResult; kwargs...)

Throws an error that names an uncertainty set estimator which reads a Prior Result and declares no fit.

AbstractPriorUncertaintySetEstimator states three verbs over a Prior Result, and each member must add a method of each verb. These three methods belong to the root, and they throw an error. The three-argument form of the ucs Triple calls them. Without them, a member that declares none of the three fails with a MethodError that names the root, not the type that the author wrote.

The root has no default fit. An estimator of this family reads a fitted Prior Result, and no two members read the same part of it. So a default method must invent a set, and it cannot build one. factor_residual_config uses the same rule for a declaration of each type, where a missing declaration is a defect and not an answer.

Arguments

  • ue: Uncertainty set estimator, which the error names.
  • pr: Prior Result, which the method ignores.
  • kwargs...: More keyword arguments, which the method ignores.

Validation

  • Throws an ArgumentError that names the type of ue.

Related

source
PortfolioOptimisers.ucs — Method
ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult, pr::AbstractPriorResult)

Fits the two uncertainty sets from an estimator, the returns data and the Prior Result that the optimisation solves on.

Both JuMP builders call this form, so one call site serves every estimator. Each estimator reads the one argument that its fit uses, and reads_prior_result selects it. The passthrough method takes args... and is the third method of this form. So a field that holds a built pair also gets an answer here.

ucReadsForwards to
an estimator with a pe of its ownrducs(uc, rd)
an AbstractPriorUncertaintySetEstimator, or a returns-data estimator with pe = nothingprucs(uc, pr; rd = rd)
a built pair, or nothingneitheritself, unchanged

On the first row, the method drops the prior and does not check it. An estimator that holds its own pe fits it on the returns that it gets. The prior of the optimisation is not an input of that fit, and it changes no number. An estimator on the second row calibrates on pr. Inside an optimiser, pr is the prior of the optimisation. So the centre of the set and the mu of the objective are the same number.

Arguments

  • uc: Uncertainty set estimator, built pair, or nothing.
  • rd: ReturnsResult. An estimator with its own pe reads it under the source that its pe states. An estimator that reads a Prior Result drops it, and reads pr, which is already in the frame of the fit of the prior.
  • pr: AbstractPriorResult. An estimator that reads a Prior Result reads it, and an estimator with its own pe drops it.

Returns

  • uc::Tuple{AbstractUncertaintySetResult, AbstractUncertaintySetResult}: The uncertainty sets of the mean and of the covariance.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(uc::Option{<:AbstractUncertaintySetResult}, args...; kwargs...)

Returns a built uncertainty set of the mean unchanged, so that a consumer can call mu_ucs on an estimator or on a result.

The method is a passthrough. It does no procedure, so it has no # Algorithm section. The method that takes an AbstractUncertaintySetEstimator does the fit.

Arguments

  • uc: Uncertainty set of the mean, or nothing.
  • args...: More positional arguments, which the method ignores.
  • kwargs...: More keyword arguments, which the method ignores.

Returns

  • uc::Option{<:AbstractUncertaintySetResult}: The input, unchanged.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult; dims::Int = 1)

Fits the uncertainty set of the mean from an estimator and a ReturnsResult.

The method reads the fields of the container and calls the matrix method. A caller that needs the two axes calls ucs, which fits them in one call. The only keyword is dims, and the method ignores it, as ucs states.

Algorithm

  1. Check that rd.X is not nothing. If it is, throw an error.
  2. If needs_factor_returns returns true for uc.pe, check that rd.F is not nothing. If it is, throw an error. A factor leaf at any position in the estimator tree reads the factor returns, and no other prior reads them.
  3. Read the source x_src that uc.pe states, with returns_source. The set holds no source of its own. It gives the returns to its prior, and the prior states the source. A set with pe = nothing reads rd.X.
  4. Remove the observations of a Shared Series gap from the data and from the observation weights of uc, with shared_series_fit. These are the gaps of a vector benchmark under x_src = ExcessSource(), and the gaps of the factor returns when reads_factor_returns returns true for uc.pe.
  5. Read the asset returns X with benchmark_relative_returns under x_src. X is rd.X, or rd.X - rd.B under ExcessSource().
  6. Call mu_ucs(uc, X, rd.F; iv = rd.iv, ivpa = rd.ivpa, dims = 1), and return the fitted set of the mean. The method gives the implied volatility fields with the returns, because a prior that reads them takes them by keyword. dims = 1 states that a ReturnsResult holds its observations in the rows.

Arguments

  • uc: Estimator of the uncertainty set of the mean.
  • rd: ReturnsResult that holds the returns data and its metadata.
  • dims: Accepted and ignored. A ReturnsResult holds its observations along the rows, so the call passes dims = 1. The method takes no other keyword that it does not list: an unknown keyword raises the MethodError of the language, and no estimator swallows it.

Validation

  • !isnothing(rd.X), else an IsNothingError.
  • The rules of benchmark_relative_returns.
  • If needs_factor_returns(uc.pe) === true, then !isnothing(rd.F), else an IsNothingError.

Returns

  • uc::AbstractUncertaintySetResult: The uncertainty set of the mean.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult, pr::AbstractPriorResult)

Fits the uncertainty set of the mean from an estimator, the returns data and the Prior Result that the optimisation solves on.

The builder of the robust return calls this form. The table of ucs states which argument each estimator reads, and reads_prior_result selects it. The passthrough method takes args... and is the third method of this form. So a field that holds a built set also gets an answer here.

Arguments

  • uc: Uncertainty set estimator, built set, or nothing.
  • rd: ReturnsResult. An estimator with its own pe reads it under the source that its pe states. An estimator that reads a Prior Result drops it, and reads pr, which is already in the frame of the fit of the prior.
  • pr: AbstractPriorResult. An estimator that reads a Prior Result reads it, and an estimator with its own pe drops it.

Returns

  • uc::AbstractUncertaintySetResult: The uncertainty set of the mean.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(uc::Option{<:AbstractUncertaintySetResult}, args...; kwargs...)

Returns a built uncertainty set of the covariance unchanged, so that a consumer can call sigma_ucs on an estimator or on a result.

The method is a passthrough. It does no procedure, so it has no # Algorithm section. The method that takes an AbstractUncertaintySetEstimator does the fit.

Arguments

  • uc: Uncertainty set of the covariance, or nothing.
  • args...: More positional arguments, which the method ignores.
  • kwargs...: More keyword arguments, which the method ignores.

Returns

  • uc::Option{<:AbstractUncertaintySetResult}: The input, unchanged.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult; dims::Int = 1)

Fits the uncertainty set of the covariance from an estimator and a ReturnsResult.

The method reads the fields of the container and calls the matrix method. An estimator with no covariance set throws an error in the matrix method, as CharacteristicUncertaintySet does. The only keyword is dims, and the method ignores it, as ucs states.

Algorithm

  1. Check that rd.X is not nothing. If it is, throw an error.
  2. If needs_factor_returns returns true for uc.pe, check that rd.F is not nothing. If it is, throw an error. A factor leaf at any position in the estimator tree reads the factor returns, and no other prior reads them.
  3. Read the source x_src that uc.pe states, with returns_source. The set holds no source of its own. It gives the returns to its prior, and the prior states the source. A set with pe = nothing reads rd.X.
  4. Remove the observations of a Shared Series gap from the data and from the observation weights of uc, with shared_series_fit. These are the gaps of a vector benchmark under x_src = ExcessSource(), and the gaps of the factor returns when reads_factor_returns returns true for uc.pe.
  5. Read the asset returns X with benchmark_relative_returns under x_src. X is rd.X, or rd.X - rd.B under ExcessSource().
  6. Call sigma_ucs(uc, X, rd.F; iv = rd.iv, ivpa = rd.ivpa, dims = 1), and return the fitted set of the covariance. The method gives the implied volatility fields with the returns, because a prior that reads them takes them by keyword. dims = 1 states that a ReturnsResult holds its observations in the rows.

Arguments

  • uc: Estimator of the uncertainty set of the covariance.
  • rd: ReturnsResult that holds the returns data and its metadata.
  • dims: Accepted and ignored. A ReturnsResult holds its observations along the rows, so the call passes dims = 1. The method takes no other keyword that it does not list: an unknown keyword raises the MethodError of the language, and no estimator swallows it.

Validation

  • !isnothing(rd.X), else an IsNothingError.
  • The rules of benchmark_relative_returns.
  • If needs_factor_returns(uc.pe) === true, then !isnothing(rd.F), else an IsNothingError.

Returns

  • uc::AbstractUncertaintySetResult: The uncertainty set of the covariance.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult, pr::AbstractPriorResult)

Fits the uncertainty set of the covariance from an estimator, the returns data and the Prior Result that the optimisation solves on.

The builder of the uncertainty set variance calls this form. The table of ucs states which argument each estimator reads, and reads_prior_result selects it. The passthrough method takes args... and is the third method of this form. So a field that holds a built set also gets an answer here.

Arguments

  • uc: Uncertainty set estimator, built set, or nothing.
  • rd: ReturnsResult. An estimator with its own pe reads it under the source that its pe states. An estimator that reads a Prior Result drops it, and reads pr, which is already in the frame of the fit of the prior.
  • pr: AbstractPriorResult. An estimator that reads a Prior Result reads it, and an estimator with its own pe drops it.

Returns

  • uc::AbstractUncertaintySetResult: The uncertainty set of the covariance.

Related

source
PortfolioOptimisers.reads_prior_result — Function
reads_prior_result(ue::AbstractUncertaintySetEstimator) -> Bool
reads_prior_result(::AbstractPriorUncertaintySetEstimator) -> Bool
reads_prior_result(::DeltaUncertaintySet{Nothing}) -> Bool
reads_prior_result(::NormalUncertaintySet{Nothing}) -> Bool
reads_prior_result(::ARCHUncertaintySet{Nothing}) -> Bool
reads_prior_result(::CharacteristicUncertaintySet{Nothing}) -> Bool
reads_prior_result(::Option{<:AbstractUncertaintySetResult}) -> Bool

States whether an uncertainty set estimator calibrates on a Prior Result from the caller, and not on a prior that it fits.

The predicate reads the type and the pe field, and never a method table. Three consumers give an estimator the argument that it reads. These are the three-argument form of the ucs Triple, ucs_risk_measure and the uncertainty step of the Pipeline. All three ask this one question, so they agree on the answer.

Two kinds of estimator return true. The first kind is every AbstractPriorUncertaintySetEstimator, which holds no pe. The second kind is each of the four returns-data families when its pe is nothing. Each of these families declares its own method beside its method over a Prior Result.

Every other estimator returns false, and a subtype that a caller writes gets this default. A built set, or nothing, also returns false, because it is already fitted and every verb returns it unchanged. So a caller can ask a field that holds an estimator or a result, with no test of its own.

Arguments

  • ue: Uncertainty set estimator, built set, or nothing.

Returns

  • reads::Bool: true when the estimator reads a Prior Result. false when it fits its own prior, or when it is a built set.

Related

source
PortfolioOptimisers.k_ucs — Function
k_ucs(km::NormalKUncertaintyAlgorithm, q::Number, X::MatNum, sigma_X::MatNum,
      ::Integer = size(sigma_X, 1))
k_ucs(::GeneralKUncertaintyAlgorithm, q::Number, args...)
k_ucs(km::ChiSqKUncertaintyAlgorithm, q::Number, ::Any, sigma_X::MatNum,
      df::Integer = size(sigma_X, 1))
k_ucs(type::Number, args...)

Computes the radius k of an ellipsoidal uncertainty set at the significance level q.

The two closed forms are the two branches of Equation 11.23 of [12]. The branch for every distribution is the factor of Theorem 1 of [168]. The chi-squared branch comes from Equation 50 of [170]. The radius from a simulated sample is the method that Section 11.3.2 of [12] describes. A plain Number in place of an algorithm is the radius.

Algorithm

Each of the first three methods does one procedure. The fourth method, k_ucs(type::Number, args...), returns its argument and does no step, so it has no numbered steps below.

NormalKUncertaintyAlgorithm:

  1. Compute k_mus = LinearAlgebra.diag(X * (sigma_X \ transpose(X))), the squared Mahalanobis distance of each row of X against the shape matrix. The method does the solve one time for the full sample, not one row at a time.
  2. Take the 1 - q quantile of k_mus with the keywords km.kwargs, and return its square root as the radius.

GeneralKUncertaintyAlgorithm:

  1. Return sqrt((one(q) - q) / q) as the radius. The method reads neither X nor sigma_X, so args... takes the two of them.

ChiSqKUncertaintyAlgorithm:

  1. Read the degrees of freedom from df, the dimension of the set. If km.ambient is true, read them from size(sigma_X, 1).
  2. Return the square root of the 1 - q chi-squared quantile at those degrees of freedom as the radius. The method runs no simulation, so it ignores the sample argument.

Arguments

  • km: Radius algorithm.
  • q: Significance level.
  • X: Matrix of estimation errors, with one row for each sample. Every caller gives centred deviations, not levels. Each row is a deviation from the point estimate, and the method cannot check it. A sample that is not centred makes the distance non-central, and makes the radius too large.
  • sigma_X: Shape matrix of the ellipsoid, against which the method measures the distances. It is $N \times N$ on the mean axis and $N^{2} \times N^{2}$ on the covariance axis. Under its default diagonal = true, ellipsoidal_set gives the diagonal of the asymptotic covariance. So the method takes the quantile against that diagonal, not against the full matrix.
  • df: Dimension of the set, which ucs_dimension gives. The default size(sigma_X, 1) is correct on a shape of full rank. It is too large on a full covariance shape, whose rank is $N(N+1)/2$, so ellipsoidal_set always gives df. NormalKUncertaintyAlgorithm ignores it, because its sampled distances contain the dimension.
  • args...: More arguments, which the algorithms that need no sample ignore.
  • type: The radius as a number.

Returns

  • k::Number: Radius of the ellipsoid.

Related

References

  • [168] L. El Ghaoui, M. Oks and F. Oustry. Worst-Case Value-At-Risk and Robust Portfolio Optimization: A Conic Programming Approach. Operations Research 51, 543–556 (2003). Theorem 1, Equations 7 and 8.
  • [170] D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003). Section 5, Equation 50.
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 11.3.2, Equation 11.23 and Listings 11.10 and 11.11. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(risk_ucs::Option{<:AbstractUncertaintySetEstimator}, i, args...)

Returns an uncertainty set estimator unchanged, because an estimator has no asset axis to restrict.

The method is a passthrough, so it has no # Algorithm section. A hierarchical optimiser calls port_opt_view once for each cluster. Later, the optimiser fits the estimator on the returns of the cluster. So the fit does the restriction, and this method does not. The methods that take a built result apply the index, and each one states its steps.

Arguments

  • risk_ucs: Uncertainty set estimator, or nothing.
  • i: Index of the cluster or of the assets, which the method ignores.
  • args...: More positional arguments, which the method ignores.

Returns

  • risk_ucs::Option{<:AbstractUncertaintySetEstimator}: The input, unchanged.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    risk_ucs::BoxUncertaintySet{<:AbstractVector{<:Union{Number, AbstractJuMPScalar}}, <:AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    i,
    args...
) -> Union{BoxUncertaintySet{var"#s185", <:AbstractArray{var"#s166", N}, Nothing} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N, var"#s185"<:AbstractArray{var"#s166", N}, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}, BoxUncertaintySet{var"#s185", var"#s1851", <:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N, var"#s185"<:AbstractArray{var"#s166", N}, var"#s166"<:Union{Number, AbstractJuMPScalar}, N, var"#s1851"<:AbstractArray{var"#s166", N}, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}

Returns a view of a vector BoxUncertaintySet restricted to the asset indices i.

The method applies to the mean axis, where each bound has one entry for each asset. So the method applies the asset index to the two bounds.

Algorithm

  1. Take view(risk_ucs.lb, i) and view(risk_ucs.ub, i), the two bounds restricted to the selected assets.
  2. Take nothing_scalar_array_view(risk_ucs.val, i), the centre restricted to the same assets. It returns nothing unchanged.
  3. Build a BoxUncertaintySet from the three views. The bounds stay a pair, so the half-width that the mean route reads is the half-width of the restricted box.

Arguments

  • risk_ucs: Box uncertainty set with vector bounds.
  • i: Index of the cluster or of the assets.
  • args...: More positional arguments, which the method ignores.

Returns

  • risk_ucs::BoxUncertaintySet: The set restricted to i.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    risk_ucs::BoxUncertaintySet{<:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, <:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    i,
    args...
) -> Union{BoxUncertaintySet{var"#s185", <:AbstractArray{var"#s166", N}, Nothing} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N, var"#s185"<:AbstractArray{var"#s166", N}, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}, BoxUncertaintySet{var"#s185", var"#s1851", <:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N, var"#s185"<:AbstractArray{var"#s166", N}, var"#s166"<:Union{Number, AbstractJuMPScalar}, N, var"#s1851"<:AbstractArray{var"#s166", N}, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}

Returns a view of a matrix BoxUncertaintySet restricted to the asset indices i.

The method applies to the covariance axis, where each bound is an N × N matrix. So the method applies the asset index to the two dimensions of each bound.

Algorithm

  1. Take view(risk_ucs.lb, i, i) and view(risk_ucs.ub, i, i), the two bounds restricted to the selected assets on the two axes. The two bounds stay symmetric, because the source bounds are symmetric and the method applies the same index two times.
  2. Take nothing_scalar_array_view(risk_ucs.val, i), the fitted covariance restricted to the same assets. It returns nothing unchanged.
  3. Build a BoxUncertaintySet from the three views. On this axis each bound binds alone, so the method restricts each bound and does not combine them.

Arguments

  • risk_ucs: Box uncertainty set with matrix bounds.
  • i: Index of the cluster or of the assets.
  • args...: More positional arguments, which the method ignores.

Returns

  • risk_ucs::BoxUncertaintySet: The set restricted to i.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    risk_ucs::EllipsoidalUncertaintySet{<:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, <:Any, <:SigmaUncertaintySetClass},
    i,
    args...
) -> Union{EllipsoidalUncertaintySet{<:AbstractMatrix{var"#s166"}, <:Number, <:AbstractUncertaintySetClass, Nothing} where var"#s166"<:Union{Number, AbstractJuMPScalar}, EllipsoidalUncertaintySet{var"#s185", var"#s1851", var"#s1852", <:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s185"<:AbstractMatrix{var"#s166"}, var"#s1851"<:Number, var"#s1852"<:AbstractUncertaintySetClass, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}

Returns a view of a covariance EllipsoidalUncertaintySet restricted to the assets at the index i.

The set bounds a vectorised covariance. So its shape matrix is on the $N^{2}$ axis, and its centre is on the $N$ axis. The method applies a different index to each of the two fields.

Algorithm

  1. Take nothing_scalar_array_view(risk_ucs.val, i), the fitted $N \times N$ covariance restricted to the selected assets. It takes the plain asset index, and it returns nothing unchanged. This step is first, because step 2 writes a new value to i.
  2. Find N as floor(Int, sqrt(size(risk_ucs.sigma, 1))) from the shape matrix. Expand i with fourth_moment_index_generator(N, i), which gives the positions of the selected assets in the vectorised covariance.
  3. Take view(risk_ucs.sigma, i, i) with the expanded index, which gives the restricted shape matrix.
  4. Rebuild the set from the two views with rebuild_struct. k and class do not change. The method does not calibrate the radius again on the smaller dimension. So under every radius algorithm except GeneralKUncertaintyAlgorithm, the view is more conservative than a fit on the subset.

Arguments

  • risk_ucs: Ellipsoidal uncertainty set on the covariance axis.
  • i: Index of the cluster or of the assets.
  • args...: More positional arguments, which the method ignores.

Returns

  • risk_ucs::EllipsoidalUncertaintySet: The set restricted to i.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    risk_ucs::EllipsoidalUncertaintySet{<:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, <:Any, <:MuUncertaintySetClass},
    i,
    args...
) -> Union{EllipsoidalUncertaintySet{<:AbstractMatrix{var"#s166"}, <:Number, <:AbstractUncertaintySetClass, Nothing} where var"#s166"<:Union{Number, AbstractJuMPScalar}, EllipsoidalUncertaintySet{var"#s185", var"#s1851", var"#s1852", <:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, var"#s185"<:AbstractMatrix{var"#s166"}, var"#s1851"<:Number, var"#s1852"<:AbstractUncertaintySetClass, var"#s166"<:Union{Number, AbstractJuMPScalar}, N}}

Returns a view of a mean EllipsoidalUncertaintySet restricted to the assets at the index i.

The set bounds a mean vector, so its shape matrix and its centre are both on the $N$ axis. One index serves the two fields.

Algorithm

  1. Take view(risk_ucs.sigma, i, i), the $N \times N$ shape matrix restricted to the selected assets on the two dimensions.
  2. Take nothing_scalar_array_view(risk_ucs.val, i), the fitted mean vector restricted to the same assets. It returns nothing unchanged.
  3. Rebuild the set from the two views with rebuild_struct. k and class do not change. The method does not calibrate the radius again on the smaller dimension. So under every radius algorithm except GeneralKUncertaintyAlgorithm, the view is more conservative than a fit on the subset.

Arguments

  • risk_ucs: Ellipsoidal uncertainty set on the mean axis.
  • i: Index of the cluster or of the assets.
  • args...: More positional arguments, which the method ignores.

Returns

  • risk_ucs::EllipsoidalUncertaintySet: The set restricted to i.

Related

source
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(uc::AbstractUncertaintySetEstimator, i)

Return the uncertainty set estimator with the observation weights of its children cut to the observations i.

An uncertainty set estimator fits its prior, and some also fit a covariance and a mean estimator, on the returns that it receives. Each child can hold fixed observation weights. A Shared Series gap drops observations from those returns, so the weights of the children must lose the same observations, see shared_series_fit. The estimators are not @propagatable, so this method cuts every field through obs_weights_fields.

Arguments

  • uc: The uncertainty set estimator. Its keyword constructor takes every field name, as the constructors of the library do.
  • i: The observations to keep: a mask of the full sample, or their positions.

Returns

  • uc: The estimator at the kept observations.

Related

source

References

[12]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
[53]
Y. Feng and D. P. Palomar. A signal processing perspective of financial engineering. Foundations and Trends in Signal Processing 9, 1–231 (2016).
[167]
M. Sousa Lobo and S. Boyd. The Worst-Case Risk of a Portfolio (Stanford University, 2000).
[168]
L. El Ghaoui, M. Oks and F. Oustry. Worst-Case Value-At-Risk and Robust Portfolio Optimization: A Conic Programming Approach. Operations Research 51, 543–556 (2003).
[169]
J. R. Magnus and H. Neudecker. The Commutation Matrix: Some Properties and Applications. The Annals of Statistics 7, 381–394 (1979).
[170]
D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003).
[171]
D. Bertsimas, D. B. Brown and C. Caramanis. Theory and Applications of Robust Optimization. SIAM Review 53, 464–501 (2011).
[172]
D. Bertsimas, D. Pachamanova and M. Sim. Robust linear optimization under general norms. Operations Research Letters 32, 510–516 (2004).
[173]
A. Ben-Tal and A. Nemirovski. Robust Convex Optimization. Mathematics of Operations Research 23, 769–805 (1998).