Clustering

PortfolioOptimisers.HierarchicalClustering — Type
struct HierarchicalClustering{T1, T2, T3, T4} <: AbstractClusteringResult
    clustering::T1
    S::T2
    D::T3
    k::T4
end

Result type for hierarchical clustering in PortfolioOptimisers.jl.

HierarchicalClustering stores the output of a hierarchical clustering algorithm, including the clustering object, similarity and distance matrices, and the number of clusters.

Fields

  • clustering: The hierarchical clustering object.
  • S: Similarity matrix used for clustering.
  • D: Distance matrix used for clustering.
  • k: Number of clusters.

Constructor

HierarchicalClustering(; clustering::Clustering.Hclust, S::AbstractMatrix,
                       D::AbstractMatrix, k::Integer)

Keyword arguments correspond to the fields above.

Validation

  • !isempty(S).
  • !isempty(D).
  • size(S) == size(D).
  • k ≥ 1.

Related

source
PortfolioOptimisers.clusterise — Method
clusterise(cle::AbstractClusteringResult, args...; kwargs...)

Return the clustering result as-is.

This function provides a generic interface for extracting or processing clustering results. By default, it simply returns the provided clustering result object unchanged. This allows for consistent downstream handling of clustering results in PortfolioOptimisers.jl workflows.

Arguments

  • cle::AbstractClusteringResult: The clustering result object.
  • args...: Additional positional arguments, ignored.
  • kwargs...: Additional keyword arguments, ignored.

Returns

  • The input cle object.

Related

source
PortfolioOptimisers.SecondOrderDifference — Type
struct SecondOrderDifference <: AbstractOptimalNumberClustersAlgorithm end

Algorithm type for estimating the optimal number of clusters using the second-order difference method.

The SecondOrderDifference algorithm selects the optimal number of clusters by maximizing the second-order difference of a clustering evaluation metric (such as within-cluster sum of squares or silhouette score) across different cluster counts. This approach helps identify the "elbow" point in the metric curve.

Related

source
PortfolioOptimisers.StandardisedSilhouetteScore — Type
struct StandardisedSilhouetteScore{T1} <: AbstractOptimalNumberClustersAlgorithm
    metric::T1
end

Algorithm type for estimating the optimal number of clusters using the standardised silhouette score.

StandardisedSilhouetteScore selects the optimal number of clusters by maximizing the silhouette score, which measures how well each object lies within its cluster compared to other clusters. The score can be computed using different distance metrics.

Fields

  • metric: The distance metric used for silhouette calculation from Distances.jl, or nothing for the default.

Constructor

StandardisedSilhouetteScore(; metric::Union{Nothing, <:Distances.SemiMetric} = nothing)

Keyword arguments correspond to the fields above.

Examples

julia> StandardisedSilhouetteScore()
StandardisedSilhouetteScore
  metric | nothing

Related

source
PortfolioOptimisers.OptimalNumberClusters — Type
struct OptimalNumberClusters{T1, T2} <: AbstractOptimalNumberClustersEstimator
    max_k::T1
    alg::T2
end

Estimator type for selecting the optimal number of clusters in PortfolioOptimisers.jl.

OptimalNumberClusters encapsulates the configuration for determining the optimal number of clusters, including the maximum allowed clusters and the algorithm used for selection.

Fields

  • max_k: Maximum number of clusters to consider. If nothing, computed as the sqrt(N), where N is the number of assets.
  • alg: Algorithm for selecting the optimal number of clusters. If an integer, defines the number of clusters directly.

Constructor

OptimalNumberClusters(; max_k::Union{Nothing, <:Integer} = nothing,
                      alg::Union{<:Integer, <:AbstractOptimalNumberClustersAlgorithm} = SecondOrderDifference())

Keyword arguments correspond to the fields above.

Validation

  • max_k >= 1.
  • If alg is an integer, alg >= 1.

Examples

julia> OptimalNumberClusters(; max_k = 10)
OptimalNumberClusters
  max_k | Int64: 10
    alg | SecondOrderDifference()

Related

source
PortfolioOptimisers.HClustAlgorithm — Type
struct HClustAlgorithm{T1} <: AbstractClusteringAlgorithm
    linkage::T1
end

Algorithm type for hierarchical clustering in PortfolioOptimisers.jl.

HClustAlgorithm specifies the linkage method used for hierarchical clustering, such as :ward, :single, :complete, or :average.

Fields

  • linkage: Linkage method for hierarchical clustering from Clustering.jl.

Constructor

HClustAlgorithm(; linkage::Symbol = :ward)

Keyword arguments correspond to the fields above.

Examples

julia> HClustAlgorithm(; linkage = :average)
HClustAlgorithm
  linkage | Symbol: :average

Related

source
PortfolioOptimisers.ClusteringEstimator — Type
struct ClusteringEstimator{T1, T2, T3, T4} <: AbstractClusteringEstimator
    ce::T1
    de::T2
    alg::T3
    onc::T4
end

Estimator type for clustering in PortfolioOptimisers.jl.

ClusteringEstimator encapsulates all configuration required for clustering, including the covariance estimator, distance estimator, clustering algorithm, and optimal number of clusters estimator.

Fields

  • ce: Covariance estimator.
  • de: Distance estimator.
  • alg: Clustering algorithm.
  • onc: Optimal number of clusters estimator.

Constructor

ClusteringEstimator(; ce::StatsBase.CovarianceEstimator = PortfolioOptimisersCovariance(),
                    de::AbstractDistanceEstimator = Distance(; alg = CanonicalDistance()),
                    alg::AbstractClusteringAlgorithm = HClustAlgorithm(),
                    onc::AbstractOptimalNumberClustersEstimator = OptimalNumberClusters())

Keyword arguments correspond to the fields above.

Examples

julia> ClusteringEstimator()
ClusteringEstimator
   ce | PortfolioOptimisersCovariance
      |   ce | Covariance
      |      |    me | SimpleExpectedReturns
      |      |       |   w | nothing
      |      |    ce | GeneralWeightedCovariance
      |      |       |   ce | StatsBase.SimpleCovariance: StatsBase.SimpleCovariance(true)
      |      |       |    w | nothing
      |      |   alg | Full()
      |   mp | DefaultMatrixProcessing
      |      |       pdm | Posdef
      |      |           |   alg | UnionAll: NearestCorrelationMatrix.Newton
      |      |   denoise | nothing
      |      |    detone | nothing
      |      |       alg | nothing
   de | Distance
      |   alg | CanonicalDistance()
  alg | HClustAlgorithm
      |   linkage | Symbol: :ward
  onc | OptimalNumberClusters
      |   max_k | nothing
      |     alg | SecondOrderDifference()

Related

source
PortfolioOptimisers.AbstractOptimalNumberClustersAlgorithm — Type
abstract type AbstractOptimalNumberClustersAlgorithm <: AbstractAlgorithm end

Abstract supertype for all optimal number of clusters algorithm types in PortfolioOptimisers.jl.

All concrete types implementing specific algorithms for determining the optimal number of clusters should subtype AbstractOptimalNumberClustersAlgorithm. This enables flexible extension and dispatch of cluster number selection routines.

Related

source