Base

01_Base.jl implements the most basal symbols used in PortfolioOptimisers.jl.

Base abstract types

PortfolioOptimisers.jl is designed in a deliberately structured and hierarchical way. Enabling us to create self-contained, independent, composable processes. These abstract types form the basis of this hierarchy.

PortfolioOptimisers.AbstractEstimator Type

julia

abstract type AbstractEstimator end

Abstract supertype for all estimator types in PortfolioOptimisers.jl.

All custom estimators should subtype AbstractEstimator.

Estimators consume data to estimate parameters or models. Some estimators may utilise different algorithms. These can range from simple implementation details that don't change the result much but may have different numerical characteristics, to entirely different methodologies or algorithms yielding different results.

Related

PortfolioOptimisers.AbstractAlgorithm Type

julia

abstract type AbstractAlgorithm end

Abstract supertype for all algorithm types in PortfolioOptimisers.jl.

All algorithms should subtype AbstractAlgorithm.

Algorithms are often used by estimators to perform specific tasks. These can be in the form of simple implementation details to entirely different procedures for estimating a quantity.

Related

PortfolioOptimisers.AbstractResult Type

julia

abstract type AbstractResult end

Abstract supertype for all result types in PortfolioOptimisers.jl.

All result objects should subtype AbstractResult.

Result types encapsulate the outcomes of estimators. This makes dispatch and usage more straightforward, especially when the results encapsulate a wide range of information.

Related

Pretty printing

PortfolioOptimisers.jl's types tend to contain quite a lot of information, these functions enable pretty printing so they are easier to interpret.

PortfolioOptimisers.@define_pretty_show Macro

julia

@define_pretty_show(T)

Macro to define a custom pretty-printing Base.show method for types in PortfolioOptimisers.jl.

This macro generates a show method that displays the type name and all fields in a readable, aligned format. For fields that are themselves custom types or collections, the macro recursively applies pretty-printing for nested structures. Handles compact and multiline IO contexts gracefully.

Arguments

T: The type for which to define the pretty-printing method.

Returns

Defines a Base.show(io::IO, obj::T) method for the given type.

Details

Prints the type name and all fields with aligned labels.
Recursively pretty-prints nested custom types and collections.
Handles compact and multiline IO contexts.
Displays matrix/vector fields with their size and type.
Skips fields that are not present or are nothing.

Related

PortfolioOptimisers.has_pretty_show_method Function

julia

has_pretty_show_method(::Any)

Default method indicating whether a type has a custom pretty-printing show method.

Overloading this method to return true indicates that type already has a custom pretty-printing method.

Arguments

::Any: Any type.

Returns

flag::Bool: false by default, indicating no custom pretty-printing method.

Related

@define_pretty_show

Error types

Many of the types defined in PortfolioOptimisers.jl make use of extensive data validation to ensure values meet various criteria. This simplifies the implementation of methods, and improves performance and by delegating as many checks as possible to variable instantiation. In cases where validation cannot be performed at variable instantiation, they are performed as soon as possible within functions.

PortfolioOptimisers.jl aims to catch potential data validation issues as soon as possible and in an informative manner, in order to do so it makes use of a few custom error types.

PortfolioOptimisers.PortfolioOptimisersError Type

julia

abstract type PortfolioOptimisersError <: Exception end

Abstract supertype for all custom exception types in PortfolioOptimisers.jl.

All error types specific to PortfolioOptimisers.jl should be subtypes of PortfolioOptimisersError.

Related

PortfolioOptimisers.IsNothingError Type

julia

struct IsNothingError{T1} <: PortfolioOptimisersError
    msg::T1
end

Exception type thrown when an argument or value is unexpectedly nothing.

Fields

msg: Error message describing the condition that triggered the exception.

Constructors

julia

IsNothingError(msg)

Arguments correspond to the fields above.

Examples

julia

julia> throw(IsNothingError("Input data must not be nothing"))
ERROR: IsNothingError: Input data must not be nothing
Stacktrace:
 [1] top-level scope
   @ none:1

Related

PortfolioOptimisers.IsEmptyError Type

julia

struct IsEmptyError{T1} <: PortfolioOptimisersError
    msg::T1
end

Exception type thrown when an argument or value is unexpectedly empty.

Fields

msg: Error message describing the condition that triggered the exception.

Constructors

julia

IsEmptyError(msg)

Arguments correspond to the fields above.

