GitHub

Centrality Queries

PortfolioOptimisers.centrality_vector — Function
centrality_vector(plr::PhylogenyResult{<:VecNum}, args...; kwargs...)

Fallback no-op for returning a validated centrality vector result as-is.

This method provides a generic interface for handling precomputed centrality vectors wrapped in a PhylogenyResult. It simply returns the input object unchanged, enabling consistent downstream workflows for centrality-based analysis and constraint generation.

Arguments

  • plr::PhylogenyResult{<:VecNum}: Centrality vector result object.
  • args...: Additional positional arguments (ignored).
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • The input plr object.

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

source
centrality_vector(
    plr::PhylogenyResult{<:AbstractMatrix{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}}},
    ct::AbstractCentralityAlgorithm,
    args...;
    kwargs...
) -> PhylogenyResult{<:AbstractArray{var"#s137", N}} where {var"#s137"<:(Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}), N}

Compute the centrality vector from a matrix PhylogenyResult using the specified centrality algorithm.

Builds a graph from the phylogeny matrix and applies ct to compute node centrality scores.

The graph is always unweighted, whatever polarity ct declares. A precomputed PhylogenyResult is a matrix of 0s and 1s, so it is one of the weightless sources listed on centrality_vector's warning, and the weights it does not carry cannot be recovered from it. Pass the estimator instead of its result to get the weighted answer.

Algorithm

  1. Read plr.X, the precomputed phylogeny matrix, into a plain Graphs.SimpleGraph, giving the structure G.
  2. Score the vertices of G with calc_centrality, giving the centrality vector.
  3. Wrap that vector in a PhylogenyResult.

Arguments

  • plr: Phylogeny matrix result object.
  • ct: Centrality algorithm.
  • args...: Additional positional arguments (ignored).
  • kwargs...: Additional keyword arguments (ignored).

Returns

  • plr::PhylogenyResult{<:VecNum}: Centrality scores for each asset.

Related

source
centrality_vector(pl::NwE_ClE_Cl, ct::AbstractCentralityAlgorithm,
                  X::MatNum; dims::Int = 1, kwargs...)

Compute the centrality vector for a network and centrality algorithm.

This function builds the graph with centrality_graph — weighted in the polarity centrality_polarity answers for ct, where the source can supply it — and computes node centrality scores with calc_centrality.

Warning

Five cases run on the unweighted graph, and none of them raises. A caller names a configured algorithm and never asks for weights, so an unweightable pairing has not been handed a request it cannot serve. TopologyOnly asks away from them, which every source can serve, so it adds no case to this list and is not one of the five.

  1. A clustering estimator, a precomputed Clusters, or a precomputed PhylogenyResult as the source. A partition has no edge weights, and does not borrow any.
  2. DegreeCentrality. Graphs.jl ignores weights.
  3. Pagerank. Graphs.jl ignores weights.
  4. KatzCentrality. Graphs.katz_centrality binarises through adjacency_matrix(g, Bool).
  5. EigenvectorCentrality on a tree branch. The branch carries no similarity for it to read.

On the weighted routes the estimator's sep field is inert: they read the structure itself rather than the separation closure 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

  1. Build the graph with centrality_graph, weighted in the polarity ct declares wherever the source can supply it.
  2. Score the vertices of that graph with calc_centrality.
  3. Wrap the scores in a PhylogenyResult.

Arguments

  • pl: Phylogeny estimator.
  • ct: Centrality algorithm.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments.

Returns

  • cv::VecNum: Centrality scores for each asset.

Related

source
centrality_vector(cte::CentralityEstimator, X::MatNum; dims::Int = 1, kwargs...)

Compute the centrality vector for a centrality estimator.

This function applies the centrality algorithm in the estimator to the network constructed from the data.

Arguments

  • cte: Centrality estimator.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments.

Returns

  • cv::VecNum: Centrality scores for each asset.

Related

source
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

  1. Pick the asset returns matrix X from the carrier that x_src names, with returns_matrix_picker.
  2. Call the asset-returns method of centrality_vector with X, passing both carriers on as pr and rd, and return the centrality result it produces.

