Base Uncertainty Sets

PortfolioOptimisers.BoxUncertaintySet Type

struct BoxUncertaintySet{__T_lb, __T_ub} <: AbstractUncertaintySetResult

Represents a box uncertainty set for risk or prior statistics in portfolio optimisation. Stores lower and upper bounds for the uncertain quantity, such as expected returns or covariance.

Mathematical definition

$$\begin{array}{rl}{U}_{\mathit{\mu }}^{\text{box}}& =\{\mathit{\mu }||\mathit{\mu }-\hat{\mathit{\mu }}|\le \delta \}\\ U_{\mathbf{\Sigma }}^{\text{box}}& =\{\mathbf{\Sigma }|{\mathbf{\Sigma }}_l\le \mathbf{\Sigma }\le {\mathbf{\Sigma }}_u,\mathbf{\Sigma }⪰0\}.\end{array}$$

Where:

• $U_{\mathit{\mu }}^{\text{box}}$: Box uncertainty set for expected returns.

• $U_{\mathbf{\Sigma }}^{\text{box}}$: Box uncertainty set for the covariance matrix.

• $\mathit{\mu }$, $\mathbf{\Sigma }$: Uncertain expected returns and covariance.

• $\hat{\mathit{\mu }}$: Estimated (reference) mean vector.

• $\delta$: Half-width of the box (element-wise).

• ${\mathbf{\Sigma }}_l$, ${\mathbf{\Sigma }}_u$: Lower and upper bounds for the covariance matrix.

• $\mathbf{\Sigma }⪰0$: Positive semi-definiteness constraint.

Fields

• lb: Lower bound.

• ub: Upper bound.

Constructors

BoxUncertaintySet(;
    lb::ArrNum,
    ub::ArrNum
) -> BoxUncertaintySet

Keywords correspond to the struct's fields.

Validation

• !isempty(lb).

• !isempty(ub).

• size(lb) == size(ub).

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]

Related

• BoxUncertaintySetAlgorithm

• AbstractUncertaintySetResult

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.BoxUncertaintySetAlgorithm Type

struct BoxUncertaintySetAlgorithm <: AbstractUncertaintySetAlgorithm

Algorithm for constructing box uncertainty sets in portfolio optimisation. Box uncertainty sets model uncertainty by specifying lower and upper bounds for risk or prior statistics.

Related

• BoxUncertaintySet

• AbstractUncertaintySetAlgorithm

• EllipsoidalUncertaintySetAlgorithm

source

PortfolioOptimisers.MuEllipsoidalUncertaintySet Type

struct MuEllipsoidalUncertaintySet <: AbstractEllipsoidalUncertaintySetResultClass

Represents the class identifier for mean ellipsoidal uncertainty sets in portfolio optimisation.

Used to distinguish ellipsoidal uncertainty sets that encode uncertainty for mean statistics, such as expected returns.

Related

• AbstractEllipsoidalUncertaintySetResultClass

• SigmaEllipsoidalUncertaintySet

source

PortfolioOptimisers.SigmaEllipsoidalUncertaintySet Type

struct SigmaEllipsoidalUncertaintySet <: AbstractEllipsoidalUncertaintySetResultClass

Represents the class identifier for covariance ellipsoidal uncertainty sets in portfolio optimisation.

Used to distinguish ellipsoidal uncertainty sets that encode uncertainty for covariance statistics, such as covariance matrices.

Related

• AbstractEllipsoidalUncertaintySetResultClass

• MuEllipsoidalUncertaintySet

source

PortfolioOptimisers.NormalKUncertaintyAlgorithm Type

struct NormalKUncertaintyAlgorithm{__T_kwargs} <: AbstractUncertaintyKAlgorithm

Algorithm for computing the scaling parameter k for ellipsoidal uncertainty sets under the assumption of normally distributed returns in portfolio optimisation.

Fields

• kwargs: Additional keyword arguments.

Constructors

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

Keyword arguments correspond to the field above.

Validation

• kwargs must be a valid NamedTuple.

Examples

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

Related

• AbstractUncertaintyKAlgorithm

• GeneralKUncertaintyAlgorithm

• ChiSqKUncertaintyAlgorithm

• k_ucs

source

PortfolioOptimisers.GeneralKUncertaintyAlgorithm Type

struct GeneralKUncertaintyAlgorithm <: AbstractUncertaintyKAlgorithm

