Base Risk Measures

PortfolioOptimisers.RiskMeasure Type

julia

abstract type RiskMeasure <: OptimisationRiskMeasure

Abstract supertype for standard risk measures used in portfolio optimisation.

Subtype RiskMeasure to implement concrete risk measures that quantify portfolio risk and can be used as objectives or constraints in optimisation problems. This type ensures compatibility with the optimisation framework and enables composability with other estimators and algorithms.

Related

PortfolioOptimisers.HierarchicalRiskMeasure Type

julia

abstract type HierarchicalRiskMeasure <: OptimisationRiskMeasure

Abstract supertype for hierarchical risk measures used in portfolio optimisation.

Subtype HierarchicalRiskMeasure to implement risk measures that operate on hierarchical or clustered portfolio structures. These measures are designed for use as objectives or constraints in optimisation problems that leverage asset clustering, hierarchical risk parity, or similar techniques.

Related

PortfolioOptimisers.Frontier Type

julia

struct Frontier{__T_N, __T_factor, __T_bound} <: AbstractAlgorithm

Defines the number of points on the efficient frontier (Pareto Front).

Fields

N: Number of points on the efficient frontier.
factor: Scaling factor for the efficient frontier range.
bound: What operation needs to be performed on the risk lower bound.

Constructors

julia

Frontier(;
    N::Integer = 20,
    bound::FrontierBoundEstimator = LinearBound()
) -> Frontier

Creates a Frontier with N points, a scaling factor of 1, and the specified bound strategy. Used to set appropriate frontier bounds in variance_risk_bounds_val and second_moment_bound_val.

julia

PortfolioOptimisers._Frontier(;
    N::Integer = 20,
    factor::Number,
    bound::FrontierBoundEstimator
) -> Frontier

Internal constructor. Keywords correspond to the struct's fields.

Validation

N > 0.
isfinite(factor) and factor > 0.

Examples

julia

julia> Frontier(; N = 15)
Frontier
       N ┼ Int64: 15
  factor ┼ Int64: 1
   bound ┴ LinearBound()

Related

PortfolioOptimisers.RiskMeasureSettings Type

julia

struct RiskMeasureSettings{__T_scale, __T_ub, __T_rke} <: JuMPRiskMeasureSettings

Settings type for configuring risk measure estimators in PortfolioOptimisers.jl. Encapsulates scaling, upper bounds, and risk evaluation flags for risk measures used in optimisation routines.

Fields

scale: Scaling factor applied to the risk measure.
ub: Upper bound(s) for the risk measure. Can be a scalar, vector, or Frontier.
rke: Whether to include the risk measure value in the JuMP risk expression.

Constructors

julia

RiskMeasureSettings(;
    scale::Number = 1.0,
    ub::Option{<:RkRtBounds} = nothing,
    rke::Bool = true,
) -> RiskMeasureSettings

Creates a RiskMeasureSettings instance with the specified scale, upper bound, and risk evaluation flag.

Validation

isfinite(scale).
ub is validated with assert_nonempty_nonneg_finite_val.

Examples

julia

julia> RiskMeasureSettings()
RiskMeasureSettings
  scale ┼ Float64: 1.0
     ub ┼ nothing
    rke ┴ Bool: true

Related

PortfolioOptimisers.HierarchicalRiskMeasureSettings Type

julia

struct HierarchicalRiskMeasureSettings{__T_scale} <: AbstractRiskMeasureSettings

Settings type for configuring hierarchical risk measure estimators in PortfolioOptimisers.jl.

Used for HierarchicalRiskMeasure, where it is impossible to set a risk upper bound.

Fields

scale: Scaling factor applied to the risk measure.

Constructors

julia

HierarchicalRiskMeasureSettings(;
    scale::Number,
) -> HierarchicalRiskMeasureSettings

Creates a HierarchicalRiskMeasureSettings instance with the specified scaling factor.

Validation

scale must be finite.

Examples

julia

julia> HierarchicalRiskMeasureSettings()
HierarchicalRiskMeasureSettings
  scale ┴ Float64: 1.0

