Simple expected returns

The simplest estimate of the expected returns is the mean return of each asset. The types and functions below compute it, with or without observation weights.

PortfolioOptimisers.SimpleExpectedReturns — Type
struct SimpleExpectedReturns{__T_w, __T_cvg, __T_cache} <: AbstractExpectedReturnsEstimator

Computes the expected returns as the sample mean of the asset returns.

w holds the optional observation weights. If w is nothing, the mean is unweighted. The library uses this estimator as its default expected returns estimator.

Fields

  • w: Optional observation weights vector observations × 1, or a concrete subtype of DynamicAbstractWeights. If nothing, the computation is unweighted.
  • cvg: Optional CoveragePolicy. nothing selects the reduce-and-expand path of the Coverage Universe. On that path, an asset that is not finite or not active at an observation of the window is NaN in all of the result. A policy replaces that path with available-case estimation. The fit of each cell reads the observations at which all the assets of that cell are finite and active, and each cell has its own denominator. An asset is in the result where admits admits it.
  • cache: Optional partial-fit state. It is nothing until partial_fit! writes one. When the caller gives no data matrix, the batch verb of the estimator reads it. Each propagation channel does one thing with it. factory keeps it unchanged, because a factory call resolves the configuration, not the sample. port_opt_view copies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone. obs_weights_view removes it, because a state has no slice on the observation axis. Only a type with an observation-weights field has that channel. A type with no such field falls through to the identity method, so it keeps its state. A family whose state has no exact asset slice removes it on both axes and names the reason.

Constructors

SimpleExpectedReturns(;    w::Option{<:ObsWeights} = nothing,    cvg::Option{<:CoveragePolicy} = nothing,    cache::Option{<:AbstractPartialFitState} = nothing) -> SimpleExpectedReturns

Keywords correspond to the struct's fields.

Validation

  • If w is not nothing, !isempty(w).

Propagated parameters

factory passes its arguments on to these @fprop fields:

View parameters

port_opt_view takes the view of these @vprop fields at the selected indices:

Observation weight parameters

obs_weights_view indexes these fields to the selected observations:

Examples

julia> SimpleExpectedReturns()SimpleExpectedReturns  w ┴ nothingjulia> SimpleExpectedReturns(; w = StatsBase.Weights([0.5, 0.5]))SimpleExpectedReturns  w ┴ StatsBase.Weights{Float64, Float64, Vector{Float64}}: [0.5, 0.5]

Related

source
Statistics.mean — Method
Statistics.mean(
    me::SimpleExpectedReturns,
    X::MatNum;
    dims::Int = 1,
    kwargs...
) -> ArrNum

Compute the mean of the asset returns with a SimpleExpectedReturns estimator.

The method computes the expected returns as the sample mean of X, as me configures it.

Mathematical definition

Unweighted:

\[\begin{align} \hat{\mu}_j &= \frac{1}{T} \sum_{t=1}^{T} r_{tj}\,. \end{align}\]

Weighted:

\[\begin{align} \hat{\mu}_j &= \frac{\sum_{t=1}^{T} w_t \, r_{tj}}{\sum_{t=1}^{T} w_t}\,. \end{align}\]

Where:

  • $\hat{\boldsymbol{\mu}}$: The $N \times 1$ vector of estimated expected returns. Its $j$-th entry is $\hat{\mu}_j$.
  • $\hat{\mu}_j$: Estimated mean of asset $j$.
  • $r_{tj}$: Return of asset $j$ at time $t$.
  • $T$: Number of observations.
  • $w_{t}$: Observation weight of observation $t$.

Algorithm

  1. Check that dims is 1 or 2.
  2. Get the observation weights w from me.w and X.
  3. When w is nothing, take the unweighted mean of X along dims.
  4. Otherwise take the mean of X weighted by w along dims.

Arguments

  • me: Expected returns estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments for get_observation_weights, where a DynamicAbstractWeights can read them. The method does not pass them to Statistics.mean.

Validation

  • dims in (1, 2).

Returns

  • mu::ArrNum: Expected returns vector assets x 1 if the dims keyword does not exist or dims = 2, 1 x assets if dims = 1.

Examples

julia> X = [0.01 0.02; 0.03 0.04];julia> ser = SimpleExpectedReturns()SimpleExpectedReturns  w ┴ nothingjulia> mean(ser, X)1×2 Matrix{Float64}: 0.02  0.03julia> serw = SimpleExpectedReturns(; w = StatsBase.Weights([0.2, 0.8]))SimpleExpectedReturns  w ┴ StatsBase.Weights{Float64, Float64, Vector{Float64}}: [0.2, 0.8]julia> mean(serw, X)1×2 Matrix{Float64}: 0.026  0.036

