Custom value expected returns

PortfolioOptimisers.CustomExpectedReturnsValueAlgorithm — Type
abstract type CustomExpectedReturnsValueAlgorithm <: AbstractCustomValue

Abstract supertype for the custom expected returns value algorithms. A subtype is one of the types that the val field of CustomValueExpectedReturns accepts.

Interfaces

To add a custom expected returns value algorithm, subtype CustomExpectedReturnsValueAlgorithm and make the subtype callable. The call must return a vector with one element per asset of the returns matrix:

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

Where:

  • alg: The custom expected returns value algorithm.
  • X: The data matrix of asset returns.
  • dims: 1 when the observations run down the rows of X, and 2 when they run along the columns.
  • kwargs...: The keyword arguments of the mean call, which the estimator passes on.

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

source
PortfolioOptimisers.CustomValueExpectedReturns — Type
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. The type of val selects the branch that mean(me::CustomValueExpectedReturns, X::MatNum; dims::Int = 1, kwargs...) takes. The keyword constructor takes a val of the CER_Func_Num_VecNum bound alone, and raises a TypeError on any other type. The field itself has no bound, so a positional call with another type builds the estimator without a check.

The constructor checks only that a vector is not empty, because it does not know the number of assets before the data arrive. assert_custom_expected_returns_val checks the length of a stored vector, and the shape and the length of what a callable returns, when mean uses them.

Fields

  • val: Custom expected returns value.

    • If a scalar, every asset gets this value.
    • If a vector, each element is the value of one asset.
    • If a callable, the estimator calls it as val(X; dims = dims, kwargs...), and it 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

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

Compute expected returns as custom values.

Mathematical definition

The method returns the scalar, the vector, or the result of the callable that the caller gave as val.

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

Where:

  • $\hat{\mu}_j$: The expected return of asset $j$.
  • $v_j$: The $j$-th element of the custom value me.val. A scalar gives the same $v_j$ to every asset. A vector gives its $j$-th element. A callable gives the $j$-th element of its result.
  • $N$: Number of assets.

Algorithm

  1. Check dims.

  2. Read the asset count _ncols from X and dims, as the size of the dimension that dims does not name.

  3. Take the branch that the type of me.val selects.

    • me.val::Number: Fill a vector of length _ncols with me.val.
    • me.val::VecNum: Check the stored me.val against _ncols with assert_custom_expected_returns_val, and take it unchanged.
    • me.val::Function or me.val::CustomExpectedReturnsValueAlgorithm: Call me.val(X; dims = dims, kwargs...). The result is val. Check val against _ncols with assert_custom_expected_returns_val.
  4. On the first two branches, insert the reduced dimension with insertdims. The callable branch returns val unchanged, and inserts no dimension.

Arguments

  • me: The custom value expected returns estimator.
  • X: The data matrix of asset returns, observations × assets.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments. The callable branch passes them to me.val. The other two branches ignore them.

Validation

Returns

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

    • me.val::Number and me.val::VecNum: A Matrix{<:Number}. It is a (1, N) matrix if dims == 1 or an (N, 1) matrix if dims == 2, as most 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

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    me::CustomValueExpectedReturns{<:VecNum},
    i,
    args...
) -> CustomValueExpectedReturns

The port_opt_view method for the per-asset vector shape of CustomValueExpectedReturns. It slices val to the selected assets.

val is the one field of the estimator, and only the vector shape has one entry per asset. A scalar does not depend on the universe. A callable gets the reduced matrix and returns one value per column of it. Both therefore keep the identity method of AbstractExpectedReturnsEstimator. A stored vector has one entry per asset of the universe that the caller wrote it for. If a reduction left it whole, the vector would keep the full universe while the sample has fewer assets, and mean(me::CustomValueExpectedReturns, X::MatNum; dims::Int = 1, kwargs...) would raise a DimensionMismatch.

The bound of val is a union of the three shapes. An @vprop tag on the field would slice all three, so this file declares a method on the vector shape alone.

Algorithm

  1. Return a new estimator whose val is view(me.val, i).

Arguments

  • me::CustomValueExpectedReturns{<:VecNum}: The estimator whose val is one entry per asset.
  • i: The index or the mask of the assets to select.
  • args...: More positional arguments of the port_opt_view call, which the method ignores.

Returns

  • me::CustomValueExpectedReturns: A new estimator whose val is restricted to the selected assets.

Related

source