0
# Riskfolio-Lib
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: Riskfolio-Lib
7
- **Language**: Python
8
- **Installation**: `pip install Riskfolio-Lib`
9
- **Requirements**: Python >=3.9
10

11
## Core Imports
12

13
```python
14
import riskfolio as rp
15
```
16

17
All classes and functions are available at the top level:
18

19
```python
20
# Import specific components
21
from riskfolio import Portfolio, HCPortfolio
22
from riskfolio import plot_frontier, mean_vector, MAD
23
```
24

25
## Basic Usage
26

27
```python
28
import riskfolio as rp
29
import numpy as np
30
import pandas as pd
31

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

35
# Create Portfolio object
36
port = rp.Portfolio(returns=returns)
37

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

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

44
# Display allocation
45
print(w.T)
46

47
# Plot efficient frontier
48
ax = rp.plot_frontier(
49
    w_frontier=port.efficient_frontier(model='Classic', rm='MV'),
50
    mu=port.mu,
51
    cov=port.cov,
52
    returns=returns,
53
    rm='MV',
54
    rf=0.0
55
)
56
```
57

58
## Architecture
59

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

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

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

72
## Capabilities
73

74
### Portfolio Optimization
75

76
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.
77

78
```python { .api }
79
class Portfolio:
80
    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): ...
81
    def assets_stats(self, method_mu='hist', method_cov='hist', **kwargs): ...
82
    def optimization(self, model='Classic', rm='MV', obj='Sharpe', rf=0, l=0, hist=True): ...
83
    def efficient_frontier(self, model='Classic', rm='MV', points=20, rf=0, hist=True): ...
84
```
85

86
[Portfolio Optimization](./portfolio-optimization.md)
87

88
### Hierarchical Clustering
89

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

92
```python { .api }
93
class HCPortfolio:
94
    def __init__(self, returns=None, alpha=0.05): ...
95
    def optimization(self, model='HRP', codependence='pearson', covariance='hist', obj='MinRisk'): ...
96
```
97

98
[Hierarchical Clustering](./hierarchical-clustering.md)
99

100
### Risk Functions
101

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

104
```python { .api }
105
def MAD(X): ...
106
def CVaR_Hist(X, alpha=0.05): ...
107
def MDD_Abs(X): ...
108
def Sharpe(X, rf=0): ...
109
def Risk_Contribution(w, cov, rm='MV'): ...
110
```
111

112
[Risk Functions](./risk-functions.md)
113

114
### Parameter Estimation
115

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

118
```python { .api }
119
def mean_vector(X, method='hist', **kwargs): ...
120
def covar_matrix(X, method='hist', **kwargs): ...
121
def black_litterman(X_hist, P, Q, **kwargs): ...
122
def loadings_matrix(X, Y, method='stepwise'): ...
123
```
124

125
[Parameter Estimation](./parameter-estimation.md)
126

127
### Plotting and Visualization
128

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

131
```python { .api }
132
def plot_frontier(w_frontier, mu, cov, returns, rm='MV', rf=0): ...
133
def plot_pie(w, title='Portfolio Composition'): ...
134
def plot_risk_con(w, cov, returns, rm='MV'): ...
135
def plot_clusters(returns, codependence='pearson', linkage='ward'): ...
136
```
137

138
[Plotting and Visualization](./plotting-visualization.md)
139

140
### Constraints and Advanced Features
141

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

144
```python { .api }
145
def assets_constraints(assets, min_val=None, max_val=None): ...
146
def risk_constraint(w, cov, rm='MV', rf=0): ...
147
def connection_matrix(returns, network_method='MST'): ...
148
def centrality_vector(adjacency_matrix, centrality='degree'): ...
149
```
150

151
[Constraints and Advanced Features](./constraints-advanced.md)
152

153
### Reports and Analysis
154

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

157
```python { .api }
158
def jupyter_report(returns, w, rm='MV', rf=0, alpha=0.05): ...
159
def excel_report(returns, w, rf=0, alpha=0.05, name='report', folder='Reports/'): ...
160
```
161

162
[Reports and Analysis](./reports.md)
163

164
## Types
165

166
```python { .api }
167
# Risk measure codes
168
rmeasures = ["MV", "KT", "MAD", "GMD", "MSV", "SKT", "FLPM", "SLPM", 
169
            "CVaR", "TG", "EVaR", "RLVaR", "WR", "CVRG", "TGRG", 
170
            "EVRG", "RVRG", "RG", "MDD", "ADD", "CDaR", "EDaR", 
171
            "RLDaR", "UCI"]
172

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

176
# Objectives
177
objectives = ["MinRisk", "Utility", "Sharpe", "MaxRet"]
178
```