Network Estimator
PortfolioOptimisers.NetworkEstimator — Type
struct NetworkEstimator{__T_ce, __T_de, __T_alg<:Union{AbstractNonNegativeSimilarityMatrixAlgorithm, AbstractTreeType}, __T_sep, __T_x_src} <: AbstractNetworkEstimatorBuilds 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 refusesAngularSimilarity.
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,nothingor anAbstractReturnsSource.nothingandDataSourceread the asset returnsrd.X, andnothingreads theXof the Prior Result when the call gives no returns data.ExcessSourcereads the returns in excess of the benchmark,rd.X - rd.B, the Excess Frame.PriorSourcereads theXof the Prior Result, in the frame that the prior fitted in. Under a factor prior thatXis a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give,DataSource()orExcessSource()with no returns data, orPriorSource()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 keepsnothing, 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) -> NetworkEstimatorKeywords correspond to the struct's fields.
Validation
ceis not anAbstractVarianceEstimator. A variance estimator has nocovorcor, soassert_covariance_estimatorraises anArgumentErrorthat namesce. The tree route underVariationInfoDistancereads no correlation, and the constructor refuses a variance estimator on it too, becauseceholds a covariance estimator on every route.x_src in ALL_RETURNS_SOURCES, seeassert_returns_source. The constructor throws anArgumentErrorotherwise.
Propagated parameters
factory passes its arguments on to these @fprop fields:
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 ┴ nothingRelated
AbstractNetworkEstimatorAbstractTreeTypeAbstractNonNegativeSimilarityMatrixAlgorithmTree_SimMatfactory
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.
PortfolioOptimisers.NetworkClustersEstimator — Type
struct NetworkClustersEstimator{__T_nte, __T_alg, __T_onc, __T_x_src} <: AbstractClustersEstimatorClusters 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,nothingor anAbstractReturnsSource.nothingandDataSourceread the asset returnsrd.X, andnothingreads theXof the Prior Result when the call gives no returns data.ExcessSourcereads the returns in excess of the benchmark,rd.X - rd.B, the Excess Frame.PriorSourcereads theXof the Prior Result, in the frame that the prior fitted in. Under a factor prior thatXis a reconstruction of the rank of the factors, and a scenario window cuts its rows. A stated source that the call cannot give,DataSource()orExcessSource()with no returns data, orPriorSource()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 keepsnothing, and the outer estimator states the source.
Constructors
NetworkClustersEstimator(; nte::AbstractNetworkEstimator = NetworkEstimator(), alg::AbstractClustersAlgorithm = HClustAlgorithm(), onc::AbstractOptimalNumberClustersEstimator = OptimalNumberClusters(), x_src::Option{<:AbstractReturnsSource} = nothing) -> NetworkClustersEstimatorKeywords correspond to the struct's fields.
Validation
x_src in ALL_RETURNS_SOURCES, seeassert_returns_source. The constructor throws anArgumentErrorotherwise.returns_source(nte) === nothing. The network estimator reads the matrix that this estimator selects, so it states no source of its own, seeassert_inner_reader. The constructor throws anArgumentErrorotherwise.
Propagated parameters
factory passes its arguments on to these @fprop fields:
nte: Recursively updated throughfactory.
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 ┴ nothingRelated
References
- [117]
- D. Cajas. A Graph Theory Approach to Portfolio Optimization. Available at SSRN 4602019 (2023).
- [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), arXiv:https://academic.oup.com/comnet/article-pdf/5/2/161/13794756/cnw015.pdf.
- [135]
- R. N. Mantegna. Hierarchical structure in financial markets. The European Physical Journal B 11, 193–197 (1999).