Phylogeny constraint generation

PortfolioOptimisers.SemiDefinitePhylogenyEstimator — Type
struct SemiDefinitePhylogenyEstimator{__T_pl, __T_p, __T_x_src} <: AbstractPhylogenyConstraintEstimator

Fits the relatedness of the assets to returns, and drives the product of the weights of each related pair to zero through a semidefinite relaxation.

The estimator holds the source that builds the relatedness matrix, and the penalty factor p. phylogeny_constraints fits the source to a returns matrix and returns a SemiDefinitePhylogeny, which holds the matrix and p for the model.

The AbstractSeparationAlgorithm of a network source decides which pairs are related. No field of this estimator changes that set. The row A ⊙ W == 0 reads only which entries of A are non-zero, not their size. So the separation algorithm changes the number of forbidden pairs, and nothing else.

Cajas [117] states the constraint over a network. Section 13.2.4.2 of [12] names [148] as the source of the same constraint over clusters. No copy of that work is available.

Warning

NetworkEstimator(; sep = PathLength()) relates every pair of assets that a path joins. A bare PathLength leaves dmax = nothing, which resolves to the observed diameter, so no pair is outside the budget. On a tree of 20 assets it relates all 190 pairs, and the constraint then drives the product of the weights of every pair to zero. HopCount with its default n = 1 is the other extreme, and relates only the neighbours. Set a numeric dmax to relate fewer pairs.

Fields

  • pl: Network estimator or clustering estimator. The field refuses a precomputed PhylogenyResult or Clusters. It states how to build the phylogeny for the universe of each call, and a precomputed structure holds one fixed universe. To use a precomputed structure, pass the constraint result instead.
  • p: Non-negative penalty factor on the trace of the semidefinite matrix variable. The model reads it only when the objective does not minimise a variance on the same weights. Such a variance is itself a trace against that variable, so it holds the variable down, and the model adds no second term. The penalty holds the matrix variable down to the outer product of the weights, which the relatedness rows need to bind the weights. The penalty term is also at least $p \lVert \boldsymbol{w} \rVert_2^2 / k$, so it spreads the weights, and a large p can leave both assets of a related pair in the portfolio. The relatedness rows hold on the matrix variable for every p.
  • x_src: The source of the returns that the clustering, phylogeny or centrality estimator reads, nothing or an AbstractReturnsSource. nothing and DataSource read the asset returns rd.X, and nothing reads the X of the Prior Result when the call gives no returns data. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame. PriorSource reads the X of the Prior Result, in the frame that the prior fitted in. Under a factor prior that X is a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give, DataSource() or ExcessSource() with no returns data, or PriorSource() on returns data with no Prior Result, gives a warning, and the estimator reads the matrix that the call gives. A call on a bare matrix reads that matrix under every source. An estimator inside another graph estimator keeps nothing, and the outer estimator states the source.

Constructors

SemiDefinitePhylogenyEstimator(;    pl::NwE_ClE = NetworkEstimator(),    p::Number = 0.05,    x_src::Option{<:AbstractReturnsSource} = nothing) -> SemiDefinitePhylogenyEstimator

Keywords correspond to the struct's fields. The default p = 0.05 is the penalty of the worked example in Section 6.2 of [117].

Validation

  • p >= 0.
  • x_src in ALL_RETURNS_SOURCES, see assert_returns_source. Otherwise the constructor raises an ArgumentError.
  • returns_source(pl) === nothing, see assert_inner_reader. The network or clustering estimator reads the matrix that this estimator selects, so it states no source of its own. Otherwise the constructor raises an ArgumentError.
  • The type bound NwE_ClE of pl refuses a precomputed PhylogenyResult or Clusters. So the keyword constructor raises a TypeError at once, and not later in a solve. To use a precomputed structure, build the SemiDefinitePhylogeny that phylogeny_constraints(estimator, X) returns.

Examples