Algorithm for computing the scaling parameter k for ellipsoidal uncertainty sets using a general formula sqrt((1 - q) / q), this ignores the distribution of the underlying data.

Related

• AbstractUncertaintyKAlgorithm

• NormalKUncertaintyAlgorithm

• ChiSqKUncertaintyAlgorithm

• k_ucs

source

PortfolioOptimisers.ChiSqKUncertaintyAlgorithm Type

struct ChiSqKUncertaintyAlgorithm <: AbstractUncertaintyKAlgorithm

Algorithm for computing the scaling parameter k for ellipsoidal uncertainty sets using the chi-squared distribution in portfolio optimisation.

Related

• AbstractUncertaintyKAlgorithm

• NormalKUncertaintyAlgorithm

• GeneralKUncertaintyAlgorithm

• k_ucs

source

PortfolioOptimisers.EllipsoidalUncertaintySet Type

struct EllipsoidalUncertaintySet{__T_sigma, __T_k, __T_class} <: AbstractUncertaintySetResult

Represents an ellipsoidal uncertainty set for risk or prior statistics in portfolio optimisation. Stores a covariance matrix, a scaling parameter, and a class identifier for the uncertain quantity, such as expected returns or covariance.

Mathematical definition

$$\begin{array}{rl}{U}_{\mathit{\mu }}^{\text{ellip}}& =\{\mathit{\mu }|{(\mathit{\mu }-\hat{\mathit{\mu }})}^{⊺}{\mathbf{\Sigma }}_{\mathit{\mu }}^{-1}(\mathit{\mu }-\hat{\mathit{\mu }})\le k_{\mathit{\mu }}^2\}\\ U_{\mathbf{\Sigma }}^{\text{ellip}}& =\{\mathbf{\Sigma }|{(\text{vec}\left(\mathbf{\Sigma }\right)-\text{vec}\left(\hat{\mathbf{\Sigma }}\right))}^{⊺}{\mathbf{\Sigma }}_{\mathbf{\Sigma }}^{-1}(\text{vec}\left(\mathbf{\Sigma }\right)-\text{vec}\left(\hat{\mathbf{\Sigma }}\right))\le k_{\mathbf{\Sigma }}^2,\mathbf{\Sigma }⪰0\}.\end{array}$$

Where:

• $U_{\mathit{\mu }}^{\text{ellip}}$: Ellipsoidal uncertainty set for expected returns.

• $U_{\mathbf{\Sigma }}^{\text{ellip}}$: Ellipsoidal uncertainty set for covariance matrix.

• $\mathit{\mu }$, $\mathbf{\Sigma }$: Uncertain expected returns and covariance.

• $\hat{\mathit{\mu }}$, $\hat{\mathbf{\Sigma }}$: Estimated reference mean and covariance.

• ${\mathbf{\Sigma }}_{\mathit{\mu }}$: Covariance matrix of estimation error in mean.

• ${\mathbf{\Sigma }}_{\mathbf{\Sigma }}$: Covariance matrix of estimation error in covariance (vectorised).

• $k_{\mathit{\mu }}^2$, $k_{\mathbf{\Sigma }}^2$: Scaling parameters (squared ellipsoid radii).

• $\text{vec}(\cdot )$: Vectorisation operator (column-stacking).

• $\mathbf{\Sigma }⪰0$: Positive semi-definiteness constraint.

Fields

• sigma: Covariance matrix features × features.

• k: Uncertainty set scaling parameter.

• class: Uncertainty set class.

Constructors

EllipsoidalUncertaintySet(;
    sigma::MatNum,
    k::Number,
    class::AbstractEllipsoidalUncertaintySetResultClass
) -> EllipsoidalUncertaintySet

Keywords correspond to the struct's fields.

Validation

• !isempty(sigma).

• size(sigma, 1) == size(sigma, 2).

• k > 0.

Examples

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

Related

• AbstractEllipsoidalUncertaintySetResultClass

• AbstractUncertaintySetResult

• BoxUncertaintySet

• k_ucs

source

PortfolioOptimisers.EllipsoidalUncertaintySetAlgorithm Type

struct EllipsoidalUncertaintySetAlgorithm{__T_method, __T_diagonal} <: AbstractUncertaintySetAlgorithm

