Tools

struct ReturnsResult{T1, T2, T3, T4, T5, T6, T7} <: AbstractReturnsResult
    nx::T1
    X::T2
    nf::T3
    F::T4
    ts::T5
    iv::T6
    ivpa::T7
end

A flexible container type for storing the results of asset and factor returns calculations in PortfolioOptimisers.jl.

ReturnsResult is the standard result type returned by returns-processing routines, such as prices_to_returns. It supports both asset and factor returns, as well as optional time series and implied volatility information, and is designed for downstream compatibility with optimization and analysis routines.

Fields

• nx: Names or identifiers of asset columns (assets × 1).
• X: Asset returns matrix (observations × assets).
• nf: Names or identifiers of factor columns (factors × 1).
• F: Factor returns matrix (observations × factors).
• ts: Optional timestamps for each observation (observations × 1).
• iv: Implied volatilities matrix (observations × assets).
• ivpa: Implied volatility risk premium adjustment, if a vector (assets × 1).

Constructor

ReturnsResult(; nx::Union{Nothing, <:AbstractVector} = nothing,
              X::Union{Nothing, <:AbstractMatrix} = nothing,
              nf::Union{Nothing, <:AbstractVector} = nothing,
              F::Union{Nothing, <:AbstractMatrix} = nothing,
              ts::Union{Nothing, <:AbstractVector} = nothing,
              iv::Union{Nothing, <:AbstractMatrix} = nothing,
              ivpa::Union{Nothing, <:Real, <:AbstractVector{<:Real}} = nothing)

Keyword arguments correspond to the fields above.

Validation

• If nx or X is provided, !isempty(nx), !isempty(X), and length(nx) == size(X, 2).
• If nf or F is provided, !isempty(nf), !isempty(F), and length(nf) == size(F, 2), and size(X, 1) == size(F, 1).
• If ts is provided, !isempty(ts), and length(ts) == size(X, 1).
• If iv is provided, !isempty(iv), all(x -> x >= 0, iv), and size(iv) == size(X).
• If ivpa is provided, all(x -> x >= 0, ivpa), all(x -> isfinite(x), ivpa); if a vector, length(ivpa) == size(iv, 2).

Examples

julia> ReturnsResult(; nx = ["A", "B"], X = [0.1 0.2; 0.3 0.4])
ReturnsResult
    nx | Vector{String}: ["A", "B"]
     X | 2×2 Matrix{Float64}
    nf | nothing
     F | nothing
    ts | nothing
    iv | nothing
  ivpa | nothing

Related

• AbstractReturnsResult
• prices_to_returns

prices_to_returns(X::TimeArray; F::TimeArray = TimeArray(TimeType[], []),
                  iv::Union{Nothing, <:TimeArray} = nothing,
                  ivpa::Union{Nothing, <:Real, <:AbstractVector{<:Real}} = nothing,
                  ret_method::Symbol = :simple, padding::Bool = false,
                  missing_col_percent::Real = 1.0,
                  missing_row_percent::Union{Nothing, <:Real} = 1.0,
                  collapse_args::Tuple = (), map_func::Union{Nothing, Function} = nothing,
                  join_method::Symbol = :outer,
                  impute_method::Union{Nothing, <:Impute.Imputor} = nothing)

Convert price data (and optionally factor data) in TimeArray format to returns, with flexible handling of missing data, imputation, and optional implied volatility information.

ReturnsResult a ReturnsResult containing asset and factor returns, time series, and optional implied volatility data, suitable for downstream portfolio optimization.

Arguments

• X: Asset price data (timestamps × assets).
• F: Optional Factor price data (timestamps × factors).
• iv: Optional Implied volatility data.
• ivpa: Optional Implied volatility risk premium adjustment.
• ret_method: Return calculation method (:simple or :log).
• padding: Whether to pad missing values in returns calculation.
• missing_col_percent: Maximum allowed fraction (0, 1] of missing values per column (asset + factor).
• missing_row_percent: Maximum allowed fraction (0, 1] of missing values per row (timestamp).
• collapse_args: Arguments for collapsing the time series (e.g., to lower frequency).
• map_func: Optional function to apply to the data before returns calculation.
• join_method: How to join asset and factor data (:outer, :inner, etc.).
• impute_method: Optional imputation method for missing data.

Returns

• ReturnsResult: Struct containing asset/factor returns, names, time series, and optional implied volatility data.

Examples

julia> using TimeSeries

julia> X = TimeArray(Date(2020, 1, 1):Day(1):Date(2020, 1, 3), [100 101; 102 103; 104 105],
                     ["A", "B"])
