Schur Complement Hierarchical Risk Parity

A new Schur complement algorithm subtypes SchurComplementAlgorithm and adds a method of schur_complement_weights.

PortfolioOptimisers.SchurComplementAlgorithm — Type
abstract type SchurComplementAlgorithm <: AbstractAlgorithm

Abstract supertype for the algorithms that choose the Schur complement parameter $\gamma$.

A subtype decides whether SchurComplementParams.gamma is the value to use or the upper end of a range to search.

Interfaces

To implement a new way to choose $\gamma$, subtype SchurComplementAlgorithm and implement the following method:

schur_complement_weights

  • schur_complement_weights(pr::AbstractPriorResult, items::VecVecInt, wb::WeightBounds, params::SchurComplementParams{<:Any, <:Any, <:Any, <:MySchurComplementAlgorithm, <:Any}) -> Tuple: The weights of the bundle params, at the value of $\gamma$ that the new algorithm chooses.

Arguments

  • pr: Prior result.
  • items: The leaf orders to split, one entry that holds the whole leaf order of the dendrogram.
  • wb: Resolved weight bounds.
  • params: The bundle, whose alg field holds the new algorithm.

Returns

  • (w, gamma, r)::Tuple: The weights, the value of $\gamma$ the allocation ran at, and the measure that factory resolved. w is nothing when the allocation fails. The usual implementation chooses $\gamma$ and calls the NonMonotonicSchurComplement method at it.

Examples

An algorithm that runs the allocation at half of params.gamma:

julia> struct MyHalfGamma <: PortfolioOptimisers.SchurComplementAlgorithm endjulia> function PortfolioOptimisers.schur_complement_weights(pr::PortfolioOptimisers.AbstractPriorResult,                                                             items::PortfolioOptimisers.VecVecInt,                                                             wb::WeightBounds,                                                             params::SchurComplementParams{<:Any,                                                                                           <:Any,                                                                                           <:Any,                                                                                           <:MyHalfGamma,                                                                                           <:Any})           nm = SchurComplementParams(; r = params.r, gamma = params.gamma / 2, pdm = params.pdm,                                      alg = NonMonotonicSchurComplement(), flag = params.flag)           return PortfolioOptimisers.schur_complement_weights(pr, items, wb, nm)       endjulia> pr = LowOrderPrior(; X = zeros(2, 4), mu = zeros(4),                          sigma = [4.0 1 1 0; 1 3 0 1; 1 0 2 0; 0 1 0 1] / 100);julia> w, gamma, _ = PortfolioOptimisers.schur_complement_weights(pr, [collect(1:4)],                                                                  WeightBounds(; lb = zeros(4),                                                                               ub = ones(4)),                                                                  SchurComplementParams(;                                                                                        gamma = 0.8,                                                                                        alg = MyHalfGamma()));julia> gamma0.4julia> round.(w; digits = 4)4-element Vector{Float64}: 0.0872 0.0956 0.2616 0.5557

Related

source
PortfolioOptimisers.NonMonotonicSchurComplement — Type
struct NonMonotonicSchurComplement <: SchurComplementAlgorithm

Selects the allocation at the value of $\gamma$ that the caller gives, with no search.

The augmentation uses SchurComplementParams.gamma as it is. The portfolio variance is not monotonic in $\gamma$, so a larger value does not always give a portfolio of lower variance. MonotonicSchurComplement searches for a value that does.

Related

source
PortfolioOptimisers.MonotonicSchurComplement — Type
struct MonotonicSchurComplement{__T_N, __T_tol, __T_iter, __T_strict} <: SchurComplementAlgorithm

Caps $\gamma$ at the first turning point of the portfolio variance in $[0, \gamma]$.

The portfolio variance is not monotonic in the Schur complement parameter. It falls, then it can rise again. The allocation runs at the value that this tag finds, which is at most the SchurComplementParams.gamma that the caller gives.

Mathematical definition

\[\begin{align} v(g) &= \boldsymbol{w}(g)^\intercal \mathbf{\Sigma} \boldsymbol{w}(g)\,,\\ \gamma^{\star} &= \sup \left\{ g \in [0, \gamma] : v \textrm{ is non-increasing on } [0, g] \right\}\,. \end{align}\]