Related

PortfolioOptimisers.SumScalariser Type

julia

struct SumScalariser <: NonHierarchicalScalariser

Scalariser that combines multiple risk measures using a weighted sum.

SumScalariser aggregates a vector of risk measures by computing the weighted sum of their scaled values. The weights are specified in the scale field of RiskMeasureSettings or HierarchicalRiskMeasureSettings. This scalarisation strategy is used in portfolio optimisation routines that require a single risk value from multiple risk measures.

\begin{aligned} ϕ & = \sum_{i = 1}^{N} w_{i} \cdot r_{i} . \end{aligned}

Where:

$N$ : Number of risk measures.
$i$ : Subscript denoting the i-th risk measure.
$r_{i}$ : i-th risk measure value.
$w_{i}$ : Weight of the i-th risk measure.

Related

PortfolioOptimisers.MaxScalariser Type

julia

struct MaxScalariser <: NonHierarchicalScalariser

Scalariser that selects the risk expression whose scaled value is the largest.

MaxScalariser aggregates a vector of risk measures by selecting the maximum of their scaled values. The weights are specified in the scale field of RiskMeasureSettings or HierarchicalRiskMeasureSettings. In clustering optimisations, the risk of each cluster is computed separately, so there is no coherence in which risk measure is chosen between clusters.

\begin{aligned} ϕ & = max_{i \in (1, N)} (w_{i} \cdot r_{i}) . \end{aligned}

Where:

$N$ : Number of risk measures.
$i$ : Subscript denoting the i-th risk measure.
$r_{i}$ : i-th risk measure value.
$w_{i}$ : Weight of the i-th risk measure.

Related

PortfolioOptimisers.MinScalariser Type

julia

struct MinScalariser <: HierarchicalScalariser

Scalariser that selects the risk expression whose scaled value is the largest.

MinScalariser aggregates a vector of risk measures by selecting the minimum of their scaled values. The weights are specified in the scale field of RiskMeasureSettings or HierarchicalRiskMeasureSettings. In clustering optimisations, the risk of each cluster is computed separately, so there is no coherence in which risk measure is chosen between clusters.

\begin{aligned} ϕ & = min_{i \in (1, N)} (w_{i} \cdot r_{i}) . \end{aligned}

Where:

$N$ : Number of risk measures.
$i$ : Subscript denoting the i-th risk measure.
$r_{i}$ : i-th risk measure value.
$w_{i}$ : Weight of the i-th risk measure.

Related

PortfolioOptimisers.LogSumExpScalariser Type

julia

struct LogSumExpScalariser{__T_gamma} <: NonHierarchicalScalariser

Scalariser that aggregates multiple risk measures using the log-sum-exp function.

LogSumExpScalariser combines a vector of risk measures by applying the log-sum-exp transformation to their scaled values. The weights are specified in the scale field of RiskMeasureSettings or HierarchicalRiskMeasureSettings.

The parameter gamma controls the approximation accuracy to the maximum function: as gamma → 0, the function approaches the weighted sum; as gamma → ∞, it approaches the maximum. This behaviour is only true in JuMP-based optimisations. In clustering optimisations, each cluster's risk is computed separately, so there is no coherence between clusters.

\begin{aligned} ϕ & = \frac{1}{γ} \log (\sum_{i = 1}^{N} \exp [γ \cdot w_{i} \cdot r_{i}]) . \end{aligned}

Where:

$N$ : Number of risk measures.
$i$ : Subscript denoting the i-th risk measure.
$r_{i}$ : i-th risk measure value.
$w_{i}$ : Weight of the i-th risk measure.
$γ$ : Positive parameter controlling the interpolation between the weighted sum and the maximum functions.

Fields

gamma: Log-sum-exp scalariser smoothing parameter.

Constructors

julia

LogSumExpScalariser(;
    gamma::Number = 1.0,
) -> LogSumExpScalariser

Keywords correspond to the struct's fields.

Validation

gamma > 0.

Examples

julia