Examples

julia

julia> throw(IsEmptyError("Input array must not be empty"))
ERROR: IsEmptyError: Input array must not be empty
Stacktrace:
 [1] top-level scope
   @ none:1

Related

PortfolioOptimisers.IsNonFiniteError Type

julia

struct IsNonFiniteError{T1} <: PortfolioOptimisersError
    msg::T1
end

Exception type thrown when an argument or value is unexpectedly non-finite (e.g., contains NaN or Inf).

Fields

msg: Error message describing the condition that triggered the exception.

Constructors

julia

IsNonFiniteError(msg)

Arguments correspond to the fields above.

Examples

julia

julia> throw(IsNonFiniteError("Input array contains non-finite values"))
ERROR: IsNonFiniteError: Input array contains non-finite values
Stacktrace:
 [1] top-level scope
   @ none:1

Related

Utility types

Custom types are the bread and butter of PorfolioOptimisers.jl, the following types non-specific and used throughout the library.

PortfolioOptimisers.VecScalar Type

julia

struct VecScalar{T1, T2} <: AbstractResult
    v::T1
    s::T2
end

Represents a composite result containing a vector and a scalar in PortfolioOptimisers.jl.

Encapsulates a vector and a scalar value, commonly used for storing results that combine both types of data (e.g., weighted statistics, risk measures).

Fields

v: Vector value.
s: Scalar value.

Constructors

julia

VecScalar(; v::VecNum, s::Number)

Keyword arguments correspond to the fields above.

Validation

v: !isempty(v) and all(isfinite, v).
s: isfinite(s).

Examples

julia

julia> VecScalar([1.0, 2.0, 3.0], 4.2)
VecScalar
  v ┼ Vector{Float64}: [1.0, 2.0, 3.0]
  s ┴ Float64: 4.2

Related

PortfolioOptimisers.AbstractEstimatorValueAlgorithm Type

julia

abstract type AbstractEstimatorValueAlgorithm <: AbstractAlgorithm end

Abstract supertype for all estimator value algorithm types in PortfolioOptimisers.jl.

Subtypes of AbstractEstimatorValueAlgorithm implement algorithms for computing constraint result values. These are used to extend or modify the behavior of estimators in a composable and modular fashion.

Related

EstValType

Base type aliases

PortfolioOptimisers.jl heavily relies on Julia's dispatch and type system to ensure data validity. Many custom types and functions/methods can accept different data types. These can be represented as type unions, many of which are used throughout the library. The following type aliases centralise these union definitions, as well as improving correctness and maintainability.

PortfolioOptimisers.Option Type

julia

const Option{T} = Union{Nothing, T}

Alias for an optional value of type T, which may be nothing.

Related

EstValType

PortfolioOptimisers.VecNum Type

julia

const VecNum = Union{<:AbstractVector{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}}}

Alias for an abstract vector of numeric types or JuMP scalar types.

Related

PortfolioOptimisers.VecInt Type

julia

const VecInt = AbstractVector{<:Integer}

Alias for an abstract vector of integer types.

Related

PortfolioOptimisers.MatNum Type

julia

const MatNum = Union{<:AbstractMatrix{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}}}

Alias for an abstract matrix of numeric types or JuMP scalar types.

Related

PortfolioOptimisers.ArrNum Type

julia

const ArrNum = Union{<:AbstractArray{<:Union{<:Number, <:JuMP.AbstractJuMPScalar}}}

Alias for an abstract array of numeric types or JuMP scalar types.

Related

PortfolioOptimisers.Num_VecNum Type

julia

const Num_VecNum = Union{<:Number, <:VecNum}

Alias for a union of a numeric type or an abstract vector of numeric types.

Related

PortfolioOptimisers.Num_ArrNum Type

julia

const Num_ArrNum = Union{<:Number, <:ArrNum}

Alias for a union of a numeric type or an abstract array of numeric types.

Related

PortfolioOptimisers.PairStrNum Type

julia

const PairStrNum = Pair{<:AbstractString, <:Number}

Alias for a pair consisting of an abstract string and a numeric type.

Related

PortfolioOptimisers.DictStrNum Type

julia

const DictStrNum = AbstractDict{<:AbstractString, <:Number}

Alias for an abstract dictionary with string keys and numeric values.

Related

PortfolioOptimisers.MultiEstValType Type

julia

const MultiEstValType = Union{<:DictStrNum, <:AbstractVector{<:PairStrNum}}