Where:

  • $v(g)$: Portfolio variance of the allocation at $g$. It is $+\infty$ when an augmented block at $g$ is not positive definite.
  • $\boldsymbol{w}(g)$: Weights of the allocation at $g$, with no repair of an augmented block.
  • $\mathbf{\Sigma}$: Covariance matrix of the measure of the bundle. It is the covariance matrix of the prior unless the measure holds its own.
  • $\gamma$: Schur complement parameter, in $[0, 1]$. At $\gamma = 0$ every augmented block equals the plain block.
  • $\gamma^{\star}$: The value that the allocation runs at.

$\gamma^{\star}$ is the first turning point, not the minimiser of $v$ over $[0, \gamma]$. Past the turning point the variance can fall again to a lower value, but a monotone path from HierarchicalRiskParity does not reach a portfolio there.

The objective is the variance for both measures. A StandardDeviation measure changes the split factors of the allocation, but not the quantity that the search compares.

Algorithm

The branch of schur_complement_weights that this tag selects runs these steps.

  1. When gamma is zero, run the allocation at zero with the flag of the bundle, and return it.
  2. Make nm_params, a NonMonotonicSchurComplement copy of the bundle with flag = false. The objective of a value runs the allocation of nm_params at that value and returns the weights and $v$. A failed allocation scores the largest value of the weight type.
  3. Make gammas, N evenly spaced values from zero to gamma.
  4. Evaluate objective at each entry of gammas in order. At the first entry gammas[i] whose variance is not lower than the variance at gammas[i - 1], bisect the bracket with schur_complement_binary_search and return its result. The bracket is gammas[i - 2] to gammas[i], or gammas[1] to gammas[2] when i is 2.
  5. When the scan finds no rise, evaluate objective at gamma - tol, or reuse the variance at zero when gamma <= tol. If the variance at gamma is not higher, return gamma and its weights.
  6. Otherwise, bisect the bracket from gammas[N - 1] to gamma.

The scan sees a turning point only to the resolution of gammas. A rise and a fall again between two neighbouring entries stay unseen. Every value that the search evaluates is in $[0, \gamma]$, the range of the definition, so each probe of the slope from the left stops at zero.

Fields

  • N: Number of evenly spaced values of gamma the monotonic Schur complement scans for its turning point, both ends included.
  • tol: Convergence tolerance.
  • iter: Maximum number of iterations.
  • strict: Whether to raise an error if convergence is not achieved.

Constructors

MonotonicSchurComplement(;    N::Integer = 10,    tol::Number = 1e-4,    iter::Option{<:Integer} = nothing,    strict::Bool = false) -> MonotonicSchurComplement

Keywords correspond to the struct's fields. iter defaults to nothing, which means the bisection derives its own budget from the bracket and tol, as max(1, ceil(Int, log2((hgamma - lgamma) / tol) * 2 + 1)).

Validation

  • N > 1. The scan needs both ends of the range.
  • tol > 0.
  • If iter is given: iter > 0.

Related

source
PortfolioOptimisers.schur_complement_weights — Function
schur_complement_weights(pr::AbstractPriorResult, items::VecVecInt,
                         wb::WeightBounds, params::SchurComplementParams,
                         gamma::Option{<:Number} = nothing) -> Tuple

Run the Schur complement recursion at one value of $\gamma$.

This method takes a NonMonotonicSchurComplement bundle. The MonotonicSchurComplement method searches over $\gamma$ and calls this method at each value it tries. SchurComplementHierarchicalRiskParity states the mathematics.

Algorithm

  1. Resolve the measure r of the bundle against pr with factory, and copy its covariance matrix into sigma.
  2. Take gamma from the argument, or from params.gamma when the argument is nothing.
  3. Set every entry of the weights w to one.
  4. Split each entry of items of more than one leaf into its halves, giving the new items. Stop when no entry has more than one leaf.
  5. For each pair of halves lc and rc, read the blocks A and C of sigma. When lc holds more than one leaf, augment both blocks with schur_augmentation. The results are A_aug and C_aug. Otherwise A_aug and C_aug are A and C.
  6. When params.flag is true, repair A_aug and C_aug with params.pdm. When params.flag is false and either block is not positive definite, return nothing as the weights.
  7. Write A_aug and C_aug back into sigma. A later split then reads the augmented and repaired blocks.
  8. Compute the risks lrisk and rrisk of the two blocks with naive_portfolio_risk, and the split factor alpha from them.
  9. Clamp alpha to wb with split_factor_weight_constraints. Multiply the weights of lc by alpha, and the weights of rc by 1 - alpha.
  10. Go back to step 4.

