tessl/pypi-riskfolio-lib

Portfolio Optimization and Quantitative Strategic Asset Allocation in Python

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Hierarchical Clustering

Name: tessl/pypi-riskfolio-lib
Author: tessl

Hierarchical clustering-based portfolio optimization using advanced clustering algorithms for asset allocation based on correlation structures. The HCPortfolio class implements Hierarchical Risk Parity (HRP), Nested Clustered Optimization (NCO), and other clustering-based portfolio construction methods.

Capabilities

HCPortfolio Class

Hierarchical clustering portfolio optimization class for correlation-based asset allocation.

class HCPortfolio:
    def __init__(self, returns=None, kappa=0.30, kappa_g=None):
        """
        Initialize HCPortfolio object.
        
        Parameters:
        - returns (DataFrame): Assets returns data
        - kappa (float): Deformation parameter for RLVaR/RLDaR (0-1) (default: 0.30)
        - kappa_g (float): Deformation parameter for RLVaR gains (default: None)
        """

Hierarchical Optimization

Main optimization method supporting multiple clustering-based portfolio models.

def optimization(self, model='HRP', codependence='pearson', covariance='hist', 
                obj='MinRisk', rm='MV', rf=0, l=0, linkage='single', 
                max_k=10, leaf_order=True):
    """
    Hierarchical clustering portfolio optimization.
    
    Parameters:
    - model (str): Optimization model ('HRP', 'HERC', 'NCO', 'HERC2')
    - codependence (str): Codependence measure ('pearson', 'spearman', 'abs_pearson', 
                         'abs_spearman', 'distance_corr', 'mutual_info', 'tail')
    - covariance (str): Covariance estimation method ('hist', 'ewma1', 'ewma2', 
                       'ledoit', 'oas', 'shrunk', 'gl', 'jlogo', 'fixed', 'spectral', 'shrink')
    - obj (str): Objective function ('MinRisk', 'Utility', 'Sharpe', 'MaxRet')
    - rm (str): Risk measure for optimization
    - rf (float): Risk-free rate
    - l (float): Risk aversion parameter
    - linkage (str): Linkage method ('single', 'complete', 'average', 'weighted', 
                    'centroid', 'median', 'ward', 'DBHT')
    - max_k (int): Maximum number of clusters for NCO
    - leaf_order (bool): Optimize leaf order in dendrogram
    
    Returns:
    DataFrame: Optimal portfolio weights
    """

Properties

Key properties for accessing portfolio data and parameters.

@property
def returns(self):
    """Get/set assets returns DataFrame."""

@property
def assetslist(self):
    """Get list of asset names."""

@property  
def kappa(self):
    """Get/set RLVaR deformation parameter."""

@property
def kappa_g(self):
    """Get/set RLVaR deformation parameter for gains."""

Model Types

Hierarchical Risk Parity (HRP)

Allocates capital by recursively bisecting the correlation matrix based on hierarchical clustering, providing diversification benefits without traditional mean-variance optimization.

Hierarchical Equal Risk Contribution (HERC)

Extension of HRP that allocates capital to equalize risk contributions across clusters and within clusters, providing better risk budgeting.

Nested Clustered Optimization (NCO)

Combines hierarchical clustering with traditional optimization by first clustering assets and then optimizing within and across clusters.

HERC2

Advanced version of HERC with improved risk contribution calculations and cluster allocation methods.

Usage Example

import riskfolio as rp
import pandas as pd

# Load returns data
returns = pd.read_csv('returns.csv', index_col=0, parse_dates=True)

# Create hierarchical portfolio
hc_port = rp.HCPortfolio(returns=returns)

# Hierarchical Risk Parity optimization
w_hrp = hc_port.optimization(
    model='HRP',
    codependence='pearson',
    covariance='hist',
    obj='MinRisk',
    rm='MV',
    linkage='ward'
)

# Nested Clustered Optimization  
w_nco = hc_port.optimization(
    model='NCO',
    codependence='pearson',
    covariance='hist', 
    obj='Sharpe',
    rm='MV',
    rf=0.02,
    linkage='ward',
    max_k=10
)

# HERC optimization with custom parameters
w_herc = hc_port.optimization(
    model='HERC',
    codependence='spearman',
    covariance='ledoit',
    obj='MinRisk',
    rm='CVaR',
    linkage='complete'
)

print("HRP Weights:")
print(w_hrp.T)
print("\nNCO Weights:")
print(w_nco.T) 
print("\nHERC Weights:")
print(w_herc.T)

# Visualize clustering
ax = rp.plot_dendrogram(
    returns=returns,
    codependence='pearson',
    linkage='ward'
)

# Plot clustered correlation matrix
ax = rp.plot_clusters(
    returns=returns,
    codependence='pearson', 
    linkage='ward'
)