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} <: AbstractExpectedReturnsEstimatorComputes 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 vectorobservations × 1, or a concrete subtype ofDynamicAbstractWeights. Ifnothing, the computation is unweighted.
cvg: OptionalCoveragePolicy.nothingselects 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 isNaNin 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 whereadmitsadmits it.
cache: Optional partial-fit state. It isnothinguntilpartial_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.factorykeeps it unchanged, because a factory call resolves the configuration, not the sample.port_opt_viewcopies the entries of the selected assets into a new state, so the viewed estimator holds the state of those assets alone.obs_weights_viewremoves 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) -> SimpleExpectedReturnsKeywords correspond to the struct's fields.
Validation
- If
wis notnothing,!isempty(w).
Propagated parameters
factory passes its arguments on to these @fprop fields:
w: Replaced with the incomingObsWeights.cache: Carried unchanged throughfactory.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
cache: Sliced to the selected assets throughport_opt_view.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
w: Indexed to the selected observations throughobs_weights_view.cache: Removed byobs_weights_view, because a state has no slice on the observation axis.
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
Statistics.mean — Method
Statistics.mean(
me::SimpleExpectedReturns,
X::MatNum;
dims::Int = 1,
kwargs...
) -> ArrNumCompute 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
- Check that
dimsis1or2. - Get the observation weights
wfromme.wandX. - When
wisnothing, take the unweighted mean ofXalongdims. - Otherwise take the mean of
Xweighted bywalongdims.
Arguments
me: Expected returns estimator.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.dims: Dimension along which the computation runs.kwargs...: More keyword arguments forget_observation_weights, where aDynamicAbstractWeightscan read them. The method does not pass them toStatistics.mean.
Validation
dims in (1, 2).
Returns
mu::ArrNum: Expected returns vectorassets x 1if thedimskeyword does not exist ordims = 2,1 x assetsifdims = 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.036Related
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
- Refuse an observation whose length is not the number of assets that the state describes.
- Add one to the count.
- Add the deviation, divided by the new count, to
muin place. - Build the state with the new count through its positional constructor, and return it.
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
) -> Union{ExpWeightedVariance{<:Any, <:Any, <:Any, <:Union{Nothing, var"#s2433"} where var"#s2433"<:ExpWeightedVarianceState}, ExpWeightedVariance{<:Number, <:Integer, <:AbstractCentring, <:AbstractPartialFitState}}
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
- Read the buffer out of the
cachefield withassert_sample_buffer, which refuses an estimator that was never wrapped inOnline. - 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. - Rebuild the estimator with the new buffer in
cachethroughrebuild_struct, and return it.
Arguments
est: Estimator whose buffer is folded forward.X: Observations to fold. A matrix holds one observation per row whendims == 1, and one per column whendims == 2. A vector is a single observation across the assets, anddimsis ignored.dims: Dimension along which the computation runs.active_mask: The active mask of the block, of the shape ofX, or of one entry per asset whenXis one observation, ornothing.estimation_mask: The estimation mask, on the same terms asactive_mask.iv: The implied volatilities, on the same terms asactive_mask.ivpa: The implied volatility risk premium adjustment, ornothing.
Validation
estcarries aSampleBufferState. AnArgumentErroris thrown otherwise.- The masks and
iv, when they are notnothing, have the shape ofX. ADimensionMismatchis thrown otherwise. - A buffer that holds observations receives the masks that it records, and it receives
ivif and only if it records implied volatilities. AnArgumentErroris thrown otherwise. ivpaequals the adjustment that the first append pinned. AnArgumentErroris thrown otherwise.dims in (1, 2).
Returns
est: The estimator, with itscachefield rebound to the buffer after the last observation.
Related
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
) -> Union{ExpWeightedVariance{<:Any, <:Any, <:Any, <:Union{Nothing, var"#s2433"} where var"#s2433"<:ExpWeightedVarianceState}, ExpWeightedVariance{<:Number, <:Integer, <:AbstractCentring, <:AbstractPartialFitState}}
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
- Read the buffer out of the
cachefield withassert_sample_buffer, which refuses an estimator that was never wrapped inOnline. - 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. - Rebuild the estimator with the new buffer in
cachethroughrebuild_struct, and return it.
Arguments
est: Estimator whose buffer is folded forward.X: Observations to fold. A matrix holds one observation per row whendims == 1, and one per column whendims == 2. A vector is a single observation across the assets, anddimsis ignored.dims: Dimension along which the computation runs.active_mask: The active mask of the block, of the shape ofX, or of one entry per asset whenXis one observation, ornothing.estimation_mask: The estimation mask, on the same terms asactive_mask.iv: The implied volatilities, on the same terms asactive_mask.ivpa: The implied volatility risk premium adjustment, ornothing.
Validation
estcarries aSampleBufferState. AnArgumentErroris thrown otherwise.- The masks and
iv, when they are notnothing, have the shape ofX. ADimensionMismatchis thrown otherwise. - A buffer that holds observations receives the masks that it records, and it receives
ivif and only if it records implied volatilities. AnArgumentErroris thrown otherwise. ivpaequals the adjustment that the first append pinned. AnArgumentErroris thrown otherwise.dims in (1, 2).
Returns
est: The estimator, with itscachefield rebound to the buffer after the last observation.
Related
Statistics.mean — Method
Statistics.mean(
me::SimpleExpectedReturns,
state::SimpleExpectedReturnsState
) -> VecNum
Statistics.mean(
me::SimpleExpectedReturns
) -> VecNumRead 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
- Refuse a configuration that no incremental fit can reproduce, with
assert_partial_fittable. - Return a vector of
NaNwhen the state holds no observation.min_obsreads an asset with too few observations in the same way. - Otherwise return the running mean.
Arguments
me: Expected returns estimator.state: The state to read.
Validation
meholds no observation weights. AnArgumentErroris thrown otherwise.me.cacheis notnothing, for the one-argument method. AnArgumentErroris thrown otherwise.
Returns
mu::VecNum: The running mean of the fit,assets × 1, withNaNwhere 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.0Related
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
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
- Refuse the pair with
assert_mergeable_states. - If one of the two states holds no coverage counts, fold the counts and the means with
chan_merge. Its accumulator argument isfalse, which is the zero of a state that has no accumulator. Discard the accumulator that it returns. - Otherwise, fold the mean of each asset with the per-asset counts
nuof 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
aandbpassassert_mergeable_states.
Returns
state::SimpleExpectedReturnsState: The state of the two blocks, as if one fit read them as one block.
Related
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
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
- Refuse an observation whose length is not the number of assets that the state describes.
- Read the valid assets, and the assets that became inactive at this observation, with
coverage_valid. - Apply the fold-time rule of the coverage algorithm with
fold_inactive!. - Fold the return of each valid asset into the count and the mean of that asset.
- 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, ornothing.
Validation
length(x)is the number of assets that the state describes. ADimensionMismatchis thrown otherwise.
Returns
state::SimpleExpectedReturnsState: The state after the observation.
Related
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