Arguments

  • pr: Prior result. Its covariance matrix is the default of the measure, and its X gives the number of assets and the number type of the weights.
  • items: The leaf orders to split. The recursion starts from one entry, the whole leaf order of the dendrogram.
  • wb: Resolved weight bounds, which clamp each split factor.
  • params: The bundle. The method reads r, gamma, pdm and flag.
  • gamma: A value that overrides params.gamma, or nothing to use the field. The monotonic search passes each value it tries in this argument.

Validation

  • With params.flag true, a repair that throws, for example on a negative diagonal entry, is rethrown as an ArgumentError that names gamma. A repair that returns a matrix that is positive semidefinite to round-off lets the recursion continue, and posdef! refuses every other result with a PosdefRepairError, which is rethrown the same way.

Returns

  • (w, gamma, r)::Tuple: The weights, the value of $\gamma$ the recursion ran at, and the measure that factory resolved. The weights sum to one. w is nothing when params.flag is false and an augmented block is not positive definite. assert_schur_weights turns that nothing into an error for a caller that keeps the weights.

Related

source
PortfolioOptimisers.schur_complement_weights — Method
schur_complement_weights(
    pr::AbstractPriorResult,
    items::AbstractVector{<:AbstractVector{<:Integer}},
    wb::WeightBounds,
    params::SchurComplementParams{<:Any, <:Any, <:Any, <:MonotonicSchurComplement}
) -> Tuple{Any, Any, Any}

Search $[0, \gamma]$ for the turning point of the portfolio variance, then allocate at it.

MonotonicSchurComplement states the definition of the value that the search finds and the steps of this method. Every evaluation calls the NonMonotonicSchurComplement method with the repair off, so a value that fails scores the largest value of the weight type. The returned weights are always the weights at the returned value of $\gamma$.

Related

source
PortfolioOptimisers.SchurComplementParams — Type
struct SchurComplementParams{__T_r, __T_gamma, __T_pdm, __T_alg, __T_flag} <: AbstractAlgorithm

Collects the risk measure, the interpolation parameter $\gamma$ and the two algorithms of one Schur complement bundle.

SchurComplementHierarchicalRiskParity holds one bundle or a vector of bundles. A vector runs one allocation per bundle, and blends the portfolios of the bundles in proportion to the r.settings.scale of each bundle.

The parameter $\gamma$ in $[0, 1]$ sets how much of the cross-cluster covariance the augmentation uses. It is the parameter of Section 5 of [230], where $\gamma = 0$ is the hierarchical recursion, as in Table 2 of that work.

Fields

  • r: Risk measure or vector of risk measures.
  • gamma: Schur complement parameter, in [0, 1]. At 0 the recursion augments no block, and with a Variance measure the allocation equals that of HierarchicalRiskParity under a Variance measure. A larger value subtracts more of the cross-cluster block from the covariance block of each half, which moves the allocation towards the minimum variance portfolio. Under MonotonicSchurComplement it is the upper end of the searched range, not the value that the allocation runs at.
  • pdm: Positive definite matrix estimator.
  • alg: Algorithm that chooses the value of gamma that the allocation runs at.
  • flag: Whether to repair an augmented covariance block that is not positive definite. When true, pdm repairs the block, and a repair that throws raises an error. When false, the recursion abandons the allocation instead. The MonotonicSchurComplement search needs that, and a caller that keeps the weights gets an error that names the gamma that failed.

Constructors

SchurComplementParams(;    r::Sd_Var = Variance(),    gamma::Number = 0.5,    pdm::Option{<:AbstractPosdefEstimator} = Posdef(),    alg::SchurComplementAlgorithm = MonotonicSchurComplement(),    flag::Bool = true) -> SchurComplementParams

Keywords correspond to the struct's fields. Sd_Var bounds r, because the allocation reads the risk of a half from the augmented covariance block of that half.

Validation

  • 0 <= gamma <= 1.

Related

References

  • [230] P. Cotton. Schur Complementary Allocation: A Unification of Hierarchical Risk Parity and Minimum Variance Portfolios. arXiv preprint arXiv:2411.05807 (2024). Section 5, Table 2.
source
PortfolioOptimisers.SchurComplementHierarchicalRiskParityResult — Type
struct SchurComplementHierarchicalRiskParityResult{__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk, __T_fb} <: HierarchicalOptimisationResult

Holds the weights of a Schur complement allocation, with the prior, the clustering and the parameters that produced them.