Alias for a union of a dictionary with string keys and numeric values, or a vector of string-number pairs.

Related

PortfolioOptimisers.EstValType Type

julia

const EstValType = Union{<:Num_VecNum, <:PairStrNum, <:MultiEstValType, <:AbstractEstimatorValueAlgorithm}

Alias for a union of numeric, vector of numeric, string-number pair, or multi-estimator value types.

Related

PortfolioOptimisers.PairGSCV Type

julia

const PairGSCV = Pair{<:AbstractString, <:AbstractVector}

Alias for a pair consisting of an abstract string and an abstract vector.

Related

PortfolioOptimisers.DictGSCV Type

julia

const DictGSCV = AbstractDict{<:AbstractString, <:AbstractVector}

Alias for an abstract dictionary with string keys and abstract vector values.

Related

PortfolioOptimisers.MultiGSCVValType Type

julia

const MultiGSCVValType = Union{<:DictGSCV, <:AbstractVector{<:PairGSCV}}

Alias for a union of an abstract dictionary with string keys and abstract vector values, or a vector of string-vector pairs.

Related

PortfolioOptimisers.VecMultiGSCVValType Type

julia

const VecMultiGSCVValType = AbstractVector{<:MultiGSCVValType}

Alias for an abstract vector of MultiGSCVValType elements.

Related

PortfolioOptimisers.MultiGSCVValType_VecMultiGSCVValType Type

julia

const MultiGSCVValType_VecMultiGSCVValType = Union{<:MultiGSCVValType,
                                               <:VecMultiGSCVValType}

Alias for a union of MultiGSCVValType and VecMultiGSCVValType elements.

Related

PortfolioOptimisers.Str_Expr Type

julia

const Str_Expr = Union{<:AbstractString, Expr}

Alias for a union of abstract string or Julia expression.

Related

PortfolioOptimisers.VecStr_Expr Type

julia

const VecStr_Expr = AbstractVector{<:Str_Expr}

Alias for an abstract vector of strings or Julia expressions.

Related

PortfolioOptimisers.EqnType Type

julia

const EqnType = Union{<:AbstractString, Expr, <:VecStr_Expr}

Alias for a union of string, Julia expression, or vector of strings/expressions.

Related

PortfolioOptimisers.VecVecNum Type

julia

const VecVecNum = AbstractVector{<:VecNum}

Alias for an abstract vector of numeric vectors.

Related

PortfolioOptimisers.VecVecInt Type

julia

const VecVecInt = AbstractVector{<:VecInt}

Alias for an abstract vector of integer vectors.

Related

VecInt

PortfolioOptimisers.VecMatNum Type

julia

const VecMatNum = AbstractVector{<:MatNum}

Alias for an abstract vector of numeric matrices.

Related

PortfolioOptimisers.VecStr Type

julia

const VecStr = Union{<:AbstractVector{<:AbstractString}}

Alias for an abstract vector of strings.

Related

PortfolioOptimisers.VecPair Type

julia

const VecPair = AbstractVector{<:Pair}

Alias for an abstract vector of pairs.

Related

PairStrNum

PortfolioOptimisers.VecJuMPScalar Type

julia

const VecJuMPScalar = Union{<:AbstractVector{<:JuMP.AbstractJuMPScalar}}

Alias for an abstract vector of JuMP scalar types.

Related

VecNum

PortfolioOptimisers.MatNum_VecMatNum Type

julia

const MatNum_VecMatNum = Union{<:MatNum, <:VecMatNum}

Alias for a union of a numeric matrix or a vector of numeric matrices.

Related

PortfolioOptimisers.Int_VecInt Type

julia

const Int_VecInt = Union{<:Integer, <:VecInt}

Alias for a union of an integer or a vector of integers.

Related

VecInt

PortfolioOptimisers.VecNum_VecVecNum Type

julia

const VecNum_VecVecNum = Union{<:VecNum, <:VecVecNum}

Alias for a union of a numeric vector or a vector of numeric vectors.

Related

PortfolioOptimisers.VecDate Type

julia

const VecDate = AbstractVector{<:Dates.AbstractTime}

Alias for an abstract vector of date or time types.

Related

PortfolioOptimisers.Dict_Vec Type

julia

const Dict_Vec = Union{<:AbstractDict, <:AbstractVector}

Alias for a union of an abstract dictionary or an abstract vector.

