Base clustering optimisation: private API

PortfolioOptimisers.BaseClusteringOptimisationEstimator — Type
abstract type BaseClusteringOptimisationEstimator <: BaseOptimisationEstimator

Abstract 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

source
PortfolioOptimisers.ClusteringOptimisationEstimator — Type
abstract type ClusteringOptimisationEstimator <: NonFiniteAllocationOptimisationEstimator

Abstract 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

source
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

  1. Read one cluster label per asset with assignments.
  2. Throw a DimensionMismatch when their count is not N.

Arguments

  • clr: Clustering result, fitted by clusterise or 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 DimensionMismatch is raised.

Returns

  • nothing.

Related

source
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 not nothing.

Related

source
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_fields returns;
  • its inner optimiser opt.opt is time-dependent;
  • its fallback opt.fb is time-dependent.

NestedClustered overrides this with its own method.

Arguments

  • opt: Clustering optimiser that holds the fields opt and fb.

Returns

  • flag::Bool: true when a fold loop must resolve a schedule before the optimiser runs.

Related

source
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

  1. Return opt unchanged when is_time_dependent is false.
  2. Replace each scheduled field of opt with its static default, through reset_time_dependent_fields. This gives the new opt.
  3. Reset the inner optimiser opt.opt and the fallback opt.fb of the new opt.
  4. Rebuild opt with the two reset estimators, through rebuild_struct.

Arguments

  • opt: Clustering optimiser that holds the fields opt and fb.

Returns

  • opt: The optimiser with no schedule left, of the same type as the input.

Related

source
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.cle holds no AbstractClusteringResult.
  • A JuMP optimiser: opt passes assert_rc_variance and assert_rc_pl. opt.opt.lcse, opt.opt.cte, opt.opt.gcarde and opt.opt.sgcarde hold no LinearConstraint, and opt.opt.ple holds no AbstractPhylogenyConstraintResult.
  • A vector of optimisers: each entry passes.
  • A NestedClustered: opt.cle holds no AbstractClusteringResult, and opt.opto passes assert_external_optimiser. When opt.opti is not opt.opto, it passes this function.

The methods throw an ArgumentError otherwise.

Returns

  • nothing.

Related

source
PortfolioOptimisers.unitary_expected_risks — Method
unitary_expected_risks(r::OptimisationRiskMeasure, X::MatNum,
                       fees::Option{<:Fees} = nothing) -> Vector

Compute 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

  1. Make the weight vector wk, all zero, of length size(X, 2). Its entries take the element type of X.
  2. For each asset i, set wk[i] to one, evaluate expected_risk(r, wk, X, fees) as the i-th risk, and set wk[i] back to zero.
  3. Collect the risks into rk, whose element type is the type that expected_risk returns.

Arguments

  • r: Risk measure, already resolved by factory.
  • X: Asset return matrix, observations by assets.
  • fees: Fees to charge against each unit portfolio, or nothing.

Returns

  • rk::Vector: Expected risk of each asset held alone, of length size(X, 2). Its element type is the type of the risk, not the element type of X.

Related

source
PortfolioOptimisers.unitary_expected_risks! — Method
unitary_expected_risks!(wk::VecNum, rk::VecNum, r::OptimisationRiskMeasure,
                        X::MatNum, fees::Option{<:Fees} = nothing) -> Nothing

Write 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

  1. Set every entry of rk to zero.
  2. For each asset i, set wk[i] to one, evaluate expected_risk(r, wk, X, fees) into rk[i], and set wk[i] back to zero.

Arguments

  • wk: Scratch weight vector, of length size(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 length size(X, 2). It is overwritten in full. Its element type must hold a risk.
  • r: Risk measure, already resolved by factory.
  • X: Asset return matrix, observations by assets.
  • fees: Fees to charge against each unit portfolio, or nothing.

Returns

  • nothing. The result is rk.

Related

source
PortfolioOptimisers.reader_frames — Method
reader_frames(opt::HierarchicalOptimiser, path::AbstractString, refit::Bool) -> ReturnsFrames
group_frames(opt::HierarchicalOptimiser) -> ReturnsFrames
group_frames(est::ClusteringOptimisationEstimator) -> ReturnsFrames

Walk 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: true when a regression reader at x_src = nothing in the group fits its regression on the raw returns data. refits_regression finds the value.
  • est: The hierarchical head.

Returns

  • fr::ReturnsFrames: The frames of the slots of opt, at path or from the configuration itself, or of the group of est.

Related

source