julia> LogSumExpScalariser()
LogSumExpScalariser
  gamma ┴ Float64: 1.0

Related

PortfolioOptimisers.AbstractBaseRiskMeasure Type

julia

abstract type AbstractBaseRiskMeasure <: AbstractEstimator

Abstract supertype for all risk measure estimators in PortfolioOptimisers.jl.

Defines the interface for risk measure types, which quantify portfolio risk using various statistical or econometric methods. All concrete risk measure types should subtype AbstractBaseRiskMeasure to ensure consistency and composability within the optimisation framework.

All concrete risk measures can be used as functors (callable structs) to compute their associated risk quantity.

Related

PortfolioOptimisers.NonOptimisationRiskMeasure Type

julia

abstract type NonOptimisationRiskMeasure <: AbstractBaseRiskMeasure

Abstract supertype for risk measures that are not intended for use in portfolio optimisation routines.

These risk measures are typically used for analysis, reporting, or diagnostics, and are not designed to be included as objectives or constraints in optimisation problems. Subtype this when implementing a risk measure that should not be selectable by optimisation algorithms.

Related

PortfolioOptimisers.OptimisationRiskMeasure Type

julia

abstract type OptimisationRiskMeasure <: AbstractBaseRiskMeasure

Abstract supertype for risk measures that are intended for use in portfolio optimisation routines.

All concrete risk measures that can be used as objectives or constraints in optimisation problems should subtype OptimisationRiskMeasure. This ensures compatibility with the optimisation framework and enables composability with other estimators and algorithms.

Related

PortfolioOptimisers.AbstractRiskMeasureSettings Type

julia

abstract type AbstractRiskMeasureSettings <: AbstractEstimator

Abstract supertype for all risk measure settings in PortfolioOptimisers.jl.

Defines the interface for settings types that configure the behavior of risk measure estimators. All concrete risk measure settings types should subtype AbstractRiskMeasureSettings to ensure consistency and composability within the optimisation framework.

Related

PortfolioOptimisers.JuMPRiskMeasureSettings Type

julia

abstract type JuMPRiskMeasureSettings <: AbstractRiskMeasureSettings

Abstract supertype for risk measure settings used in JuMP-based optimisation routines.

All concrete settings types compatible with JuMP optimisation (e.g. RiskMeasureSettings, MaxRiskMeasureSettings) should subtype JuMPRiskMeasureSettings.

Related

PortfolioOptimisers.FrontierBoundEstimator Type

julia

abstract type FrontierBoundEstimator <: AbstractEstimator

Abstract supertype for bound-transformation strategies applied to efficient frontier bounds.

Concrete subtypes control how numeric bound values are transformed before being applied to JuMP risk expressions. All subtypes should subtype FrontierBoundEstimator.

Related

PortfolioOptimisers.LinearBound Type

julia

struct LinearBound <: FrontierBoundEstimator

Passes bound values through unchanged (identity transformation).

Used when the risk expression and the user-supplied bound are already in the same units (e.g. SDP variance formulation where both sides are in variance units).

Related

PortfolioOptimisers.SquareRootBound Type

julia

struct SquareRootBound <: FrontierBoundEstimator

Applies a square-root transformation to bound values before enforcing them.

Used when the risk expression is in standard-deviation units but the user-supplied bound is in variance units (e.g. kurtosis and negative-skewness SOC formulations).

Related

PortfolioOptimisers.SquaredBound Type

julia

struct SquaredBound <: FrontierBoundEstimator

Applies a squaring transformation to bound values before enforcing them.

Used when the risk expression is in squared units but the user-supplied bound is in linear units (e.g. kurtosis SDP formulation).

Related

PortfolioOptimisers.Scalariser Type

julia

abstract type Scalariser <: AbstractEstimator

Abstract supertype for scalarisation strategies used to combine multiple risk measures into a single scalar value for optimisation.

Subtype Scalariser to implement different methods for aggregating risk measures. These strategies are used in portfolio optimisation routines that require a single risk value from multiple risk measures.

Related

