Cokurtosis

PortfolioOptimisers.CokurtosisEstimator — Type
abstract type CokurtosisEstimator <: AbstractEstimator

Abstract supertype for all cokurtosis estimators.

A subtype computes the square cokurtosis matrix of a returns matrix.

Interfaces

To add a cokurtosis estimator, subtype CokurtosisEstimator, keep its parameters and its observation weights in the fields of the struct, and add these methods:

Cokurtosis

  • PortfolioOptimisers.cokurtosis(kte::CokurtosisEstimator, X::MatNum; dims::Int = 1, mean = nothing, kwargs...) -> MatNum: Returns the square cokurtosis matrix.

Arguments

  • kte: Cokurtosis 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.
  • mean: Optional precomputed centre of the data.
  • kwargs...: More keyword arguments.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Factory

  • PortfolioOptimisers.factory(kte::CokurtosisEstimator, w::PortfolioOptimisers.ObsWeights) -> CokurtosisEstimator: Returns a copy of the estimator that holds the new observation weights.

Arguments

  • kte: Cokurtosis estimator.
  • w: Observation weights vector observations × 1.

Returns

  • kte::CokurtosisEstimator: A new cokurtosis estimator of the same type, with the new weights.

View

  • PortfolioOptimisers.port_opt_view(kte::CokurtosisEstimator, i) -> CokurtosisEstimator: Returns the estimator for the assets that i selects.

Arguments

  • kte: Cokurtosis estimator.
  • i: The index or the indices of the assets to keep.

Returns

  • ktev: New cokurtosis estimator of the same type as the argument, for the new view.

Factor prior

HighOrderFactorPriorEstimator reads two more verbs of its kte:

  • PortfolioOptimisers.cokurtosis_processor(kte::CokurtosisEstimator) -> Option{<:AbstractMatrixProcessingEstimator}: The matrix processing estimator of the lifted cokurtosis, or nothing to skip the processing and the repair. The fallback refuses the type by name, and the prior calls it at construction under every rsd. See cokurtosis_processor.
  • PortfolioOptimisers.cokurtosis_expected_returns(kte::CokurtosisEstimator) -> AbstractExpectedReturnsEstimator: The expected returns estimator of the residual moments. It is necessary under rsd = true. The fallback refuses the type by name, and the prior calls it at construction. See cokurtosis_expected_returns.

Examples

The example below defines a minimal cokurtosis estimator.

julia> struct MyCokurtosisEstimator{T1} <: PortfolioOptimisers.CokurtosisEstimator           w::T1           function MyCokurtosisEstimator(w::PortfolioOptimisers.Option{<:PortfolioOptimisers.ObsWeights})               PortfolioOptimisers.assert_nonempty_nonneg_finite_val(w, :w)               return new{typeof(w)}(w)           end       endjulia> function MyCokurtosisEstimator(;                                      w::PortfolioOptimisers.Option{<:PortfolioOptimisers.ObsWeights} = nothing)           return MyCokurtosisEstimator(w)       endMyCokurtosisEstimatorjulia> function PortfolioOptimisers.factory(::MyCokurtosisEstimator,                                            w::PortfolioOptimisers.ObsWeights)           return MyCokurtosisEstimator(; w = w)       endjulia> function PortfolioOptimisers.port_opt_view(kte::MyCokurtosisEstimator, i)           return kte       endjulia> function PortfolioOptimisers.cokurtosis(kte::MyCokurtosisEstimator,                                               X::PortfolioOptimisers.MatNum; dims::Int = 1,                                               mean = nothing, kwargs...)           N = size(X, 2)           return zeros(N^2, N^2)       endjulia> cokurtosis(MyCokurtosisEstimator(), [1.0 2.0; 0.3 0.7; 0.5 1.1])4×4 Matrix{Float64}: 0.0  0.0  0.0  0.0 0.0  0.0  0.0  0.0 0.0  0.0  0.0  0.0 0.0  0.0  0.0  0.0julia> PortfolioOptimisers.factory(MyCokurtosisEstimator(), StatsBase.Weights([1, 2, 3]))MyCokurtosisEstimator  w ┴ StatsBase.Weights{Int64, Int64, Vector{Int64}}: [1, 2, 3]

