Hierarchical

PortfolioOptimisers.ClusterNode — Type
struct ClusterNode{tid, tl, tr, td, tcnt} <: AbstractResult
    id::tid
    left::tl
    right::tr
    height::td
    level::tcnt
end

Node type for representing clusters in a hierarchical clustering tree.

ClusterNode encapsulates the structure of a node in a clustering tree, including its unique identifier, left and right child nodes, height, and level in the tree. Leaf nodes have left and right set to nothing.

Fields

  • id: Unique identifier for the node.
  • left: Left child node.
  • right: Right child node.
  • height: Height of the node in the tree.
  • level: Level of the node in the tree.

Constructor

ClusterNode(id; left::Union{Nothing, <:ClusterNode} = nothing,
            right::Union{Nothing, <:ClusterNode} = nothing, height::Real = 0.0,
            level::Int = 1)

Positional and keyword arguments correspond to the fields above. The level is automatically computed based on the levels of child nodes if they exist.

Examples

julia> ClusterNode(1)
ClusterNode
      id | Int64: 1
    left | nothing
   right | nothing
  height | Float64: 0.0
   level | Int64: 1

Related

source
PortfolioOptimisers.is_leaf — Function
is_leaf(a::ClusterNode)

Determine if a ClusterNode is a leaf node.

Returns true if the node has no left child (left == nothing), indicating it is a leaf in the clustering tree.

Arguments

  • a: The node to check.

Returns

  • Bool: true if the node is a leaf, false otherwise.

Examples

julia> PortfolioOptimisers.is_leaf(ClusterNode(1))
true

Related

source
PortfolioOptimisers.pre_order — Function
pre_order(a::ClusterNode; preorder_by::AbstractPreorderBy = PreorderTreeByID())

Perform a preorder traversal of a hierarchical clustering tree.

Returns a vector of node properties (by default, node IDs) in preorder (root, left, right) order. The traversal strategy can be customised by providing a subtype of AbstractPreorderBy.

Arguments

  • a: The root node of the tree.
  • preorder_by: Traversal strategy.

Returns

  • Vector{Int}: Vector of node properties in preorder.

Related

source
PortfolioOptimisers.to_tree — Function
to_tree(a::Hclust)

Convert a hierarchical clustering result to a tree of ClusterNode objects.

This function takes a hierarchical clustering object from Clustering.jl and constructs a tree representation using ClusterNode nodes. It returns the root node and a vector of all nodes in the tree.

Arguments

  • a: Hierarchical clustering object.

Returns

  • root::ClusterNode: The root node of the clustering tree.
  • nodes::Vector{ClusterNode}: Vector containing all nodes in the tree.

Related

source
PortfolioOptimisers.optimal_number_clusters — Function
optimal_number_clusters(onc::OptimalNumberClusters{<:Any, <:Integer}, clustering::Hclust,
                        args...)
optimal_number_clusters(onc::OptimalNumberClusters{<:Any, <:SecondOrderDifference},
                        clustering::Hclust, dist::AbstractMatrix)
optimal_number_clusters(onc::OptimalNumberClusters{<:Any, <:StandardisedSilhouetteScore},
                        clustering::Hclust, dist::AbstractMatrix)

Select the optimal number of clusters for a hierarchical clustering tree.

This function applies the specified optimal number of clusters estimator (onc) to a hierarchical clustering result and distance matrix, using the configured algorithm (e.g., SecondOrderDifference, StandardisedSilhouetteScore, or given directly). The selection is based on cluster validity and scoring metrics.

Arguments

  • onc: Optimal number of clusters estimator.

    • onc::OptimalNumberClusters{<:Any, <:Integer}: Uses a user-specified fixed number of clusters k directly. If k is not valid, searches above and below for the nearest valid cluster count.
    • onc::OptimalNumberClusters{<:Any, <:SecondOrderDifference}: Computes the second-order difference of a clustering evaluation metric for each possible cluster count, and selects the first valid k that maximises the difference.
    • onc::OptimalNumberClusters{<:Any, <:StandardisedSilhouetteScore}: Computes the standardised silhouette score for each possible cluster count, and selects the first valid k that maximises the score.

  • clustering: Hierarchical clustering object.

  • dist: Distance matrix used for clustering.

Returns

  • Integer: Selected optimal number of clusters.

Related

source
PortfolioOptimisers.clusterise — Method
clusterise(cle::ClusteringEstimator{<:Any, <:Any, <:HClustAlgorithm, <:Any},
           X::AbstractMatrix{<:Real}; branchorder::Symbol = :optimal, dims::Int = 1,
           kwargs...)

Run hierarchical clustering and return the result as a HierarchicalClustering object.

This function applies the specified clustering estimator to the input data matrix, computes the similarity and distance matrices, performs hierarchical clustering, and selects the optimal number of clusters. The result is returned as a HierarchicalClustering object.

Arguments

  • cle: Clustering estimator.
  • X: Data matrix (observations × assets).
  • branchorder: Branch ordering strategy for hierarchical clustering.
  • dims: Dimension along which to cluster.
  • kwargs...: Additional keyword arguments.

Returns

  • res::HierarchicalClustering: Result object containing clustering, similarity, distance matrices, and number of clusters.

Related

source
PortfolioOptimisers.get_node_property — Function
get_node_property(preorder_by::PreorderTreeByID, a::ClusterNode)

Get the property of a node used for preorder traversal.

For PreorderTreeByID, this returns the node's id.

Arguments

  • preorder_by: Preorder traversal strategy.
  • a: The node.

Returns

  • The node's identifier.

Related

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

Abstract supertype for all preorder traversal strategies in PortfolioOptimisers.jl.

Concrete types implementing specific preorder traversal logic should subtype AbstractPreorderBy. This enables flexible extension and dispatch of preorder routines for hierarchical clustering trees.

Related

source
PortfolioOptimisers.validate_k_value — Function
validate_k_value(clustering::Hclust, nodes::AbstractVector{<:ClusterNode}, k::Integer)

Validate whether a given number of clusters k is consistent with the hierarchical clustering tree.

This function checks if the clustering assignment for k clusters is compatible with the tree structure, ensuring that each non-leaf node's children correspond to valid clusters.

Arguments

  • clustering: Hierarchical clustering object.
  • nodes: Vector of nodes in the clustering tree.
  • k: Number of clusters to validate.

Returns

  • flag::Bool: true if k is a valid number of clusters, false otherwise.

Related

source
PortfolioOptimisers.valid_k_clusters — Function
valid_k_clusters(clustering::Hclust, arr::AbstractVector)

Find a valid number of clusters for a hierarchical clustering tree given a scoring array.

This function iteratively searches for a valid k (number of clusters) by checking the scoring array and validating each candidate using validate_k_value. Returns the first valid k found, or 1 if none are valid.

Arguments

  • clustering: Hierarchical clustering object.
  • arr: Array of scores for each possible number of clusters.

Returns

  • k::Integer: Valid number of clusters.

Related

source