Related

source

Incremental fit

The sample mean updates with each new block of observations, and does not read the earlier observations again. partial_fit! returns a new estimator whose cache field holds the running state, and mean(me) returns the estimate from the estimator alone.

PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    state::SimpleExpectedReturnsState,
    x::AbstractVector{<:Union{Number, AbstractJuMPScalar}}
) -> SimpleExpectedReturnsState

The SimpleExpectedReturnsState method of partial_fit! folds one observation into the count and the running mean.

Mathematical definition

\[\begin{align} n &\leftarrow n + 1\\ \boldsymbol{d} &= \boldsymbol{x} - \boldsymbol{\mu}\\ \boldsymbol{\mu} &\leftarrow \boldsymbol{\mu} + \frac{\boldsymbol{d}}{n}\, . \end{align}\]

Where:

  • $n$: The observation count.
  • $\boldsymbol{x}$: The observation.
  • $\boldsymbol{\mu}$: The running mean.
  • $\boldsymbol{d}$: The deviation of the observation from the mean before the fold.

Algorithm

  1. Refuse an observation whose length is not the number of assets that the state describes.
  2. Add one to the count.
  3. Add the deviation, divided by the new count, to mu in place.
  4. Build the state with the new count through its positional constructor, and return it.
source
PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    est::Union{AbstractEstimator, CovarianceEstimator},
    X::Union{AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, AbstractVector{<:Union{Number, AbstractJuMPScalar}}};
    dims,
    active_mask,
    estimation_mask,
    iv,
    ivpa
) -> Covariance{<:AbstractExpectedReturnsEstimator, <:CovarianceEstimator, <:AbstractMomentAlgorithm}

Folds observations into the sample buffer an estimator carries.

This is the buffering arm of partial_fit!. Each estimator that carries a SampleBufferState reaches this method. A family that folds exactly has methods of its own, and each of them narrows the cache type parameter of its estimator to the state of that fold. So a buffer never reaches them, and it reaches this method. The type of the state selects the route, and no method refuses the step.

The method covers both arms of the interface. The families that refuse the step also declare one method over both arms, and two narrower methods here would be ambiguous against each of them. So the body selects the arm by the type of X, and the compiler resolves that branch at each call site.

A buffer carries the per-observation masks beside the observations. So a CoveragePolicy mask goes through the wrapper as it goes through the accumulator of an estimator, and the call with no data gives it back to the batch verb. A wrapped estimator folded under a policy gives the answer of a batch fit over the same window under the same policy. The implied volatilities and ivpa go through the wrapper in the same way, so a wrapped estimator that reads them, such as an ImpliedVolatility inside a PortfolioOptimisersCovariance, gives the answer of a batch fit over the same rows.

Algorithm

  1. Read the buffer out of the cache field with assert_sample_buffer, which refuses an estimator that was never wrapped in Online.
  2. Fold a matrix, its masks and its implied volatilities through the block arm of partial_fit!, and a vector, its masks and its implied volatilities through the single-observation arm.
  3. Rebuild the estimator with the new buffer in cache through rebuild_struct, and return it.

Arguments

  • est: Estimator whose buffer is folded forward.
  • X: Observations to fold. A matrix holds one observation per row when dims == 1, and one per column when dims == 2. A vector is a single observation across the assets, and dims is ignored.
  • dims: Dimension along which the computation runs.
  • active_mask: The active mask of the block, of the shape of X, or of one entry per asset when X is one observation, or nothing.
  • estimation_mask: The estimation mask, on the same terms as active_mask.
  • iv: The implied volatilities, on the same terms as active_mask.
  • ivpa: The implied volatility risk premium adjustment, or nothing.

Validation

  • est carries a SampleBufferState. An ArgumentError is thrown otherwise.
  • The masks and iv, when they are not nothing, have the shape of X. A DimensionMismatch is thrown otherwise.
  • A buffer that holds observations receives the masks that it records, and it receives iv if and only if it records implied volatilities. An ArgumentError is thrown otherwise.
  • ivpa equals the adjustment that the first append pinned. An ArgumentError is thrown otherwise.
  • dims in (1, 2).

Returns

  • est: The estimator, with its cache field rebound to the buffer after the last observation.

Related

source
PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    est::Union{AbstractEstimator, CovarianceEstimator},
    X::Union{AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, AbstractVector{<:Union{Number, AbstractJuMPScalar}}};
    dims,
    active_mask,
    estimation_mask,
    iv,
    ivpa
) -> Covariance{<:AbstractExpectedReturnsEstimator, <:CovarianceEstimator, <:AbstractMomentAlgorithm}

Folds observations into the sample buffer an estimator carries.