PortfolioOptimisers.NonHierarchicalScalariser Type

julia

abstract type NonHierarchicalScalariser <: Scalariser

Abstract supertype for scalarisation strategies that combine multiple risk measures into a single scalar value compatible with all portfolio optimisation estimators.

Subtype NonHierarchicalScalariser to implement aggregation methods that work with all optimisation estimators.

Related

PortfolioOptimisers.HierarchicalScalariser Type

julia

abstract type HierarchicalScalariser <: Scalariser

Abstract supertype for scalarisation strategies that combine multiple risk measures into a single scalar value compatible only with hierarchical optimisations.

Subtype HierarchicalScalariser to implement aggregation methods that only work with hierarchical optimisation estimators.

Related

PortfolioOptimisers.nothing_scalar_array_selector Function

julia

nothing_scalar_array_selector(risk_variable::Nothing, prior_variable::Nothing)
nothing_scalar_array_selector(risk_variable::Num_ArrNum_VecScalar_DynWeights, ::Any)
nothing_scalar_array_selector(risk_variable::Nothing, prior_variable::Num_ArrNum_VecScalar_DynWeights)

Function for selecting a non-nothing value when provided by a risk measure, or fall back to a value contained in a prior result

Arguments

risk_variable : The risk-side input.
prior_variable : The prior-side input.

Returns

If both inputs are nothing returns nothing.
If risk_variable is not nothing, returns risk_variable.
If risk_variable is nothing and prior_variable is not nothing, returns prior_variable.

PortfolioOptimisers.risk_measure_nothing_scalar_array_view Function

julia

risk_measure_nothing_scalar_array_view(risk_variable, prior_variable, i)

Get a view of a risk measure's risk or prior variable for index i.

Internal helper for slicing scalar, array, or nothing risk/prior variables by index. Dispatches on the types of risk_variable and prior_variable.

Arguments

risk_variable: Risk variable (scalar, array, or nothing).
prior_variable: Prior variable (array or nothing).
i: Index or range to slice.

Returns

Sliced or unchanged value.

Related

port_opt_view

PortfolioOptimisers.solver_selector Function

julia

solver_selector(risk_solvers, slv)

Select the appropriate solver for a risk measure computation.

Returns the risk-measure-specific solver if provided, otherwise falls back to the optimiser-level solver. Returns nothing if neither is available.

Arguments

risk_solvers: Risk-measure-specific solver(s) or nothing.
slv: Optimiser-level solver(s) or nothing.

Returns

Selected solver(s) or nothing.

Related

PortfolioOptimisers.VecBaseRM Type

julia

const VecBaseRM = AbstractVector{<:AbstractBaseRiskMeasure}

Alias for an abstract vector of AbstractBaseRiskMeasure elements.

Related

PortfolioOptimisers.VecOptRM Type

julia

const VecOptRM = AbstractVector{<:OptimisationRiskMeasure}

Alias for an abstract vector of OptimisationRiskMeasure elements.

Related

PortfolioOptimisers.OptRM_VecOptRM Type

julia

const OptRM_VecOptRM = Union{<:OptimisationRiskMeasure, <:VecOptRM}

Union type accepting a single OptimisationRiskMeasure or a vector of them.

Related

PortfolioOptimisers.VecRM Type

julia

const VecRM = AbstractVector{<:RiskMeasure}

Alias for an abstract vector of RiskMeasure elements.

Related

PortfolioOptimisers.RM_VecRM Type

julia

const RM_VecRM = Union{<:RiskMeasure, <:VecRM}

Union type accepting a single RiskMeasure or a vector of them.

Related

PortfolioOptimisers.RkRtBounds Type

julia

const RkRtBounds = Union{<:Num_VecNum, <:Frontier}

Union type for risk-measure upper bound specifications.

Accepts either a scalar/vector numeric bound or a Frontier sweep configuration. Used in RiskMeasureSettings to set the upper bound field.

Related

PortfolioOptimisers.Front_NumVec Type

julia

const Front_NumVec = Union{<:VecNum, <:Frontier}