Related

PortfolioOptimisers.Sym_Str Type

julia

const Sym_Str = Union{Symbol, <:AbstractString}

Alias for a union of a symbol or an abstract string.

Related

VecStr

PortfolioOptimisers.Str_Vec Type

julia

const Str_Vec = Union{<:AbstractString, <:AbstractVector}

Alias for a union of an abstract string or an abstract vector.

Related

PortfolioOptimisers.Num_VecNum_VecScalar Type

julia

const Num_VecNum_VecScalar = Union{<:Num_VecNum, <:VecScalar}

Alias for a union of a numeric type, a vector of numeric types, or a VecScalar result.

Related

PortfolioOptimisers.Num_ArrNum_VecScalar Type

julia

const Num_ArrNum_VecScalar = Union{<:Num_ArrNum, <:VecScalar}

Alias for a union of a numeric type, an array of numeric types, or a VecScalar result.

Related

Documentation arg_dict

In order to standardise the documentation we use a arg_dict of terms.

PortfolioOptimisers.arg_dict Constant

julia

arg_dict = Dict(
             # Weight vectors.
             :pw => "`w`: Portfolio weights vector.",
             :ow => "`w`: Observation weights vector.",
             :oow => "`w`: Optional observation weights vector.",
             # Matrix processing.
             :pdm => "`pdm`: Positive definite matrix estimator.",
             :dn => "`dn`: Matrix denoising estimator.",
             :dt => "`dt`: Matrix detoning estimator.",
             :mp => "`mp`: Matrix processing estimator.",
             # Moments.
             :me => "`me`: Expected returns estimator.",
             :ce => "`ce`: Covariance estimator.",
             :ve => "`ve`: Variance estimator.",
             :ske => "`ske`: Coskewness estimator.",
             :kte => "`kte`: Cokurtosis estimator.",
             :de => "`de`: Distance matrix estimator.",
             # Priors.
             :pe => "`pe`: Prior estimator.",
             :pr => "`pr`: Prior result.",
             :per => "`pe`: Prior estimator or result.",
             # Phylogeny.
             :cle => "`cle`: Clusters estimator.",
             :clr => "`clr`: Clusters result.",
             :cler => "`cle`: Clusters estimator or result.",
             :ple => "`pl`: Phylogeny estimator.",
             :plr => "`pl`: Phylogeny result.",
             :pler => "`pl`: Phylogeny estimator or result.",
             :nte => "`pl`: Network estimator.",
             :ntr => "`pl`: Network result.",
             :nter => "`pl`: Network estimator or result.",
             :cte => "`cte`: Centrality estimator.",
             :cta => "`ct`: Centrality algorithm.",
             :ctr => "`ct`: Centrality result.",
             :cter => "`ct`: Centrality estimator or result.",
             # Turnover.
             :tne => "`tn`: Turnover estimator.",
             :tnr => "`tn`: Turnover result.",
             :tner => "`tn`: Turnover estimator or result.",
             :tnes => "`tn`: Turnover estimator(s).",
             :tnrs => "`tn`: Turnover result(s).",
             :tners => "`tn`: Turnover estimator(s) or result(s).",
             # Tracking.
             :tre => "`tr`: Tracking error estimator.",
             :trr => "`tr`: Tracking error result.",
             :trer => "`tr`: Tracking error estimator or result.",
             :tres => "`tr`: Tracking error estimator(s).",
             :trrs => "`tr`: Tracking error result(s).",
             :trers => "`tr`: Tracking error estimator(s) or result(s).",
             # Weight bounds.
             :wbe => "`wb`: Weight bounds estimator.",
             :wbr => "`wb`: Weight bounds result.",
             :wber => "`wb`: Weight bounds estimator or result.",
             # Fees.
             :feese => "`fees`: Fees estimator.",
             :feesr => "`fees`: Fees result.",
             :feeser => "`fees`: Fees estimator or result.")

This dictionary contains the arg_dict terms and their corresponding descriptions used in the documentation of PortfolioOptimisers.jl.

PortfolioOptimisers.val_dict Constant

julia

val_dict = Dict(:oow => "If `w` is not `nothing`, `!isempty(w)`.")

Validation rules for certain arg_dict terms used in the documentation of PortfolioOptimisers.jl.

PortfolioOptimisers.ret_dict Constant

Dictionary containing return value descriptions for common parameters used in PortfolioOptimisers.jl.