This is the buffering arm of partial_fit!. Each estimator that carries a SampleBufferState reaches this method. A family that folds exactly has methods of its own, and each of them narrows the cache type parameter of its estimator to the state of that fold. So a buffer never reaches them, and it reaches this method. The type of the state selects the route, and no method refuses the step.

The method covers both arms of the interface. The families that refuse the step also declare one method over both arms, and two narrower methods here would be ambiguous against each of them. So the body selects the arm by the type of X, and the compiler resolves that branch at each call site.

A buffer carries the per-observation masks beside the observations. So a CoveragePolicy mask goes through the wrapper as it goes through the accumulator of an estimator, and the call with no data gives it back to the batch verb. A wrapped estimator folded under a policy gives the answer of a batch fit over the same window under the same policy. The implied volatilities and ivpa go through the wrapper in the same way, so a wrapped estimator that reads them, such as an ImpliedVolatility inside a PortfolioOptimisersCovariance, gives the answer of a batch fit over the same rows.

Algorithm

  1. Read the buffer out of the cache field with assert_sample_buffer, which refuses an estimator that was never wrapped in Online.
  2. Fold a matrix, its masks and its implied volatilities through the block arm of partial_fit!, and a vector, its masks and its implied volatilities through the single-observation arm.
  3. Rebuild the estimator with the new buffer in cache through rebuild_struct, and return it.

Arguments

  • est: Estimator whose buffer is folded forward.
  • X: Observations to fold. A matrix holds one observation per row when dims == 1, and one per column when dims == 2. A vector is a single observation across the assets, and dims is ignored.
  • dims: Dimension along which the computation runs.
  • active_mask: The active mask of the block, of the shape of X, or of one entry per asset when X is one observation, or nothing.
  • estimation_mask: The estimation mask, on the same terms as active_mask.
  • iv: The implied volatilities, on the same terms as active_mask.
  • ivpa: The implied volatility risk premium adjustment, or nothing.

Validation

  • est carries a SampleBufferState. An ArgumentError is thrown otherwise.
  • The masks and iv, when they are not nothing, have the shape of X. A DimensionMismatch is thrown otherwise.
  • A buffer that holds observations receives the masks that it records, and it receives iv if and only if it records implied volatilities. An ArgumentError is thrown otherwise.
  • ivpa equals the adjustment that the first append pinned. An ArgumentError is thrown otherwise.
  • dims in (1, 2).

Returns

  • est: The estimator, with its cache field rebound to the buffer after the last observation.

Related

source
Statistics.mean — Method
Statistics.mean(
    me::SimpleExpectedReturns,
    state::SimpleExpectedReturnsState
) -> VecNum
Statistics.mean(
    me::SimpleExpectedReturns
) -> VecNum

Read the mean of an incremental fit from a SimpleExpectedReturnsState.

The two-argument method reads a state that the caller holds. The one-argument method reads the state in the cache field of me. Both methods return the running mean as a vector, assets × 1. The batch method over a matrix returns a row when dims = 1.

Algorithm

  1. Refuse a configuration that no incremental fit can reproduce, with assert_partial_fittable.
  2. Return a vector of NaN when the state holds no observation. min_obs reads an asset with too few observations in the same way.
  3. Otherwise return the running mean.

Arguments

  • me: Expected returns estimator.
  • state: The state to read.

Validation

  • me holds no observation weights. An ArgumentError is thrown otherwise.
  • me.cache is not nothing, for the one-argument method. An ArgumentError is thrown otherwise.

Returns

  • mu::VecNum: The running mean of the fit, assets × 1, with NaN where the state holds no observation.

Examples

julia> me = foldl(partial_fit!, eachrow([1.0 2.0; 3.0 4.0]); init = SimpleExpectedReturns());julia> mean(me)2-element Vector{Float64}: 2.0 3.0

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    x::SimpleExpectedReturnsState,
    i,
    args...
) -> Union{SimpleExpectedReturnsState{_A, _B, Nothing} where {_A, _B}, SimpleExpectedReturnsState{_A, _B, __T_cvg} where {_A, _B, __T_cvg<:CoverageCounts}}

Slices a SimpleExpectedReturnsState to the selected assets.

The Welford mean of one asset reads only the observations of that asset, so the slice of the state is the state of the sliced universe, entry for entry. All the assets share the count, so the method uses it without change. The slice copies by index and does not use a view. With a view, a later partial_fit! on the viewed estimator writes into the arrays of the original estimator.

Arguments

  • x: The state to slice.
  • i: The index or the indices of the assets to keep.
  • args...: More positional arguments, which the method ignores.

Returns

  • state::SimpleExpectedReturnsState: The state of the same sample over the selected assets.

Related

