GitHub

Non hierarchical clustering

PortfolioOptimisers.KMeansAlgorithm — Type
struct KMeansAlgorithm{__T_rng, __T_seed, __T_kwargs} <: AbstractNonHierarchicalClusteringAlgorithm

Partitions assets into k groups by Lloyd's algorithm, with no dendrogram.

Runs Clustering.kmeans over the columns of the distance matrix, so each asset is the point given by its distances to every asset, and two assets cluster together when they sit at similar distances from the rest of the universe. The result is a flat partition: there is no tree, so nothing downstream can cut it at a different k.

rng and seed are here because the algorithm is randomised. resolve_rng combines them at the point of use, so a stated seed makes a run reproducible without the caller building a generator.

kwargs reaches Clustering.kmeans unchanged

Whatever kwargs holds is splatted into the call. The constructor checks only that a weights entry is a non-empty AbstractVector; it does not check the length, and Clustering.kmeans wants one weight per point, which here means one per asset.

factory never writes observation weights into kwargs. An observation weight has no meaning here, because every step after ce reads an assets x assets matrix.

Fields

  • rng: Random number generator.
  • seed: Seed for the random number generator.

Constructors

KMeansAlgorithm(;    rng::Random.AbstractRNG = Random.default_rng(),    seed::Option{<:Integer} = nothing,    kwargs::NamedTuple = (;)) -> KMeansAlgorithm

Keywords correspond to the struct's fields.

Validation

  • If kwargs contains weights, it must be a non-empty AbstractVector. Its length is not checked; Clustering.kmeans raises the DimensionMismatch at the point of use.

Examples

julia> KMeansAlgorithm()KMeansAlgorithm     rng ┼ Random.TaskLocalRNG: Random.TaskLocalRNG()    seed ┼ nothing  kwargs ┴ @NamedTuple{}: NamedTuple()

Related

References

  • [51] S. P. Lloyd. Least squares quantization in PCM. IEEE Transactions on Information Theory 28, 129–137 (1982).
source
PortfolioOptimisers.clusterise — Method
clusterise(cle::ClustersEstimator{<:Any, <:Any,
                                  <:AbstractNonHierarchicalClusteringAlgorithm, <:Any},
           X::MatNum; dims::Int = 1, kwargs...)

Cluster assets with a non-hierarchical algorithm and return a Clusters result.

Estimates the similarity and distance matrices from X, then hands D to optimal_number_clusters, which chooses k and returns the clustering for it. P is left as nothing, because the clustering ran on D itself.

Algorithm

  1. Estimate the similarity matrix S and the distance matrix D from X with cor_and_dist, under cle.de and cle.ce.
  2. Hand D and the algorithm cle.alg to optimal_number_clusters(cle.onc, cle.alg, D), giving both the partition res and its count k. No further clustering runs, because the partition is the one that won.
  3. Return Clusters(; res = res, S = S, D = D, k = k). P is left as nothing, because the clustering ran on D itself.

Arguments

  • cle: Clustering estimator configured with a non-hierarchical algorithm.
  • X: Data matrix (observations × assets).
  • dims: Dimension along which to perform the computation.
  • kwargs...: Additional keyword arguments passed to the underlying estimators.

Returns

  • res::Clusters: Clustering result containing the result, similarity and distance matrices, and number of clusters.

Related

source

References

[51]
S. P. Lloyd. Least squares quantization in PCM. IEEE Transactions on Information Theory 28, 129–137 (1982).