Centrality Queries
PortfolioOptimisers.centrality_vector — Function
centrality_vector(plr::PhylogenyResult{<:VecNum}, args...; kwargs...)Return a precomputed centrality vector unchanged.
A PhylogenyResult that holds a vector already holds the answer, so this method builds nothing and returns plr. It does not read a centrality algorithm, so an algorithm in args does not change the scores. The vector keeps the length of the set of assets that made it.
Arguments
plr::PhylogenyResult{<:VecNum}: Precomputed centrality vector.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.2, 0.5, 0.3]);julia> centrality_vector(plr)PhylogenyResult X ┴ Vector{Float64}: [0.2, 0.5, 0.3]Related
centrality_vector(
plr::PhylogenyResult{<:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
ct::AbstractCentralityAlgorithm,
args...;
kwargs...
) -> PhylogenyResult{<:AbstractArray{var"#s166", N}} where {var"#s166"<:Union{Number, AbstractJuMPScalar}, N}
Compute the centrality vector of a precomputed phylogeny matrix with the algorithm ct.
The graph is always unweighted, whatever polarity ct declares. Graphs.SimpleGraph reads every nonzero entry of plr.X as an edge, and removes its value. A precomputed PhylogenyResult is one of the sources with no weights that the warning of centrality_vector lists. To get the weighted answer, pass the estimator and not its result.
Algorithm
- Convert
plr.X, the precomputed phylogeny matrix, to a plainGraphs.SimpleGraphG. - Score the vertices of
Gwithcalc_centrality. - Return the scores in a
PhylogenyResult.
Arguments
plr: Precomputed phylogeny matrix.ct: Centrality algorithm.args...: Positional arguments. The method does not read them.kwargs...: Keyword arguments. The method does not read them.
Returns
plr::PhylogenyResult{<:VecNum}: One centrality score for each asset.
Related
centrality_vector(pl::NwE_ClE_Cl, ct::AbstractCentralityAlgorithm,
X::MatNum; dims::Int = 1, kwargs...)Compute the centrality vector of the structure that pl builds, with the algorithm ct.
centrality_graph builds the graph, with the weights of the polarity that centrality_polarity returns for ct where the source can give them. calc_centrality then scores each asset.
Five cases run on the unweighted graph, and none of them raises an error. A caller names a configured algorithm and never asks for weights. A source and an algorithm that cannot use weights have no request to refuse. TopologyOnly asks for no weights, and every source can give that, so it is not one of the five cases.
- A clustering estimator, a precomputed
Clusters, or a precomputedPhylogenyResultas the source. Neither a partition nor a precomputed phylogeny matrix has edge weights, and neither borrows weights. DegreeCentrality.Graphs.jldoes not read the weights.Pagerank.Graphs.jldoes not read the weights.KatzCentrality.Graphs.katz_centralityreadsadjacency_matrix(g, Bool), and raises anInexactErroron a weighted graph.EigenvectorCentralityon a tree branch. The branch carries no similarity for it to read.
The weighted routes do not read the sep field of the estimator. They read the structure, and not the separation closure that phylogeny_matrix builds. At the default HopCount(; n = 1) the two agree, because the closure of a graph at one hop is the graph.
Algorithm
- Build the graph with
centrality_graph, with the weights of the polarity thatctdeclares wherever the source can give them. - Score the vertices of that graph with
calc_centrality. - Return the scores in a
PhylogenyResult.
Arguments
pl: Network estimator, clustering estimator, or clustering result.ct: Centrality algorithm.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
cv::PhylogenyResult{<:VecNum}: One centrality score for each asset.
Related
centrality_vector(cte::CentralityEstimator, X::MatNum; dims::Int = 1, kwargs...)Compute the centrality vector that a centrality estimator states.
The method calls centrality_vector with the pl and the ct of cte.
Arguments
cte: Centrality 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
cv::PhylogenyResult{<:VecNum}: One centrality score for each asset.
Related
centrality_vector(cte::CentralityEstimator, pr::AbstractPriorResult; kwargs...)Compute the centrality vector for a centrality estimator and prior result.
centrality_vector applies the centrality algorithm in the estimator to the network constructed from the asset returns in the prior result, returning centrality scores for each asset.
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
centrality_vectorwithX, passing both results on asprandrdanddims = 1last, and return the centrality result it produces.
Arguments
cte: Centrality 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 asset-returns method. An unknown keyword raises aMethodError, seegraph_verb_keywords.
Returns
plr::PhylogenyResult: Result object containing the centrality vector.
Related
centrality_vector(pl::NwE_ClE_Cl, ct::AbstractCentralityAlgorithm,
pr::AbstractPriorResult; kwargs...)Compute the centrality vector for a network or clustering estimator and centrality algorithm.
centrality_vector constructs the phylogeny matrix from the asset returns in the prior result, builds a graph, and computes node centrality scores using the specified centrality algorithm.
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
centrality_vectorwithX, passing both results on asprandrdanddims = 1last, and return the centrality result it produces.
Arguments
pl: Network estimator, clusters estimator, or clustering result.ct: Centrality algorithm.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 asset-returns method. An unknown keyword raises aMethodError, seegraph_verb_keywords.
Returns
plr::PhylogenyResult: Result object containing the centrality vector.
Related
PortfolioOptimisers.average_centrality — Function
average_centrality(pl::NwE_Pl_ClE_Cl,
ct::AbstractCentralityAlgorithm, w::VecNum, X::MatNum;
dims::Int = 1, kwargs...)Compute the average centrality of a portfolio, weighted by w.
The function computes the centrality vector, and returns its dot product with w. It is the average centrality measure of Equation 13.6 of [12],
\[\begin{align} \mathrm{CM}(\boldsymbol{x}) &= \boldsymbol{C}_n^{\intercal} \boldsymbol{x}\,, \end{align}\]
Where:
- $\boldsymbol{C}_n$: Centrality score vector from
centrality_vector. - $\boldsymbol{x}$: Portfolio weight vector.
The function does not normalise and takes no absolute value, so the average has the units of the score. The score of DegreeCentrality is already divided by $n - 1$.
Algorithm
- Score the assets with
centrality_vector. - Return the dot product of the scores and
w.
Arguments
pl: Network estimator, phylogeny result, clustering estimator, or clustering result.ct: Centrality algorithm.w: Portfolio weight vector.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
ac::Number: Average centrality.
Related
References
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 13.1.5.1, Equation 13.6.
average_centrality(cte::CentralityEstimator, w::VecNum, X::MatNum;
dims::Int = 1, kwargs...)Compute the average centrality of a portfolio with the configuration of a centrality estimator.
The method calls average_centrality with the pl and the ct of cte.
Arguments
cte: Centrality estimator.w: Portfolio weight vector.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
ac::Number: Average centrality.
Related
average_centrality(pl::NwE_Pl_ClE_Cl,
ct::AbstractCentralityAlgorithm, w::VecNum,
pr::AbstractPriorResult; kwargs...)Compute the weighted average centrality for a network or phylogeny result.
average_centrality computes the centrality vector using the specified network or phylogeny estimator and centrality algorithm, then returns the weighted average using the provided portfolio weights.
Algorithm
- Compute the centrality result with the
Pr_RRmethod ofcentrality_vector, forwardingrdunchanged. That method picks the matrix from the source thatplstates, so this method never reads a result itself. - Return the dot product of that result's
X, the centrality vector, with the weightsw.
Arguments
pl: Network estimator or phylogeny result.ct: Centrality algorithm.w: Portfolio weights vector.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.kwargs...: Additional keyword arguments passed to the asset-returns method. An unknown keyword raises aMethodError, seegraph_verb_keywords.
Returns
ac::Number: Weighted average centrality.
Related
average_centrality(cte::CentralityEstimator, w::VecNum, pr::AbstractPriorResult;
kwargs...)Compute the weighted average centrality for a centrality estimator.
average_centrality applies the centrality algorithm in the estimator to the network constructed from the asset returns in the prior result, then returns the weighted average using the provided portfolio weights.
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
average_centralitywithX, passing both results on asprandrdanddims = 1last, and return the weighted average it produces.
The estimator method picks between the results itself, where the network-and-algorithm method above delegates that to centrality_vector. The two reach the same selection: cte carries pl and ct in its own fields, so the asset-returns method it calls is the one the other method's step 1 would have reached.
Arguments
cte: Centrality estimator.w: Portfolio weights vector.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 asset-returns method. An unknown keyword raises aMethodError, seegraph_verb_keywords.
Returns
ac::Number: Weighted average centrality.
Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).