Related

References

  • [66] D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022). Section 2, Equation 4, and Appendix A.
  • [64] E. Jondeau and M. Rockinger. Optimal portfolio allocation under higher moments. Notes d'Études et de Recherche 108, Banque de France (2004). Section 2.3.
source
PortfolioOptimisers.Cokurtosis — Type
struct Cokurtosis{__T_me, __T_mp, __T_alg, __T_w, __T_cvg, __T_cache} <: CokurtosisEstimator

Estimates the square cokurtosis matrix of a returns matrix.

Cokurtosis holds a mean estimator, a matrix processing estimator and a moment algorithm. cokurtosis returns one assets² × assets² matrix. That matrix is the stacked fourth comoment $\mathbf{\Sigma}_{4}$ of Section 2 of [66] and not the assets × assets³ tensor $\mathbf{M}_{4}$ of Section 2.3 of [64].

Fields

  • me: Expected returns estimator.
  • mp: Matrix processing estimator.
  • alg: Moment algorithm.
  • 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

Cokurtosis(;    me::AbstractExpectedReturnsEstimator = SimpleExpectedReturns(),    mp::AbstractMatrixProcessingEstimator = MatrixProcessing(),    alg::AbstractMomentAlgorithm = FullMoment(),    w::Option{<:ObsWeights} = nothing,    cvg::Option{<:CoveragePolicy} = nothing,    cache::Option{<:AbstractPartialFitState} = nothing) -> Cokurtosis

Keywords correspond to the struct's fields.

Validation

  • If w is not nothing, !isempty(w).
  • If cvg is a CoveragePolicy, me is nothing or a SimpleExpectedReturns, through assert_coverage_fittable. The available-case fit centres each asset on the mean of its own observations, and on no other centre. With no w, the fit folds, so me holds no weights. With w, the fit centres on the weighted mean, and w replaces the weights of me. An ArgumentError is thrown otherwise.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • me: Recursively updated through factory.
  • w: Replaced with the incoming ObsWeights.
  • cache: Carried unchanged through factory.

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> Cokurtosis()Cokurtosis     me ┼ SimpleExpectedReturns        │   w ┴ nothing     mp ┼ MatrixProcessing        │     pdm ┼ Posdef        │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton        │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │      dn ┼ nothing        │      dt ┼ nothing        │     alg ┼ nothing        │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)    alg ┼ FullMoment()      w ┼ nothing  cache ┴ nothing

Related

References

  • [66] D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022). Section 2, Equation 4, and Appendix A.
  • [64] E. Jondeau and M. Rockinger. Optimal portfolio allocation under higher moments. Notes d'Études et de Recherche 108, Banque de France (2004). Section 2.3.
source
PortfolioOptimisers.cokurtosis — Function
cokurtosis(kte::Option{<:Cokurtosis}, X::MatNum; dims::Int = 1,
           mean = nothing, kwargs...)

Computes the square cokurtosis matrix of a dataset.

The method centres the data with kte.me, and it repairs the result with kte.mp. It applies the observation weights of kte.w when they are set. FullMoment takes the centred returns, and SemiMoment clips every positive deviation to zero. When the estimator is nothing, the method returns nothing.

kte.w weights the whole estimate, so it applies to the centre and to the deviations. When mean is nothing and kte.w is not, the method sends kte.me through factory with kte.w. So kte.w replaces the weights that kte.me holds. Pass mean for a centre that kte.w does not describe.

Algorithm

The type of kte.cvg selects the method, so no branch reads the value of the policy. coverage_covariance selects the arm of a covariance in the same way.

