GitHub

Normal Uncertainty Sets

PortfolioOptimisers.NormalUncertaintySet — Type
struct NormalUncertaintySet{__T_pe, __T_alg, __T_n_sim, __T_q, __T_rng, __T_seed, __T_ens, __T_pdm, __T_kwargs} <: AbstractUncertaintySetEstimator

Fits a box or an ellipsoidal uncertainty set from the sampling laws that normal returns imply: the mean is normal and the covariance is Wishart.

The two laws are Equation 11.16 of the source. alg picks the shape, and n_sim sets the number of Wishart draws the covariance bounds are read from. Its sampling-free counterpart is DeltaUncertaintySet, and its distribution-free counterpart is ARCHUncertaintySet.

Fields

  • pe: Prior estimator the set fits on the returns it is handed, or nothing. With nothing the set holds no prior of its own and is calibrated on the prior result it is handed — inside an optimiser, the prior the optimiser is solving on, so its centre is the objective's own — through the prior-result arm of the ucs triple; the returns-data form then refuses by name. The default, EmpiricalPrior(), fits an empirical prior on the returns.
  • alg: Uncertainty set algorithm.
  • n_sim: Number of simulation samples.
  • q: Confidence level that sizes the uncertainty set (0 < q < 1). A smaller q is more demanding and yields a larger, more conservative set (wider box intervals / larger ellipsoid radius); a larger q gives a tighter set closer to the point estimate.
  • rng: Random number generator.
  • seed: Seed for the random number generator.
  • ens: Effective sample size.
  • pdm: Positive definite matrix estimator.
  • kwargs: Additional keyword arguments.

Constructors

NormalUncertaintySet(;    pe::Option{<:AbstractLowOrderPriorEstimator} = EmpiricalPrior(),    alg::AbstractUncertaintySetAlgorithm = BoxUncertaintySetAlgorithm(),    n_sim::Integer = 3_000,    q::Number = 0.05,    rng::Random.AbstractRNG = Random.default_rng(),    seed::Option{<:Integer} = nothing,    ens::Option{<:Number} = nothing,    pdm::Option{<:AbstractPosdefEstimator} = Posdef(),    kwargs::NamedTuple = (;),) -> NormalUncertaintySet

Keywords correspond to the struct's fields.

Validation

  • n_sim > 0.
  • 0 < q < 1.

Examples

julia> NormalUncertaintySet()NormalUncertaintySet      pe ┼ EmpiricalPrior         │           ce ┼ PortfolioOptimisersCovariance         │              │   ce ┼ Covariance         │              │      │    me ┼ SimpleExpectedReturns         │              │      │       │   w ┴ nothing         │              │      │    ce ┼ GeneralCovariance         │              │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)         │              │      │       │    w ┴ nothing         │              │      │   alg ┼ FullMoment()         │              │      │     w ┴ nothing         │              │   mp ┼ MatrixProcessing         │              │      │     pdm ┼ Posdef         │              │      │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton         │              │      │         │   kwargs ┴ @NamedTuple{}: NamedTuple()         │              │      │      dn ┼ nothing         │              │      │      dt ┼ nothing         │              │      │     alg ┼ nothing         │              │      │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)         │           me ┼ SimpleExpectedReturns         │              │   w ┴ nothing         │      horizon ┼ nothing         │   fill_limit ┴ nothing     alg ┼ BoxUncertaintySetAlgorithm()   n_sim ┼ Int64: 3000       q ┼ Float64: 0.05     rng ┼ Random.TaskLocalRNG: Random.TaskLocalRNG()    seed ┼ nothing     ens ┼ nothing     pdm ┼ Posdef         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton         │   kwargs ┴ @NamedTuple{}: NamedTuple()  kwargs ┴ @NamedTuple{}: NamedTuple()

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equations 11.16, 11.17 and 11.24.
  • [87] F. J. Fabozzi, P. N. Kolm, D. A. Pachamanova and S. M. Focardi. Robust Portfolio Optimization and Management (John Wiley & Sons, Hoboken, NJ, 2007).
  • [25] A. Meucci. Risk and Asset Allocation (Springer Berlin Heidelberg, 2005).
source
PortfolioOptimisers.ucs — Function
ucs(ue::NormalUncertaintySet, X::MatNum,
    F::Option{<:MatNum} = nothing; dims::Int = 1, kwargs...)
mu_ucs(ue::NormalUncertaintySet, X::MatNum,
       F::Option{<:MatNum} = nothing; dims::Int = 1, kwargs...)
sigma_ucs(ue::NormalUncertaintySet, X::MatNum,
          F::Option{<:MatNum} = nothing; dims::Int = 1, kwargs...)

Fits a NormalUncertaintySet from returns data, by fitting the set's own prior and calibrating the set on the result.