Arguments

  • cte: Centrality estimator.
  • pr: Prior result or returns result. Both carry the asset returns matrix X and the feature matrix Z, so either can supply them.
  • rd: The returns result to use. Read for X only when x_src is :data, and passed on to the estimator tree.
  • x_src: Which returns matrix the clustering, phylogeny and centrality estimators read: :prior takes the prior result's X, :data takes the raw returns result's X. Ignored when no returns result is available, in which case the prior result's X is used.
  • kwargs...: Additional keyword arguments.

Returns

  • plr::PhylogenyResult: Result object containing the centrality vector.

Related

source
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

  1. Pick the asset returns matrix X from the carrier that x_src names, with returns_matrix_picker.
  2. Call the asset-returns method of centrality_vector with X, passing both carriers on as pr and rd, 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 matrix X and the feature matrix Z, so either can supply them.
  • rd: The returns result to use. Read for X only when x_src is :data, and passed on to the estimator tree.
  • x_src: Which returns matrix the clustering, phylogeny and centrality estimators read: :prior takes the prior result's X, :data takes the raw returns result's X. Ignored when no returns result is available, in which case the prior result's X is used.
  • kwargs...: Additional keyword arguments.

Returns

  • plr::PhylogenyResult: Result object containing the centrality vector.

Related

source
PortfolioOptimisers.average_centrality — Function
average_centrality(pl::NwE_Pl_ClE_Cl,
                   ct::AbstractCentralityAlgorithm, w::VecNum, X::MatNum;
                   dims::Int = 1, kwargs...)

Compute the weighted average centrality for a network and centrality algorithm.

This function computes the centrality vector and returns the weighted average using the provided weights. It is the average centrality measure of CentralityEstimator's Equation 13.6,

\[\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.

There is no normalisation and no absolute value, so the average carries the units of the score. A DegreeCentrality score is divided by $n - 1$ before it arrives here.

Algorithm

  1. Score the assets with centrality_vector, giving the score vector.
  2. Take the dot product of that vector and w.

Arguments

  • pl: NetworkEstimator estimator.
  • ct: Centrality algorithm.
  • w: Weights vector.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments.

Returns

  • ac::Number: Average centrality.

Related

source
average_centrality(cte::CentralityEstimator, w::VecNum, X::MatNum;
                   dims::Int = 1, kwargs...)

Compute the weighted average centrality for a centrality estimator.

This function applies the centrality algorithm in the estimator to the network and returns the weighted average using the provided weights.

Arguments

  • cte: Centrality estimator.
  • w: Weights vector.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments.

Returns

  • ac::Number: Average centrality.

Related

source
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

  1. Compute the centrality result with the Pr_RR method of centrality_vector, forwarding rd and x_src unchanged. The source selection is therefore made once, there, and this method never reads a carrier itself.
  2. Return the dot product of that result's X, the centrality vector, with the weights w.

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 matrix X and the feature matrix Z, so either can supply them.
  • rd: The returns result to use. Read for X only when x_src is :data, and passed on to the estimator tree.
  • x_src: Which returns matrix the clustering, phylogeny and centrality estimators read: :prior takes the prior result's X, :data takes the raw returns result's X. Ignored when no returns result is available, in which case the prior result's X is used.
  • kwargs...: Additional keyword arguments.

Returns

  • ac::Number: Weighted average centrality.

Related

source
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

  1. Pick the asset returns matrix X from the carrier that x_src names, with returns_matrix_picker.
  2. Call the asset-returns method of average_centrality with X, passing both carriers on as pr and rd, and return the weighted average it produces.

The estimator method picks the carriers 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 matrix X and the feature matrix Z, so either can supply them.
  • rd: The returns result to use. Read for X only when x_src is :data, and passed on to the estimator tree.
  • x_src: Which returns matrix the clustering, phylogeny and centrality estimators read: :prior takes the prior result's X, :data takes the raw returns result's X. Ignored when no returns result is available, in which case the prior result's X is used.
  • kwargs...: Additional keyword arguments.

Returns

  • ac::Number: Weighted average centrality.

Related

source