When kte.cvg is nothing, the method takes the Coverage Universe arm. It centres the whole window on one vector. The FullMoment and the SemiMoment methods differ only in step 5.

  1. Orient X to observations × assets with dims_oriented, which validates dims.
  2. Refuse an inactive cell of active_mask with assert_finite_sample, because a plain estimator reads that cell as a non-finite return.
  3. Resolve the observation weights w from kte.w with get_observation_weights.
  4. Resolve the centre mu from kte.me and kte.w with weighted_centre, which reads mean when the caller gave one.
  5. Replace X with the deviation matrix. FullMoment takes X .- mu, and SemiMoment takes min.(X .- mu, 0).
  6. Delegate to _cokurtosis with the deviation matrix, kte.mp and w, and return the matrix it returns.

When kte.cvg is a CoveragePolicy, the method takes the available-case arm. It fits each quadruple on the observations at which its four assets are all finite and active, so each cell has its own denominator. The centre of each asset is the available-case mean of that asset, over its own finite and active observations. It is not a mean over the observations of the quadruple. coskewness states the reason, and the arm refuses an external mean for the same reason.

The repair reads the block alone. matrix_processing_block! finds the block from the diagonal of the matrix. The diagonal entry at the pair (i, j) is E[yᵢ²yⱼ²], and it is finite if and only if the pair shares an observation. So the block is the set of pairs that the fit gives a value for, and the repair does not change the cells outside it.

Neither an available-case cokurtosis nor an available-case coskewness folds. An exact recursion for each cell needs the second and the third comoments over the observations of each quadruple. So the online form of an available-case cokurtosis refits a buffer through Online.

  1. Get the valid entries, the deviations from the available-case centre of each asset, and the mask of the admitted assets with coverage_comoment_block.
  2. Take the numerator as transpose(z) * z and the denominator as transpose(zc) * zc. z and zc are the pairwise expansions of the zeroed deviations and of the valid mask.
  3. Divide with coverage_divide, and frame the refused assets down both pair axes with coverage_refuse_comoment!.
  4. Repair the block with matrix_processing_block!.

When kte.w holds observation weights as well, the available-case arm makes one weighted pass, because the weights describe the whole sample.

  1. Read the deviations, the valid entries and the admitted assets with weighted_comoment_block.
  2. Build the fourth co-moment with weighted_comoment, and reshape it to N² × N².
  3. Frame the refused assets with coverage_refuse_comoment!, and repair the block with matrix_processing_block!.

Arguments

  • kte: The cokurtosis estimator.

    • kte.alg::FullMoment: The FullMoment moment algorithm gives the cokurtosis.
    • kte.alg::SemiMoment: The SemiMoment moment algorithm gives the downside cokurtosis.
    • kte::Nothing: The method returns nothing.
  • X: The data matrix (observations × assets).

  • dims: Dimension along which the computation runs.

  • mean: The optional mean vector. When it is nothing, the method computes the centre with kte.me and kte.w. The available-case arm refuses a mean vector.

  • active_mask: The active mask of the Asset Panel over the window, or nothing. The Coverage Universe arm refuses an inactive cell, as it refuses a non-finite return. The available-case arm leaves the cell out of each comoment of its asset.

  • kwargs...: More keyword arguments. When kte.cvg is nothing, the method passes them to get_observation_weights and to weighted_centre. The available-case arm ignores them.

Validation

  • dims is either 1 or 2.
  • The available-case arm with no observation weights: kte.me is a SimpleExpectedReturns with no weights, and mean is nothing. Otherwise, it raises an ArgumentError.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Examples

julia> using StableRNGsjulia> rng = StableRNG(123456789);julia> X = randn(rng, 10, 2);julia> cokurtosis(Cokurtosis(), X)4×4 Matrix{Float64}:  1.33947   -0.246726  -0.246726   0.493008 -0.246726   0.493008   0.493008  -0.201444 -0.246726   0.493008   0.493008  -0.201444  0.493008  -0.201444  -0.201444   0.300335

Related

source
cokurtosis(kte::WindowedCokurtosis, X::MatNum; dims::Int = 1, mean = nothing, iv::Option{<:MatNum} = nothing, kwargs...)