These are the returns-data arms of the three verbs, and they are one method each whatever shape the set builds, because the shape is decided one call later. Each fits ue.pe once through ucs_prior, which refuses a pe of nothing by name, and hands the result to the prior-result arm of the same verb on the same set with its pe set to nothing, which is where the box, the ellipsoid and the norm ball are dispatched. A set with a prior of its own is therefore calibrated on that prior fitted on the returns it is handed, and on nothing else; the two routes share one body per shape, so a set reached through ucs(ue, X) and one reached through ucs(ue′, prior(ue.pe, X)) with ue′ the same set without its prior are the same set to the last bit.

Algorithm

  1. Fit the prior with ucs_prior on ue.pe, X and F, giving pr.
  2. Forward to the prior-result arm of the verb on the set with pe = nothing, which builds the set of the shape ue.alg names from pr.

Arguments

  • ue: Normal uncertainty set estimator.
  • X: Data matrix.
  • F: Optional factor matrix. Used by the prior estimator.
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments passed to the prior estimator.

Validation

  • ue.pe is not nothing. An ArgumentError naming the prior-result form is thrown otherwise.

Returns

  • mu_ucs::AbstractUncertaintySetResult: Expected returns uncertainty set, from mu_ucs.
  • sigma_ucs::AbstractUncertaintySetResult: Covariance uncertainty set, from sigma_ucs.
  • (mu_ucs, sigma_ucs): Both, from ucs.

Related

source
PortfolioOptimisers.ucs — Method
ucs(ue::NormalUncertaintySet{Nothing, <:BoxUncertaintySetAlgorithm, <:Any, <:Any, <:Any},
    pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs box uncertainty sets for mean and covariance statistics under the assumption of normally distributed returns.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

Mathematical definition

Simulates $M$ covariance matrices $\hat{\mathbf{\Sigma}}^{(m)} \sim \mathrm{Wishart}(T,\, \hat{\mathbf{\Sigma}}/T)$ and computes element-wise quantile bounds:

\[\begin{align} (\mathbf{\Sigma}_{l})_{ij} &= Q_{q/2}\!\left(\hat{\Sigma}^{(m)}_{ij}\right)\,, \\ (\mathbf{\Sigma}_{u})_{ij} &= Q_{1-q/2}\!\left(\hat{\Sigma}^{(m)}_{ij}\right)\,. \end{align}\]

Mean bounds use the normal complementary quantile $z_{q/2} = \Phi^{-1}(1-q/2)$:

\[\begin{align} \boldsymbol{\mu}_{l} &= \boldsymbol{0}\,, \\ \mu_{u,i} &= 2 z_{q/2} \sqrt{(\hat{\mathbf{\Sigma}}/T)_{ii}}\,. \end{align}\]

Where:

  • $(\mathbf{\Sigma}_{l})_{ij}$, $(\mathbf{\Sigma}_{u})_{ij}$: Element-wise lower/upper covariance bounds.
  • $Q_{q/2}$, $Q_{1-q/2}$: Lower and upper quantile functions at level $q/2$.
  • $\hat{\Sigma}^{(m)}_{ij}$: $(i,j)$-element of the $m$-th simulated Wishart covariance draw.
  • $\boldsymbol{\mu}_{l}$, $\mu_{u,i}$: Lower and upper bounds for expected returns.
  • $z_{q/2} = \Phi^{-1}(1 - q/2)$: Normal complementary quantile.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.
  • $q$: Significance level.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Run normal_box_preamble on the prior result pr the set is calibrated on, giving T, sigma_mu and the halved q.
  3. Build the mean set with mu_normal_box_set from pr.mu, sigma_mu and q.
  4. Build the covariance set with sigma_normal_box_set from ue, pr, T, sigma_mu and q.
  5. Return the two sets as a tuple, mean first.
  6. Before the two sets leave, write both back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::BoxUncertaintySet: Expected returns uncertainty set.
  • sigma_ucs::BoxUncertaintySet: Covariance uncertainty sets.

Related

source
PortfolioOptimisers.ucs — Method
ucs(ue::NormalUncertaintySet{Nothing,
                             <:EllipsoidalUncertaintySetAlgorithm{<:NormalKUncertaintyAlgorithm, <:Any},
                             <:Any, <:Any, <:Any},
    pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs ellipsoidal uncertainty sets for expected returns and covariance statistics under the assumption of normally distributed returns.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The two samples are estimation errors, not levels. k_ucs measures a Mahalanobis distance against the shape matrix, so step 5 draws from the sampling law of the estimator, $\mathcal{N}(\hat{\boldsymbol{\mu}}, \hat{\mathbf{\Sigma}}/T)$, and centres the draws on $\hat{\boldsymbol{\mu}}$. A draw from $\mathcal{N}(\hat{\boldsymbol{\mu}}, \hat{\mathbf{\Sigma}})$ in its place multiplies every deviation, and therefore the radius, by $\sqrt{T}$. Step 6 is on the matching scale for the same reason: the variance of an entry of a $\mathrm{Wishart}(T, \hat{\mathbf{\Sigma}}/T)$ draw is the matching diagonal entry of $\mathbf{\Sigma}_{\mathbf{\Sigma}}$.

One generator serves both draws, so this method's covariance radius is not sigma_ucs's. Issue #590 holds the decision on whether to change that. Step 4 resolves the generator once, and step 5 consumes it before step 6 reaches it. sigma_ucs draws its Wishart matrices off a generator that nothing has advanced, so under one seed the two covariance radii differ. The mean radius agrees, because the mean sample is the first draw in both. The box route has no such split: sigma_normal_box_set resolves its own generator, so there the two entry points agree entry for entry.

Mathematical definition

Ellipsoidal sets centred at the prior estimates with asymptotic covariances:

\[\begin{align} \mathbf{\Sigma}_{\boldsymbol{\mu}} &= \hat{\mathbf{\Sigma}} / T\,, \\ \mathbf{\Sigma}_{\mathbf{\Sigma}} &= T (\mathbf{I} + \mathbf{K})(\mathbf{\Sigma}_{\boldsymbol{\mu}} \otimes \mathbf{\Sigma}_{\boldsymbol{\mu}})\,. \end{align}\]

The radius of each ellipsoid is the one k_ucs returns for NormalKUncertaintyAlgorithm, which states its own form. The significance level reaches it undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

\[\begin{align} \mathcal{E}_{\boldsymbol{\mu}} &= \left\{\boldsymbol{\mu} : (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}})^{\intercal} \mathbf{\Sigma}_{\boldsymbol{\mu}}^{-1} (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}}) \leq k_{\boldsymbol{\mu}}^2 \right\}\,. \end{align}\]