3×2 TimeSeries.TimeArray{Int64, 2, Dates.Date, Matrix{Int64}} 2020-01-01 to 2020-01-03
┌────────────┬─────┬─────┐
│            │ A   │ B   │
├────────────┼─────┼─────┤
│ 2020-01-01 │ 100 │ 101 │
│ 2020-01-02 │ 102 │ 103 │
│ 2020-01-03 │ 104 │ 105 │
└────────────┴─────┴─────┘

julia> rr = prices_to_returns(X)
ReturnsResult
    nx | Vector{String}: ["A", "B"]
     X | 2×2 Matrix{Float64}
    nf | nothing
     F | nothing
    ts | Vector{Dates.Date}: [Dates.Date("2020-01-02"), Dates.Date("2020-01-03")]
    iv | nothing
  ivpa | nothing

Related

• ReturnsResult

brinson_attribution(X::TimeArray, w::AbstractVector, wb::AbstractVector,
                    asset_classes::DataFrame, col; date0 = nothing, date1 = nothing)

traverse_concrete_subtypes(t; ctarr::Union{Nothing, <:AbstractVector} = nothing)

Recursively traverse all subtypes of the given abstract type t and collect all concrete struct types into ctarr.

Arguments

• t: An abstract type whose subtypes will be traversed.
• ctarr: Optional An array to collect the concrete types. If not provided, a new empty array is created.

Returns

An array containing all concrete struct types that are subtypes (direct or indirect) of types.

Examples

julia> abstract type MyAbstract end

julia> struct MyConcrete1 <: MyAbstract end

julia> struct MyConcrete2 <: MyAbstract end

julia> traverse_concrete_subtypes(MyAbstract)
2-element Vector{Any}:
 MyConcrete1
 MyConcrete2

abstract type AbstractReturnsResult <: AbstractResult end

Abstract supertype for all returns result types in PortfolioOptimisers.jl.

All concrete types representing the result of returns calculations (e.g., asset returns, factor returns) should subtype AbstractReturnsResult. This enables a consistent interface for downstream analysis and optimization routines.

Related

• AbstractResult
• ReturnsResult

assert_matrix_issquare(A::AbstractMatrix)

Assert that A is a square matrix.

⊗(A::AbstractArray, B::AbstractArray)

Tensor product of two arrays. ReturnsResult a matrix of size (length(A), length(B)) where each element is the product of elements from A and B.

Examples

julia> PortfolioOptimisers.:⊗([1, 2], [3, 4])
2×2 Matrix{Int64}:
 3  4
 6  8

⊙(A, B)

Elementwise multiplication.

Examples

julia> PortfolioOptimisers.:⊙([1, 2], [3, 4])
2-element Vector{Int64}:
 3
 8

julia> PortfolioOptimisers.:⊙([1, 2], 2)
2-element Vector{Int64}:
 2
 4

julia> PortfolioOptimisers.:⊙(2, [3, 4])
2-element Vector{Int64}:
 6
 8

julia> PortfolioOptimisers.:⊙(2, 3)
6

⊘(A, B)

Elementwise division.

Examples

julia> PortfolioOptimisers.:⊘([4, 9], [2, 3])
2-element Vector{Float64}:
 2.0
 3.0

julia> PortfolioOptimisers.:⊘([4, 6], 2)
2-element Vector{Float64}:
 2.0
 3.0

julia> PortfolioOptimisers.:⊘(8, [2, 4])
2-element Vector{Float64}:
 4.0
 2.0

julia> PortfolioOptimisers.:⊘(8, 2)
4.0

⊕(A, B)

Elementwise addition.

Examples

julia> PortfolioOptimisers.:⊕([1, 2], [3, 4])
2-element Vector{Int64}:
 4
 6

julia> PortfolioOptimisers.:⊕([1, 2], 2)
2-element Vector{Int64}:
 3
 4

julia> PortfolioOptimisers.:⊕(2, [3, 4])
2-element Vector{Int64}:
 5
 6

julia> PortfolioOptimisers.:⊕(2, 3)
5

⊖(A, B)

Elementwise subtraction.

Examples

julia> PortfolioOptimisers.:⊖([4, 6], [1, 2])
2-element Vector{Int64}:
 3
 4

julia> PortfolioOptimisers.:⊖([4, 6], 2)
2-element Vector{Int64}:
 2
 4

julia> PortfolioOptimisers.:⊖(8, [2, 4])
2-element Vector{Int64}:
 6
 4

julia> PortfolioOptimisers.:⊖(8, 2)
6

concrete_typed_array(A::AbstractArray)

Convert an AbstractArray A to a concrete typed array, where each element is of the same type as the elements of A.

This is useful for converting arrays with abstract element types to arrays with concrete element types, which can improve performance in some cases.

Arguments

• A: The input array.

Returns

A new array with the same shape as A, but with a concrete element type inferred from the elements of A.

Examples

julia> A = Any[1, 2.0, 3];