Union type for frontier or numeric-vector specifications used internally for risk bounds.

Related

PortfolioOptimisers.bigger_is_better Function

julia

bigger_is_better(r::AbstractBaseRiskMeasure) -> Bool

Return whether a larger value of risk measure r is preferred over a smaller one.

The default implementation returns false (lower risk is better) for all AbstractBaseRiskMeasure subtypes. Ratio-based or return-like measures that should be maximised may override this method to return true.

Returns

Bool: true if a higher value of r is preferred; false otherwise.

Related

AbstractBaseRiskMeasure

julia

bigger_is_better(_::Skewness) -> Bool

Return true because higher skewness is preferred over lower skewness.

Related

PortfolioOptimisers.needs_previous_weights Method

julia

needs_previous_weights(r::AbstractBaseRiskMeasure) -> Bool
needs_previous_weights(r::VecBaseRM) -> Bool

Return whether risk measure r requires previous portfolio weights as input.

The default returns false. Override to true for risk measures such as turnover or tracking constraints that depend on prior weights. The VecBaseRM overload returns true if any element returns true.

Returns

Bool: true if prior weights are required; false otherwise.

Related

PortfolioOptimisers.RiskInputKind Type

julia

abstract type RiskInputKind

Abstract supertype for the input-shape classification of a risk measure, used by expected_risk to decide what to feed a measure's functor.

Each concrete AbstractBaseRiskMeasure declares its kind via risk_input_kind. The three kinds correspond to the three functor call shapes:

NetReturnsInput: r(calc_net_returns(w, X, fees)).
WeightsReturnsFeesInput: r(w, X, fees).
WeightsInput: r(w).

Related

PortfolioOptimisers.NetReturnsInput Type

julia

struct NetReturnsInput <: RiskInputKind

Input kind for risk measures whose expected risk is computed on net returns (returns after fees). The measure's functor is called as r(calc_net_returns(w, X, fees)).

Related

PortfolioOptimisers.WeightsReturnsFeesInput Type

julia

struct WeightsReturnsFeesInput <: RiskInputKind

Input kind for risk measures whose expected risk depends on weights, the returns matrix, and fees. The measure's functor is called as r(w, X, fees).

Related

PortfolioOptimisers.WeightsInput Type

julia

struct WeightsInput <: RiskInputKind

Input kind for risk measures whose expected risk depends only on portfolio weights. The measure's functor is called as r(w).

Related

PortfolioOptimisers.risk_input_kind Function

julia

risk_input_kind(r::AbstractBaseRiskMeasure) -> RiskInputKind

Return the RiskInputKind of risk measure r, declaring what its functor consumes when expected_risk evaluates it.

There is no default: every concrete AbstractBaseRiskMeasure (other than composite measures handled by explicit expected_risk methods) must declare its kind beside its type definition. Returning one of NetReturnsInput, WeightsReturnsFeesInput, or WeightsInput. An undeclared measure throws, rather than silently routing to the wrong input shape.

Returns

RiskInputKind: the declared input kind.

Related

PortfolioOptimisers.supports_precomputed_returns Method

julia

supports_precomputed_returns(r::AbstractBaseRiskMeasure) -> Bool
supports_precomputed_returns(rk::RiskInputKind, r::AbstractBaseRiskMeasure) -> Bool

Whether risk measure r has a well-defined precomputed-returns form — i.e. whether its expected risk can be evaluated on an already-reduced net-return series x alone, via the functor r(x::VecNum) (ADR 0007).

The contract is well-defined exactly when the measure's result is a function of the series alone:

NetReturnsInput measures (quantile / drawdown families): always true — their functor is the net-returns functor.
The moment family (LowOrderMoment, HighOrderMoment, Skewness, Kurtosis, MedianAbsoluteDeviation, ThirdCentralMoment): true iff its target is weight-independent (mu is nothing, a scalar, or a centering function); a per-asset mu (VecNum/VecScalar) reduces as dot(w, mu) and needs the weights the series no longer carries, so false.
WeightsInput measures, tracking measures, and variance-carrying composites (VarianceSkewKurtosis): false — "risk of a bare return series" is undefined for them.

