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

• is_leaf

• pre_order

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

• ClusterNode

source

PortfolioOptimisers.PreorderTreeByID Type

struct PreorderTreeByID <: AbstractPreorderBy end

Preorder traversal strategy that visits nodes by their ID.

PreorderTreeByID is used to specify that preorder traversal should be performed using the node's id property.

Related

• AbstractPreorderBy

• get_node_property

• pre_order

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

• ClusterNode

• AbstractPreorderBy

• PreorderTreeByID

• get_node_property

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

• ClusterNode

• pre_order

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

• OptimalNumberClusters

• valid_k_clusters

• validate_k_value

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

• HierarchicalClustering

• ClusteringEstimator

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

• PreorderTreeByID

• pre_order

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

• PreorderTreeByID

• pre_order

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

• optimal_number_clusters

• ClusterNode

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

• validate_k_value

• optimal_number_clusters

source