\[\begin{align} \mathcal{E}_{\mathbf{\Sigma}} &= \left\{\mathbf{\Sigma} : \left\lVert \mathbf{\Sigma}_{\mathbf{\Sigma}}^{-1/2} \operatorname{vec}(\mathbf{\Sigma} - \hat{\mathbf{\Sigma}}) \right\rVert_2 \leq k_{\mathbf{\Sigma}} \right\}\,. \end{align}\]

Where:

  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Asymptotic covariance of the covariance estimator, vectorised.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{K}$: Commutation matrix.
  • $\otimes$: Kronecker product.
  • $\mathcal{E}_{\boldsymbol{\mu}}$: Ellipsoidal uncertainty set for expected returns.
  • $\mathcal{E}_{\mathbf{\Sigma}}$: Ellipsoidal uncertainty set for covariance.
  • $k_{\boldsymbol{\mu}}$, $k_{\mathbf{\Sigma}}$: Radii of the two ellipsoids, fitted on the sampled estimation errors.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read mu, sigma and N = size(pr.X, 2) from it. The asset count comes from the prior's own returns matrix, so a prior that changes the asset count is followed.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Resolve the random number generator from ue.rng and ue.seed with resolve_rng.
  6. Draw the mean sample with normal_mu_error_sample, giving X_mu, one mean estimation error per row.
  7. Draw the covariance sample with normal_sigma_error_sample, giving X_sigma, one vectorised covariance estimation error per row.
  8. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  9. Fit the mean ellipsoid with ellipsoidal_set on X_mu and sigma_mu, with pr.mu as the centre.
  10. Fit the covariance ellipsoid the same way on X_sigma and sigma_sigma, with pr.sigma as the centre.
  11. Return the two sets as a tuple, mean first.
  12. Before the two sets leave, write both back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::EllipsoidalUncertaintySet: Expected returns uncertainty set.
  • sigma_ucs::EllipsoidalUncertaintySet: Covariance uncertainty sets.

Related