SchurComplementHierarchicalRiskParity returns it. It also holds the resolved weight bounds, the resolved fees, the resolved risk measure, the value of $\gamma$ the allocation ran at, the return code and the fallback.

The result belongs to HierarchicalOptimisationResult, because its estimator holds a HierarchicalOptimiser. It does not embed a HierarchicalResult as its two siblings do. It keeps a flat block of fields, because it also holds gamma.

The result holds no scalariser. SchurComplementParams bounds its measure to Sd_Var, so a bundle has one standard deviation or one variance and no vector of measures to combine.

Warning

With a vector of bundles, r and gamma are vectors with one entry per bundle, and the allocation blends the portfolios of the bundles, not their risks. expected_risk(res.r, res.w, res.pr) then adds the scaled risk of each measure at the blended weights. The allocation never computes that number. With one bundle, which is the default, the same call returns the risk of the allocation under its measure.

Fields

  • pr: Prior result.
  • wb: Weight bounds.
  • clr: Clusters result.
  • fees: Fees estimator or result.
  • r: The measure that the optimisation ran under, resolved by factory. It holds one measure for one bundle, and one measure per bundle for a vector of bundles. The type of r is not a type parameter of the Result, so the Results of two measures have one type.
  • gamma: The Schur complement parameter that the allocation ran at. It holds one value for one bundle, and one value per bundle for a vector of bundles. Under MonotonicSchurComplement it is the value that the search chose, which is at most the gamma of the bundle.
  • retcode: Optimisation return code.
  • w: Portfolio weights vector assets × 1.
  • imsk: The Investable Mask the optimisation reduced on: true at every asset whose prior moments were finite. It is nothing when every asset was investable, and that sentinel is what skips both the reduction and the expansion. investable_mask derives it once from the full-universe prior result, and the result carries it, because the reduced prior can no longer yield it.
  • fb: The fallback chain that answered this result: the (estimator, result) pair of every attempt optimise made before this one, in the order they ran, or nothing when the estimator it was asked of answered (see FbChain).

Constructors

SchurComplementHierarchicalRiskParityResult(;    pr::Option{<:AbstractPriorResult},    wb::Option{<:WeightBounds},    clr::Option{<:AbstractClusteringResult},    fees::Option{<:Fees},    r::Union{Sd_Var, VecBaseRM},    gamma::Union{Number, VecNum},    retcode::OptimisationReturnCode,    w::Option{<:VecNum},    imsk::Option{<:BitVector} = nothing,    fb::Option{<:OptE_Opt_FbChain}) -> SchurComplementHierarchicalRiskParityResult

Keywords correspond to the struct's fields.

_optimise builds the result with the keyword constructor alone, so that constructor expands the solved weights back onto the full asset universe with expand_investable_weights. The positional constructor does not expand. A rebuild calls it, and a second expansion of expanded weights is wrong.

Related

source
PortfolioOptimisers.SchurComplementHierarchicalRiskParity — Type
struct SchurComplementHierarchicalRiskParity{__T_opt, __T_params, __T_fb} <: ClusteringOptimisationEstimator

Runs the hierarchical risk parity recursion on covariance blocks that a Schur complement augments with the information of the cross-cluster block.

The parameter $\gamma$ interpolates. At gamma = 0 with a Variance measure, the allocation equals that of HierarchicalRiskParity with the same opt and a Variance measure. A larger value moves the allocation towards the minimum variance portfolio.

Mathematical definition

The recursion is that of HierarchicalRiskParity. It splits the dendrogram's leaf order in half, and divides the weight of the part between the two halves in inverse proportion to their risks. Schur changes only the covariance block that gives the risk of each half. Partition the covariance matrix of the part over its two halves $C_1$ and $C_2$:

\[\begin{align} \mathbf{\Sigma} &= \begin{pmatrix} \mathbf{\Sigma}_{11} & \mathbf{\Sigma}_{12} \\ \mathbf{\Sigma}_{21} & \mathbf{\Sigma}_{22} \end{pmatrix}\,,\\ \mathbf{A} &= \mathbf{\Sigma}_{11} - \gamma \, \mathbf{\Sigma}_{12} \mathbf{\Sigma}_{22}^{-1} \mathbf{\Sigma}_{21}\,,\\ \mathbf{R} &= \mathbf{I} - \gamma \, \mathbf{\Sigma}_{12} \mathbf{\Sigma}_{22}^{-1} \mathbf{M}^\intercal\,,\\ \hat{\mathbf{\Sigma}}_{11} &= \frac{1}{2}\left(\mathbf{R}^{-1}\mathbf{A} + \left(\mathbf{R}^{-1}\mathbf{A}\right)^\intercal\right)\,. \end{align}\]