source
PortfolioOptimisers.merge_states — Method
merge_states(
    a::SimpleExpectedReturnsState,
    b::SimpleExpectedReturnsState
) -> Union{SimpleExpectedReturnsState{_A, _B, Nothing} where {_A, _B}, SimpleExpectedReturnsState{_A, _B, __T_cvg} where {_A, _B, __T_cvg<:(CoverageCounts{_A, Nothing} where _A)}}

Folds two SimpleExpectedReturnsState fitted on disjoint blocks into the state of the concatenated block.

Algorithm

  1. Refuse the pair with assert_mergeable_states.
  2. If one of the two states holds no coverage counts, fold the counts and the means with chan_merge. Its accumulator argument is false, which is the zero of a state that has no accumulator. Discard the accumulator that it returns.
  3. Otherwise, fold the mean of each asset with the per-asset counts nu of the two states. An asset with no observation in the two blocks keeps a mean of zero. Merge the coverage counts too.

Arguments

  • a: The state of the first block of observations.
  • b: The state of the second block of observations.

Validation

Returns

  • state::SimpleExpectedReturnsState: The state of the two blocks, as if one fit read them as one block.

Related

source

Available-case fit

With a CoveragePolicy in its cvg field, the estimator fits each asset on the observations where that asset is finite and active. Without a policy, it fits on the coverage universe, the assets that are finite and active at every observation. PortfolioOptimisers.coverage_mean chooses between the two fits.

PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    state::SimpleExpectedReturnsState,
    x::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    _::Nothing,
    active_mask::Union{Nothing, AbstractVector{<:Bool}}
) -> SimpleExpectedReturnsState

This is the Nothing method of the coverage arm of partial_fit!. An estimator that holds no CoveragePolicy folds through partial_fit!(state::SimpleExpectedReturnsState, x::VecNum). A plain state holds one count for all the assets, so it cannot skip an inactive cell. inactive_as_nonfinite writes NaN in that cell, and the mean of the asset is then NaN. The Asset Panel method gives the same NaN for an asset outside the Coverage Universe of the same rows.

Related

source
PortfolioOptimisers.partial_fit! — Method
partial_fit!(
    state::SimpleExpectedReturnsState,
    x::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    cvg::CoveragePolicy,
    active_mask::Union{Nothing, AbstractVector{<:Bool}}
) -> SimpleExpectedReturnsState

This is the CoveragePolicy method of the coverage arm of partial_fit!. It folds one observation into the count and the running mean of each asset. Each asset reads only its own observations.

Mathematical definition

\[\begin{align} \nu_j &\leftarrow \nu_j + 1\\ \mu_j &\leftarrow \mu_j + \frac{r_{tj} - \mu_j}{\nu_j}\, , \end{align}\]

for each asset $j$ that is finite and active at observation $t$. The method applies neither line to an asset that is not finite and active. Where:

  • $\nu_j$: The number of observations at which asset $j$ is finite and active.
  • $r_{tj}$: Return of asset $j$ at time $t$.
  • $\mu_j$: The running mean of asset $j$.

An asset with no observation keeps $\mu_j = 0$ and $\nu_j = 0$. mean(me) with no data returns NaN for it, so no caller reads the zero as an estimate. This is the Welford recursion for each asset. A mean that folds one observation at a time is the mean of the same rows in one block fit.

Algorithm

  1. Refuse an observation whose length is not the number of assets that the state describes.
  2. Read the valid assets, and the assets that became inactive at this observation, with coverage_valid.
  3. Apply the fold-time rule of the coverage algorithm with fold_inactive!.
  4. Fold the return of each valid asset into the count and the mean of that asset.
  5. Update the per-asset records with coverage_step!. Add one to the observation count, and return the state.

Arguments

  • state: The state to fold into. The method changes it in place.
  • x: One observation, with one entry for each asset.
  • cvg: The policy that the estimator holds.
  • active_mask: The active mask of the Asset Panel at this observation, or nothing.

Validation

  • length(x) is the number of assets that the state describes. A DimensionMismatch is thrown otherwise.

Returns

  • state::SimpleExpectedReturnsState: The state after the observation.

Related

source
PortfolioOptimisers.fold_inactive! — Method
fold_inactive!(
    _::ResetCoverage,
    state::SimpleExpectedReturnsState,
    ni::AbstractVector{<:Bool}
) -> SimpleExpectedReturnsState

This is the SimpleExpectedReturnsState method of fold_inactive! under ResetCoverage. It sets to zero the count, the centre and the running mean of each asset that became inactive at this observation. A relisted asset then starts cold. The centre of a per-asset state is nothing, because its mu is already the centre of the cell. coverage_reset! does nothing to a nothing.

Related

source