source
PortfolioOptimisers.ucs — Method
ucs(ue::NormalUncertaintySet{Nothing, <:EllipsoidalUncertaintySetAlgorithm{<:Any, <:Any},
                             <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs ellipsoidal uncertainty sets for expected returns and covariance statistics under the assumption of normally distributed returns, using a generic ellipsoidal algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs. The two routes build the same shapes, so they differ only in the radius.

Mathematical definition

Ellipsoidal sets centred at the prior estimates, whose shapes are the two asymptotic covariances:

\[\begin{align} \mathbf{\Sigma}_{\boldsymbol{\mu}} &= \hat{\mathbf{\Sigma}} / T\,, \\ \mathbf{\Sigma}_{\mathbf{\Sigma}} &= T (\mathbf{I} + \mathbf{K})(\mathbf{\Sigma}_{\boldsymbol{\mu}} \otimes \mathbf{\Sigma}_{\boldsymbol{\mu}})\,. \end{align}\]

Where:

  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Asymptotic covariance of the covariance estimator, vectorised.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{K}$: Commutation matrix.
  • $\otimes$: Kronecker product.

The radius of each ellipsoid is the one k_ucs returns for ue.alg.method, and that algorithm states its own closed form. The significance level reaches it undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  6. Fit the mean ellipsoid with ellipsoidal_set on sigma_mu, passing nothing in place of a sample and pr.mu as the centre.
  7. Fit the covariance ellipsoid the same way on sigma_sigma, with pr.sigma as the centre.
  8. Return the two sets as a tuple, mean first.
  9. Before the two sets leave, write both back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::EllipsoidalUncertaintySet: Expected returns uncertainty set.
  • sigma_ucs::EllipsoidalUncertaintySet: Covariance uncertainty sets.

Related

source
PortfolioOptimisers.ucs — Method
ucs(ue::NormalUncertaintySet{Nothing, <:EllipsoidalUncertaintySetAlgorithm{<:Any, <:Any},
                             <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs ellipsoidal uncertainty sets for expected returns and covariance statistics under the assumption of normally distributed returns, using a generic ellipsoidal algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs. The two routes build the same shapes, so they differ only in the radius.

Mathematical definition

Ellipsoidal sets centred at the prior estimates, whose shapes are the two asymptotic covariances:

\[\begin{align} \mathbf{\Sigma}_{\boldsymbol{\mu}} &= \hat{\mathbf{\Sigma}} / T\,, \\ \mathbf{\Sigma}_{\mathbf{\Sigma}} &= T (\mathbf{I} + \mathbf{K})(\mathbf{\Sigma}_{\boldsymbol{\mu}} \otimes \mathbf{\Sigma}_{\boldsymbol{\mu}})\,. \end{align}\]

Where:

  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Asymptotic covariance of the covariance estimator, vectorised.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{K}$: Commutation matrix.
  • $\otimes$: Kronecker product.

The radius of each ellipsoid is the one k_ucs returns for ue.alg.method, and that algorithm states its own closed form. The significance level reaches it undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  6. Fit the mean ellipsoid with ellipsoidal_set on sigma_mu, passing nothing in place of a sample and pr.mu as the centre.
  7. Fit the covariance ellipsoid the same way on sigma_sigma, with pr.sigma as the centre.
  8. Return the two sets as a tuple, mean first.
  9. Before the two sets leave, write both back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::EllipsoidalUncertaintySet: Expected returns uncertainty set.
  • sigma_ucs::EllipsoidalUncertaintySet: Covariance uncertainty sets.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(ue::NormalUncertaintySet{Nothing, <:BoxUncertaintySetAlgorithm, <:Any, <:Any, <:Any},
       pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs a box uncertainty set for expected returns under the assumption of normally distributed returns.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

Mathematical definition

\[\begin{align} \boldsymbol{\mu}_{l} &= \boldsymbol{0}\,, \\ \mu_{u,i} &= 2 \Phi^{-1}\!\left(1 - \tfrac{q}{2}\right) \sqrt{(\hat{\mathbf{\Sigma}}/T)_{ii}}\,. \end{align}\]

Where:

  • $\boldsymbol{\mu}_{l}$, $\mu_{u,i}$: Lower and upper bounds for expected returns.
  • $\Phi^{-1}(1 - q/2)$: Normal complementary quantile.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.
  • $q$: Significance level.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Run normal_box_preamble on the prior result pr the set is calibrated on, giving sigma_mu and the halved q. The scaling parameter is dropped, because only the covariance set reads it.
  3. Build and return the mean set with mu_normal_box_set from pr.mu, sigma_mu and q.
  4. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::BoxUncertaintySet: Expected returns uncertainty set.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(ue::NormalUncertaintySet{Nothing,
                                <:EllipsoidalUncertaintySetAlgorithm{<:NormalKUncertaintyAlgorithm, <:Any},
                                <:Any, <:Any, <:Any},
       pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs an ellipsoidal uncertainty set for expected returns under the assumption of normally distributed returns, using a normal scaling algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The sample is the estimation error, not the level. k_ucs measures a Mahalanobis distance against the shape matrix, so step 4 draws from the sampling law of the estimator, $\mathcal{N}(\hat{\boldsymbol{\mu}}, \hat{\mathbf{\Sigma}}/T)$, and centres the draws on $\hat{\boldsymbol{\mu}}$. A draw from $\mathcal{N}(\hat{\boldsymbol{\mu}}, \hat{\mathbf{\Sigma}})$ in its place multiplies every deviation, and therefore the radius, by $\sqrt{T}$.

Mathematical definition

\[\mathcal{E}_{\boldsymbol{\mu}} = \left\{\boldsymbol{\mu} : (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}})^{\intercal} \mathbf{\Sigma}_{\boldsymbol{\mu}}^{-1} (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}}) \leq k_{\boldsymbol{\mu}}^2 \right\}\,, \qquad \mathbf{\Sigma}_{\boldsymbol{\mu}} = \hat{\mathbf{\Sigma}} / T\,.\]

Where:

  • $\mathcal{E}_{\boldsymbol{\mu}}$: Ellipsoidal uncertainty set for expected returns.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\hat{\boldsymbol{\mu}}$: Estimated expected returns vector.
  • $k_{\boldsymbol{\mu}}$: Empirically fitted radius, the $1 - q$ quantile of the sampled Mahalanobis distances.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read mu and sigma from it.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Resolve the random number generator with resolve_rng, and draw the sample with normal_mu_error_sample, giving X_mu, one estimation error per row.
  6. Fit and return the ellipsoid with ellipsoidal_set on X_mu and sigma_mu, with pr.mu as the centre.
  7. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::EllipsoidalUncertaintySet: Expected returns uncertainty set.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(ue::NormalUncertaintySet{Nothing, <:EllipsoidalUncertaintySetAlgorithm{<:Any, <:Any},
                                <:Any, <:Any, <:Any},
       pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs an ellipsoidal uncertainty set for expected returns under the assumption of normally distributed returns, using a generic ellipsoidal algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The shape matrix is $\hat{\mathbf{\Sigma}} / T$ of Equation 11.24. This method runs no simulation, so it serves every radius algorithm that reads none, which is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs, and builds the same shape.

Mathematical definition

\[\mathcal{E}_{\boldsymbol{\mu}} = \left\{\boldsymbol{\mu} : (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}})^{\intercal} \mathbf{\Sigma}_{\boldsymbol{\mu}}^{-1} (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}}) \leq k_{\boldsymbol{\mu}}^2 \right\}\,, \qquad \mathbf{\Sigma}_{\boldsymbol{\mu}} = \hat{\mathbf{\Sigma}} / T\,.\]

