Base clustering optimisation: private API
PortfolioOptimisers.BaseClusteringOptimisationEstimator — Type
abstract type BaseClusteringOptimisationEstimator <: BaseOptimisationEstimatorAbstract supertype for the shared configuration that a hierarchical optimiser holds in its opt field.
A subtype is not an optimiser, so optimise does not take one. HierarchicalOptimiser is the one subtype, and HierarchicalRiskParity, HierarchicalEqualRiskContribution and SchurComplementHierarchicalRiskParity each hold one.
Related
PortfolioOptimisers.ClusteringOptimisationEstimator — Type
abstract type ClusteringOptimisationEstimator <: NonFiniteAllocationOptimisationEstimatorAbstract supertype for the optimisers that cluster the assets and allocate over the clusters.
It has four subtypes. HierarchicalRiskParity, HierarchicalEqualRiskContribution and SchurComplementHierarchicalRiskParity hold a HierarchicalOptimiser in the field opt and a fallback in the field fb. The methods of this file that dispatch on the family read those two fields, so a new subtype that holds them needs no method of its own for time-dependent constraints. NestedClustered holds neither field, and it overrides all four of those methods.
Related
PortfolioOptimisers.assert_clustering_universe — Function
assert_clustering_universe(
clr::AbstractClusteringResult,
N::Integer
)
Assert that a clustering covers exactly the assets the optimisation allocates over.
clusterise returns a fitted AbstractClusteringResult unchanged, so a caller who states one instead of an estimator also states the leaf order, and nothing slices that order. Under an Investable Mask, or inside a subset or a nested view, the optimisation runs on fewer assets than the caller clustered. The leaf order would then index the wrong columns, and the optimisation would return wrong weights without an error. This check raises before the leaf order is read.
To keep one clustering method while the universe changes, state a ClustersEstimator. It refits on each window, so its result always matches.
Algorithm
- Read one cluster label per asset with
assignments. - Throw a
DimensionMismatchwhen their count is notN.
Arguments
clr: Clustering result, fitted byclusteriseor stated by the caller.N: Number of assets the optimisation runs on, after the reduction.
Validation
- The clustering carries one label per asset of the reduced universe, else a
DimensionMismatchis raised.
Returns
nothing.
Related
PortfolioOptimisers.hierarchical_optimiser_td_defaults — Function
hierarchical_optimiser_td_defaults(
) -> @NamedTuple{pe::EmpiricalPrior{PortfolioOptimisersCovariance{Covariance{SimpleExpectedReturns{Nothing, Nothing, Nothing}, GeneralCovariance{SimpleCovariance, Nothing, Nothing}, FullMoment, Nothing, Nothing, Nothing}, MatrixProcessing{Posdef{UnionAll, @NamedTuple{}}, Nothing, Nothing, Nothing, NTuple{4, Symbol}}, Nothing}, SimpleExpectedReturns{Nothing, Nothing, Nothing}, Nothing, Nothing, Nothing, Nothing, Nothing}, cle::ClustersEstimator{PortfolioOptimisersCovariance{Covariance{SimpleExpectedReturns{Nothing, Nothing, Nothing}, GeneralCovariance{SimpleCovariance, Nothing, Nothing}, FullMoment, Nothing, Nothing, Nothing}, MatrixProcessing{Posdef{UnionAll, @NamedTuple{}}, Nothing, Nothing, Nothing, NTuple{4, Symbol}}, Nothing}, Distance{Nothing, CanonicalDistance}, HClustAlgorithm{Symbol}, OptimalNumberClusters{Nothing, SecondOrderDifference{StandardisedValue{MeanValue{Nothing}, StdValue{Nothing, Bool}}}}, Nothing}, wb::WeightBounds{Float64, Float64}, wf::IterativeWeightFinaliser{Int64}}
Return the one copy of the static defaults of the schedulable fields of HierarchicalOptimiser.
The constructor reads it to try each value of a schedule, and time_dependent_field_defaults returns it, so the two agree on the fold-less value of each field. It names pe, cle, wb and wf. The fields fees and sets default to nothing, so they have no entry.
Returns
defaults::NamedTuple: The default value of each schedulable field whose default is notnothing.
Related
PortfolioOptimisers.is_time_dependent — Method
is_time_dependent(
opt::ClusteringOptimisationEstimator
) -> Any
Return true when a clustering optimiser, or an estimator it holds, carries a TimeDependent schedule.
The optimiser is time-dependent when any one of three things holds:
- one of its own fields holds a schedule that
time_dependent_fieldsreturns; - its inner optimiser
opt.optis time-dependent; - its fallback
opt.fbis time-dependent.
NestedClustered overrides this with its own method.
Arguments
opt: Clustering optimiser that holds the fieldsoptandfb.
Returns
flag::Bool:truewhen a fold loop must resolve a schedule before the optimiser runs.
Related
PortfolioOptimisers.reset_time_dependent_estimator — Method
reset_time_dependent_estimator(
opt::ClusteringOptimisationEstimator
) -> NestedClustered
Replace every TimeDependent schedule of a clustering optimiser with its static default.
A fold-less optimise calls it first, so the optimiser runs with each scheduled field at its default. NestedClustered overrides this with its own method.
Algorithm
- Return
optunchanged whenis_time_dependentisfalse. - Replace each scheduled field of
optwith its static default, throughreset_time_dependent_fields. This gives the newopt. - Reset the inner optimiser
opt.optand the fallbackopt.fbof the newopt. - Rebuild
optwith the two reset estimators, throughrebuild_struct.
Arguments
opt: Clustering optimiser that holds the fieldsoptandfb.
Returns
opt: The optimiser with no schedule left, of the same type as the input.
Related
PortfolioOptimisers.assert_internal_optimiser — Method
assert_internal_optimiser(opt::ClusteringOptimisationEstimator)
assert_internal_optimiser(opt::JuMPOptimisationEstimator)
assert_internal_optimiser(opt::VecOptE_Opt_TD)
assert_internal_optimiser(opt::NestedClustered)Assert that an optimiser can solve the intra-cluster problem of a NestedClustered.
Each cluster solves its problem over its own assets, so each input of the inner optimiser must follow the view onto those assets. An estimator fits again on the view. A precomputed result states one fixed universe, so the methods refuse it. A slot can hold such a result directly, in a vector, or in a TimeDependent schedule, and holds_precomputed reads each of these shapes. Other files add the methods of the other families of optimisers.
Arguments
opt: The inner optimiser.
Validation
- A clustering optimiser:
opt.opt.cleholds noAbstractClusteringResult. - A JuMP optimiser:
optpassesassert_rc_varianceandassert_rc_pl.opt.opt.lcse,opt.opt.cte,opt.opt.gcardeandopt.opt.sgcardehold noLinearConstraint, andopt.opt.pleholds noAbstractPhylogenyConstraintResult. - A vector of optimisers: each entry passes.
- A
NestedClustered:opt.cleholds noAbstractClusteringResult, andopt.optopassesassert_external_optimiser. Whenopt.optiis notopt.opto, it passes this function.
The methods throw an ArgumentError otherwise.
Returns
nothing.
Related
PortfolioOptimisers.unitary_expected_risks — Method
unitary_expected_risks(r::OptimisationRiskMeasure, X::MatNum,
fees::Option{<:Fees} = nothing) -> VectorCompute the expected risk of each asset held alone.
The result has one entry per asset, not per cluster. HierarchicalRiskParity and HierarchicalEqualRiskContribution weight the assets of a cluster in proportion to the inverse of these risks, which is the naive risk parity allocation inside the cluster.
Mathematical definition
\[\begin{align} \rho(\{i\}) &= R(\boldsymbol{e}_i)\,, \quad i = 1,\, \ldots,\, N\,. \end{align}\]
For Variance, $\rho(\{i\}) = \Sigma_{ii}$, so the vector is the diagonal of the covariance matrix. A measure that reads the returns evaluates $R$ on the returns of asset $i$ net of the fees that fees charges on $\boldsymbol{e}_i$.
Where:
- $\rho(\{i\})$: Risk of asset $i$ held alone.
- $R(\boldsymbol{w})$: Portfolio risk.
- $\boldsymbol{e}_i$: Weight vector that is one at asset $i$ and zero at every other asset.
- $\Sigma_{ii}$: Variance of asset $i$.
- $N$: Number of assets.
Algorithm
- Make the weight vector
wk, all zero, of lengthsize(X, 2). Its entries take the element type ofX. - For each asset
i, setwk[i]to one, evaluateexpected_risk(r, wk, X, fees)as thei-th risk, and setwk[i]back to zero. - Collect the risks into
rk, whose element type is the type thatexpected_riskreturns.
Arguments
r: Risk measure, already resolved byfactory.X: Asset return matrix, observations by assets.fees: Fees to charge against each unit portfolio, ornothing.
Returns
rk::Vector: Expected risk of each asset held alone, of lengthsize(X, 2). Its element type is the type of the risk, not the element type ofX.
Related
PortfolioOptimisers.unitary_expected_risks! — Method
unitary_expected_risks!(wk::VecNum, rk::VecNum, r::OptimisationRiskMeasure,
X::MatNum, fees::Option{<:Fees} = nothing) -> NothingWrite the expected risk of each asset held alone into rk.
This is the in-place form of unitary_expected_risks, which states the mathematics. A caller that evaluates several risk measures uses it to reuse one pair of buffers.
Algorithm
- Set every entry of
rkto zero. - For each asset
i, setwk[i]to one, evaluateexpected_risk(r, wk, X, fees)intork[i], and setwk[i]back to zero.
Arguments
wk: Scratch weight vector, of lengthsize(X, 2). It must be all zero on entry, and it is all zero on exit, because each step sets one entry to one and then back to zero.rk: Output risk vector, of lengthsize(X, 2). It is overwritten in full. Its element type must hold a risk.r: Risk measure, already resolved byfactory.X: Asset return matrix, observations by assets.fees: Fees to charge against each unit portfolio, ornothing.
Returns
nothing. The result isrk.
Related
PortfolioOptimisers.reader_frames — Method
reader_frames(opt::HierarchicalOptimiser, path::AbstractString, refit::Bool) -> ReturnsFrames
group_frames(opt::HierarchicalOptimiser) -> ReturnsFrames
group_frames(est::ClusteringOptimisationEstimator) -> ReturnsFramesWalk the readers of a hierarchical head, for the warning of a forgotten raw reader and the gap rule of the head.
The group of a hierarchical head is the head, the configuration that it holds in opt, and every reader in their slots: the prior opt.pe, the clustering opt.cle, and the readers inside the risk measures. field_frames walks every field. The walk stops at a fallback, because it is a head with its own group. A configuration that takes an online step with no head answers for its own slots. NestedClustered holds its prior in pe and has a method of its own.
Arguments
opt: The configuration of a hierarchical head.path: The path of the value from the head, for example"pe","cle"or"r[2].pe". A warning names a reader by its path.refit:truewhen a regression reader atx_src = nothingin the group fits its regression on the raw returns data.refits_regressionfinds the value.est: The hierarchical head.
Returns
fr::ReturnsFrames: The frames of the slots ofopt, atpathor from the configuration itself, or of the group ofest.
Related