Exp weighted variance: private API

Types

PortfolioOptimisers.ExpWeightedVarianceState — Type
struct ExpWeightedVarianceState{__T_variance, __T_location, __T_obs_count, __T_active} <: AbstractPartialFitState

Internal mutable cache for the online variance update in ExpWeightedVariance.

This type is an implementation detail and is not intended for direct use.

Fields

  • variance: Running per-asset variance vector.
  • location: Exponentially smoothed location (mean) vector.
  • obs_count: Per-asset count of observations processed.
  • active: Boolean mask of the assets that are active now.

Related

source

Functions

PortfolioOptimisers.process_observation! — Method
process_observation!(
    cache::ExpWeightedVarianceState,
    ce::ExpWeightedVariance,
    X::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    active_mask::Union{Nothing, AbstractVector{<:Bool}}
) -> ExpWeightedVarianceState

Folds one observation into the online variance cache.

An asset is valid when its return is finite and the active mask admits it. A valid asset takes one step of the recursion, and an active asset with a non-finite return freezes. An asset that has just become inactive goes back to the cold state, so the bias correction starts again if it lists again.

Algorithm

  1. Mark each asset whose return is finite and that active_mask admits, giving valid. With nothing, valid is the finite mask alone.
  2. Where active_mask is not nothing, mark each asset that was active before this observation and is inactive now, giving newly_inactive. Set its variance and obs_count to zero, and its location to NaN.
  3. Store active_mask in active. With nothing, set every entry of active to true.
  4. If no entry of valid is true, return the cache unchanged.
  5. Take the deviations, and the mask dvalid of the assets that give a term, with centring_location!. It also moves the location of each valid asset.
  6. Divide the square of each deviation by its factor, centring_factor of the count before the observation. Give the variance of each asset of dvalid one step of the recursion of $S_i$, and add one to the obs_count of each valid asset.
  7. Return the cache.

An active asset whose return is not finite is not in valid, so steps 5 and 6 leave its state as it was: the state freezes over the holiday. Under EstimatedCentring the first valid return of an asset moves its location and its count, and gives no term.

Arguments

  • cache::ExpWeightedVarianceState: The online variance cache, which this call mutates.
  • ce::ExpWeightedVariance: Variance estimator configuration.
  • X::VecNum: Returns vector for the current observation.
  • active_mask::Option{<:AbstractVector{<:Bool}}: Optional mask of currently active assets. An asset that becomes inactive has its variance, its location and its count reset. With nothing every asset is active, so a non-finite return reads as a holiday.

Returns

  • cache::ExpWeightedVarianceState: The cache to read, and to pass to the next observation. Every field is an array that this call mutates in place.

Related

source
PortfolioOptimisers.exp_weighted_pass! — Function
exp_weighted_pass!(
    f,
    est::ExpWeightedVariance,
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    dims::Int64,
    active_mask::Union{Nothing, AbstractMatrix{<:Bool}}
) -> ExpWeightedVarianceState
exp_weighted_pass!(
    f,
    est::ExpWeightedVariance,
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    dims::Int64,
    active_mask::Union{Nothing, AbstractMatrix{<:Bool}},
    state::Union{Nothing, ExpWeightedVarianceState}
) -> ExpWeightedVarianceState

Variance method of exp_weighted_pass!. Runs one forward pass of the online variance update over the observations of X, and calls f after each observation. The pass continues from state when the caller gives one, and starts from the cold state otherwise. A verb that needs only the last cache passes Returns(nothing) as f.

Related

source
PortfolioOptimisers.exp_weighted_moment — Method
exp_weighted_moment(
    cache::ExpWeightedVarianceState,
    est::ExpWeightedVariance
) -> Any

Variance method of exp_weighted_moment. Reads the exponentially weighted variance out of a cache, as it stands.

Applies the cold-start bias correction and sets every asset that is not ready to NaN. This method reads the cache and never writes it, so the same cache answers this call after every observation of a forward pass.

Algorithm

  1. Copy cache.variance into variance.
  2. Take the count of the terms $K_i$ of each asset from its obs_count with centring_terms, and mark each asset with a positive count, giving counted.
  3. Give each counted asset the cold-start correction $1 / (1 - \lambda^{K_i})$. Every other asset keeps a correction of one.
  4. Multiply variance by correction.
  5. Mark each asset that is inactive, or that centring_ready does not find ready, giving not_ready, and set its entry of variance to NaN.
  6. Return variance.