Where:

  • $\mathcal{E}_{\boldsymbol{\mu}}$: Ellipsoidal uncertainty set for expected returns.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\hat{\boldsymbol{\mu}}$: Estimated expected returns vector.
  • $k_{\boldsymbol{\mu}}$: Radius, the one k_ucs returns for ue.alg.method.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.

The significance level reaches k_ucs undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Fit and return the ellipsoid with ellipsoidal_set on sigma_mu, passing nothing in place of a sample and pr.mu as the centre.
  6. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::EllipsoidalUncertaintySet: Expected returns uncertainty set.

Related

source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(ue::NormalUncertaintySet{Nothing, <:EllipsoidalUncertaintySetAlgorithm{<:Any, <:Any},
                                <:Any, <:Any, <:Any},
       pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs an ellipsoidal uncertainty set for expected returns under the assumption of normally distributed returns, using a generic ellipsoidal algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The shape matrix is $\hat{\mathbf{\Sigma}} / T$ of Equation 11.24. This method runs no simulation, so it serves every radius algorithm that reads none, which is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs, and builds the same shape.

Mathematical definition

\[\mathcal{E}_{\boldsymbol{\mu}} = \left\{\boldsymbol{\mu} : (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}})^{\intercal} \mathbf{\Sigma}_{\boldsymbol{\mu}}^{-1} (\boldsymbol{\mu} - \hat{\boldsymbol{\mu}}) \leq k_{\boldsymbol{\mu}}^2 \right\}\,, \qquad \mathbf{\Sigma}_{\boldsymbol{\mu}} = \hat{\mathbf{\Sigma}} / T\,.\]

Where:

  • $\mathcal{E}_{\boldsymbol{\mu}}$: Ellipsoidal uncertainty set for expected returns.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\hat{\boldsymbol{\mu}}$: Estimated expected returns vector.
  • $k_{\boldsymbol{\mu}}$: Radius, the one k_ucs returns for ue.alg.method.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.

