Simple expected returns: private API
The simplest estimate of the expected return of an asset is its sample mean, which SimpleExpectedReturns computes. The entries below support it.
PortfolioOptimisers.show_fields — Method
show_fields(
me::SimpleExpectedReturns
) -> Union{Tuple{Symbol}, Tuple{Symbol, Symbol}}
Renders every field of a SimpleExpectedReturns except cache, and cvg only where a policy is set.
A cache holds the state of an incremental fit. That state is not part of the configuration, and it prints under the estimator at each site that renders the estimator. Set set_show_nothing_fields!(:SimpleExpectedReturns, true) to render it. The method reads cvg from the instance and not from the type, because an option that the caller did not set is not part of the configuration that the caller chose. An estimator whose cvg is nothing renders as it did before the field existed. An estimator that holds a CoveragePolicy renders it.
Arguments
me: The expected returns estimator. The method reads only itscvgfield.
Returns
fields::Tuple: The field names to render, which is(:w,)with no policy and(:w, :cvg)with one.
Related
Incremental fit
The sample mean can take the observations one at a time, so you do not need to keep a long history or read it again. partial_fit! returns a new estimator whose cache field holds the running count and mean. mean(me) then computes the estimate from that field, with no data.
PortfolioOptimisers.SimpleExpectedReturnsState — Type
struct SimpleExpectedReturnsState{__T_n, __T_mu, __T_cvg} <: AbstractPartialFitStateHolds the observation count and the running mean of an incremental sample-mean fit.
It is the state of SimpleExpectedReturns under partial_fit!. It holds no second-moment accumulator, because the mean is the whole estimate. merge_states folds the two counts and the two means, and it discards the accumulator that chan_merge returns.
Fields
n: Number of observations folded into the state.
mu: Running mean of the observations folded into the state,assets × 1.
cvg: OptionalCoverageCounts, the per-cell denominators and the per-asset records of an available-case fold. It isnothingwhen the estimator holds noCoveragePolicy, so the plain state costs nothing.
Constructors
SimpleExpectedReturnsState(; n::Integer = 0, mu::VecNum, cvg::Option{<:CoverageCounts} = nothing) -> SimpleExpectedReturnsStateKeywords correspond to the struct's fields. A state seeded for N assets is SimpleExpectedReturnsState(; mu = zeros(N)), which partial_fit! builds when the cache field of the estimator holds nothing.
Validation
n >= 0. ADomainErroris thrown otherwise.!isempty(mu). AnIsEmptyErroris thrown otherwise.- Every entry of
muis finite. AnIsNonFiniteErroris thrown otherwise.
The positional constructor runs the first two checks, see assert_partial_fit_state, so a fold and a lens write run them too. The keyword constructor alone runs the scan for finite values, see assert_partial_fit_values.
View parameters
port_opt_view takes the view of its fields at the selected assets:
mu: Sliced to the selected indices throughport_opt_view.
Examples
julia> PortfolioOptimisers.SimpleExpectedReturnsState(; mu = [0.0, 0.0])PortfolioOptimisers.SimpleExpectedReturnsState n ┼ Int64: 0 mu ┼ Vector{Float64}: [0.0, 0.0] cvg ┴ nothingRelated
PortfolioOptimisers.expected_returns_state_seed — Function
expected_returns_state_seed(cache::Nothing, x::VecNum,
cvg::Option{<:CoveragePolicy} = nothing) -> SimpleExpectedReturnsState
expected_returns_state_seed(cache::SimpleExpectedReturnsState, x::VecNum,
cvg::Option{<:CoveragePolicy} = nothing) -> SimpleExpectedReturnsStateReturns the SimpleExpectedReturnsState that an incremental mean fit folds into. If the estimator holds no state, the function seeds a state of zeros.
The seed is in this function and not in partial_fit!, so the fold is one line, and the dispatch on the type of the cache field is in one place.
Arguments
cache: The state that the estimator holds, ornothing.x: One observation,assets × 1. The function reads only its length and its element type.cvg: The policy that the estimator holds. It decides if the seed holds per-asset counts.
Returns
state::SimpleExpectedReturnsState: The state thatcacheholds, or a state of zeros overlength(x)assets.
Related
Base.copy — Method
copy(
x::SimpleExpectedReturnsState
) -> SimpleExpectedReturnsState
Copies a SimpleExpectedReturnsState, so the copy shares no array with the original.
This method is the copy method of the AbstractPartialFitState interface, which partial_fit calls before it folds. The count is a scalar, and the method uses it without change. The method copies the running mean and the coverage counts.
Arguments
x: The state to copy.
Returns
state::SimpleExpectedReturnsState: A new state, equal tox, whosemuis a new vector.
Related
Available-case fit
With a CoveragePolicy in its cvg field, the estimator computes the mean of each asset from the rows where that asset's return is finite and the asset is active. This is the available-case fit. Without a policy, the estimator computes the ordinary sample mean over the assets that have no gap in the window. PortfolioOptimisers.coverage_mean selects one of the two fits from the type of the cvg field.
The available-case fit centres each asset on the mean of its own rows, so it takes no other centre. With observation weights, it fits each asset over its own rows with their weights, in one pass. The constructor of each estimator with a cvg field refuses a configuration that neither fit can read, with PortfolioOptimisers.assert_coverage_fittable.
PortfolioOptimisers.assert_coverage_fittable — Function
assert_coverage_fittable(cvg::Nothing, args...)
assert_coverage_fittable(cvg::CoveragePolicy,
me::Option{<:AbstractExpectedReturnsEstimator}, w::Nothing,
name::AbstractString)
assert_coverage_fittable(cvg::CoveragePolicy,
me::Option{<:AbstractExpectedReturnsEstimator}, w::ObsWeights,
name::AbstractString)
assert_coverage_fittable(cvg::CoveragePolicy,
me::Option{<:AbstractExpectedReturnsEstimator},
w::Option{<:ObsWeights}, name::AbstractString,
ce::StatsBase.CovarianceEstimator)Refuses, at construction, an estimator whose CoveragePolicy cannot fit with the rest of its configuration.
The available-case arm of each batch verb centres each asset on its own observations, and the type of w selects the arm.
- No weights. The arm folds the block through
partial_fit!, so it takes only a configuration that an incremental fit takes. The centre is the running sample mean, and the inner estimator of aCovariancemust be aStatsBase.SimpleCovariancewith no weights. - Observation weights. The arm makes one pass over the block. It fits each asset, each pair and each cell of a co-moment over its own valid observations, with their weights, as
observed_samplestates. The centre is the weighted mean of the observations of each asset, somemust benothingor aSimpleExpectedReturns, whose weightswreplaces. The inner estimator of aCovariancemust read as aStatsBase.SimpleCovariance, throughcoverage_inner_corrected.
The configuration alone decides the refusal, so the constructor makes it, and not the fit. factory rebuilds an estimator through its constructor, so the rules hold on the estimator that a prior builds. The SimpleExpectedReturns, SimpleVariance, Covariance, Coskewness and Cokurtosis constructors call the function. An estimator with no me field passes nothing.
Arguments
cvg: The policy of the estimator. TheNothingmethod checks nothing.me: The estimator that centres the fit, ornothing.w: The observation weights of the estimator, ornothing.name: The name of the estimator, for the message.ce: The inner covariance estimator of aCovariance.
Validation
- With no weights,
meisnothingor aSimpleExpectedReturnswith no weights, throughassert_partial_fittable. With weights,meisnothingor aSimpleExpectedReturns. AnArgumentErroris thrown otherwise. cereads the sample as aStatsBase.SimpleCovariance, throughpartial_fit_correctedwith no weights and throughcoverage_inner_correctedwith weights. With no weights, it holds no weights of its own. AnArgumentErroris thrown otherwise.
Returns
nothing.
Related
PortfolioOptimisers.coverage_mean — Function
coverage_mean(me, cvg, X; dims::Int = 1, active_mask = nothing, kwargs...) -> ArrNumRoutes a sample-mean fit to the Coverage Universe arm or to the available-case arm.
The cvg field of the estimator is the second argument, so dispatch on the policy selects the arm, not a branch on its value. The field costs nothing for an estimator that holds no policy. The Nothing method is the body that mean(me::SimpleExpectedReturns, X::MatNum; dims::Int = 1, kwargs...) had before the field existed. The compiler resolves it statically, because the type of the field is concrete.
Arguments
me: Expected returns estimator.cvg: The policy that the estimator holds. It selects the arm.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.dims: Dimension along which the computation runs.active_mask: The active mask of the Asset Panel,observations × assets, ornothing. The Coverage Universe arm refuses an inactive cell, as it refuses a return that is not finite.kwargs...: More keyword arguments. TheNothingmethod passes them toget_observation_weights. TheCoveragePolicymethod ignores them.
Returns
mu::ArrNum: Expected returns vectorassets x 1if thedimskeyword does not exist ordims = 2,1 x assetsifdims = 1.
Related
PortfolioOptimisers.coverage_mean — Method
coverage_mean(
me::SimpleExpectedReturns,
::Nothing,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}};
dims,
active_mask,
kwargs...
) -> Any
The Nothing method of coverage_mean is the Coverage Universe arm. It returns the sample mean of a window that every asset covers. This is the result that mean(me::SimpleExpectedReturns, X::MatNum; dims::Int = 1, kwargs...) gave before the cvg field existed. It refuses a gapped sample with assert_finite_sample. A cell is a gap when its return is not finite or when active_mask is false at that cell, so the arm refuses an inactive cell too. An estimator with no policy reads the universe through coverage_reduction, which gives it a block with no gap.
Related
PortfolioOptimisers.coverage_mean — Method
coverage_mean(
me::SimpleExpectedReturns,
cvg::CoveragePolicy,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}};
dims,
active_mask,
kwargs...
) -> Any
The CoveragePolicy method of coverage_mean is the available-case arm. It fits the mean of each asset on the finite and active observations of that asset. The batch result is the incremental result, because the arm folds the block through partial_fit! and then reads the state.
Because the batch arm is the fold, the batch result and the incremental result agree to the last bit, not only to a tolerance. There is one recursion, so a caller who gives the same rows one at a time gets the same floating-point number.
Algorithm
- Fold each row of
Xinto a new state withpartial_fit!, together with its row of the active mask. - Read the state with
mean(me::SimpleExpectedReturns, state::SimpleExpectedReturnsState). - Orient the result as the
dimsof the caller sets.
Related
PortfolioOptimisers.coverage_mean — Method
coverage_mean(
_::SimpleExpectedReturns,
_::Nothing,
state::SimpleExpectedReturnsState
) -> Any
This is the Nothing method of coverage_mean for a state. mean(me) with no data calls it. All the assets share one count, so the result is all NaN before the first observation, and the running mean after it.
The method returns a copy of the running mean, not the vector in the state. partial_fit! writes the Welford recursion into state.mu in place. A returned reference to that vector changes at the next fold, with no message to the caller. A prior that puts that mu into a Result then has a Result that changes after the next observation. The CoveragePolicy method of this file copies for the same reason, through coverage_frame.
Related
PortfolioOptimisers.coverage_mean — Method
coverage_mean(
_::SimpleExpectedReturns,
cvg::CoveragePolicy,
state::SimpleExpectedReturnsState
) -> Any
This is the CoveragePolicy method of coverage_mean for a state. mean(me) with no data calls it. The method reads the mean of each asset with the count of that asset. An asset that the policy refuses is NaN.
Algorithm
- Read the admitted assets with
coverage_admission. - Put the running mean in a frame with
coverage_frame, which copies the mean of each asset that has an observation. A running per-asset mean is already the ratio, so the method does not divide it again.
Related