Separation: private API

PortfolioOptimisers.separation_graph — Function
separation_graph(sep::HopCount, G::Graphs.AbstractGraph)
separation_graph(sep::HopCount, nte::AbstractNetworkEstimator, X::MatNum;
                 dims::Int = 1, kwargs...)
separation_graph(sep::PathLength, nte::AbstractNetworkEstimator, X::MatNum;
                 dims::Int = 1, kwargs...)

Build the structure a separation measures over.

This function is one of the three kernels that a member of AbstractSeparationAlgorithm implements. separation_matrix and separation_budget are the other two. It is a kernel of its own, so that a consumer builds the structure one time for each call. separation_matrix and resolve_separation both take the graph. Without this kernel, a consumer that needs the separations and a resolved budget rule builds the same structure two times.

What each member measures over

  • HopCount: the structure of calc_adjacency, as a Graphs.SimpleGraph. The graph is binary, because a hop count does not read the weights and its consumers do. _phylogeny_matrix reads Graphs.adjacency_matrix of this graph for a sum of powers. With weights, A^i sums products of distances and does not count walks.
  • PathLength: the structure of calc_distance_weighted_graph. It has the same edge set, with distances as weights on either branch. A shortest path over the similarities of a PMFG takes the route through the weakest links.

Two entry points, and why only the hop count takes a graph

The methods that take nte build the structure from X. The method that takes G is for a caller that already holds the structure. Both clusterise methods build it from the quantity that selects the edges, through the entry point of calc_weighted_adjacency_graph that takes alg. Without this method, they compute the distance again to resolve a budget rule. Under VariationInfoDistance, that computation is 98% of the run time of clusterise.

PathLength has no method that takes a graph, and it cannot have one. A graph carries no polarity tag. G has distances as weights on the tree branch and similarities on the PMFG branch, and the argument does not show which. A shortest path over the similarities of a PMFG returns an answer and raises no error, see calc_distance_weighted_graph. The hop count is not affected, because it removes the weights.

Algorithm

  1. Build the structure from X, through the branch that sep selects.

  2. Convert the structure of a HopCount to a Graphs.SimpleGraph, which removes the weights. The method that takes G receives it and starts here.

Arguments

  • sep: Separation algorithm. The function dispatches on its type and does not read its budget. A member whose budget is a rule measures over the same structure as a member whose budget is a number. resolve_separation can therefore take this graph.
  • G: Network structure that the caller holds, in either polarity.
  • 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

  • g::Graphs.AbstractGraph: The structure sep measures over.

Related

source
PortfolioOptimisers.separation_quantile — Function
separation_quantile(
    sep::AbstractSeparationAlgorithm,
    d::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
    q::Number
) -> Number

Compute the quantile of the reachable off-diagonal entries of a separation matrix.

The population is the set of pairs that a budget can relate. The diagonal is zero, and an unreachable pair holds the sentinel of separation_matrix, so neither is a separation. phylogeny_matrix selects from the same population. q is then the fraction of the pairs that the budget relates.

The test for the sentinel belongs to the family

The function removes an unreachable pair from the population with is_reachable, and not with a test of its own. isfinite does not work. It is true for every Integer, so it admits the sentinel typemax(Int) of HopCount.

Algorithm

  1. Collect into v the off-diagonal entries of d that is_reachable admits. v is the population of the quantile.
  2. Throw an ArgumentError when v is empty.
  3. Return the q-quantile of v from Statistics.quantile.

Arguments

Validation

  • Throws an ArgumentError if no off-diagonal entry of d is reachable, because an empty population has no quantile.

Returns

  • dmax::Number: The q-quantile of the reachable off-diagonal separations.

Related

source