$\hat{\mathbf{\Sigma}}_{22}$ follows when the two halves exchange their roles. The risk of a half then comes from its augmented block, with the naive risk parity weights of that block:

\[\begin{align} \tilde{w}_i &= \frac{\left(\hat{\mathbf{\Sigma}}_{11}\right)_{ii}^{-1}}{\sum_{j} \left(\hat{\mathbf{\Sigma}}_{11}\right)_{jj}^{-1}}\,,\\ \tilde{\rho}(C_1) &= \tilde{\boldsymbol{w}}^\intercal \hat{\mathbf{\Sigma}}_{11} \tilde{\boldsymbol{w}}\,,\\ \alpha &= \frac{\tilde{\rho}(C_2)}{\tilde{\rho}(C_1) + \tilde{\rho}(C_2)}\,. \end{align}\]

Where:

  • $C_1$, $C_2$: Halves of a part of the dendrogram's leaf order. $C_1$ holds the first $\lfloor n/2 \rfloor$ of the part's $n$ leaves, and $C_2$ holds the rest.
  • $\gamma$: Schur complement parameter, in $[0, 1]$. At $\gamma = 0$ every augmented block equals the plain block.
  • $\mathbf{\Sigma}_{11}$, $\mathbf{\Sigma}_{12}$, $\mathbf{\Sigma}_{21}$, $\mathbf{\Sigma}_{22}$: Blocks of the covariance matrix of a part, with the rows and the columns of $C_1$ first and those of $C_2$ second.
  • $\mathbf{A}$: Scaled Schur complement of $\mathbf{\Sigma}_{22}$. At $\gamma = 1$ it is the Schur complement of $\mathbf{\Sigma}_{22}$ in the covariance matrix of the part.
  • $\mathbf{M}$: Symmetric step-up matrix of size $|C_1| \times |C_2|$, see symmetric_step_up_matrix.
  • $\mathbf{I}$: Identity matrix.
  • $\mathbf{R}$: Step-up correction, the matrix that carries the augmentation back to the size of $C_1$.
  • $\hat{\mathbf{\Sigma}}_{11}$: Augmented block of $C_1$, made symmetric. $\hat{\mathbf{\Sigma}}_{22}$ follows when $C_1$ and $C_2$ exchange their roles.
  • $\tilde{\boldsymbol{w}}$: Naive risk parity weights of a block, the inverses of its diagonal entries divided by their sum.
  • $\tilde{\rho}(C)$: Risk of the naive risk parity sub-portfolio of the augmented block of $C$. A Variance measure takes the quadratic form, and a StandardDeviation measure takes its square root.
  • $\alpha$: Split factor, the fraction of the part's weight that goes to $C_1$. $C_2$ receives $1 - \alpha$.

$\mathbf{A}$ is the Schur complement with the parameter $\gamma$ of Equation 5.2 of [230], and $\gamma = 0$ is the hierarchical recursion, as in Table 2 of that work. Equation 4.2 of that work divides $\mathbf{A}$ entry by entry by $\boldsymbol{b} \boldsymbol{b}^\intercal$, where $\boldsymbol{b} = \boldsymbol{1} - \gamma \, \mathbf{\Sigma}_{12} \mathbf{\Sigma}_{22}^{-1} \boldsymbol{1}$ is Equation 5.3. This type does not. It builds $\hat{\mathbf{\Sigma}}_{11}$ from $\mathbf{R}$ and $\mathbf{M}$, which that work does not state. The closing remark of Appendix A of that work says that the code that accompanies it provides an alternative, and this type builds that alternative. The function pseudo_schur_complement of version 0.11.17 of that code, the Python package precise, computes $\mathbf{R}^{-1}\mathbf{A}$ with the same $\mathbf{R}$ and $\mathbf{M}$. Its symmetric part equals $\hat{\mathbf{\Sigma}}_{11}$ to round-off, and that code does not augment a part with a half of one leaf either. The block of Equation 4.2 and this block differ for $\gamma > 0$. The risk of a half is the variance of its naive risk parity portfolio, so the allocation at $\gamma = 1$ is not the minimum variance portfolio of Table 2 of that work.