The significance level reaches k_ucs undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Fit and return the ellipsoid with ellipsoidal_set on sigma_mu, passing nothing in place of a sample and pr.mu as the centre.
  6. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::EllipsoidalUncertaintySet: Expected returns uncertainty set.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(ue::NormalUncertaintySet{Nothing, <:BoxUncertaintySetAlgorithm, <:Any, <:Any, <:Any},
          pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs a box uncertainty set for covariance under the assumption of normally distributed returns.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

Mathematical definition

Simulates $M$ matrices $\hat{\mathbf{\Sigma}}^{(m)} \sim \mathrm{Wishart}(T,\,\hat{\mathbf{\Sigma}}/T)$ and takes element-wise quantiles:

\[\begin{align} (\mathbf{\Sigma}_{l})_{ij} &= Q_{q/2}\!\left(\hat{\Sigma}^{(m)}_{ij}\right)\,, \\ (\mathbf{\Sigma}_{u})_{ij} &= Q_{1-q/2}\!\left(\hat{\Sigma}^{(m)}_{ij}\right)\,. \end{align}\]

Where:

  • $(\mathbf{\Sigma}_{l})_{ij}$, $(\mathbf{\Sigma}_{u})_{ij}$: Element-wise lower/upper covariance bounds.
  • $Q_{q/2}$, $Q_{1-q/2}$: Lower and upper quantile functions at level $q/2$.
  • $\hat{\Sigma}^{(m)}_{ij}$: $(i,j)$-element of the $m$-th Wishart draw.
  • $T$: Number of observations.
  • $q$: Significance level.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Run normal_box_preamble on the prior result pr the set is calibrated on, giving T, sigma_mu and the halved q.
  3. Build and return the covariance set with sigma_normal_box_set from ue, pr, T, sigma_mu and q.
  4. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • sigma_ucs::BoxUncertaintySet: Covariance uncertainty set.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(ue::NormalUncertaintySet{Nothing,
                                   <:EllipsoidalUncertaintySetAlgorithm{<:NormalKUncertaintyAlgorithm, <:Any},
                                   <:Any, <:Any, <:Any},
          pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs an ellipsoidal uncertainty set for covariance under the assumption of normally distributed returns, using a normal scaling algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The sample is the estimation error, not the level. The draws of step 4 are subtracted from $\hat{\mathbf{\Sigma}}$, and the variance of an entry of a $\mathrm{Wishart}(T, \hat{\mathbf{\Sigma}}/T)$ draw is the matching diagonal entry of $\mathbf{\Sigma}_{\mathbf{\Sigma}}$, so the sample and the shape it is measured against are on one scale. N is read from size(pr.X, 2), the same source ucs reads it from, so a prior that changes the asset count moves both, and the two shape matrices are equal.

The radius is not the one ucs fits, under the same seed. Issue #590 holds the decision on whether to change that. This method draws its Wishart matrices off a generator that nothing has advanced. ucs resolves one generator and draws its mean sample off it first, so its Wishart draws differ from these. Both radii are valid fits of the same quantity, and only the box route makes the two entry points agree entry for entry.

Mathematical definition

\[\mathcal{E}_{\mathbf{\Sigma}} = \left\{\mathbf{\Sigma} : \left\lVert \mathbf{\Sigma}_{\mathbf{\Sigma}}^{-1/2} \operatorname{vec}(\mathbf{\Sigma} - \hat{\mathbf{\Sigma}}) \right\rVert_2 \leq k_{\mathbf{\Sigma}} \right\}\,, \qquad \mathbf{\Sigma}_{\mathbf{\Sigma}} = T (\mathbf{I} + \mathbf{K})(\mathbf{\Sigma}_{\boldsymbol{\mu}} \otimes \mathbf{\Sigma}_{\boldsymbol{\mu}})\,.\]

Where:

  • $\mathcal{E}_{\mathbf{\Sigma}}$: Ellipsoidal uncertainty set for the covariance matrix.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Asymptotic covariance of the covariance estimator, vectorised.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{K}$: Commutation matrix.
  • $\otimes$: Kronecker product.
  • $k_{\mathbf{\Sigma}}$: Empirically fitted radius, the $1 - q$ quantile of the sampled Mahalanobis distances.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma and N = size(pr.X, 2).
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Resolve the random number generator with resolve_rng, and draw the sample with normal_sigma_error_sample, giving X_sigma, one vectorised estimation error per row.
  6. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  7. Fit and return the ellipsoid with ellipsoidal_set on X_sigma and sigma_sigma, with pr.sigma as the centre.
  8. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • sigma_ucs::EllipsoidalUncertaintySet: Covariance uncertainty set.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(ue::NormalUncertaintySet{Nothing,
                                   <:EllipsoidalUncertaintySetAlgorithm{<:Any, <:Any},
                                   <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs an ellipsoidal uncertainty set for covariance under the assumption of normally distributed returns, using a generic ellipsoidal algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs. The two routes build the same shapes, so they differ only in the radius.

Mathematical definition

\[\mathcal{E}_{\mathbf{\Sigma}} = \left\{\mathbf{\Sigma} : \left\lVert \mathbf{\Sigma}_{\mathbf{\Sigma}}^{-1/2} \operatorname{vec}(\mathbf{\Sigma} - \hat{\mathbf{\Sigma}}) \right\rVert_2 \leq k_{\mathbf{\Sigma}} \right\}\,, \qquad \mathbf{\Sigma}_{\mathbf{\Sigma}} = T (\mathbf{I} + \mathbf{K})(\mathbf{\Sigma}_{\boldsymbol{\mu}} \otimes \mathbf{\Sigma}_{\boldsymbol{\mu}})\,.\]

Where:

  • $\mathcal{E}_{\mathbf{\Sigma}}$: Ellipsoidal uncertainty set for the covariance matrix.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Asymptotic covariance of the covariance estimator, vectorised.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator, $\hat{\mathbf{\Sigma}} / T$.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{K}$: Commutation matrix.
  • $\otimes$: Kronecker product.
  • $k_{\mathbf{\Sigma}}$: Radius, the one k_ucs returns for ue.alg.method.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.

The significance level reaches k_ucs undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  6. Fit and return the ellipsoid with ellipsoidal_set on sigma_sigma, passing nothing in place of a sample and pr.sigma as the centre.
  7. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • sigma_ucs::EllipsoidalUncertaintySet: Covariance uncertainty set.

Related

source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(ue::NormalUncertaintySet{Nothing,
                                   <:EllipsoidalUncertaintySetAlgorithm{<:Any, <:Any},
                                   <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs an ellipsoidal uncertainty set for covariance under the assumption of normally distributed returns, using a generic ellipsoidal algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs. The two routes build the same shapes, so they differ only in the radius.

Mathematical definition

\[\mathcal{E}_{\mathbf{\Sigma}} = \left\{\mathbf{\Sigma} : \left\lVert \mathbf{\Sigma}_{\mathbf{\Sigma}}^{-1/2} \operatorname{vec}(\mathbf{\Sigma} - \hat{\mathbf{\Sigma}}) \right\rVert_2 \leq k_{\mathbf{\Sigma}} \right\}\,, \qquad \mathbf{\Sigma}_{\mathbf{\Sigma}} = T (\mathbf{I} + \mathbf{K})(\mathbf{\Sigma}_{\boldsymbol{\mu}} \otimes \mathbf{\Sigma}_{\boldsymbol{\mu}})\,.\]

Where:

  • $\mathcal{E}_{\mathbf{\Sigma}}$: Ellipsoidal uncertainty set for the covariance matrix.
  • $\mathbf{\Sigma}_{\mathbf{\Sigma}}$: Asymptotic covariance of the covariance estimator, vectorised.
  • $\mathbf{\Sigma}_{\boldsymbol{\mu}}$: Asymptotic covariance of the mean estimator, $\hat{\mathbf{\Sigma}} / T$.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{K}$: Commutation matrix.
  • $\otimes$: Kronecker product.
  • $k_{\mathbf{\Sigma}}$: Radius, the one k_ucs returns for ue.alg.method.
  • $\hat{\mathbf{\Sigma}}$: Estimated covariance matrix.
  • $T$: Number of observations.

The significance level reaches k_ucs undivided, because an ellipsoid cuts only the upper tail of a distance that cannot be negative.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter.
  4. Build the mean shape sigma_mu with mu_asymptotic_cov.
  5. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  6. Fit and return the ellipsoid with ellipsoidal_set on sigma_sigma, passing nothing in place of a sample and pr.sigma as the centre.
  7. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • sigma_ucs::EllipsoidalUncertaintySet: Covariance uncertainty set.

Related

source
PortfolioOptimisers.ucs — Method
ucs(ue::NormalUncertaintySet{Nothing,
                             <:NormBallUncertaintySetAlgorithm{<:NormalKUncertaintyAlgorithm, <:Any, <:Any},
                             <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs norm-ball uncertainty sets for expected returns and covariance statistics under the assumption of normally distributed returns, using a normal scaling algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The two sets are the two ellipsoids of the sibling route with their shape matrices factorised, so they name the same region and reach the same weights. The gain is on the consumer's side: a NormBallUncertaintySet carries the factor, so neither builder factorises anything at solve time. This route draws the sample the empirical radius reads, off one generator, so its Wishart draws follow its normal draws.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read mu, sigma and N = size(pr.X, 2).
  3. Resolve the scaling parameter T with choose_scaling_parameter, and build the mean shape sigma_mu with mu_asymptotic_cov.
  4. Resolve one generator with resolve_rng, and draw the two samples with normal_mu_error_sample and normal_sigma_error_sample, mean first.
  5. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  6. Assemble the two sets with norm_ball_set, on the mean shape and on the covariance shape, and return them as a tuple, mean first.
  7. Before the two sets leave, write both back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::NormBallUncertaintySet: Expected returns uncertainty set.
  • sigma_ucs::NormBallUncertaintySet: Covariance uncertainty set.

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equations 11.16, 11.17 and 11.24.
  • [88] 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(ue::NormalUncertaintySet{Nothing, <:NormBallUncertaintySetAlgorithm{<:Any, <:Any, <:Any},
                             <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs norm-ball uncertainty sets for expected returns and covariance statistics under the assumption of normally distributed returns, using a generic radius algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs. The two routes build the same maps, so they differ only in the radius.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter, and build the mean shape sigma_mu with mu_asymptotic_cov.
  4. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  5. Assemble the two sets with norm_ball_set, passing nothing in place of a sample, and return them as a tuple, mean first.
  6. Before the two sets leave, write both back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::NormBallUncertaintySet: Expected returns uncertainty set.
  • sigma_ucs::NormBallUncertaintySet: Covariance uncertainty set.

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equations 11.16, 11.17 and 11.24.
  • [89] D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003). Section 5.
source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(ue::NormalUncertaintySet{Nothing,
                                <:NormBallUncertaintySetAlgorithm{<:NormalKUncertaintyAlgorithm, <:Any, <:Any},
                                <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs a norm-ball uncertainty set for expected returns under the assumption of normally distributed returns, using a normal scaling algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The map is the factor of $\hat{\mathbf{\Sigma}} / T$, so the set is the mean ellipsoid of the sibling route with its shape factorised. This method draws its normal sample off a generator that nothing has advanced, which is the same stream position ucs draws its own mean sample from, so the two radii agree under one seed.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read mu and sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter, and build the mean shape sigma_mu with mu_asymptotic_cov.
  4. Resolve the generator with resolve_rng, and draw the sample with normal_mu_error_sample.
  5. Assemble and return the set with norm_ball_set, with pr.mu as the centre.
  6. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::NormBallUncertaintySet: Expected returns uncertainty set.

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equation 11.24.
  • [88] A. Ben-Tal and A. Nemirovski. Robust Convex Optimization. Mathematics of Operations Research 23, 769–805 (1998). Section 3, Equation 14.
source
PortfolioOptimisers.mu_ucs — Method
mu_ucs(ue::NormalUncertaintySet{Nothing, <:NormBallUncertaintySetAlgorithm{<:Any, <:Any, <:Any},
                                <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs a norm-ball uncertainty set for expected returns under the assumption of normally distributed returns, using a generic radius algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs, and builds the same map.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter, and build the mean shape sigma_mu with mu_asymptotic_cov.
  4. Assemble and return the set with norm_ball_set, passing nothing in place of a sample and pr.mu as the centre.
  5. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • mu_ucs::NormBallUncertaintySet: Expected returns uncertainty set.

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equation 11.24.
  • [89] D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003). Section 5.
source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(ue::NormalUncertaintySet{Nothing,
                                   <:NormBallUncertaintySetAlgorithm{<:NormalKUncertaintyAlgorithm, <:Any, <:Any},
                                   <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs a norm-ball uncertainty set for covariance under the assumption of normally distributed returns, using a normal scaling algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

The map is the factor of the vectorised covariance's asymptotic covariance, so the set is the covariance ellipsoid of the sibling route with its shape factorised. The radius is not the one ucs fits, under the same seed, because this method draws its Wishart matrices off a generator that nothing has advanced while ucs draws its mean sample first. Both radii are valid fits of the same quantity.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma and N = size(pr.X, 2).
  3. Resolve the scaling parameter T with choose_scaling_parameter, and build the mean shape sigma_mu with mu_asymptotic_cov.
  4. Resolve the generator with resolve_rng, and draw the sample with normal_sigma_error_sample.
  5. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  6. Assemble and return the set with norm_ball_set, with pr.sigma as the centre.
  7. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • sigma_ucs::NormBallUncertaintySet: Covariance uncertainty set.

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equations 11.17 and 11.24.
  • [88] A. Ben-Tal and A. Nemirovski. Robust Convex Optimization. Mathematics of Operations Research 23, 769–805 (1998). Section 3, Equation 14.
source
PortfolioOptimisers.sigma_ucs — Method
sigma_ucs(ue::NormalUncertaintySet{Nothing, <:NormBallUncertaintySetAlgorithm{<:Any, <:Any, <:Any},
                                   <:Any, <:Any, <:Any}, pr::AbstractPriorResult; rd = nothing, kwargs...)

Constructs a norm-ball uncertainty set for covariance under the assumption of normally distributed returns, using a generic radius algorithm.

This is the prior-result arm of the verb, defined for a set whose pe is nothing. Inside an optimiser pr is the prior the optimiser is solving on, so the set is centred on the objective's own mu and folds with it under the online step; standalone it takes prior(pe, X) spelled out. The returns-data arm of the same verb fits the set's own prior through ucs_prior and forwards here, so the two routes share this one body.

This route runs no simulation, so it serves every radius algorithm that reads no sample. That is ChiSqKUncertaintyAlgorithm, GeneralKUncertaintyAlgorithm, and a plain number. Its sibling on NormalKUncertaintyAlgorithm draws the sample that the empirical radius needs, and builds the same map.

Algorithm

  1. Reduce the prior result to the Investable Mask with investable_ucs_reduction. Inside an optimiser the result arrives already reduced and the step is a passthrough; standalone, on a prior fitted on a point-in-time Asset Panel, it takes the view the optimiser would have taken.
  2. Take the prior result pr the set is calibrated on, and read sigma = pr.sigma.
  3. Resolve the scaling parameter T with choose_scaling_parameter, and build the mean shape sigma_mu with mu_asymptotic_cov.
  4. Build the covariance shape sigma_sigma with sigma_asymptotic_cov.
  5. Assemble and return the set with norm_ball_set, passing nothing in place of a sample and pr.sigma as the centre.
  6. Before the set leaves, write it back onto the full universe with expand_investable_ucs, so a set fitted standalone is over the same assets the prior is, and a view of it at the mask recovers the reduced fit.

Arguments

  • ue: Normal uncertainty set estimator with no prior of its own.
  • pr: Fitted prior result the set is calibrated on.
  • rd: Returns result the three-argument form passes beside the prior. Not read.
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • sigma_ucs::NormBallUncertaintySet: Covariance uncertainty set.

Related

References

  • [5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Equations 11.17 and 11.24.
  • [89] D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003). Section 5.
source

References

[5]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
[25]
A. Meucci. Risk and Asset Allocation (Springer Berlin Heidelberg, 2005).
[87]
F. J. Fabozzi, P. N. Kolm, D. A. Pachamanova and S. M. Focardi. Robust Portfolio Optimization and Management (John Wiley & Sons, Hoboken, NJ, 2007).
[88]
A. Ben-Tal and A. Nemirovski. Robust Convex Optimization. Mathematics of Operations Research 23, 769–805 (1998).
[89]
D. Goldfarb and G. Iyengar. Robust Portfolio Selection Problems. Mathematics of Operations Research 28, 1–38 (2003).