Network Estimator

PortfolioOptimisers.NetworkEstimator — Type
struct NetworkEstimator{__T_ce, __T_de, __T_alg<:Union{AbstractNonNegativeSimilarityMatrixAlgorithm, AbstractTreeType}, __T_sep, __T_x_src} <: AbstractNetworkEstimator

Builds an asset network from a covariance estimate, and says which pairs of assets it relates.

ce and de give the distance matrix of the assets. alg selects a minimum spanning tree or a PMFG over that matrix. sep measures how far apart two assets are in the graph, and it states the budget beyond which two assets count as unrelated.

Fields

  • ce: Covariance estimator.
  • de: Distance matrix estimator.
  • alg: Tree or similarity matrix algorithm. A similarity algorithm selects the network through a PMFG, so it must come from the non-negative family. The type bound refuses AngularSimilarity.
  • sep: Separation algorithm. It states how to measure how far apart two assets are in the network, and the budget beyond which two assets count as unrelated.
  • x_src: The source of the returns that the clustering, phylogeny or centrality estimator reads, nothing or an AbstractReturnsSource. nothing and DataSource read the asset returns rd.X, and nothing reads the X of the Prior Result when the call gives no returns data. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame. PriorSource reads the X of the Prior Result, in the frame that the prior fitted in. Under a factor prior that X is a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give, DataSource() or ExcessSource() with no returns data, or PriorSource() on returns data with no Prior Result, gives a warning, and the estimator reads the matrix that the call gives. A call on a bare matrix reads that matrix under every source. An estimator inside another graph estimator keeps nothing, and the outer estimator states the source.

Constructors

NetworkEstimator(;    ce::StatsBase.CovarianceEstimator = PortfolioOptimisersCovariance(),    de::AbstractDistanceEstimator = Distance(; alg = CanonicalDistance()),    alg::Tree_SimMat = KruskalTree(),    sep::AbstractSeparationAlgorithm = HopCount(),    x_src::Option{<:AbstractReturnsSource} = nothing) -> NetworkEstimator

Keywords correspond to the struct's fields.

Validation

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • ce: Recursively updated through factory.
  • de: Recursively updated through factory.

The separation lives here, not on the consumer

sep states which pairs the network relates. Every consumer that reads a closure of this graph needs that answer. These consumers are phylogeny_matrix and the phylogeny constraint families, both clusterise methods, and Proximity. sep is therefore a field of the estimator that builds the graph, and not of one consumer. The constraint path receives only this estimator, so it cannot read a rule that a different consumer holds.

A consumer that reads the structure, and not a closure of it, does not read sep. The weighted routes of centrality_graph take the weighted graph. A closure is a sum of matrix powers, and a power of a weighted matrix sums products of distances. For example, a HopCount of n = 2 changes a DegreeCentrality and does not change a ClosenessCentrality. At the default HopCount(; n = 1) the two routes agree, because the closure of a graph at one hop is the graph.

The budget is a field of the member, as in HopCount(; n = 2), and not a separate field of this estimator. A budget apart from the rule that measures it has no unit. Such a field has no use for a member that does not count hops. PathLength is such a member, and it states its budget in the units of the distance estimator.

Every consumer accepts a HopCount. A consumer that sums matrix powers does not accept a PathLength. Both clusterise methods add up $\sum_{i=0}^{n}(\mathbf{D}^i - \mathbf{A}^i)$, so they read sep.n as a count of powers. They refuse a PathLength at dispatch, because a radius has no equivalent of a matrix power. phylogeny_matrix and Proximity take either member, each through a method of its own. A hop ball is a clamped sum of powers, and a radius ball is a threshold on separation_matrix.

Examples

julia> NetworkEstimator()NetworkEstimator     ce ┼ PortfolioOptimisersCovariance        │   ce ┼ Covariance        │      │    me ┼ SimpleExpectedReturns        │      │       │   w ┴ nothing        │      │    ce ┼ GeneralCovariance        │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)        │      │       │    w ┴ nothing        │      │   alg ┼ FullMoment()        │      │     w ┴ nothing        │   mp ┼ MatrixProcessing        │      │     pdm ┼ Posdef        │      │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton        │      │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │      │      dn ┼ nothing        │      │      dt ┼ nothing        │      │     alg ┼ nothing        │      │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)     de ┼ Distance        │   power ┼ nothing        │     alg ┴ CanonicalDistance()    alg ┼ KruskalTree        │     args ┼ Tuple{}: ()        │   kwargs ┴ @NamedTuple{}: NamedTuple()    sep ┼ HopCount        │   n ┼ CountOf        │     │   val ┴ Int64: 1  x_src ┴ nothing

Related

