Merge pull request hudson-and-thames#401 from hudson-and-thames/develop

Develop

docs/source/index.rst

@@ -333,7 +333,7 @@ This project is licensed under an all rights reserved licence.
     portfolio_optimisation/mean_variance
     portfolio_optimisation/critical_line_algorithm
     portfolio_optimisation/hierarchical_risk_parity
-    portfolio_optimisation/hierarchical_clustering_asset_allocation
+    portfolio_optimisation/hierarchical_equal_risk_contribution
     portfolio_optimisation/nested_clustered_optimisation
     portfolio_optimisation/theory_implied_correlation
 

docs/source/portfolio_optimisation/hierarchical_clustering_asset_allocation.rst → docs/source/portfolio_optimisation/hierarchical_equal_risk_contribution.rst

@@ -1,4 +1,4 @@
-.. _portfolio_optimisation-hierarchical_clustering_asset_allocation:
+.. _portfolio_optimisation-hierarchical_equal_risk_contribution:
 
 .. |br| raw:: html
 
@@ -28,13 +28,11 @@
     for users to use them.
 
 ===============================================
-Hierarchical Clustering Asset Allocation (HCAA)
+Hierarchical Equal Risk Contribution (HERC)
 ===============================================
 
-The Hierarchical Clustering based Asset Allocation (HCAA) method takes inspiration from the Hierarchical Risk Parity (HRP)
-algorithm and uses machine learning to allocate weights efficiently. While both the HCAA and HRP algorithms use hierarchical tree
-clustering and machine learning to allocate their weights, there are some subtle differences between the two. Lets look at a quick
-overview of how the HCAA algorithm works:
+The Hierarchical Equal Risk Contribution (HERC) method takes inspiration from the Hierarchical Risk Parity (HRP)
+algorithm and the Hierarchical Clustering based Asset Allocation (HCAA) and uses machine learning to allocate weights efficiently. While both the HERC and HRP algorithms use hierarchical tree clustering to allocate their weights, there are some subtle differences between the two. Lets look at a quick overview of how the HERC algorithm works:
 
 Overview of the Algorithm
 #########################
@@ -56,9 +54,9 @@ dendrogram).
 Calculate Optimal Number of Clusters
 ************************************
 
-This step is where HCAA deviates from the traditional HRP algorithm. The hierarchical risk parity method uses single linkage
+This step is where HERC deviates from the traditional HRP algorithm. The hierarchical risk parity method uses single linkage
 and grows the tree to maximum depth. However, the number of clusters identified by growing the tree maximally may not be the
-optimal one and can lead to sub-optimal results. **This is why before allocating the weights, HCAA calculates the optimal number of clusters and cuts the hierarchical tree formed in Step-1 to the required height and clusters**. Currently, the Gap Index is used for
+optimal one and can lead to sub-optimal results. **This is why before allocating the weights, HERC calculates the optimal number of clusters and cuts the hierarchical tree formed in Step-1 to the required height and clusters**. Currently, the Gap Index is used for
 calculating the required number of clusters.
 
 .. image:: portfolio_optimisation_images/gap.png
@@ -77,7 +75,7 @@ difference between the recursive bisections of the two algorithms.
 As seen in the above image, at each step, the weights in HRP trickle down the tree by breaking it down the middle based on the
 number of assets. Although, this uses the hierarchical tree identified in Step-1, it does not make use of the exact structure
 of the dendrogram while calculating the cluster contributions. This is a fundamental disadvantage of HRP which is improved
-upon by HCAA by dividing the tree, at each step, based on the structure induced by the dendrogram.
+upon by HERC by dividing the tree, at each step, based on the structure induced by the dendrogram.
 
 At each level of the tree, an Equal Risk Contribution allocation is used i.e. the weights are:
 
@@ -94,7 +92,7 @@ are the risk contributions of left and right clusters.
     and can underestimate the true risk of a portfolio which is why there are many other important risk metrics used by
     investment managers that can correctly reflect the true risk of a portfolio/asset. With respect to this, the original HRP
     algorithm can be tweaked to allocate its weights based on different risk representations of the clusters and generate
-    better weights. The HCAA method in mlfinlab provides the following risk metrics:
+    better weights. The HERC method in mlfinlab provides the following risk metrics:
 
     1. ``variance`` : Variance of the clusters is used as a risk metric.
     2. ``standard_deviation`` : Standard deviation of the clusters is used as a risk metric.
@@ -118,18 +116,21 @@ weight of the  :math:`i^{th}` cluster calculated in Step-3.
 
 .. tip::
     |h4| Underlying Literature |h4_|
-    This implementation is based on the following two papers written by Thomas Raffinot.
+    This implementation is based on the following two papers written by Thomas Raffinot:
 
         * `Hierarchical Clustering based Asset Allocation <https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3237540>`_
         * `Hierarchical Equal Risk Contribution <https://ssrn.com/abstract=2840729>`_
+
+    You can read more about the Gap Index method in this paper:
+
         * `Gap Index Paper <https://statweb.stanford.edu/~gwalther/gap>`_
 
 Implementation
 ##############
 
-.. automodule:: mlfinlab.portfolio_optimization.hcaa
+.. automodule:: mlfinlab.portfolio_optimization.herc
 
-    .. autoclass:: HierarchicalClusteringAssetAllocation
+    .. autoclass:: HierarchicalEqualRiskContribution
         :members:
 
         .. automethod:: __init__
