Phylogeny constraint generation
PortfolioOptimisers.SemiDefinitePhylogenyEstimator — Type
struct SemiDefinitePhylogenyEstimator{__T_pl, __T_p, __T_x_src} <: AbstractPhylogenyConstraintEstimatorFits 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.
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 precomputedPhylogenyResultorClusters. 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 largepcan leave both assets of a related pair in the portfolio. The relatedness rows hold on the matrix variable for everyp.
x_src: The source of the returns that the clustering, phylogeny or centrality estimator reads,nothingor anAbstractReturnsSource.nothingandDataSourceread the asset returnsrd.X, andnothingreads theXof the Prior Result when the call gives no returns data.ExcessSourcereads the returns in excess of the benchmark,rd.X - rd.B, the Excess Frame.PriorSourcereads theXof the Prior Result, in the frame that the prior fitted in. Under a factor prior thatXis a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give,DataSource()orExcessSource()with no returns data, orPriorSource()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 keepsnothing, and the outer estimator states the source.
Constructors
SemiDefinitePhylogenyEstimator(; pl::NwE_ClE = NetworkEstimator(), p::Number = 0.05, x_src::Option{<:AbstractReturnsSource} = nothing) -> SemiDefinitePhylogenyEstimatorKeywords 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, seeassert_returns_source. Otherwise the constructor raises anArgumentError.returns_source(pl) === nothing, seeassert_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 anArgumentError.- The type bound
NwE_ClEofplrefuses a precomputedPhylogenyResultorClusters. So the keyword constructor raises aTypeErrorat once, and not later in a solve. To use a precomputed structure, build theSemiDefinitePhylogenythatphylogeny_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 ┴ nothingRelated
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.
PortfolioOptimisers.SemiDefinitePhylogeny — Type
struct SemiDefinitePhylogeny{__T_A, __T_p} <: AbstractPhylogenyConstraintResultDrives 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
Afield. - $p$: Penalty factor, the
pfield. - $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 largepcan leave both assets of a related pair in the portfolio. The relatedness rows hold on the matrix variable for everyp.
Constructors
SemiDefinitePhylogeny( A::MatNum_PhRMatNum, p::Number) -> SemiDefinitePhylogenySemiDefinitePhylogeny(; A::MatNum_PhRMatNum, p::Number = 0.05) -> SemiDefinitePhylogenyKeywords 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)andall(iszero, LinearAlgebra.diag(A)). A breach raises anArgumentError.p >= 0. A breach raises aDomainError.
Examples
julia> SemiDefinitePhylogeny([0.0 1.0; 1.0 0.0], 0.05)SemiDefinitePhylogeny A ┼ 2×2 Matrix{Float64} p ┴ Float64: 0.05Related
set_sdp_constraints!set_sdp_frc_constraints!set_sdp_phylogeny_constraints!: writesA ⊙ W == 0for every result of this type, and addsp * tr(W)to the objective penalty unless the objective minimises a variance on the same weights.SemiDefinitePhylogenyEstimatorAbstractPhylogenyConstraintResultphylogeny_constraints
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.
PortfolioOptimisers.IntegerPhylogenyEstimator — Type
struct IntegerPhylogenyEstimator{__T_pl, __T_B, __T_x_src} <: AbstractPhylogenyConstraintEstimatorFits 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.
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 precomputedPhylogenyResultorClusters. 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 ofA * z <= B, wherezis the held binary. Each entry is the largest number of assets that the portfolio can hold out of one row ofA. A scalar applies to every row. A vector states one bound per row, so its length must match the row count of the storedA, 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,nothingor anAbstractReturnsSource.nothingandDataSourceread the asset returnsrd.X, andnothingreads theXof the Prior Result when the call gives no returns data.ExcessSourcereads the returns in excess of the benchmark,rd.X - rd.B, the Excess Frame.PriorSourcereads theXof the Prior Result, in the frame that the prior fitted in. Under a factor prior thatXis a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give,DataSource()orExcessSource()with no returns data, orPriorSource()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 keepsnothing, and the outer estimator states the source.
Constructors
IntegerPhylogenyEstimator(; pl::NwE_ClE = NetworkEstimator(), B::Int_VecInt = 1, x_src::Option{<:AbstractReturnsSource} = nothing) -> IntegerPhylogenyEstimatorKeywords correspond to the struct's fields.
Validation
assert_nonempty_nonneg_finite_valchecksB.AbstractVector:validate_length_integer_phylogeny_constraint_Balso checks it.
x_src in ALL_RETURNS_SOURCES, seeassert_returns_source. Otherwise the constructor raises anArgumentError.returns_source(pl) === nothing, seeassert_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 anArgumentError.The type bound
NwE_ClEofplrefuses a precomputedPhylogenyResultorClusters. So the keyword constructor raises aTypeErrorat once, and not later in a solve. To use a precomputed structure, build theIntegerPhylogenythatphylogeny_constraints(estimator, X)returns.
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 ┴ nothingRelated
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.
PortfolioOptimisers.IntegerPhylogeny — Type
struct IntegerPhylogeny{__T_A, __T_B} <: AbstractPhylogenyConstraintResultCaps 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
Afield. - $\boldsymbol{B}$: Cap, the
Bfield. - $\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:
- Check that the diagonal of
Ais zero and thatAis symmetric. - Add the identity to
A, which puts each asset in its own row. - Drop the repeated rows of the sum with
unique(...; dims = 1). The result is the storedA. One row survives per distinct neighbourhood or cluster, so the stored matrix usually has fewer rows than columns. - Check that
Bis non-empty, non-negative and finite. - Check
size(A, 1) == length(B)whenBis 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 storesunique(A + I; dims = 1), not the matrix passed in. The identity puts each asset in its own row, anduniquedrops 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 ofA * z <= B, wherezis the held binary. Each entry is the largest number of assets that the portfolio can hold out of one row ofA. A scalar applies to every row. A vector states one bound per row, so its length must match the row count of the storedA, 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) -> IntegerPhylogenyKeywords correspond to the struct's fields.
Validation
LinearAlgebra.issymmetric(A)andall(iszero, LinearAlgebra.diag(A)). A breach raises anArgumentError.assert_nonempty_nonneg_finite_valchecksB.AbstractVector:size(unique(A + LinearAlgebra.I; dims = 1), 1) == length(B). A breach raises aDimensionMismatch.
Examples
julia> IntegerPhylogeny(; A = [0.0 1.0; 1.0 0.0], B = 2)IntegerPhylogeny A ┼ 1×2 Matrix{Float64} B ┴ Int64: 2Related
set_iplg_constraints!mip_constraintsIntegerPhylogenyEstimatorAbstractPhylogenyConstraintResultphylogeny_constraints
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.
PortfolioOptimisers.CentralityConstraint — Type
struct CentralityConstraint{__T_A, __T_B, __T_comp, __T_x_src} <: AbstractCentralityConstraintBounds 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
Acomputes. - $\bar{c}$: Threshold, the
Bfield. - $\square$: Comparison operator, the
compfield. - $\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. AVectorToScalarMeasurederives the threshold from the centrality vector thatAgives, so the threshold moves with the graph. The measure reads that vector, never the row aftercompflips its sign, soMinValue()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,nothingor anAbstractReturnsSource.nothingandDataSourceread the asset returnsrd.X, andnothingreads theXof the Prior Result when the call gives no returns data.ExcessSourcereads the returns in excess of the benchmark,rd.X - rd.B, the Excess Frame.PriorSourcereads theXof the Prior Result, in the frame that the prior fitted in. Under a factor prior thatXis a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give,DataSource()orExcessSource()with no returns data, orPriorSource()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 keepsnothing, and the outer estimator states the source.
Constructors
CentralityConstraint(; A::CentralityEstimator = CentralityEstimator(), B::Num_VecToScaM = MinValue(), comp::ComparisonOperator = <=, x_src::Option{<:AbstractReturnsSource} = nothing) -> CentralityConstraintKeywords correspond to the struct's fields.
Validation
Ais bounded byCentralityEstimator,BbyNum_VecToScaM, andcompbyComparisonOperator. A value outside a bound raises aTypeErrorfrom the keyword constructor.x_src in ALL_RETURNS_SOURCES, seeassert_returns_source. Otherwise the constructor raises anArgumentError.returns_source(A) === nothing, seeassert_inner_reader. The centrality estimator reads the matrix that this constraint selects, so it states no source of its own. Otherwise the constructor raises anArgumentError.- The constructor checks no value of
B. A non-finiteBreaches the generated row unchanged.centrality_constraintsstores aNaNor anInfright-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 ┴ nothingRelated
References
- [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Section 4, Equation 8.
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, ornothing.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 forphylogeny_matrix. Only an estimator reads them.
Returns
res: The phylogeny constraint result, or a vector of them forplcs.SemiDefinitePhylogeny: For a semidefinite estimator or result.IntegerPhylogeny: For an integer estimator or result.nothing: Whenplcisnothing.
Related
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
- Pick the asset returns matrix
Xfrom the source that the reader states,returns_source, withreturns_matrix_picker. Refuse a gap inXthat a plain graph reader cannot read, withassert_graph_readable. - Call the asset-returns method of
phylogeny_constraintswithX, passing both results on asprandrdanddims = 1last, and return the constraint result it produces.
Arguments
plc: Phylogeny constraint estimator.pr: Prior result or returns result. Both carry the asset returns matrixX, so either can supply it.rd: The returns result to use. Read forXunder the source of the reader, and passed on to the estimator tree.iv: Optional implied volatility matrix,observations × assets, read by anImpliedVolatilityestimator in the tree. The estimator receives the last rows ofiv, one for each row of the pickedX, throughimplied_volatility_picker, so a prior that keeps fewer rows than the returns data still pairs each row of itsXwith the implied volatility of the same observation.kwargs...: Additional keyword arguments passed to the estimator. An unknown keyword raises aMethodError, seegraph_verb_keywords.
Returns
- Phylogeny constraint result.
Related
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
- Check that
ccsis not empty when it is a vector. - Check
dimswithassert_dims, and read the asset countNfrom the axis ofXthatdimsdoes not name.Nis the width of every row the loop builds. - For each
ccinccs, compute the centrality vectorAwith the estimator incc.A, alongdims. - Report
ccthroughstrict_diagnosticwithzero_centrality_msgand skip it whenAis empty or all zero. - Read the sign
dand the inequality flagflag_ineqofcc.compfromcomparison_sign_ineq_flag. - Derive the right-hand side
Bfromcc.Bagainst the unscaledAwithvec_to_real_measure, and scale it byd. - Scale
Abyd, which negates a>=row so that every inequality is stored in theA w <= Bsense. - Append
AandBto the inequality pair or to the equality pair, asflag_ineqselects. - Reshape each flat accumulator into
Ncolumns, so that each surviving constraint gives one row. Build theLinearConstraintfrom the halves that hold a row. Returnnothingwhen 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: OneCentralityConstraintor a vector of them.X: The data matrix.dims: Dimension along which the computation runs.strict: Iftrue, a constraint whose centrality vector is empty or all zero raises anIsZeroError. Iffalse, it gives a warning. The function drops the constraint in both cases.kwargs...: More keyword arguments forcentrality_vector.
Validation
!isempty(ccs)whenccsis a vector. A breach raises anIsEmptyError.dims in (1, 2). The check is made withassert_dims, which raises theDomainError.- A centrality vector that is empty or all zero raises an
IsZeroErrorwhenstrictistrue, and gives a warning otherwise. The function drops the constraint in both cases. - The function checks no value of
cc.B. ANaNor anInfthreshold reaches the returned right-hand side unchanged.
Returns
lc::Option{<:LinearConstraint}: The inequality rows and the equality rows, ornothingwhen the function drops every constraint.
Related
CentralityConstraintLinearConstraintPartialLinearConstraintcentrality_vectorcomparison_sign_ineq_flag: the one sign and flag table, shared withget_linear_constraints.assert_dimsstrict_diagnosticzero_centrality_msg
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: ALinearConstraintornothing.args...: Any positional arguments. The method ignores them.kwargs...: Any keyword arguments. The method ignores them.
Returns
lc::Option{<:LinearConstraint}: The input, unchanged.
Related
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
- 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
nothingwithmerge_linear_constraints. Returnnothingwhen every result isnothing. - Otherwise pick the asset returns matrix
Xfrom the source that the constraints state,returns_source, withreturns_matrix_picker. Refuse a gap inXthat a plain graph reader cannot read, withassert_graph_readable. - Call the asset-returns method of
centrality_constraintswithX, passing both results on asprandrdanddims = 1last, 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 matrixX, so either can supply it.rd: The returns result to use. Read forXunder the source of the reader, and passed on to the estimator tree.iv: Optional implied volatility matrix,observations × assets, read by anImpliedVolatilityestimator in the tree. The estimator receives the last rows ofiv, one for each row of the pickedX, throughimplied_volatility_picker, so a prior that keeps fewer rows than the returns data still pairs each row of itsXwith the implied volatility of the same observation.kwargs...: Additional keyword arguments passed to the estimator.strictis read by the asset-returns variant, which reports a dropped zero centrality vector through it. An unknown keyword raises aMethodError, seegraph_verb_keywords.
Returns
- Centrality constraint result.
Related
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
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(cc::CentralityConstraint, i) -> CentralityConstraintReturn 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
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).