Algorithm for constructing ellipsoidal uncertainty sets in portfolio optimisation. Ellipsoidal uncertainty sets model uncertainty by specifying an ellipsoidal region for risk or prior statistics, typically using a covariance matrix and a scaling parameter.

Fields

• method: Ellipsoidal uncertainty set estimation method.

• diagonal: Whether to use only the diagonal of the covariance matrix.

Constructors

EllipsoidalUncertaintySetAlgorithm(;
    method::Num_UcSK = ChiSqKUncertaintyAlgorithm(),
    diagonal::Bool = true
) -> EllipsoidalUncertaintySetAlgorithm

• method: Sets the scaling algorithm or value for the ellipsoidal.

• diagonal: Sets whether to use only diagonal elements.

Examples

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

Related

• AbstractUncertaintySetAlgorithm

• AbstractUncertaintyKAlgorithm

• EllipsoidalUncertaintySet

• BoxUncertaintySetAlgorithm

source

PortfolioOptimisers.ucs Method

ucs(uc::Option{<:Tuple{<:Option{<:AbstractUncertaintySetResult},
                       <:Option{<:AbstractUncertaintySetResult}}}, args...; kwargs...)

Returns the argument(s) unchanged. This is a no-op function used to handle cases where uncertainty sets are pre-processed (nothing or a tuple of results).

Arguments

• uc: Tuple of uncertainty sets, or nothing.

• args...: Additional positional arguments (ignored).

• kwargs...: Additional keyword arguments (ignored).

Returns

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

Related

• mu_ucs

• sigma_ucs

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.ucs Method

ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult; kwargs...)

Constructs an uncertainty set from a given estimator and returns data.

Arguments

• uc: Uncertainty set estimator. Used to construct the uncertainty set.

• rd: ReturnsResult. Contains the returns data and associated metadata.

• kwargs...: Additional keyword arguments passed to the estimator.

Returns

• uc::Tuple{<:AbstractUncertaintySetResult, <:AbstractUncertaintySetResult}: Expected returns and covariance uncertainty sets.

Details

• Calls the estimator on the returns data and metadata in rd.

• Passes rd.X, rd.F, and relevant metadata (iv, ivpa) to the estimator.

• Additional keyword arguments are forwarded.

• Used for compatibility with ReturnsResult objects.

Related

• mu_ucs

• sigma_ucs

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.mu_ucs Method

mu_ucs(uc::Option{<:AbstractUncertaintySetResult}, args...; kwargs...)

Returns the argument unchanged. This is a no-op function used to handle cases where the expected returns uncertainty set is already a result or is absent (nothing).

Arguments

• uc: Expected returns uncertainty set or nothing.

• args...: Additional positional arguments (ignored).

• kwargs...: Additional keyword arguments (ignored).

Returns

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

Related

• ucs

• sigma_ucs

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.mu_ucs Method

mu_ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult; kwargs...)

Constructs an expected returns uncertainty set from a given estimator and returns data.

Arguments

• uc: Uncertainty set estimator. Used to construct the expected returns uncertainty set.

• rd: ReturnsResult. Contains the returns data and associated metadata.

• kwargs...: Additional keyword arguments passed to the estimator.

Returns

• uc::AbstractUncertaintySetResult: Expected returns uncertainty set.

Details

• Calls the estimator on the returns data and metadata in rd.

• Passes rd.X, rd.F, and relevant metadata (iv, ivpa) to the estimator.

• Additional keyword arguments are forwarded.

• Used for compatibility with ReturnsResult objects.

Related

• ucs

• sigma_ucs

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.sigma_ucs Method

sigma_ucs(uc::Option{<:AbstractUncertaintySetResult}, args...; kwargs...)

Returns the argument unchanged. This is a no-op function used to handle cases where the covariance uncertainty set is already a result or is absent (nothing).

Arguments

• uc: Covariance uncertainty set or nothing.

• args...: Additional positional arguments (ignored).

• kwargs...: Additional keyword arguments (ignored).

Returns

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

Related

• ucs

• mu_ucs

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.sigma_ucs Method

sigma_ucs(uc::AbstractUncertaintySetEstimator, rd::ReturnsResult; kwargs...)

Constructs a covariance uncertainty set from a given estimator and returns data.

Arguments

• uc: Uncertainty set estimator. Used to construct the covariance uncertainty set.

• rd: ReturnsResult. Contains the returns data and associated metadata.

• kwargs...: Additional keyword arguments passed to the estimator.

