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 plr object.

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

source
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

  1. Build the structure g that nte.sep measures over, with separation_graph. The method builds one structure for each call, and the two steps below share it.
  2. Resolve nte.sep against g with resolve_separation. A budget that is a value passes through unchanged and builds nothing.
  3. Select the related pairs with _phylogeny_matrix, through the branch that the resolved separation names.
  4. Return the selection in a PhylogenyResult.

Arguments

  • nte: Network estimator.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • dims: Dimension along which the computation runs.
  • kwargs...: Additional keyword arguments.

Returns

  • plr::PhylogenyResult{<:Matrix{Int}}: Phylogeny matrix of the assets. An entry is 1 for a related pair and 0 otherwise, and the diagonal is 0.

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

  1. Partition the assets into the Clusters result res with clusterise.
  2. Read the cluster of every asset with assignments.
  3. Build the assets × res.k membership matrix P, whose entry is one when the asset belongs to the cluster of its column.
  4. Multiply P by 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.
  5. Return the selection in a PhylogenyResult.

Arguments

  • cle: Clustering estimator or result.
  • X: Data matrix observations × assets if the dims keyword does not exist or dims = 1, assets × observations when dims = 2.
  • branchorder: Order method for the dendrogram branches, :optimal by default. branch_ordered_hclust and DBHTs state 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 is 1 for two assets in the same cluster and 0 otherwise, and the diagonal is 0.

Related

source
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

  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_matrix with X, passing both results on as pr and rd and dims = 1 last, 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 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

  • plr::PhylogenyResult: Result object containing the phylogeny matrix.

Related

source

References

[12]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).