julia> PortfolioOptimisers.concrete_typed_array(A)
3-element reshape(::Vector{Union{Float64, Int64}}, 3) with eltype Union{Float64, Int64}:
 1
 2.0
 3

dot_scalar(a::Real, b::AbstractVector)
dot_scalar(a::AbstractVector, b::Real)
dot_scalar(a::AbstractVector, b::AbstractVector)

Efficient scalar and vector dot product utility.

• If one argument is a scalar and the other a vector, returns the scalar times the sum of the vector.
• If both arguments are vectors, returns their dot product.

Arguments

• a::Real, b::AbstractVector: Multiplies a by the sum of b.
• a::AbstractVector, b::Real: Multiplies the sum of a by b.
• a::AbstractVector, b::AbstractVector: Computes the dot product of a and b.

Returns

• Real: The resulting scalar.

Examples

julia> PortfolioOptimisers.dot_scalar(2.0, [1.0, 2.0, 3.0])
12.0

julia> PortfolioOptimisers.dot_scalar([1.0, 2.0, 3.0], 2.0)
12.0

julia> PortfolioOptimisers.dot_scalar([1.0, 2.0, 3.0], [4.0, 5.0, 6.0])
32.0

nothing_scalar_array_view(x, i)

Utility for safely viewing or indexing into possibly nothing, scalar, or array values.

• If x is nothing, returns nothing.
• If x is a scalar, returns x.
• If x is a vector, returns view(x, i).
• If x is a vector of vectors, returns view.(x, Ref(i)).
• If x is a matrix or higher array, returns view(x, i, i).

Arguments

• x: Input value, which may be nothing, a scalar, vector, or array.
• i: Index or indices to view.

Returns

• The corresponding view or value, or nothing if x is nothing.

Examples

julia> PortfolioOptimisers.nothing_scalar_array_view(nothing, 1:2)

julia> PortfolioOptimisers.nothing_scalar_array_view(3.0, 1:2)
3.0

julia> PortfolioOptimisers.nothing_scalar_array_view([1.0, 2.0, 3.0], 2:3)
2-element view(::Vector{Float64}, 2:3) with eltype Float64:
 2.0
 3.0

julia> PortfolioOptimisers.nothing_scalar_array_view([[1, 2], [3, 4]], 1)
2-element Vector{SubArray{Int64, 0, Vector{Int64}, Tuple{Int64}, true}}:
 fill(1)
 fill(3)

nothing_scalar_array_view_odd_order(x, i, j)

Utility for safely viewing or indexing into possibly nothing or array values with two indices.

• If x is nothing, returns nothing.
• Otherwise, returns view(x, i, j).

Arguments

• x: Input value, which may be nothing or an array.
• i, j: Indices to view.

Returns

• The corresponding view or nothing.

Examples

julia> PortfolioOptimisers.nothing_scalar_array_view_odd_order(nothing, 1, 2)

julia> PortfolioOptimisers.nothing_scalar_array_view_odd_order([1 2; 3 4], 1, 2)
0-dimensional view(::Matrix{Int64}, 1, 2) with eltype Int64:
2

nothing_scalar_array_getindex(x, i)
nothing_scalar_array_getindex(x, i, j)

Utility for safely indexing into possibly nothing, scalar, vector, or array values.

• If x is nothing, returns nothing.
• If x is a scalar, returns x.
• If x is a vector, returns x[i].
• If x is a matrix, returns x[i, i] or x[i, j].

Arguments

• x: Input value, which may be nothing, a scalar, vector, or matrix.
• i, j: Indices.

Returns

• The corresponding value or nothing.

Examples

julia> PortfolioOptimisers.nothing_scalar_array_getindex(nothing, 1)

julia> PortfolioOptimisers.nothing_scalar_array_getindex(3.0, 1)
3.0

julia> PortfolioOptimisers.nothing_scalar_array_getindex([1.0, 2.0, 3.0], 2)
2.0

julia> PortfolioOptimisers.nothing_scalar_array_getindex([1 2; 3 4], 2)
4

julia> PortfolioOptimisers.nothing_scalar_array_getindex([1 2; 3 4], 1, 2)
2

nothing_asset_sets_view(::Nothing, ::Any)

No-op fallback for indexing nothing asset sets.

Returns

• nothing.

fourth_moment_index_factory(N::Integer, i::AbstractVector)

Constructs an index vector for extracting the fourth moment submatrix corresponding to indices i from a covariance matrix of size N × N.

Arguments

• N: Size of the full covariance matrix.
• i: Indices of the variables of interest.

Returns

• idx::Vector{Int}: Indices for extracting the fourth moment submatrix.

Examples

julia> PortfolioOptimisers.fourth_moment_index_factory(3, [1, 2])
4-element Vector{Int64}:
 1
 2
 4
 5