Returns

• uc::AbstractUncertaintySetResult: Covariance uncertainty set.

Details

• Calls the estimator on the returns data and metadata in rd.

• Passes rd.X, rd.F, and relevant metadata (iv, ivpa) to the estimator.

• Additional keyword arguments are forwarded.

• Used for compatibility with ReturnsResult objects.

Related

• ucs

• mu_ucs

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.AbstractUncertaintySetEstimator Type

abstract type AbstractUncertaintySetEstimator <: AbstractEstimator

Defines the abstract interface for uncertainty set estimators in portfolio optimisation. Subtypes of this abstract type are responsible for constructing and estimating uncertainty sets for risk or prior statistics, such as box or ellipsoidal uncertainty sets.

Related

• AbstractUncertaintySetResult

• AbstractUncertaintySetAlgorithm

source

PortfolioOptimisers.AbstractUncertaintySetAlgorithm Type

abstract type AbstractUncertaintySetAlgorithm <: AbstractAlgorithm

Defines the abstract interface for algorithms that construct uncertainty sets in portfolio optimisation. Subtypes implement specific methods for generating uncertainty sets, such as box or ellipsoidal uncertainty sets, which are used to model uncertainty in risk or prior statistics.

Related

• BoxUncertaintySetAlgorithm

• EllipsoidalUncertaintySetAlgorithm

• AbstractUncertaintySetEstimator

• AbstractUncertaintySetResult

source

PortfolioOptimisers.AbstractUncertaintySetResult Type

abstract type AbstractUncertaintySetResult <: AbstractResult

Abstract type for results produced by uncertainty set algorithms in portfolio optimisation.

Represents the interface for all result types that encode uncertainty sets for risk or prior statistics, such as box or ellipsoidal uncertainty sets. Subtypes store the output of uncertainty set estimation or construction algorithms.

Related

• BoxUncertaintySet

• EllipsoidalUncertaintySet

• AbstractUncertaintySetAlgorithm

• AbstractUncertaintySetEstimator

source

PortfolioOptimisers.AbstractUncertaintyKAlgorithm Type

abstract type AbstractUncertaintyKAlgorithm <: AbstractAlgorithm

Defines the abstract interface for algorithms that compute the scaling parameter k for ellipsoidal uncertainty sets in portfolio optimisation.

Subtypes implement specific methods for generating the scaling parameter, which controls the size of the ellipsoidal region representing uncertainty in risk or prior statistics.

Related

• NormalKUncertaintyAlgorithm

• GeneralKUncertaintyAlgorithm

• ChiSqKUncertaintyAlgorithm

source

PortfolioOptimisers.UcSE_UcS Type

const UcSE_UcS = Union{<:AbstractUncertaintySetResult, <:AbstractUncertaintySetEstimator}

Alias for a union of uncertainty set result and estimator types.

Related

• AbstractUncertaintySetResult

• AbstractUncertaintySetEstimator

source

PortfolioOptimisers.Num_UcSK Type

const Num_UcSK = Union{<:AbstractUncertaintyKAlgorithm, <:Number}

Alias for a union of uncertainty scaling algorithm and numeric types.

Related

• AbstractUncertaintyKAlgorithm

source

PortfolioOptimisers.AbstractEllipsoidalUncertaintySetResultClass Type

abstract type AbstractEllipsoidalUncertaintySetResultClass <: AbstractUncertaintySetResult

Defines the abstract interface for ellipsoidal uncertainty set result classes in portfolio optimisation.

Subtypes of this abstract type represent the class or category of ellipsoidal uncertainty sets, such as those for mean or covariance statistics. Used to distinguish between different types of ellipsoidal uncertainty set results.

Related

• MuEllipsoidalUncertaintySet

• SigmaEllipsoidalUncertaintySet

source

PortfolioOptimisers.ucs_selector Function

ucs_selector(risk_ucs::Nothing, prior_ucs::Nothing)
ucs_selector(risk_ucs::UcSE_UcS, prior_ucs::Any)
ucs_selector(risk_ucs::Nothing, prior_ucs::UcSE_UcS)

Function for selecting uncertainty sets from risk measure or prior result instances.

Arguments

• risk_ucs: Risk measure uncertainty set estimator or result, or nothing.

• prior_ucs: Prior result uncertainty set estimator or result, or nothing.

Returns

