Phylogeny Matrix
PortfolioOptimisers.phylogeny_matrix — Function
phylogeny_matrix(plr::PhylogenyResult{<:MatNum}, args...; kwargs...)Return a precomputed phylogeny matrix unchanged.
A PhylogenyResult that holds a matrix already holds the answer, so this method builds nothing and returns plr. The constructor of plr checked the matrix, and this method does not check it again. The method reads no data, so the matrix keeps the size of the set of assets that made it.
Arguments
plr::PhylogenyResult{<:MatNum}: Precomputed phylogeny matrix.args...: Positional arguments. The method does not read them.kwargs...: Keyword arguments. The method does not read them.
Returns
- The input
plrobject.
Examples
julia> plr = PhylogenyResult(; X = [0 1 0; 1 0 1; 0 1 0]);julia> phylogeny_matrix(plr)PhylogenyResult X ┴ 3×3 Matrix{Int64}Related
phylogeny_matrix(nte::AbstractNetworkEstimator, X::MatNum; dims::Int = 1, kwargs...)Compute the phylogeny matrix of the network that nte builds.
The method builds the network from X. It returns the binary matrix of the pairs that nte.sep counts as related, with a zero diagonal. The separation selects the neighbourhood, through _phylogeny_matrix. HopCount gives the hop ball, the clamped sum of powers sum(A^i for i in 0:n). PathLength gives the radius ball, the matrix of separation_matrix with a threshold at separation_budget.
The hop ball is the range connection matrix
The hop branch computes the range connection matrix of the walks of length at most n, which is Equations 13.1 and 13.2 of [12]. With the binary adjacency matrix $\mathbf{A}$ and the identity $\mathbf{I}_n$,
\[\begin{align} \mathbf{B}_{k} &= \mathbf{1}_{x \geq 1}\left(\mathbf{A}^{k} + \mathbf{I}_n\right) - \mathbf{I}_n\,, \\ \mathbf{B}_{1,\,l} &= \mathbf{1}_{x \geq 1}\left(\sum_{k=1}^{l} \mathbf{B}_{k}\right)\,, \end{align}\]
Where:
- $\mathbf{1}_{x \geq 1}(\cdot)$: Element-wise indicator of the entries that are at least one.
- $\mathbf{B}_{k}$: Pairs joined by at least one walk of length exactly $k$.
- $\mathbf{B}_{1,\,l}$: Pairs joined by at least one walk of length at most $l$.
The code adds up sum(A^i for i in 0:n), clamps it to 0 or 1, and subtracts the identity. This is the same selection, written one time for all the shells.
The result is Int under either separation
The two separations select different pairs, and give values of the same kind. The matrix of the PhylogenyResult is Int here, as it is everywhere else, because no consumer needs a graded value. The values of the matrix do not change SemiDefinitePhylogeny, because A ⊙ W == 0 is the same constraint at any magnitude. IntegerPhylogeny counts an integer cardinality. centrality_vector removes the values before a centrality algorithm runs. Proximity gives the graded value of a separation.
What the radius ball gives, measured
It changes the ranking little, and on the PMFG not at all. Compare a hop shell with the first pairs of the order of path lengths, at the same cardinality. On a PMFG of 20 assets, the two sets are the same at every shell. 0 pairs are different out of 54, 121, 165 and 186. On the minimum spanning tree, they are the same at the shells of 19 and 48. They are different by 1, 1, 3 and 2 pairs at the shells of 84, 115, 144 and 170.
The distance selects both structures, so a path length refines a hop count and does not compete with it. The radius ball is not a different kind of neighbourhood.
It gives cardinalities between the shells. Over the same PMFG, the hop count relates 54, then 121, then 165 of the 190 pairs. A caller who wants about 100 pairs cannot ask for it. A sweep of dmax over the same graph reaches 36, 55, 100, 122, 151 and 179. That is the only gain. It is real for SemiDefinitePhylogeny and IntegerPhylogeny, because their constraint strength is that cardinality.
The default budget of PathLength relates every reachable pair
PathLength() sets dmax = nothing, and separation_budget resolves it to the observed diameter. No reachable pair is outside the budget, and every entry off the diagonal is one. The measured count is 190 of 190 pairs on both branches. This is the correct meaning of a budget that the caller does not state, but it is the opposite end of the scale from the default n = 1 of HopCount. A caller who replaces one separation by the other, and changes nothing else, gets the largest ball in place of the smallest. State a numeric dmax to select fewer pairs.
Algorithm
- Build the structure
gthatnte.sepmeasures over, withseparation_graph. The method builds one structure for each call, and the two steps below share it. - Resolve
nte.sepagainstgwithresolve_separation. A budget that is a value passes through unchanged and builds nothing. - Select the related pairs with
_phylogeny_matrix, through the branch that the resolved separation names. - Return the selection in a
PhylogenyResult.
Arguments
nte: Network estimator.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.dims: Dimension along which the computation runs.kwargs...: Additional keyword arguments.
Returns
plr::PhylogenyResult{<:Matrix{Int}}: Phylogeny matrix of the assets. An entry is1for a related pair and0otherwise, and the diagonal is0.
Related
References
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 13.1.2, Equations 13.1-13.2.
phylogeny_matrix(cle::ClE_Cl,
X::MatNum; branchorder::Symbol = :optimal, dims::Int = 1,
kwargs...)Compute the phylogeny matrix of a clustering estimator or result.
The method clusters the data into the number of clusters that the estimator selects. It returns the binary phylogeny matrix whose entry is 1 for two assets in the same cluster, with a zero diagonal.
Algorithm
- Partition the assets into the
Clustersresultreswithclusterise. - Read the cluster of every asset with
assignments. - Build the
assets × res.kmembership matrixP, whose entry is one when the asset belongs to the cluster of its column. - Multiply
Pby its transpose. The product is one for a pair in the same cluster, and zero otherwise. Subtract the identity to set the diagonal to zero. - Return the selection in a
PhylogenyResult.
Arguments
cle: Clustering estimator or result.X: Data matrixobservations × assetsif thedimskeyword does not exist ordims = 1,assets × observationswhendims = 2.branchorder: Order method for the dendrogram branches,:optimalby default.branch_ordered_hclustandDBHTsstate what each value does.dims: Dimension along which the computation runs.kwargs...: Additional keyword arguments.
Returns
plr::PhylogenyResult{<:Matrix{Int}}: Phylogeny matrix of the clusters. An entry is1for two assets in the same cluster and0otherwise, and the diagonal is0.
Related
phylogeny_matrix(pl::NwE_ClE_Cl, pr::AbstractPriorResult;
kwargs...)Compute the phylogeny matrix from asset returns in a prior result using a network or clustering estimator.
phylogeny_matrix applies the specified network or clustering estimator to the asset returns matrix contained in the prior result object, producing a phylogeny matrix for use in constraint generation, centrality analysis, or portfolio construction.
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_matrixwithX, passing both results on asprandrdanddims = 1last, and return the phylogeny result it produces.
Arguments
pl: Network estimator, clusters estimator, or clustering result.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
plr::PhylogenyResult: Result object containing the phylogeny matrix.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).