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::Union{Nothing, AbstractVector}: Names or identifiers of asset columns.
• X::Union{Nothing, AbstractMatrix}: Asset returns matrix (observations × assets).
• nf::Union{Nothing, AbstractVector}: Names or identifiers of factor columns.
• F::Union{Nothing, AbstractMatrix}: Factor returns matrix (observations × factors).
• ts::Union{Nothing, AbstractVector}: Optional time series (e.g., timestamps) for each observation.
• iv::Union{Nothing, AbstractMatrix}: Implied volatilities matrix.
• ivpa::Union{Nothing, <:Real, AbstractVector{<:Real}}: Implied volatility risk premium adjustment.

Constructor

ReturnsResult(; nx=nothing, X=nothing, nf=nothing, F=nothing, ts=nothing, iv=nothing, ivpa=nothing)

Keyword arguments correspond to the fields above. The constructor performs internal consistency checks (e.g., matching dimensions, non-emptiness, positivity for variances).

Related

• AbstractReturnsResult
• prices_to_returns

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)

Construct a ReturnsResult object, validating dimensions and types for asset and factor returns, time series, and instrument variance data.

Arguments

• nx::Union{Nothing, AbstractVector}: Asset names or identifiers.
• X::Union{Nothing, AbstractMatrix}: Asset returns matrix.
• nf::Union{Nothing, AbstractVector}: Factor names or identifiers.
• F::Union{Nothing, AbstractMatrix}: Factor returns matrix.
• ts::Union{Nothing, AbstractVector}: Time series (e.g., timestamps).
• iv::Union{Nothing, AbstractMatrix}: Implied volatility matrix.
• ivpa::Union{Nothing, <:Real, AbstractVector{<:Real}}: Implied volatility risk premium adjustment.

Validation

• If nx or X is provided, both must be non-empty and length(nx) == size(X, 2).
• If nf or F is provided, both must be non-empty and length(nf) == size(F, 2), and size(X, 1) == size(F, 1).
• If ts is provided, must be non-empty and length(ts) == size(X, 1).
• If iv is provided, must be non-empty, positive, and size(iv) == size(X).
• If ivpa is provided, must be positive and finite; 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

• ReturnsResult
• 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::TimeArray: Asset price data (timestamps × assets).
• F::TimeArray: (Optional) Factor price data (timestamps × factors).
• iv::Union{Nothing, TimeArray}: (Optional) Implied volatility data.
• ivpa::Union{Nothing, <:Real, AbstractVector{<:Real}}: (Optional) Implied volatility risk premium adjustment.
• ret_method::Symbol: Return calculation method (:simple or :log).
• padding::Bool: Whether to pad missing values in returns calculation.
• missing_col_percent::Real: Maximum allowed fraction of missing values per column (asset/factor).
• missing_row_percent::Union{Nothing, <:Real}: Maximum allowed fraction of missing values per row (timestamp).
• collapse_args::Tuple: Arguments for collapsing the time series (e.g., to lower frequency).
• map_func::Union{Nothing, Function}: Optional function to apply to the data before returns calculation.
• join_method::Symbol: How to join asset and factor data (:outer, :inner, etc.).
• impute_method::Union{Nothing, Impute.Imputor}: Optional imputation method for missing data.

ReturnsResult

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

Validation

• Ensures consistency of asset/factor names and dimensions.
• Handles missing data according to specified thresholds and imputation method.
• Validates implied volatility and risk premium adjustment if provided.

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)

AbstractReturnsResult <: AbstractResult

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

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::Union{Nothing, <:AbstractVector}: (Optional) An array to collect the concrete types. If not provided, a new empty array is created.

ReturnsResult

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

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::AbstractArray: The input array.

ReturnsResult

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.

ReturnsResult

• 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.

ReturnsResult

• 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.

ReturnsResult

• 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.

ReturnsResult

• 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(x, i)

Utility for safely viewing or indexing into possibly nothing or DataFrame values.

• If x is nothing, returns nothing.
• If x is a DataFrame, returns view(x, i, :).

Arguments

• x: Input value, which may be nothing or a DataFrame.
• i: Indices.

ReturnsResult

• The corresponding view or nothing.

Examples

julia> using DataFrames

julia> df = DataFrame(; A = 1:5, B = 6:10, C = 11:15)
5×3 DataFrame
 Row │ A      B      C
     │ Int64  Int64  Int64
─────┼─────────────────────
   1 │     1      6     11
   2 │     2      7     12
   3 │     3      8     13
   4 │     4      9     14
   5 │     5     10     15

julia> PortfolioOptimisers.nothing_asset_sets_view(df, 1:2)
2×3 SubDataFrame
 Row │ A      B      C
     │ Int64  Int64  Int64
─────┼─────────────────────
   1 │     1      6     11
   2 │     2      7     12

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::Integer: Size of the full covariance matrix.
• i::AbstractVector: Indices of the variables of interest.

ReturnsResult

• 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