Compute cokurtosis over a rolling or indexed window of observations, for a matrix input.

The method selects a window of observations from X, and applies the observation weights when the estimator holds them. Then it calls the inner cokurtosis estimator.

Algorithm

  1. Resolve the window and the observation weights with windowed_preamble. It returns inner, a copy of kte.kte that holds the windowed weights, and the windowed X, the windowed iv, and the active_mask and estimation_mask keywords cut to the window.
  2. Call cokurtosis on inner and the windowed X, and return its result. The inner estimator alone computes the value. This method changes only the observations and the weights that the inner estimator gets.

Arguments

  • kte: Windowed cokurtosis estimator.
  • X: Data matrix of asset returns, observations × assets.
  • dims: Dimension along which the computation runs.
  • mean: Optional precomputed mean, passed to the inner estimator.
  • iv: Optional implied volatility matrix. The estimator reads it only when one of its inner covariance estimators is an ImpliedVolatility.
  • kwargs...: More keyword arguments, passed to the inner estimator. The method cuts the active_mask and estimation_mask keywords to the window.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Related

source
cokurtosis(kte::WindowedCokurtosis, X::MatNum, pnl::Option{<:AssetPanel}; dims::Int = 1, mean = nothing, kwargs...)

Compute cokurtosis over a rolling or indexed window of observations, for an Asset Panel input.

The method selects a window of observations from X, and applies the observation weights when the estimator holds them. Then it calls the inner cokurtosis estimator. It cuts the Asset Panel to the same observations and gives it to the inner estimator. A mask-aware inner estimator then reads the active mask of the window, and a plain one reduces to the Coverage Universe of the window.

Algorithm

  1. Cut pnl to the observations of the window with windowed_panel.
  2. Resolve the window and the observation weights with windowed_preamble. It returns inner, a copy of kte.kte that holds the windowed weights, and the windowed X, the windowed iv, and the active_mask and estimation_mask keywords cut to the window.
  3. Call cokurtosis on inner and the windowed X and pnl, and return its result. The inner estimator alone computes the value. This method changes only the observations and the weights that the inner estimator gets.

Arguments

  • kte: Windowed cokurtosis estimator.
  • X: Data matrix of asset returns, observations × assets.
  • 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.
  • mean: Optional precomputed mean, passed to the inner estimator.
  • kwargs...: More keyword arguments, passed to the inner estimator. The method cuts the iv, active_mask and estimation_mask keywords to the window.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Related

source
cokurtosis(
    kte::WindowedCokurtosis{<:Any, <:Any, <:Any, <:SeedWindow};
    kwargs...
) -> Any

Read the cokurtosis from the fold of a windowed estimator under a SeedWindow.

The inner estimator holds the state of the fold, so the method reads it there.

Arguments

  • kte: Windowed cokurtosis estimator under a seed window.
  • kwargs...: Keywords for the read of the inner estimator.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Related

source
cokurtosis(
    kte::Cokurtosis{<:Any, <:Any, <:FullMoment},
    state::CokurtosisPartialFitState
) -> Any

Reads the square cokurtosis matrix out of a partial-fit state.

The method of cokurtosis that makes the estimate from a Partial Fit State. It returns the matrix the batch method returns, to machine precision, for the sample the state was fitted on.

Only the shape of that sample survives a partial fit, so the matrix processing estimator is handed a matrix of the right shape whose entries are zero. Of the shipped steps only :dn reads it, and it reads only size(X), so the two routes agree. A custom :alg step that reads the values of the sample must be run from the batch verb.

Algorithm

  1. Refuse a configuration the state no longer matches, with assert_partial_fittable. factory carries the state and replaces w, so an estimator that says weighted may hold a state fitted unweighted. The state stays on the estimator, so a caller who restores w = nothing reads it again.
  2. Divide the fourth accumulator by the observation count, giving the cokurtosis matrix.
  3. Process it in place through matrix_processing_block!, under kte.mp and the shape of the fitted sample. It is the block arm rather than the plain one for the reason the low order's cov(ce) with no data takes it: a plain fold over a changing universe answers NaN for an asset outside the Coverage Universe at every pair naming it, and a positive-definite repair over that frame meets a LAPACK refusal rather than a named error. The block arm repairs the finite block and leaves the frame for investable_mask to read, which is what the batch verb's reduce-and-expand leaves it too; a complete matrix runs the plain arm over the whole of it.