This predicate is what makes the precomputed-returns contract safe. Because a WeightsInput measure's functor r(w) shares the r(::VecNum) signature with the contract, dispatch alone cannot distinguish weights from returns; expected_risk_from_returns consults this predicate and throws an explanatory error for ineligible measures rather than silently consuming the series as weights.

Related

PortfolioOptimisers.supports_precomputed_returns Method

julia

supports_precomputed_returns(_::NetReturnsInput, _) -> Bool

Return true: NetReturnsInput measures always support precomputed returns — their functor is the net-returns functor.

Related

PortfolioOptimisers.supports_precomputed_returns Method

julia

supports_precomputed_returns(_::WeightsInput, _) -> Bool

Return false: WeightsInput measures never support precomputed returns — their functor consumes portfolio weights, not a return series.

Related

PortfolioOptimisers.supports_precomputed_returns Method

julia

supports_precomputed_returns(
    _::WeightsReturnsFeesInput,
    r::AbstractBaseRiskMeasure
)

Erroring tripwire for WeightsReturnsFeesInput measures that have not declared supports_precomputed_returns at their own definition site. Every such measure must declare it there: moment measures as supports_precomputed_returns(r::T) = weight_independent_target(r.mu); weights-dependent measures (tracking, variance-carrying composites) as supports_precomputed_returns(::T) = false. Reaching this leaf means a measure forgot to declare it — throws an ArgumentError with instructions rather than silently mis-routing (and the completeness test in test_09c_risk_input_kind.jl turns that into a CI failure).

Related

PortfolioOptimisers.weight_independent_target Method

julia

weight_independent_target(_::Nothing) -> Bool

Return true: a Nothing target is trivially weight-independent and can be evaluated on a bare return series.

Related

PortfolioOptimisers.weight_independent_target Method

julia

weight_independent_target(_::Number) -> Bool

Return true: a scalar target does not require portfolio weights and can be evaluated on a bare return series.

Related

PortfolioOptimisers.weight_independent_target Method

julia

weight_independent_target(_) -> Bool

Return false: the target type requires portfolio weights (e.g. a per-asset mu involves dot(w, mu)) and cannot be evaluated on a bare return series.

Related

PortfolioOptimisers.factory Method

julia

factory(
    rs::AbstractBaseRiskMeasure,
    args...;
    kwargs...
) -> ConditionalValueatRiskRange{RiskMeasureSettings{__T_scale, __T_ub, __T_rke}, <:Number, <:Number} where {__T_scale, __T_ub, __T_rke}

Return the risk measure rs unchanged.

Identity pass-through used when a risk measure is provided in a context that calls factory.

Related

PortfolioOptimisers.factory Method

julia

factory(
    rs::AbstractVector{<:AbstractBaseRiskMeasure},
    args...;
    kwargs...
) -> Any

Return a new vector of risk measures with factory applied element-wise.

Related

PortfolioOptimisers.port_opt_view Method

julia

port_opt_view(rs, i, X)

Get a view or subset of a risk measure for asset cluster index i.

Returns the risk measure sliced for the given cluster or asset index. Used internally in hierarchical optimisation to apply risk measures to each cluster.

Arguments

rs: Risk measure (or vector thereof).
i: Cluster or asset index.
X: Data matrix (used for dimension-aware slicing).

Returns

Sliced risk measure or the original if no slicing is needed.

Related

AbstractBaseRiskMeasure

PortfolioOptimisers._Frontier Function

julia

_Frontier(; N = 20, factor, bound)

Construct a range of N evenly-spaced frontier parameter values.

Internal helper that generates a parameter grid (e.g., for risk bounds) used when sweeping the efficient frontier.

Arguments

N: Number of frontier points (default 20).
factor: Scaling factor for the range.
bound: Controls whether to sweep from min-to-max or max-to-min.

Returns

Vector of frontier parameter values.

Related