@@ -154,7 +155,7 @@ Implementation
 
 .. tip::
     |h4| Different Linkage Methods |h4_|
-    The following linkage methods are supported by the HCAA class in mlfinlab. (The following is taken directly from and we highly
+    The following linkage methods are supported by the HERC class in mlfinlab. (The following is taken directly from and we highly
     recommend you read):
 
     `Papenbrock, J., 2011. Asset Clusters and Asset Networks in Financial Risk Management and Portfolio Optimization (Doctoral
@@ -199,14 +200,14 @@ Plotting
 
 .. code-block::
 
-    # Instantiate HCAA Class
-    hcaa = HierarchicalClusteringAssetAllocation()
-    hcaa.allocate(asset_prices=stock_prices, risk_measure='equal_weighting')
+    # Instantiate HERC Class
+    herc = HierarchicalEqualRiskContribution()
+    herc.allocate(asset_prices=stock_prices, risk_measure='equal_weighting')
 
     # Plot Dendrogram
-    hcaa.plot_clusters(assets=stock_prices.columns)
+    herc.plot_clusters(assets=stock_prices.columns)
 
-.. image:: portfolio_optimisation_images/dendrogram_hcaa.png
+.. image:: portfolio_optimisation_images/dendrogram_herc.png
 
 In the above image, the colors of assets corresponds to the cluster to which that asset belongs. Assets in the same cluster have the same color. Note that this coloring scheme may change based on the optimal number of clusters identified by the algorithm (or specified by the user).
 
@@ -215,6 +216,6 @@ Research Notebooks
 
 The following research notebooks provide a more detailed exploration of the algorithm.
 
-* `How to use mlfinlab's HierarchicalClusteringAssetAllocation class`_
+* `How to use mlfinlab's HierarchicalEqualRiskContribution class`_
 
-.. _How to use mlfinlab's HierarchicalClusteringAssetAllocation class: https://github.com/hudson-and-thames/research/blob/master/Portfolio%20Optimisation%20Tutorials/Hierarchical%20Clustering%20Asset%20Allocation%20(HCAA)/HCAA%20Tutorial%20Notebook.ipynb
+.. _How to use mlfinlab's HierarchicalEqualRiskContribution class: https://github.com/hudson-and-thames/research/blob/master/Portfolio%20Optimisation%20Tutorials/Hierarchical%20Equal%20Risk%20Contribution%20(HERC)/HERC%20Tutorial%20Notebook.ipynb

docs/source/portfolio_optimisation/hierarchical_risk_parity.rst

@@ -119,7 +119,7 @@ Implementation
     have -1 at the 3rd and 5th index. By default, a list of 1s will be initialised if no custom input is specified.
 
     |h4| Different Linkage Methods |h4_|
-    HRP, by default, uses the single-linkage clustering algorithm. (See the tip under the HCAA algorithm for more details.)
+    HRP, by default, uses the single-linkage clustering algorithm. (See the tip under the HERC algorithm for more details.)
 
 
 

mlfinlab/portfolio_optimization/__init__.py

@@ -5,7 +5,7 @@
 from mlfinlab.portfolio_optimization.cla import CriticalLineAlgorithm
 from mlfinlab.portfolio_optimization.hrp import HierarchicalRiskParity
 from mlfinlab.portfolio_optimization.mean_variance import MeanVarianceOptimisation
-from mlfinlab.portfolio_optimization.hcaa import HierarchicalClusteringAssetAllocation
+from mlfinlab.portfolio_optimization.herc import HierarchicalEqualRiskContribution
 from mlfinlab.portfolio_optimization.risk_metrics import RiskMetrics
 from mlfinlab.portfolio_optimization.returns_estimators import ReturnsEstimators
 from mlfinlab.portfolio_optimization.nco import NCO

mlfinlab/portfolio_optimization/hcaa.py → mlfinlab/portfolio_optimization/herc.py

@@ -11,7 +11,7 @@
 from mlfinlab.portfolio_optimization.risk_estimators import RiskEstimators
 
 
-class HierarchicalClusteringAssetAllocation:
+class HierarchicalEqualRiskContribution:
     """
     This class implements the Hierarchical Equal Risk Contribution (HERC) algorithm and it's extended components mentioned in the
     following papers: `Raffinot, Thomas, The Hierarchical Equal Risk Contribution Portfolio (August 23,
@@ -48,7 +48,7 @@ def allocate(self, asset_names=None, asset_prices=None, asset_returns=None, cova
                  risk_measure='equal_weighting', linkage='ward', optimal_num_clusters=None):
         # pylint: disable=too-many-branches
         """
-        Calculate asset allocations using the HCAA algorithm.
+        Calculate asset allocations using the Hierarchical Equal Risk Contribution algorithm.
 
         :param asset_names: (list) A list of strings containing the asset names.
         :param asset_prices: (pd.DataFrame) A dataframe of historical asset prices (daily close)

mlfinlab/portfolio_optimization/tic.py

@@ -5,6 +5,7 @@
 import scipy.cluster.hierarchy as sch
 from mlfinlab.portfolio_optimization.risk_estimators import RiskEstimators
 
+
 class TIC:
     """
     This class implements the Theory-Implied Correlation (TIC) algorithm and the correlation matrix distance