julia> SemiDefinitePhylogenyEstimator()SemiDefinitePhylogenyEstimator     pl ┼ NetworkEstimator        │      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 ┼ KruskalTree        │         │     args ┼ Tuple{}: ()        │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │     sep ┼ HopCount        │         │   n ┼ CountOf        │         │     │   val ┴ Int64: 1        │   x_src ┴ nothing      p ┼ Float64: 0.05  x_src ┴ nothing

Related

References

  • [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Section 5.2, Equations 10 and 11.
  • [148] D. Cajas. A Graph Theory Approach to Portfolio Optimization Part II. Available at SSRN 4667426 (2023).
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 13.2.4.2, Equation 13.15. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.SemiDefinitePhylogeny — Type
struct SemiDefinitePhylogeny{__T_A, __T_p} <: AbstractPhylogenyConstraintResult

Drives the product of weights of every related pair of assets to zero through a semidefinite relaxation.

The source that built A decides which assets are related. A network source relates the assets of one neighbourhood, and a clustering source relates the assets of one cluster. Cajas [117] states the constraint over a network. Section 13.2.4.2 of [12] names [148] as the source of the same constraint over clusters. No copy of that work is available.

p sets the size of the relaxation gap, not the strength of the constraint. The model writes A ⊙ W == 0 for every p, so a larger p forbids no more pairs. A larger p only holds W closer to the outer product of the weights. When the gap is wide, both assets of a related pair can hold weight while their entry of W is zero.

A Variance in a model with this constraint always takes the constraint form below, whatever its alg field states. Under MaximumRatio, the ratio_alg of the variance selects the degree of its objective term, and so the ratio. The default gives the Sharpe ratio, and the # Mathematical definition of MaximumRatio states the rule. Under that objective, set_sdp_phylogeny_constraints! writes the rows on the lifted matrix of set_sdp_objective_lift!.

Mathematical definition

The relaxation replaces the outer product of the weights with a symmetric matrix variable, and bounds it below through a Schur complement. A variance objective is already a trace against that variable, so the constraint form applies:

\[\begin{align} \underset{\boldsymbol{w},\, \mathbf{W}}{\min}\quad & \mathrm{tr}(\mathbf{\Sigma} \mathbf{W})\\ \textrm{s.t.}\quad & \begin{bmatrix} \mathbf{W} & \boldsymbol{w} \\ \boldsymbol{w}^\intercal & k \end{bmatrix} \succeq 0\,,\\ & \mathbf{A} \odot \mathbf{W} = 0\,,\\ & \mathbf{W} \in \mathbb{S}^{N}\,,\quad \boldsymbol{w} \in \mathcal{W}\,. \end{align}\]

For every other risk measure, no term of the objective holds the matrix variable down to the outer product. A penalty on its trace does that instead:

\[\begin{align} \underset{\boldsymbol{w},\, \mathbf{W}}{\min}\quad & \phi(\boldsymbol{w}) + p\, \mathrm{tr}(\mathbf{W})\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\mathbf{W}$: Symmetric $N \times N$ matrix variable that relaxes $\boldsymbol{w}\boldsymbol{w}^\intercal / k$.
  • $\mathbf{A}$: Relatedness matrix, the A field.
  • $p$: Penalty factor, the p field.
  • $k$: Variable that scales the budget in the homogenised problem.
  • $\mathbf{\Sigma}$: Covariance matrix.
  • $\phi$: Risk measure of the optimiser.
  • $\odot$: Hadamard product.
  • $\mathbb{S}^{N}$: Set of real symmetric $N \times N$ matrices.
  • $\mathcal{W}$: Rest of the feasible set.

Fields

  • A: Symmetric relatedness matrix with a zero diagonal. A network source gives the range connection matrix, and a clustering source gives the adjacency label matrix. The constructor stores it as given.
  • p: Non-negative penalty factor on the trace of the semidefinite matrix variable. The model reads it only when the objective does not minimise a variance on the same weights. Such a variance is itself a trace against that variable, so it holds the variable down, and the model adds no second term. The penalty holds the matrix variable down to the outer product of the weights, which the relatedness rows need to bind the weights. The penalty term is also at least $p \lVert \boldsymbol{w} \rVert_2^2 / k$, so it spreads the weights, and a large p can leave both assets of a related pair in the portfolio. The relatedness rows hold on the matrix variable for every p.

Constructors

SemiDefinitePhylogeny(    A::MatNum_PhRMatNum,    p::Number) -> SemiDefinitePhylogenySemiDefinitePhylogeny(;    A::MatNum_PhRMatNum,    p::Number = 0.05) -> SemiDefinitePhylogeny

Keywords correspond to the struct's fields. The default p = 0.05 is the penalty of the worked example in Section 6.2 of [117].

Validation

  • LinearAlgebra.issymmetric(A) and all(iszero, LinearAlgebra.diag(A)). A breach raises an ArgumentError.
  • p >= 0. A breach raises a DomainError.

Examples

julia> SemiDefinitePhylogeny([0.0 1.0; 1.0 0.0], 0.05)SemiDefinitePhylogeny  A ┼ 2×2 Matrix{Float64}  p ┴ Float64: 0.05

Related

References

  • [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Section 5.2, Equations 10 and 11.
  • [148] D. Cajas. A Graph Theory Approach to Portfolio Optimization Part II. Available at SSRN 4667426 (2023).
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 13.2.4.2, Equation 13.15. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.IntegerPhylogenyEstimator — Type
struct IntegerPhylogenyEstimator{__T_pl, __T_B, __T_x_src} <: AbstractPhylogenyConstraintEstimator

Fits the relatedness of the assets to returns, and caps the number of related assets that the portfolio holds at once.

The estimator holds the source that builds the relatedness matrix, and the cap B. phylogeny_constraints fits the source to a returns matrix and returns an IntegerPhylogeny, which holds the matrix and B for the model.

The AbstractSeparationAlgorithm of a network source decides which pairs are related, and B counts the held assets over them. The relatedness is binary under every separation algorithm. The matrix of a PhylogenyResult is an Int matrix. A cap cannot count over a graded relation.

Warning

NetworkEstimator(; sep = PathLength()) relates every pair of assets that a path joins. A bare PathLength leaves dmax = nothing, which resolves to the observed diameter, so no pair is outside the budget. On a tree of 20 assets it relates all 190 pairs. HopCount with its default n = 1 is the other extreme, and relates only the neighbours. Set a numeric dmax to relate fewer pairs.

Fields

  • pl: Network estimator or clustering estimator. The field refuses a precomputed PhylogenyResult or Clusters. It states how to build the phylogeny for the universe of each call, and a precomputed structure holds one fixed universe. To use a precomputed structure, pass the constraint result instead.
  • B: Right-hand side of A * z <= B, where z is the held binary. Each entry is the largest number of assets that the portfolio can hold out of one row of A. A scalar applies to every row. A vector states one bound per row, so its length must match the row count of the stored A, not the number of assets. An estimator has no rows yet. It checks a vector only against the largest number of clusters that a clustering source can return.
  • x_src: The source of the returns that the clustering, phylogeny or centrality estimator reads, nothing or an AbstractReturnsSource. nothing and DataSource read the asset returns rd.X, and nothing reads the X of the Prior Result when the call gives no returns data. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame. PriorSource reads the X of the Prior Result, in the frame that the prior fitted in. Under a factor prior that X is a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give, DataSource() or ExcessSource() with no returns data, or PriorSource() on returns data with no Prior Result, gives a warning, and the estimator reads the matrix that the call gives. A call on a bare matrix reads that matrix under every source. An estimator inside another graph estimator keeps nothing, and the outer estimator states the source.

Constructors

IntegerPhylogenyEstimator(;    pl::NwE_ClE = NetworkEstimator(),    B::Int_VecInt = 1,    x_src::Option{<:AbstractReturnsSource} = nothing) -> IntegerPhylogenyEstimator

Keywords correspond to the struct's fields.

Validation

Examples

julia> IntegerPhylogenyEstimator()IntegerPhylogenyEstimator     pl ┼ NetworkEstimator        │      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 ┼ KruskalTree        │         │     args ┼ Tuple{}: ()        │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │     sep ┼ HopCount        │         │   n ┼ CountOf        │         │     │   val ┴ Int64: 1        │   x_src ┴ nothing      B ┼ Int64: 1  x_src ┴ nothing

Related

References

  • [149] F. Ricca and A. Scozzari. Portfolio optimization through a network approach: network assortative mixing and portfolio diversification. European Journal of Operational Research 312, 700–717 (2024).
  • [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Section 5.1, Equation 9.
  • [148] D. Cajas. A Graph Theory Approach to Portfolio Optimization Part II. Available at SSRN 4667426 (2023).
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 13.2.4.1, Equation 13.14. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.IntegerPhylogeny — Type
struct IntegerPhylogeny{__T_A, __T_B} <: AbstractPhylogenyConstraintResult

Caps at B the number of related assets that a mixed-integer model can hold at once.

The source that built A decides which assets are related. A network source relates the assets of one neighbourhood, and a clustering source relates the assets of one cluster. A clustering source with B = 1 holds at most one asset per cluster.

A network source with B = 1 holds at most one asset of each closed neighbourhood, which is an asset together with its neighbours. So it forbids two neighbours, and it also forbids two assets that share a neighbour. The held assets are thus at a distance of at least three in the network. On the graph of seven assets in Figure 13 of [117], 32 selections hold no two neighbours, but only 12 satisfy this constraint. The semidefinite form, SemiDefinitePhylogeny, forbids only the pairs that A relates.

Ricca and Scozzari [149] state the constraint for the neighbours of a network. Cajas [117] extends it to the assets that a walk of a given length links. Section 13.2.4.1 of [12] names [148] as the source of the constraint over clusters, and of a cap per cluster. No copy of that work is available.

Mathematical definition

The cap is a mutually exclusive investment constraint on the held binary:

\[\begin{align} \underset{\boldsymbol{w}}{\mathrm{opt}}\quad & \phi(\boldsymbol{w})\\ \textrm{s.t.}\quad & \mathbf{A} \boldsymbol{z} \leq \boldsymbol{B}\,,\\ & \boldsymbol{\ell} \odot \boldsymbol{z} \leq \boldsymbol{w} \leq \boldsymbol{u} \odot \boldsymbol{z}\,,\\ & \boldsymbol{z} \in \{0, 1\}^{N}\,,\quad \boldsymbol{w} \in \mathcal{W}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{z}$: Held binary, one entry per asset.
  • $\mathbf{A}$: Stored relatedness rows, the A field.
  • $\boldsymbol{B}$: Cap, the B field.
  • $\boldsymbol{\ell}$, $\boldsymbol{u}$: Lower and upper weight bounds.
  • $\phi$: Objective function of the optimiser.
  • $\odot$: Hadamard product.
  • $\mathcal{W}$: Rest of the feasible set.

Algorithm

The constructor rewrites the matrix it is given, so the stored A is a derived quantity:

  1. Check that the diagonal of A is zero and that A is symmetric.
  2. Add the identity to A, which puts each asset in its own row.
  3. Drop the repeated rows of the sum with unique(...; dims = 1). The result is the stored A. One row survives per distinct neighbourhood or cluster, so the stored matrix usually has fewer rows than columns.
  4. Check that B is non-empty, non-negative and finite.
  5. Check size(A, 1) == length(B) when B is a vector, against the row count of step 3 and not against the number of assets.

Fields

  • A: Row set of the relatedness matrix. The constructor stores unique(A + I; dims = 1), not the matrix passed in. The identity puts each asset in its own row, and unique drops the repeated rows. One row survives per distinct neighbourhood or cluster, so the stored matrix usually has fewer rows than columns.
  • B: Right-hand side of A * z <= B, where z is the held binary. Each entry is the largest number of assets that the portfolio can hold out of one row of A. A scalar applies to every row. A vector states one bound per row, so its length must match the row count of the stored A, not the number of assets. An estimator has no rows yet. It checks a vector only against the largest number of clusters that a clustering source can return.

Constructors

IntegerPhylogeny(    A::MatNum_PhRMatNum,    B::Int_VecInt) -> IntegerPhylogenyIntegerPhylogeny(;    A::MatNum_PhRMatNum,    B::Int_VecInt = 1) -> IntegerPhylogeny

Keywords correspond to the struct's fields.

Validation

  • LinearAlgebra.issymmetric(A) and all(iszero, LinearAlgebra.diag(A)). A breach raises an ArgumentError.

  • assert_nonempty_nonneg_finite_val checks B.

    • AbstractVector: size(unique(A + LinearAlgebra.I; dims = 1), 1) == length(B). A breach raises a DimensionMismatch.

Examples

julia> IntegerPhylogeny(; A = [0.0 1.0; 1.0 0.0], B = 2)IntegerPhylogeny  A ┼ 1×2 Matrix{Float64}  B ┴ Int64: 2

Related

References

  • [149] F. Ricca and A. Scozzari. Portfolio optimization through a network approach: network assortative mixing and portfolio diversification. European Journal of Operational Research 312, 700–717 (2024).
  • [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Section 5.1, Equation 9.
  • [148] D. Cajas. A Graph Theory Approach to Portfolio Optimization Part II. Available at SSRN 4667426 (2023).
  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 13.2.4.1, Equation 13.14. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.CentralityConstraint — Type
struct CentralityConstraint{__T_A, __T_B, __T_comp, __T_x_src} <: AbstractCentralityConstraint

Bounds the average centrality of the portfolio by a number, or by a measure of the centrality vector.

The constraint controls how central the portfolio is in the asset network, not how its weight is spread. centrality_constraints turns it into one row of a LinearConstraint. Section 4 of [117] states the constraint as an equality against a target average centrality. This type also accepts either inequality.

Mathematical definition

\[\begin{align} \underset{\boldsymbol{w}}{\mathrm{opt}}\quad & \phi(\boldsymbol{w})\\ \textrm{s.t.}\quad & \boldsymbol{c}^\intercal \boldsymbol{w} \mathbin{\square} \bar{c}\,,\\ & \boldsymbol{w} \in \mathcal{W}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{c}$: Centrality vector the estimator in A computes.
  • $\bar{c}$: Threshold, the B field.
  • $\square$: Comparison operator, the comp field.
  • $\phi$: Objective function of the optimiser.
  • $\mathcal{W}$: Rest of the feasible set.

When B is a VectorToScalarMeasure, $\bar{c}$ is that measure of $\boldsymbol{c}$, so the threshold moves with the graph. Under MinValue or MaxValue, $\bar{c}$ is an entry of $\boldsymbol{c}$. The portfolio fully invested in that asset then meets the constraint with equality, under every comparison operator.

Fields

  • A: Centrality estimator. Its centrality vector gives the coefficients of the generated row.
  • B: Right-hand side of the constraint. A number is the threshold itself. A VectorToScalarMeasure derives the threshold from the centrality vector that A gives, so the threshold moves with the graph. The measure reads that vector, never the row after comp flips its sign, so MinValue() gives the smallest entry under <= and under >= alike.
  • comp: Comparison operator for the centrality constraint. == builds an equality row, every other operator an inequality row.
  • x_src: The source of the returns that the clustering, phylogeny or centrality estimator reads, nothing or an AbstractReturnsSource. nothing and DataSource read the asset returns rd.X, and nothing reads the X of the Prior Result when the call gives no returns data. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame. PriorSource reads the X of the Prior Result, in the frame that the prior fitted in. Under a factor prior that X is a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give, DataSource() or ExcessSource() with no returns data, or PriorSource() on returns data with no Prior Result, gives a warning, and the estimator reads the matrix that the call gives. A call on a bare matrix reads that matrix under every source. An estimator inside another graph estimator keeps nothing, and the outer estimator states the source.

Constructors

CentralityConstraint(;    A::CentralityEstimator = CentralityEstimator(),    B::Num_VecToScaM = MinValue(),    comp::ComparisonOperator = <=,    x_src::Option{<:AbstractReturnsSource} = nothing) -> CentralityConstraint

Keywords correspond to the struct's fields.

Validation

  • A is bounded by CentralityEstimator, B by Num_VecToScaM, and comp by ComparisonOperator. A value outside a bound raises a TypeError from the keyword constructor.
  • x_src in ALL_RETURNS_SOURCES, see assert_returns_source. Otherwise the constructor raises an ArgumentError.
  • returns_source(A) === nothing, see assert_inner_reader. The centrality estimator reads the matrix that this constraint selects, so it states no source of its own. Otherwise the constructor raises an ArgumentError.
  • The constructor checks no value of B. A non-finite B reaches the generated row unchanged. centrality_constraints stores a NaN or an Inf right-hand side, and the model gives it to the solver.

Examples

julia> CentralityConstraint()CentralityConstraint      A ┼ CentralityEstimator        │      pl ┼ NetworkEstimator        │         │      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 ┼ KruskalTree        │         │         │     args ┼ Tuple{}: ()        │         │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │         │     sep ┼ HopCount        │         │         │   n ┼ CountOf        │         │         │     │   val ┴ Int64: 1        │         │   x_src ┴ nothing        │      ct ┼ DegreeCentrality        │         │     kind ┼ Int64: 0        │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │   x_src ┴ nothing      B ┼ MinValue()   comp ┼ typeof(<=): <=  x_src ┴ nothing

Related

References

  • [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Section 4, Equation 8.
source
PortfolioOptimisers.phylogeny_constraints — Function
phylogeny_constraints(plc::Option{<:PlCE_PlC}, X::MatNum; dims::Int = 1, kwargs...)
phylogeny_constraints(plcs::VecPlCE_PlC, args...; kwargs...)

Build a phylogeny constraint result from an estimator, or pass a result through.

An estimator fits its network or clustering source to X with phylogeny_matrix. A SemiDefinitePhylogenyEstimator gives a SemiDefinitePhylogeny, and an IntegerPhylogenyEstimator gives an IntegerPhylogeny. A precomputed result and nothing pass through unchanged, and the function builds nothing for them. A vector gives a vector of results in the same order.

Arguments

  • plc: A phylogeny constraint estimator, a phylogeny constraint result, or nothing.
  • plcs: A vector of phylogeny constraint estimators and results.
  • X: The data matrix. Only an estimator reads it.
  • dims: Dimension along which the computation runs.
  • kwargs...: More keyword arguments for phylogeny_matrix. Only an estimator reads them.

Returns

  • res: The phylogeny constraint result, or a vector of them for plcs.

    • SemiDefinitePhylogeny: For a semidefinite estimator or result.
    • IntegerPhylogeny: For an integer estimator or result.
    • nothing: When plc is nothing.

Related

source
phylogeny_constraints(
    plc::AbstractPhylogenyConstraintEstimator,
    pr::Union{AbstractPriorResult, ReturnsResult};
    rd,
    iv,
    kwargs...
) -> Union{IntegerPhylogeny, SemiDefinitePhylogeny{<:AbstractMatrix{var"#s166"}, <:Number} where var"#s166"<:Union{Number, AbstractJuMPScalar}}

Compute phylogeny constraints from asset returns in a prior result using a phylogeny constraint estimator.

phylogeny_constraints delegates to the asset-returns variant with the X that plc states as its source, pr.X or the returns of rd.

Algorithm

  1. Pick the asset returns matrix X from the source that the reader states, returns_source, with returns_matrix_picker. Refuse a gap in X that a plain graph reader cannot read, with assert_graph_readable.
  2. Call the asset-returns method of phylogeny_constraints with X, passing both results on as pr and rd and dims = 1 last, and return the constraint result it produces.

Arguments

  • plc: Phylogeny constraint estimator.
  • pr: Prior result or returns result. Both carry the asset returns matrix X, so either can supply it.
  • rd: The returns result to use. Read for X under the source of the reader, and passed on to the estimator tree.
  • iv: Optional implied volatility matrix, observations × assets, read by an ImpliedVolatility estimator in the tree. The estimator receives the last rows of iv, one for each row of the picked X, through implied_volatility_picker, so a prior that keeps fewer rows than the returns data still pairs each row of its X with the implied volatility of the same observation.
  • kwargs...: Additional keyword arguments passed to the estimator. An unknown keyword raises a MethodError, see graph_verb_keywords.

Returns

  • Phylogeny constraint result.

Related

source
PortfolioOptimisers.centrality_constraints — Function
centrality_constraints(ccs::CC_VecCC, X::MatNum; dims::Int = 1, strict::Bool = false,
                       kwargs...)

Reduce one or more CentralityConstraint estimators to a LinearConstraint.

Each estimator gives one row. The coefficients of the row are the centrality vector of the asset network. The right-hand side is a number, or a measure of that vector. A constraint whose centrality vector is empty or all zero gives no row, because its row does not depend on the weights. Two assets under BetweennessCentrality give the zero vector, and a lone such constraint makes this function return nothing. strict_diagnostic reports the drop, so strict decides whether it raises or warns.

The dropped row compares zero with B, so it does not depend on the weights. Every linear constraint builder drops such a row at construction time, and strict = true makes the drop raise an IsZeroError.

Algorithm

  1. Check that ccs is not empty when it is a vector.
  2. Check dims with assert_dims, and read the asset count N from the axis of X that dims does not name. N is the width of every row the loop builds.
  3. For each cc in ccs, compute the centrality vector A with the estimator in cc.A, along dims.
  4. Report cc through strict_diagnostic with zero_centrality_msg and skip it when A is empty or all zero.
  5. Read the sign d and the inequality flag flag_ineq of cc.comp from comparison_sign_ineq_flag.
  6. Derive the right-hand side B from cc.B against the unscaled A with vec_to_real_measure, and scale it by d.
  7. Scale A by d, which negates a >= row so that every inequality is stored in the A w <= B sense.
  8. Append A and B to the inequality pair or to the equality pair, as flag_ineq selects.
  9. Reshape each flat accumulator into N columns, so that each surviving constraint gives one row. Build the LinearConstraint from the halves that hold a row. Return nothing when neither half does.

Step 6 comes before step 7 on purpose. A measure of the scaled row negates the threshold a second time. That cancels the sign flip, and turns a MinValue() into a MaxValue() with the wrong sign.

Arguments

  • ccs: One CentralityConstraint or a vector of them.
  • X: The data matrix.
  • dims: Dimension along which the computation runs.
  • strict: If true, a constraint whose centrality vector is empty or all zero raises an IsZeroError. If false, it gives a warning. The function drops the constraint in both cases.
  • kwargs...: More keyword arguments for centrality_vector.

Validation

  • !isempty(ccs) when ccs is a vector. A breach raises an IsEmptyError.
  • dims in (1, 2). The check is made with assert_dims, which raises the DomainError.
  • A centrality vector that is empty or all zero raises an IsZeroError when strict is true, and gives a warning otherwise. The function drops the constraint in both cases.
  • The function checks no value of cc.B. A NaN or an Inf threshold reaches the returned right-hand side unchanged.

Returns

  • lc::Option{<:LinearConstraint}: The inequality rows and the equality rows, or nothing when the function drops every constraint.

Related

source
centrality_constraints(lc::Option{<:LinearConstraint}, args...; kwargs...)

Return a LinearConstraint or nothing unchanged.

A caller can give the linear constraint that the CentralityConstraint estimators reduce to, in place of the estimators. This method passes it through and builds nothing.

Arguments

  • lc: A LinearConstraint or nothing.
  • args...: Any positional arguments. The method ignores them.
  • kwargs...: Any keyword arguments. The method ignores them.

Returns

  • lc::Option{<:LinearConstraint}: The input, unchanged.

Related

source
centrality_constraints(ccs::CentralityConstraint, pr::Pr_RR;
                       rd::Option{<:ReturnsResult} = nothing,
                       iv::Option{<:MatNum} = nothing, kwargs...)
centrality_constraints(ccs::VecCC, pr::Pr_RR; rd::Option{<:ReturnsResult} = nothing,
                       iv::Option{<:MatNum} = nothing, kwargs...)

Compute centrality constraints from asset returns in a prior result using a centrality constraint estimator.

centrality_constraints delegates to the asset-returns variant with the X that each constraint states as its source, pr.X or the returns of rd.

Each constraint of a vector states its own source, so two constraints of one vector can read different matrices. A vector whose constraints state one source reads one matrix. A vector whose constraints state different sources computes the rows of each constraint from its own matrix, and joins them in the order of the vector with merge_linear_constraints, which gives the rows of the one call.

Algorithm

  1. A vector whose constraints state different sources: compute the result of each constraint with the method for one constraint, and join the results that are not nothing with merge_linear_constraints. Return nothing when every result is nothing.
  2. Otherwise pick the asset returns matrix X from the source that the constraints state, returns_source, with returns_matrix_picker. Refuse a gap in X that a plain graph reader cannot read, with assert_graph_readable.
  3. Call the asset-returns method of centrality_constraints with X, passing both results on as pr and rd and dims = 1 last, and return the constraint result it produces.

Arguments

  • ccs: Centrality constraint estimator or vector thereof.
  • pr: Prior result or returns result. Both carry the asset returns matrix X, so either can supply it.
  • rd: The returns result to use. Read for X under the source of the reader, and passed on to the estimator tree.
  • iv: Optional implied volatility matrix, observations × assets, read by an ImpliedVolatility estimator in the tree. The estimator receives the last rows of iv, one for each row of the picked X, through implied_volatility_picker, so a prior that keeps fewer rows than the returns data still pairs each row of its X with the implied volatility of the same observation.
  • kwargs...: Additional keyword arguments passed to the estimator. strict is read by the asset-returns variant, which reports a dropped zero centrality vector through it. An unknown keyword raises a MethodError, see graph_verb_keywords.

Returns

  • Centrality constraint result.

Related

source
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(plc::AbstractPhylogenyConstraintEstimator, i)

Return the phylogeny constraint estimator with the observation weights of its children cut to the observations i.

A phylogeny constraint estimator fits the phylogeny of its pl on the returns of the solve, and a covariance estimator in that phylogeny can hold fixed observation weights. A Shared Series gap drops observations from those returns, so the weights must lose the same observations, see shared_series_estimator. The estimators are not @propagatable, so this method cuts every field through obs_weights_fields.

Arguments

  • plc: The phylogeny constraint estimator. Its keyword constructor takes every field name, as the constructors of the library do.
  • i: The observations to keep: a mask of the full sample, or their positions.

Returns

  • plc: The estimator at the kept observations.

Related

source
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(cc::CentralityConstraint, i) -> CentralityConstraint

Return the centrality constraint with the observation weights of its centrality estimator A cut to the observations i.

A fits a phylogeny on the returns of the solve, and a covariance estimator in that phylogeny can hold fixed observation weights. A Shared Series gap drops observations from those returns, so the weights must lose the same observations, see shared_series_estimator. The method cuts A alone. The bound B can be a VectorToScalarMeasure whose weights weight the assets, not the observations, so a cut of every field would cut them by the wrong axis.

Arguments

  • cc: The centrality constraint.
  • i: The observations to keep: a mask of the full sample, or their positions.

Returns

  • cc::CentralityConstraint: The constraint at the kept observations.

Related

source

References

[12]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
[117]
D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023).
[148]
D. Cajas. A Graph Theory Approach to Portfolio Optimization Part II. Available at SSRN 4667426 (2023).
[149]
F. Ricca and A. Scozzari. Portfolio optimization through a network approach: network assortative mixing and portfolio diversification. European Journal of Operational Research 312, 700–717 (2024).