Arguments

  • kte: Cokurtosis estimator with a FullMoment moment algorithm.
  • state: Partial-fit state written by partial_fit!.

Validation

  • kte.w is nothing and kte.me is an unweighted SimpleExpectedReturns. An ArgumentError is thrown otherwise.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Related

source
cokurtosis(kte::Cokurtosis) -> Any

Reads the square cokurtosis matrix out of the state the estimator carries.

The one-argument forwarder of cokurtosis. It reads kte.cache, which partial_fit! writes, and refuses an estimator that has been shown no observation.

Algorithm

  1. Refuse the estimator whose cache is nothing.
  2. Forward to the state method of cokurtosis.

Arguments

  • kte: Cokurtosis estimator.

Validation

  • kte.cache is not nothing. An ArgumentError is thrown otherwise.

Returns

  • ckurt::MatNum: Square cokurtosis matrix assets² x assets².

Related

source
cokurtosis(kte::CokurtosisEstimator) -> Any
cokurtosis(
    kte::CokurtosisEstimator,
    state::SampleBufferState
) -> Any

Reads a cokurtosis matrix out of a SampleBufferState, by running the batch verb over the observations the buffer holds.

The method of cokurtosis that makes the estimate from a Sample Buffer. An estimator wrapped in Online carries a buffer rather than a family state, so it takes no exact fold, and its estimate is whatever a batch fit over the rows the buffer holds gives — every observation folded so far when the buffer is uncapped, and the last max_history of them when it is capped. It runs no assert_partial_fittable check of its own: the batch verb answers configurations an incremental fold cannot, and a wrapper is how a caller reaches them. The buffer also holds the per-observation masks it was folded with, so the batch verb is given the mask that explains the rows and a wrapped estimator under a CoveragePolicy answers what an unwrapped one answers.

The call with no data, cokurtosis(kte), fills state with the state that the estimator carries, which partial_fit_cache reads out of the cache field. The call then goes to the method of cokurtosis for the type of that state, as the call with no data of coskewness does. The default serves the estimators that fold by buffering alone, such as WindowedCokurtosis.

Arguments

  • kte: Cokurtosis estimator.
  • state: The buffer to read. The default is the state that kte carries.

Validation

  • With no state, the estimator carries a state. An ArgumentError is thrown otherwise.

Returns

  • ckurt::MatNum: Cokurtosis matrix of the observations the buffer holds.

Related

source
cokurtosis(
    kte::CokurtosisEstimator,
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    pnl::Union{Nothing, AssetPanel};
    dims,
    active_mask,
    kwargs...
) -> Any

The cokurtosis root of the Asset Panel methods of the moment verbs. It is the reduce-and-expand of Statistics.cov(ce::AbstractCovarianceEstimator, X::MatNum, pnl::Option{<:AssetPanel}; dims::Int = 1, kwargs...), which states the rule and its cost. The result is assets² × assets², so it expands at the pair index on both axes.

Related

source
cokurtosis(
    kte::Cokurtosis,
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    pnl::Union{Nothing, AssetPanel};
    dims,
    kwargs...
) -> Any

Asset Panel method of cokurtosis for a Cokurtosis, which routes on its cvg field with coverage_panel_moment. The result is assets² × assets², so the Coverage Universe route frames it at the pair index on both axes.

Related

source

References

[64]
E. Jondeau and M. Rockinger. Optimal portfolio allocation under higher moments. Notes d'Études et de Recherche 108 (Banque de France, 2004).
[66]
D. Cajas. Convex Optimization of Portfolio Kurtosis. Available at SSRN 4202967 (2022).