References

  • [135] R. N. Mantegna. Hierarchical structure in financial markets. The European Physical Journal B 11, 193–197 (1999). Page 194, for the minimum spanning tree of a tree alg.
  • [129] G. P. Massara, T. Di Matteo and T. Aste. Network Filtering for Big Data: Triangulated Maximally Filtered Graph. Journal of Complex Networks 5, 161–178 (2016). Section III.A, Algorithm 1, for the graph of a similarity alg.
  • [117] D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023). Sections 3.1 and 3.2, for the two networks of a portfolio.
source
PortfolioOptimisers.NetworkClustersEstimator — Type
struct NetworkClustersEstimator{__T_nte, __T_alg, __T_onc, __T_x_src} <: AbstractClustersEstimator

Clusters assets by the pseudo-distances that a network's structure induces.

nte builds the network. clusterise turns the network into a matrix of pseudo-distances, alg clusters that matrix, and onc selects the number of clusters.

Fields

  • nte: Network estimator.
  • alg: Clustering algorithm.
  • onc: Estimator of the optimal number of clusters.
  • x_src: The source of the returns that the clustering, phylogeny or centrality estimator reads, nothing or an AbstractReturnsSource. nothing and DataSource read the asset returns rd.X, and nothing reads the X of the Prior Result when the call gives no returns data. ExcessSource reads the returns in excess of the benchmark, rd.X - rd.B, the Excess Frame. PriorSource reads the X of the Prior Result, in the frame that the prior fitted in. Under a factor prior that X is a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give, DataSource() or ExcessSource() with no returns data, or PriorSource() on returns data with no Prior Result, gives a warning, and the estimator reads the matrix that the call gives. A call on a bare matrix reads that matrix under every source. An estimator inside another graph estimator keeps nothing, and the outer estimator states the source.

Constructors

NetworkClustersEstimator(;    nte::AbstractNetworkEstimator = NetworkEstimator(),    alg::AbstractClustersAlgorithm = HClustAlgorithm(),    onc::AbstractOptimalNumberClustersEstimator = OptimalNumberClusters(),    x_src::Option{<:AbstractReturnsSource} = nothing) -> NetworkClustersEstimator

Keywords correspond to the struct's fields.

Validation

  • x_src in ALL_RETURNS_SOURCES, see assert_returns_source. The constructor throws an ArgumentError otherwise.
  • returns_source(nte) === nothing. The network estimator reads the matrix that this estimator selects, so it states no source of its own, see assert_inner_reader. The constructor throws an ArgumentError otherwise.

Propagated parameters

factory passes its arguments on to these @fprop fields:

  • nte: Recursively updated through factory.

Both clusterise methods index their sums of powers by nte.sep.n. The separation budget comes from the network estimator, and this estimator does not state it again. For the same reason, nte.sep must be a HopCount. The constructor accepts a PathLength, but no clusterise method takes it.

Examples

julia> NetworkClustersEstimator()NetworkClustersEstimator    nte ┼ NetworkEstimator        │      ce ┼ PortfolioOptimisersCovariance        │         │   ce ┼ Covariance        │         │      │    me ┼ SimpleExpectedReturns        │         │      │       │   w ┴ nothing        │         │      │    ce ┼ GeneralCovariance        │         │      │       │   ce ┼ StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)        │         │      │       │    w ┴ nothing        │         │      │   alg ┼ FullMoment()        │         │      │     w ┴ nothing        │         │   mp ┼ MatrixProcessing        │         │      │     pdm ┼ Posdef        │         │      │         │      alg ┼ UnionAll: NearestCorrelationMatrix.Newton        │         │      │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │         │      │      dn ┼ nothing        │         │      │      dt ┼ nothing        │         │      │     alg ┼ nothing        │         │      │   order ┴ NTuple{4, Symbol}: (:pdm, :dn, :dt, :alg)        │      de ┼ Distance        │         │   power ┼ nothing        │         │     alg ┴ CanonicalDistance()        │     alg ┼ KruskalTree        │         │     args ┼ Tuple{}: ()        │         │   kwargs ┴ @NamedTuple{}: NamedTuple()        │     sep ┼ HopCount        │         │   n ┼ CountOf        │         │     │   val ┴ Int64: 1        │   x_src ┴ nothing    alg ┼ HClustAlgorithm        │   linkage ┴ Symbol: :ward    onc ┼ OptimalNumberClusters        │   max_k ┼ nothing        │     alg ┼ SecondOrderDifference        │         │   alg ┼ StandardisedValue        │         │       │   mv ┼ MeanValue        │         │       │      │   w ┴ nothing        │         │       │   sv ┼ StdValue        │         │       │      │           w ┼ nothing        │         │       │      │   corrected ┴ Bool: true  x_src ┴ nothing

Related

source

References

[117]
D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023).
[129]
[135]
R. N. Mantegna. Hierarchical structure in financial markets. The European Physical Journal B 11, 193–197 (1999).