Custom value expected returns

abstract type CustomExpectedReturnsValueAlgorithm <: AbstractCustomValue

Abstract supertype for custom expected returns value algorithms. These are used to define the type of the val field in CustomValueExpectedReturns.

Interfaces

In order to implement a new concrete custom expected returns value algorithm type that works seamlessly with the library, subtype CustomExpectedReturnsValueAlgorithm and make it callable such that it returns a vector of length consistent with the returns matrix:

• (alg::MyCustomValAlg)(X::MatNum; dims::Int=1, kwargs...) -> Vector{<:Number}

Where:

• alg: Custom expected returns value algorithm.
• X: Data matrix of asset returns.
• dims: Dimension along which to compute the expected returns (1 for columns/assets, 2 for rows/observations).
• kwargs...: Additional keyword arguments.

Examples

julia> struct MyCustomValAlg <: PortfolioOptimisers.CustomExpectedReturnsValueAlgorithm endjulia> function (alg::MyCustomValAlg)(X::PortfolioOptimisers.MatNum; dims::Int = 1, kwargs...)           return fill(0.0, size(X, setdiff((1, 2), (dims,))[1]))       endjulia> mean(CustomValueExpectedReturns(; val = MyCustomValAlg()), [1 2 3; 4 5 6])3-element Vector{Float64}: 0.0 0.0 0.0

Related

• CustomValueExpectedReturns
• CER_Func_Num_VecNum

const CER_Func_Num_VecNum = Union{<:CustomExpectedReturnsValueAlgorithm,<:Func_Num_VecNum}

Alias for supported types for the val field in CustomValueExpectedReturns.

struct CustomValueExpectedReturns{__T_val} <: AbstractExpectedReturnsEstimator

Returns a caller-supplied value for each asset instead of estimating one from the data.

val holds a scalar, a per-asset vector, or a callable that the estimator calls with the data matrix.

Fields

• val: Custom expected returns value.

  • If a scalar, every asset is assigned this value.
  • If a vector, each element is one asset's value.
  • If a callable, it is called as val(X; dims = dims, kwargs...) and must return one value per asset.

Constructors

CustomValueExpectedReturns(;    val::CER_Func_Num_VecNum = 0.0) -> CustomValueExpectedReturns

Keywords correspond to the struct's fields.

Validation

• If val is a vector, !isempty(val).

Examples

julia> CustomValueExpectedReturns()CustomValueExpectedReturns  val ┴ Float64: 0.0

Related

• AbstractExpectedReturnsEstimator
• CER_Func_Num_VecNum
• CustomExpectedReturnsValueAlgorithm
• assert_custom_expected_returns_val

assert_custom_expected_returns_val(val, N::Integer)
assert_custom_expected_returns_val(
    val,
    N::Integer,
    val_sym::Union{AbstractString, Symbol}
)

Assert that a custom expected returns value is a per-asset vector of the expected length.

Both the vector field of CustomValueExpectedReturns and the value returned by a callable val must be a vector of numbers with one element per asset. The callable is checked at the point of call, which is the only seam that can see what the callable returned.

Arguments

• val: Custom value to validate. Either the stored me.val vector or the value returned by a callable me.val.
• N: Number of assets implied by the data matrix and dims.
• val_sym: Symbolic name used in the error messages.

Validation

• isa(val, VecNum).
• length(val) == N.

Returns

• nothing.

Details

• Throws ArgumentError if val is not a vector of numbers.
• Throws DimensionMismatch if the length of val does not match the number of assets.

Related

• CustomValueExpectedReturns
• CustomExpectedReturnsValueAlgorithm

Statistics.mean(me::CustomValueExpectedReturns, X::MatNum;
                dims::Int = 1, kwargs...)

Compute expected returns as custom values.

Mathematical definition

Returns a user-supplied constant, vector, or function result as the expected returns:

\[\begin{align} \hat{\mu}_j &= v_j, \quad j = 1, \ldots, N\,. \end{align}\]

Where:

• $\hat{\mu}_j$: Expected return of asset $j$.
• $v_j$: $j$-th element of the custom value me.val (broadcast from a scalar, taken directly from a vector, or evaluated from a callable).
• $N$: Number of assets.

Arguments

• me: Custom value expected returns estimator.
• X: Data matrix of asset returns (observations × assets).
• dims: Dimension along which to perform the computation.
• kwargs...: Additional keyword arguments. The callable branch passes them to me.val; the other two branches ignore them.

Validation

• dims in (1, 2).
• The vector branch and the callable branch both check the value against the number of assets with assert_custom_expected_returns_val.

Returns

• mu: Expected returns, one value per asset. The shape depends on the branch.

  • me.val::Number and me.val::VecNum: A Matrix{<:Number}, shaped as (1, N) if dims == 1 or (N, 1) if dims == 2, as the other expected returns estimators return.
  • me.val::Function and me.val::CustomExpectedReturnsValueAlgorithm: The vector the callable returned, of length N, passed through unchanged. This branch inserts no dimension.

Related

• CustomValueExpectedReturns
• assert_custom_expected_returns_val

mean(
    me::CustomValueExpectedReturns{<:AbstractVector{<:Union{var"#s89", var"#s88"} where {var"#s89"<:Number, var"#s88"<:AbstractJuMPScalar}}},
    X::AbstractMatrix{<:Union{var"#s89", var"#s88"} where {var"#s89"<:Number, var"#s88"<:AbstractJuMPScalar}};
    dims,
    kwargs...
) -> Any

Vector overload of mean(me::CustomValueExpectedReturns, X::MatNum; dims::Int = 1, kwargs...). Returns the stored vector me.val reshaped to match dims.

mean(
    me::CustomValueExpectedReturns{<:Union{var"#s324", var"#s323"} where {var"#s324"<:Function, var"#s323"<:CustomExpectedReturnsValueAlgorithm}},
    X::AbstractMatrix{<:Union{var"#s89", var"#s88"} where {var"#s89"<:Number, var"#s88"<:AbstractJuMPScalar}};
    dims,
    kwargs...
) -> Any

Function overload of mean(me::CustomValueExpectedReturns, X::MatNum; dims::Int = 1, kwargs...). Delegates to the callable me.val with the same arguments, and validates the value it returns against the number of assets.