The weights are the inverse variances of the augmented block for both measures. So at $\gamma = 0$ a Variance measure gives the allocation of HierarchicalRiskParity under a Variance measure. A StandardDeviation measure gives a different allocation from HierarchicalRiskParity under a StandardDeviation measure, because that optimiser takes inverse volatility weights.

A part of two or three leaves has a half $C_1$ of one leaf, and the recursion augments neither of its halves. The resolved weight bounds clamp $\alpha$, as in HierarchicalRiskParity. $C_1$ and $C_2$ receive $\alpha$ and $1 - \alpha$ of the weight of the part in every case, so the weights sum to one.

Algorithm

The fit of optimise runs these steps.

  1. Resolve every TimeDependent field to its static default.
  2. Compute the prior pr with opt.pe, and the investable mask imsk of the prior.
  3. Resolve the fees fees on the full asset universe.
  4. Reduce pr, the estimator and rd to the investable universe.
  5. Cluster the reduced prior with opt.cle, giving clr. The leaf order clr.res.order is the input of the recursion.
  6. Resolve the weight bounds wb on the investable universe, with one bound per asset on each side.
  7. Run schur_complement_weights with params, giving the weights w, the value gamma it ran at, and the resolved measure r. When params is a vector, run it once per bundle, add the weights of each bundle times the r.settings.scale of the bundle into w, and divide w by its sum.
  8. Check that the recursion produced weights, with assert_schur_weights.
  9. Apply the weight finaliser opt.wf to w with wb, giving the return code retcode and the final weights.
  10. Build the result, which expands the weights back onto the full asset universe.

Fields

  • opt: Base hierarchical optimiser configuration.
  • params: Schur complement bundle, or a vector of bundles whose portfolios the allocation blends.
  • fb: Fallback result or estimator.

Constructors

SchurComplementHierarchicalRiskParity(;    opt::HierarchicalOptimiser = HierarchicalOptimiser(),    params::TD{<:ScP_VecScP} = SchurComplementParams(),    fb::TDO_Option{<:OptE_Opt} = nothing) -> SchurComplementHierarchicalRiskParity

Keywords correspond to the struct's fields. A field typed TD or TDO_Option can hold a TimeDependent schedule with one value per fold. The bundles and the fallback define the problem, so a cross-validation fold loop resolves them once per fold. A plain optimise with no fold runs each at its static default, which is nothing for fb.

Validation

  • If params is a vector: !isempty(params).
  • fb schedules: bind !== :nearest.
  • A reader that states no source and reads the raw returns data, beside a reader that states x_src = ExcessSource(), logs one warning that names its path, see warn_raw_readers. The head then builds as configured.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • opt: Recursively updated through factory.
  • fb: Recursively updated through factory.

View parameters

SchurComplementHierarchicalRiskParity defines its own port_opt_view method rather than deriving one from field tags.

  • The method reads the returns matrix X as its third argument. When opt.pe already holds a prior result, the method replaces X with opt.pe.X, so it views the children against the observations of the prior and not against the matrix of the caller.
  • opt and params recurse through port_opt_view with that matrix.
  • The method views fb through view_child, which views an estimator fallback at i and keeps a precomputed result as it is.

Examples

