Riskfolio-Lib

A comprehensive Python library for quantitative strategic asset allocation and portfolio optimization. Riskfolio-Lib provides advanced mean risk and logarithmic mean risk portfolio optimization with 4 objective functions and 24 convex risk measures, supporting multiple portfolio optimization models including mean-variance, risk parity, hierarchical clustering, nested clustered optimization, and worst-case scenarios optimization.

Package Information

• Package Name: Riskfolio-Lib
• Language: Python
• Installation: pip install Riskfolio-Lib
• Requirements: Python >=3.9

Core Imports

import riskfolio as rp

All classes and functions are available at the top level:

# Import specific components
from riskfolio import Portfolio, HCPortfolio
from riskfolio import plot_frontier, mean_vector, MAD

Basic Usage

import riskfolio as rp
import numpy as np
import pandas as pd

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

# Create Portfolio object
port = rp.Portfolio(returns=returns)

# Calculate basic statistics
port.assets_stats(method_mu='hist', method_cov='hist')

# Optimize portfolio for minimum risk
w = port.optimization(model='Classic', rm='MV', obj='MinRisk', rf=0.0, l=0)

# Display allocation
print(w.T)

# Plot efficient frontier
ax = rp.plot_frontier(
    w_frontier=port.efficient_frontier(model='Classic', rm='MV'),
    mu=port.mu,
    cov=port.cov,
    returns=returns,
    rm='MV',
    rf=0.0
)

Architecture

Riskfolio-Lib is organized around core optimization classes and supporting modules:

• Portfolio: Main class for classical portfolio optimization with extensive customization
• HCPortfolio: Hierarchical clustering-based portfolio optimization
• Risk Functions: 24+ risk measures for comprehensive risk analysis
• Parameter Estimation: Statistical methods for expected returns and covariance estimation
• Plotting: Comprehensive visualization tools for portfolios and risk analysis
• Constraints: Advanced constraint modeling for complex portfolio requirements
• External Functions: High-performance C++ implementations for matrix operations

The library integrates seamlessly with the Python scientific ecosystem (NumPy, Pandas, Matplotlib) and uses CVXPY for convex optimization.

Capabilities

Portfolio Optimization

Core portfolio optimization functionality including mean-variance, risk parity, Black-Litterman, factor models, and worst-case optimization. Supports 4 objective functions and 24 risk measures.

class Portfolio:
    def __init__(self, returns=None, sht=False, uppersht=0.0001, upperlng=1, factors=None, alpha=0.05, a_sim=100, beta=None, b_sim=None): ...
    def assets_stats(self, method_mu='hist', method_cov='hist', **kwargs): ...
    def optimization(self, model='Classic', rm='MV', obj='Sharpe', rf=0, l=0, hist=True): ...
    def efficient_frontier(self, model='Classic', rm='MV', points=20, rf=0, hist=True): ...

Portfolio Optimization

Hierarchical Clustering

Hierarchical clustering-based portfolio optimization using advanced clustering algorithms for asset allocation based on correlation structures.

class HCPortfolio:
    def __init__(self, returns=None, alpha=0.05): ...
    def optimization(self, model='HRP', codependence='pearson', covariance='hist', obj='MinRisk'): ...

Hierarchical Clustering

Risk Functions

Comprehensive collection of 45+ risk measures including dispersion measures, downside risk measures, drawdown measures, and range measures for portfolio risk analysis.

def MAD(X): ...
def CVaR_Hist(X, alpha=0.05): ...
def MDD_Abs(X): ...
def Sharpe(X, rf=0): ...
def Risk_Contribution(w, cov, rm='MV'): ...

Risk Functions

Parameter Estimation

Statistical methods for estimating expected returns, covariance matrices, factor models, and implementing Black-Litterman and other advanced estimation techniques.

def mean_vector(X, method='hist', **kwargs): ...
def covar_matrix(X, method='hist', **kwargs): ...
def black_litterman(X_hist, P, Q, **kwargs): ...
def loadings_matrix(X, Y, method='stepwise'): ...

Parameter Estimation

Plotting and Visualization

Comprehensive visualization tools for portfolios, efficient frontiers, risk contributions, cluster analysis, and performance attribution.

def plot_frontier(w_frontier, mu, cov, returns, rm='MV', rf=0): ...
def plot_pie(w, title='Portfolio Composition'): ...
def plot_risk_con(w, cov, returns, rm='MV'): ...
def plot_clusters(returns, codependence='pearson', linkage='ward'): ...

Plotting and Visualization

Constraints and Advanced Features

Advanced constraint modeling including network constraints, clustering constraints, risk budgeting, and factor risk constraints for sophisticated portfolio construction.

def assets_constraints(assets, min_val=None, max_val=None): ...
def risk_constraint(w, cov, rm='MV', rf=0): ...
def connection_matrix(returns, network_method='MST'): ...
def centrality_vector(adjacency_matrix, centrality='degree'): ...

Constraints and Advanced Features

Reports and Analysis

Comprehensive portfolio reporting tools for generating detailed analysis reports in Jupyter notebooks and Excel formats with portfolio statistics, risk analysis, and visualizations.

def jupyter_report(returns, w, rm='MV', rf=0, alpha=0.05): ...
def excel_report(returns, w, rf=0, alpha=0.05, name='report', folder='Reports/'): ...

Reports and Analysis

Types

# Risk measure codes
rmeasures = ["MV", "KT", "MAD", "GMD", "MSV", "SKT", "FLPM", "SLPM", 
            "CVaR", "TG", "EVaR", "RLVaR", "WR", "CVRG", "TGRG", 
            "EVRG", "RVRG", "RG", "MDD", "ADD", "CDaR", "EDaR", 
            "RLDaR", "UCI"]

# Optimization models
models = ["Classic", "BL", "FM", "FC", "WC", "OWA"]

# Objectives
objectives = ["MinRisk", "Utility", "Sharpe", "MaxRet"]