Cokurtosis
PortfolioOptimisers.CokurtosisEstimator — Type
abstract type CokurtosisEstimator <: AbstractEstimatorAbstract 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 matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.dims: Dimension along which the computation runs.mean: Optional precomputed centre of the data.kwargs...: More keyword arguments.
Returns
ckurt::MatNum: Square cokurtosis matrixassets² 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 vectorobservations × 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 thatiselects.
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, ornothingto skip the processing and the repair. The fallback refuses the type by name, and the prior calls it at construction under everyrsd. Seecokurtosis_processor.PortfolioOptimisers.cokurtosis_expected_returns(kte::CokurtosisEstimator) -> AbstractExpectedReturnsEstimator: The expected returns estimator of the residual moments. It is necessary underrsd = true. The fallback refuses the type by name, and the prior calls it at construction. Seecokurtosis_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
PortfolioOptimisers.Cokurtosis — Type
struct Cokurtosis{__T_me, __T_mp, __T_alg, __T_w, __T_cvg, __T_cache} <: CokurtosisEstimatorEstimates 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 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
Cokurtosis(; me::AbstractExpectedReturnsEstimator = SimpleExpectedReturns(), mp::AbstractMatrixProcessingEstimator = MatrixProcessing(), alg::AbstractMomentAlgorithm = FullMoment(), w::Option{<:ObsWeights} = nothing, cvg::Option{<:CoveragePolicy} = nothing, cache::Option{<:AbstractPartialFitState} = nothing) -> CokurtosisKeywords correspond to the struct's fields.
Validation
- If
wis notnothing,!isempty(w). - If
cvgis aCoveragePolicy,meisnothingor aSimpleExpectedReturns, throughassert_coverage_fittable. The available-case fit centres each asset on the mean of its own observations, and on no other centre. With now, the fit folds, someholds no weights. Withw, the fit centres on the weighted mean, andwreplaces the weights ofme. AnArgumentErroris thrown otherwise.
Propagated parameters
factory passes its arguments on to these @fprop fields:
me: Recursively updated throughfactory.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:
me: Recursively viewed throughport_opt_view.cache: Sliced to the selected assets throughport_opt_view.
Observation weight parameters
obs_weights_view indexes these fields to the selected observations:
me: Recursively indexed throughobs_weights_view.w: Indexed to the selected observations throughobs_weights_view.cache: Dropped throughobs_weights_view, because no slice of a state exists on the observation axis.
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 ┴ nothingRelated
CokurtosisEstimatorAbstractExpectedReturnsEstimatorAbstractMatrixProcessingEstimatorAbstractMomentAlgorithmfactoryport_opt_viewobs_weights_view
References
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.
- Orient
Xto observations × assets withdims_oriented, which validatesdims. - Refuse an inactive cell of
active_maskwithassert_finite_sample, because a plain estimator reads that cell as a non-finite return. - Resolve the observation weights
wfromkte.wwithget_observation_weights. - Resolve the centre
mufromkte.meandkte.wwithweighted_centre, which readsmeanwhen the caller gave one. - Replace
Xwith the deviation matrix.FullMomenttakesX .- mu, andSemiMomenttakesmin.(X .- mu, 0). - Delegate to
_cokurtosiswith the deviation matrix,kte.mpandw, 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.
- 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. - Take the numerator as
transpose(z) * zand the denominator astranspose(zc) * zc.zandzcare the pairwise expansions of the zeroed deviations and of the valid mask. - Divide with
coverage_divide, and frame the refused assets down both pair axes withcoverage_refuse_comoment!. - 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.
- Read the deviations, the valid entries and the admitted assets with
weighted_comoment_block. - Build the fourth co-moment with
weighted_comoment, and reshape it toN² × N². - Frame the refused assets with
coverage_refuse_comoment!, and repair the block withmatrix_processing_block!.
Arguments
kte: The cokurtosis estimator.kte.alg::FullMoment: TheFullMomentmoment algorithm gives the cokurtosis.kte.alg::SemiMoment: TheSemiMomentmoment algorithm gives the downside cokurtosis.kte::Nothing: The method returnsnothing.
X: The data matrix (observations × assets).dims: Dimension along which the computation runs.mean: The optional mean vector. When it isnothing, the method computes the centre withkte.meandkte.w. The available-case arm refuses a mean vector.active_mask: The active mask of the Asset Panel over the window, ornothing. 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. Whenkte.cvgisnothing, the method passes them toget_observation_weightsand toweighted_centre. The available-case arm ignores them.
Validation
dimsis either1or2.- The available-case arm with no observation weights:
kte.meis aSimpleExpectedReturnswith no weights, andmeanisnothing. Otherwise, it raises anArgumentError.
Returns
ckurt::MatNum: Square cokurtosis matrixassets² 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.300335Related
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
- Resolve the window and the observation weights with
windowed_preamble. It returnsinner, a copy ofkte.ktethat holds the windowed weights, and the windowedX, the windowediv, and theactive_maskandestimation_maskkeywords cut to the window. - Call
cokurtosisoninnerand the windowedX, 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 anImpliedVolatility.kwargs...: More keyword arguments, passed to the inner estimator. The method cuts theactive_maskandestimation_maskkeywords to the window.
Returns
ckurt::MatNum: Square cokurtosis matrixassets² x assets².
Related
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
- Cut
pnlto the observations of the window withwindowed_panel. - Resolve the window and the observation weights with
windowed_preamble. It returnsinner, a copy ofkte.ktethat holds the windowed weights, and the windowedX, the windowediv, and theactive_maskandestimation_maskkeywords cut to the window. - Call
cokurtosisoninnerand the windowedXandpnl, 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: OptionalAssetPanel. The Coverage Universe of the fit comes from its active mask. If it isnothing, 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 theiv,active_maskandestimation_maskkeywords to the window.
Returns
ckurt::MatNum: Square cokurtosis matrixassets² x assets².
Related
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 matrixassets² x assets².
Related
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
- Refuse a configuration the state no longer matches, with
assert_partial_fittable.factorycarries the state and replacesw, so an estimator that says weighted may hold a state fitted unweighted. The state stays on the estimator, so a caller who restoresw = nothingreads it again. - Divide the fourth accumulator by the observation count, giving the cokurtosis matrix.
- Process it in place through
matrix_processing_block!, underkte.mpand the shape of the fitted sample. It is the block arm rather than the plain one for the reason the low order'scov(ce)with no data takes it: a plain fold over a changing universe answersNaNfor 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 forinvestable_maskto 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 aFullMomentmoment algorithm.state: Partial-fit state written bypartial_fit!.
Validation
kte.wisnothingandkte.meis an unweightedSimpleExpectedReturns. AnArgumentErroris thrown otherwise.
Returns
ckurt::MatNum: Square cokurtosis matrixassets² x assets².
Related
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
- Refuse the estimator whose
cacheisnothing. - Forward to the state method of
cokurtosis.
Arguments
kte: Cokurtosis estimator.
Validation
kte.cacheis notnothing. AnArgumentErroris thrown otherwise.
Returns
ckurt::MatNum: Square cokurtosis matrixassets² x assets².
Related
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 thatktecarries.
Validation
- With no
state, the estimator carries a state. AnArgumentErroris thrown otherwise.
Returns
ckurt::MatNum: Cokurtosis matrix of the observations the buffer holds.
Related
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
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
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).