julia> SchurComplementHierarchicalRiskParity()SchurComplementHierarchicalRiskParity     opt ┼ HierarchicalOptimiser         │       pe ┼ EmpiricalPrior         │          │           ce ┼ PortfolioOptimisersCovariance         │          │              │   ce ┼ Covariance         │          │              │      │    me ┼ SimpleExpectedReturns         │          │              │      │       │   w ┴ nothing         │          │              │      │    ce ┼ GeneralCovariance         │          │              │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)         │          │              │      │       │    w ┴ nothing         │          │              │      │   alg ┼ FullMoment()         │          │              │      │     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)         │          │           me ┼ SimpleExpectedReturns         │          │              │   w ┴ nothing         │          │      horizon ┼ nothing         │          │   fill_limit ┼ nothing         │          │        x_src ┴ nothing         │      cle ┼ ClustersEstimator         │          │      ce ┼ PortfolioOptimisersCovariance         │          │         │   ce ┼ Covariance         │          │         │      │    me ┼ SimpleExpectedReturns         │          │         │      │       │   w ┴ nothing         │          │         │      │    ce ┼ GeneralCovariance         │          │         │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)         │          │         │      │       │    w ┴ nothing         │          │         │      │   alg ┼ FullMoment()         │          │         │      │     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)         │          │      de ┼ Distance         │          │         │   power ┼ nothing         │          │         │     alg ┴ CanonicalDistance()         │          │     alg ┼ HClustAlgorithm         │          │         │   linkage ┴ Symbol: :ward         │          │     onc ┼ OptimalNumberClusters         │          │         │   max_k ┼ nothing         │          │         │     alg ┼ SecondOrderDifference         │          │         │         │   alg ┼ StandardisedValue         │          │         │         │       │   mv ┼ MeanValue         │          │         │         │       │      │   w ┴ nothing         │          │         │         │       │   sv ┼ StdValue         │          │         │         │       │      │           w ┼ nothing         │          │         │         │       │      │   corrected ┴ Bool: true         │          │   x_src ┴ nothing         │      slv ┼ nothing         │       wb ┼ WeightBounds         │          │   lb ┼ Float64: 0.0         │          │   ub ┴ Float64: 1.0         │     fees ┼ nothing         │     sets ┼ nothing         │       wf ┼ IterativeWeightFinaliser         │          │   iter ┴ Int64: 100         │   strict ┴ Bool: false  params ┼ SchurComplementParams         │       r ┼ Variance         │         │    settings ┼ RiskMeasureSettings         │         │             │   scale ┼ Float64: 1.0         │         │             │      ub ┼ nothing         │         │             │     rke ┴ Bool: true         │         │       sigma ┼ nothing         │         │        chol ┼ nothing         │         │          rc ┼ nothing         │         │         alg ┼ SquaredSOCRiskExpr()         │         │    mtx_sqrt ┼ EigenFallbackSquareRoot()         │         │   ratio_alg ┼ SquareRootRatio()         │         │      corner ┴ nothing         │   gamma ┼ Float64: 0.5         │     pdm ┼ Posdef         │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton         │         │   kwargs ┴ @NamedTuple{}: NamedTuple()         │     alg ┼ MonotonicSchurComplement         │         │        N ┼ Int64: 10         │         │      tol ┼ Float64: 0.0001         │         │     iter ┼ nothing         │         │   strict ┴ Bool: false         │    flag ┴ Bool: true      fb ┴ nothing

Related

References

  • [230] P. Cotton. Schur Complementary Allocation: A Unification of Hierarchical Risk Parity and Minimum Variance Portfolios. arXiv preprint arXiv:2411.05807 (2024). Sections 4 and 5, Equations 4.2, 5.2 and 5.3, and Appendix A.
source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(sp::SchurComplementParams, i, X::MatNum, args...) -> SchurComplementParams

Return the view of a Schur complement bundle on the assets i.

A view of the estimator on a subset of assets calls it, for example when an outer optimiser runs the estimator on one cluster. gamma, pdm, alg and flag hold no per-asset data, so they pass through unchanged.

Arguments

  • sp: Bundle to view.
  • i: Asset indices of the view.
  • X: Returns matrix, which the risk measure's own port_opt_view method reads.
  • args: Ignored.

Returns

  • sp::SchurComplementParams: The bundle with r replaced by its view.

Related

source
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
                                 AbstractResult, StatsBase.CovarianceEstimator}},
        args...; kwargs...) -> AbstractArray

Rebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.

factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.

factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.

The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.

Algorithm

The leaf method:

  1. Return a with no change, and drop args... and kwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.

The array method:

  1. For each element ai of a, call factory on ai, and forward args... and kwargs... with no change.
  2. Collect the results into a new array of the shape of a, in the order of a, and return it.

A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.

The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.

Arguments

  • a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators or nothing, which it rebuilds one element at a time.
  • args...: Positional arguments. The leaf method ignores them, and the array method forwards them.
  • kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.

Returns

  • a: The input with no change, for the leaf method.
  • v::AbstractArray: The rebuilt elements, in an array of the shape of a, for the array method.

Examples

julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue  w ┴ nothing

Related

source
factory(res::NonFiniteAllocationOptimisationResult, fb::Option{<:OptE_Opt_FbChain})

Rebuilds a continuous optimisation result with a new fallback record fb.

A concrete result can add its own method when a rebuild needs more than a new fb. optimise is the one caller, and it gives the FbChain of the attempts that failed.

Algorithm

  1. Read every field of res, in the order of the struct.
  2. Call the constructor of the type of res with every field except the last, and with fb as the last field.

