<a id="skfolio-cluster-hierarchicalclustering"></a>

# skfolio.cluster.HierarchicalClustering

<a id="skfolio.cluster.HierarchicalClustering"></a>

### *class* skfolio.cluster.HierarchicalClustering(max_clusters=None, linkage_method=WARD)

Hierarchical Clustering.

* **Parameters:**
  **max_clusters** *int, optional*
  : For coherent clustering, the algorithm finds a minimum threshold `r` so that
    the cophenetic distance between any two original observations in the same flat
    cluster is no more than `r` and no more than `max_clusters` flat clusters are
    formed. The default (`None`) is to estimate the maximal number of clusters
    based on the Two-Order Difference to Gap Statistic [[1]](#r15163dd2dd4e-1).

  **linkage_method** *LinkageMethod, default=LinkageMethod.WARD*
  : Methods for calculating the distance between clusters in the linkage matrix.
    See the `Linkage Methods` section of `scipy.cluster.hierarchy.linkage` for
    the full descriptions.
    The default is the Ward variance minimization algorithm `LinkageMethod.WARD`.
* **Attributes:**
  **n_clusters_** *int*
  : Number of formed clusters.

  **labels_** *ndarray of shape (n_assets,)*
  : Labels of each asset.

  **linkage_matrix_** *ndarray of shape (n_assets - 1, 4)*
  : Linkage matrix computed from the distance matrix of the `distance_estimator`.

  **condensed_distance_** *ndarray of shape (\\binom{n_assets}{2}, )*
  : The 1-D condensed distance matrix.

  **n_features_in_** *int*
  : Number of assets seen during `fit`.

  **feature_names_in_** *ndarray of shape (`n_features_in_`,)*
  : Names of assets seen during `fit`. Defined only when `X`
    has assets names that are all strings.

### Methods

| [`fit`](#skfolio.cluster.HierarchicalClustering.fit)(X[, y])                | Fit the Hierarchical Equal Risk Contribution estimator.   |
|-----------------------------------------------------------------------------|-----------------------------------------------------------|
| [`fit_predict`](#skfolio.cluster.HierarchicalClustering.fit_predict)(X[, y])        | Perform clustering on `X` and returns cluster labels.     |
| [`get_metadata_routing`](#skfolio.cluster.HierarchicalClustering.get_metadata_routing)()     | Get metadata routing of this object.                      |
| [`get_params`](#skfolio.cluster.HierarchicalClustering.get_params)([deep])         | Get parameters for this estimator.                        |
| [`plot_dendrogram`](#skfolio.cluster.HierarchicalClustering.plot_dendrogram)([heatmap]) | Plot the dendrogram.                                      |
| [`set_params`](#skfolio.cluster.HierarchicalClustering.set_params)(\*\*params)     | Set the parameters of this estimator.                     |

### References

* <a id='r15163dd2dd4e-1'>**[1]**</a> “Application of two-order difference to gap statistic”. Yue, Wang & Wei (2009)

<a id="skfolio.cluster.HierarchicalClustering.fit"></a>

#### fit(X, y=None)

Fit the Hierarchical Equal Risk Contribution estimator.

* **Parameters:**
  **X** *array-like of shape (n_assets, n_assets)*
  : Distance matrix of the assets.

  **y** *Ignored*
  : Not used, present for API consistency by convention.
* **Returns:**
  **self** *HierarchicalClustering*
  : Fitted estimator.

<a id="skfolio.cluster.HierarchicalClustering.fit_predict"></a>

#### fit_predict(X, y=None, \*\*kwargs)

Perform clustering on `X` and returns cluster labels.

* **Parameters:**
  **X** *array-like of shape (n_samples, n_features)*
  : Input data.

  **y** *Ignored*
  : Not used, present for API consistency by convention.

  **\*\*kwargs** *dict*
  : Arguments to be passed to `fit`.
    <br/>
    #### Versionadded
    Added in version 1.4.
* **Returns:**
  **labels** *ndarray of shape (n_samples,), dtype=np.int64*
  : Cluster labels.

<a id="skfolio.cluster.HierarchicalClustering.get_metadata_routing"></a>

#### get_metadata_routing()

Get metadata routing of this object.

Please check [User Guide](https://skfolio.org/user_guide/metadata_routing.html.md#metadata-routing) on how the routing
mechanism works.

* **Returns:**
  **routing** *MetadataRequest*
  : A `MetadataRequest` encapsulating
    routing information.

<a id="skfolio.cluster.HierarchicalClustering.get_params"></a>

#### get_params(deep=True)

Get parameters for this estimator.

* **Parameters:**
  **deep** *bool, default=True*
  : If True, will return the parameters for this estimator and
    contained subobjects that are estimators.
* **Returns:**
  **params** *dict*
  : Parameter names mapped to their values.

<a id="skfolio.cluster.HierarchicalClustering.plot_dendrogram"></a>

#### plot_dendrogram(heatmap=True)

Plot the dendrogram.

The blue lines represent distinct clusters composed of a single asset.
The remaining colors represent clusters of more than one asset.

When `heatmap` is set to True, the heatmap of the reordered distance matrix is
displayed below the dendrogram and clusters are outlined with yellow squares.

The number of clusters used in the plot is the same as the `n_clusters_`
attribute if it exists, otherwise a default number is used corresponding to the
number of cluster with a distance above 70% of the maximum cluster distance.

* **Parameters:**
  **heatmap** *bool, default=True*
  : If this is set to True, the distance heatmap is returned with the clustered
    outlined in yellow.
* **Returns:**
  **fig** *Figure*
  : The dendrogram figure.

<a id="skfolio.cluster.HierarchicalClustering.set_params"></a>

#### set_params(\*\*params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects
(such as `Pipeline`). The latter have
parameters of the form `<component>__<parameter>` so that it’s
possible to update each component of a nested object.

* **Parameters:**
  **\*\*params** *dict*
  : Estimator parameters.
* **Returns:**
  **self** *estimator instance*
  : Estimator instance.