Because $0 < \lambda < 1$, $1 - \lambda^{K_i} \geq 1 - \lambda > 0$ for every $K_i \geq 1$, so the division needs no floor.

Returns

  • variance::Vector{<:Number}: Per-asset variance vector. An asset that is inactive, or that carries fewer than est.min_obs valid observations, is NaN.

Related

source
PortfolioOptimisers.variance_series — Method
variance_series(
    ce::ExpWeightedVariance,
    X::MatNum;
    dims::Int = 1,
    active_mask::Option{<:AbstractMatrix{<:Bool}} = nothing,
    kwargs...
) -> Matrix{<:Number}

Compute the point-in-time exponentially weighted variance series.

Row t holds what var returns for the first t observations of X, so no row reads an observation after its own. The update is a recursion over one observation, so this method replaces the expanding-window fallback with one forward pass. It reads the cache after each observation instead of a refit.

The fallback cannot answer this estimator. It slices X once per row and passes every keyword unsliced, so a mask of the whole window meets a window of t observations and the size check refuses the call.

Arguments

  • ce: Exponentially weighted variance 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.
  • active_mask: Optional boolean matrix with the same size as X.
  • kwargs: More keyword arguments, which the method ignores.

Validation

  • dims in (1, 2).
  • If active_mask is not nothing, size(X) == size(active_mask).

Returns

  • val::Matrix{<:Number}: Variance series, shaped as (T, N) if dims == 1 or (N, T) if dims == 2. An asset with fewer than ce.min_obs observations at row t is NaN there.

Related

source
PortfolioOptimisers.variance_series — Method
variance_series(
    ce::ExpWeightedVariance,
    X::MatNum,
    pnl::Option{<:AssetPanel};
    dims::Int = 1,
    kwargs...
) -> Matrix{<:Number}

Compute the point-in-time exponentially weighted variance series from a window of an Asset Panel.

This is the variance of the same call, read after each observation, and it reads the panel's active mask through the same override. A Descriptor that holds this estimator keeps a number for a young asset, where the reduce-and-expand root would reduce every window and answer NaN.

Arguments

  • ce: Exponentially weighted variance estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • pnl: Optional AssetPanel. The Coverage Universe of the fit comes from its active mask. If it is nothing, the rule reads only the finiteness of the returns.
  • dims: Dimension along which the computation runs.
  • kwargs: More keyword arguments, which the method ignores.

Returns

  • val::Matrix{<:Number}: Variance series on the full asset universe, shaped as (T, N) if dims == 1 or (N, T) if dims == 2.

Related

source
Base.copy — Method
copy(
    x::ExpWeightedVarianceState
) -> ExpWeightedVarianceState

Copies an ExpWeightedVarianceState, so the copy shares no array with the original.

It is the copy method of the AbstractPartialFitState interface, which partial_fit calls before it folds. Every field is an array, and this method copies each one.

Arguments

  • x: The cache to copy.

Returns

  • state::ExpWeightedVarianceState: A fresh cache, equal to x, whose arrays are fresh.

Related

source
PortfolioOptimisers.exp_weighted_kish_count — Function
exp_weighted_kish_count(decay::Number, K::Integer) -> Any

Return the Kish count of K exponential weights, the closed form of variance_count(decay::Number, X::MatNum, centring::AbstractCentring, amsk::Option{<:AbstractMatrix{<:Bool}}).

The weights are proportional to $\lambda^{k}$, $k = 0, \ldots, K - 1$. The count is zero when K is zero.

Mathematical definition

\[\begin{align} \kappa &= \dfrac{\left(\sum_{k=0}^{K-1} \lambda^{k}\right)^{2}}{\sum_{k=0}^{K-1} \lambda^{2k}} = \dfrac{\left(1 - \lambda^{K}\right)\left(1 + \lambda\right)}{\left(1 - \lambda\right)\left(1 + \lambda^{K}\right)}\,. \end{align}\]

Where:

  • $\kappa$: Kish count of the weights.
  • $K$: Number of weights.
  • $\lambda$: decay, the decay factor of the exponentially weighted recursion.

Arguments

  • decay: Decay of the recursion.
  • K: Number of weights.

Returns

  • kappa::Number: The Kish count.

Related

source