Validation

  • fb is the last field of the type of res. Every concrete optimisation result obeys this rule, so the method checks nothing.

Related

source
factory(
    opt::Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult},
    _
) -> RelaxedRiskBudgeting{JuMPOptimiser{__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache}, _A, _B, <:RelaxedRiskBudgetingAlgorithm} where {__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache, _A, _B}

Returns opt unchanged.

This is the fallback factory of an optimisation estimator or result. An estimator whose parameters change at each step of an optimisation adds its own method. A precomputed result in a field of an estimator, for example in fb, reaches this method when factory gives the estimator the weights of the previous fold. A precomputed result does not change.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    sh::SchurComplementHierarchicalRiskParity,
    i,
    X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    args...
) -> SchurComplementHierarchicalRiskParity{HierarchicalOptimiser{__T_pe, __T_cle, __T_slv, __T_wb, __T_fees, __T_sets, __T_wf, __T_strict, __T_cache}} where {__T_pe, __T_cle, __T_slv, __T_wb, __T_fees, __T_sets, __T_wf, __T_strict, __T_cache}

Return a view of SchurComplementHierarchicalRiskParity sh sliced to asset indices i.

Related

source
PortfolioOptimisers._optimise — Function
_optimise(
    sh::SchurComplementHierarchicalRiskParity;
    ...
) -> SchurComplementHierarchicalRiskParityResult{__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk, Nothing} where {__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk}
_optimise(
    sh::SchurComplementHierarchicalRiskParity,
    rd::ReturnsResult;
    rmsk,
    kwargs...
) -> SchurComplementHierarchicalRiskParityResult{__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk, Nothing} where {__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk}

Fit a Schur complement allocation with one bundle.

optimise calls this method. SchurComplementHierarchicalRiskParity states its steps under # Algorithm. The weights, their bounds and the fee take the element type of the returns, so a Float32 matrix stays in Float32.

Unlike HierarchicalEqualRiskContribution and NestedClustered, this optimiser takes no branchorder keyword. Recursive bisection splits the leaf order of the dendrogram, so that order is the input of the algorithm, and the clustering always runs with the optimal order. kwargs absorbs a branchorder and the fit ignores it.

Arguments

  • sh: The Schur complement hierarchical risk parity optimiser.
  • rd: The returns result to use. When sh.opt.pe is a prior result, the fit itself does not read rd, but the clustering and a fallback can read it.
  • rmsk: The mask of a fit again after a refusal, or nothing on the first fit.
  • kwargs: Absorbed and ignored.

Related

source
PortfolioOptimisers._optimise — Function
_optimise(
    sh::SchurComplementHierarchicalRiskParity{<:Any, <:AbstractVector};
    ...
) -> SchurComplementHierarchicalRiskParityResult{__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk, Nothing} where {__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk}
_optimise(
    sh::SchurComplementHierarchicalRiskParity{<:Any, <:AbstractVector},
    rd::ReturnsResult;
    rmsk,
    kwargs...
) -> SchurComplementHierarchicalRiskParityResult{__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk, Nothing} where {__T_pr, __T_wb, __T_clr, __T_fees, __T_gamma, __T_retcode, __T_w, __T_imsk}

Fit a Schur complement allocation with a vector of bundles, and blend their portfolios.

optimise calls this method. It runs the steps of the single-bundle method, with step 7 of the # Algorithm of SchurComplementHierarchicalRiskParity once per bundle. The result holds one measure and one value of $\gamma$ per bundle.

Mathematical definition

\[\begin{align} \boldsymbol{w} &= \frac{\sum_{k=1}^{K} s_k \boldsymbol{w}_k}{\sum_{k=1}^{K} s_k}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Blended weights, before the weight finaliser.
  • $K$: Number of bundles.
  • $s_k$: Scale of the measure of bundle $k$, its r.settings.scale.
  • $\boldsymbol{w}_k$: Weights of the allocation of bundle $k$, which sum to one.

The denominator is the sum of the blended weights, because each $\boldsymbol{w}_k$ sums to one.

Arguments

  • sh: The Schur complement hierarchical risk parity optimiser, with a vector of bundles.
  • rd: The returns result to use. When sh.opt.pe is a prior result, the fit itself does not read rd, but the clustering and a fallback can read it.
  • rmsk: The mask of a fit again after a refusal, or nothing on the first fit.
  • kwargs: Absorbed and ignored.

Related

source

References