Based on the argument types, returns one of the following:

• nothing: If both risk_ucs and prior_ucs are nothing.

• risk_ucs::UcSE_UcS: If risk_ucs is not nothing.

• prior_ucs::UcSE_UcS: If risk_ucs is nothing but prior_ucs is not nothing.

Related

• AbstractUncertaintySetResult

• AbstractUncertaintySetEstimator

• factory

source

PortfolioOptimisers.k_ucs Function

k_ucs(km::NormalKUncertaintyAlgorithm, q::Number, X::MatNum, sigma_X::MatNum)
k_ucs(::GeneralKUncertaintyAlgorithm, q::Number, args...)
k_ucs(::ChiSqKUncertaintyAlgorithm, q::Number, X::ArrNum, args...)
k_ucs(type::Number, args...)

Computes the scaling parameter k for ellipsoidal uncertainty sets in portfolio optimisation.

Arguments

• km: Scaling algorithm instance.

• q: Quantile or confidence level.

• X: Data matrix (returns).

• sigma_X: Covariance matrix.

• args...: Additional arguments.

• type: Number value for direct scaling.

Returns

• k::Number: Scaling parameter.

Details

• Uses different algorithms to compute the scaling parameter:

  • Normal: 1 - q-th quantile of the Mahalanobis distances.

  • General: formula sqrt((1 - q) / q).

  • Chi-squared: 1 - q-th quantile of the chi-squared distribution.

  • Number: returns the provided value directly.

• Supports multiple dispatch for extensibility.

Related

• NormalKUncertaintyAlgorithm

• GeneralKUncertaintyAlgorithm

• ChiSqKUncertaintyAlgorithm

• EllipsoidalUncertaintySetAlgorithm

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(risk_ucs, i)

Get a view or subset of an uncertainty set for asset cluster index i.

Returns the uncertainty set sliced for the given index, or unchanged for estimator types. Used in hierarchical optimisation to apply uncertainty sets per cluster.

Arguments

• risk_ucs: Uncertainty set result, estimator, or nothing.

• i: Cluster or asset index.

Returns

• Sliced uncertainty set or unchanged value.

Related

• AbstractUncertaintySetEstimator

• BoxUncertaintySet

• EllipsoidalUncertaintySet

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(
    risk_ucs::BoxUncertaintySet{<:AbstractVector{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}}, <:AbstractVector{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}}},
    i,
    args...
) -> BoxUncertaintySet{var"#s179", <:AbstractArray{var"#s21", N}} where {var"#s21"<:(Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}), N, var"#s179"<:AbstractArray{var"#s21", N}, var"#s21"<:(Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}), N}

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

Related

• BoxUncertaintySet

• port_opt_view

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(
    risk_ucs::BoxUncertaintySet{<:AbstractMatrix{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}}, <:AbstractMatrix{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}}},
    i,
    args...
) -> BoxUncertaintySet{var"#s179", <:AbstractArray{var"#s21", N}} where {var"#s21"<:(Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}), N, var"#s179"<:AbstractArray{var"#s21", N}, var"#s21"<:(Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}), N}

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

Related

• BoxUncertaintySet

• port_opt_view

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(
    risk_ucs::EllipsoidalUncertaintySet{<:AbstractMatrix{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}}, <:Any, <:SigmaEllipsoidalUncertaintySet},
    i,
    args...
) -> EllipsoidalUncertaintySet{<:AbstractMatrix{var"#s21"}, <:Number, SigmaEllipsoidalUncertaintySet} where var"#s21"<:(Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar})

Return a view of a covariance EllipsoidalUncertaintySet restricted to assets at index i, mapping the sigma index via cokurtosis index generation.

Related

• EllipsoidalUncertaintySet

• port_opt_view

source

PortfolioOptimisers.port_opt_view Method

port_opt_view(
    risk_ucs::EllipsoidalUncertaintySet{<:AbstractMatrix{<:Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar}}, <:Any, <:MuEllipsoidalUncertaintySet},
    i,
    args...
) -> EllipsoidalUncertaintySet{<:AbstractMatrix{var"#s21"}, <:Number, MuEllipsoidalUncertaintySet} where var"#s21"<:(Union{var"#s20", var"#s19"} where {var"#s20"<:Number, var"#s19"<:AbstractJuMPScalar})

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

Related

• EllipsoidalUncertaintySet

• port_opt_view

source