0
# Risk Functions
1

2
Comprehensive collection of 45+ risk measures and portfolio analysis functions including dispersion measures, downside risk measures, drawdown measures, range measures, and performance metrics for quantitative portfolio risk analysis.
3

4
## Capabilities
5

6
### Dispersion Risk Measures
7

8
Risk measures based on the distribution of returns around the mean.
9

10
```python { .api }
11
def MAD(X):
12
    """
13
    Mean Absolute Deviation.
14
    
15
    Parameters:
16
    - X (DataFrame): Returns data
17
    
18
    Returns:
19
    float: MAD risk measure
20
    """
21

22
def SemiDeviation(X, MAR=0):
23
    """
24
    Semi-standard deviation (downside deviation).
25
    
26
    Parameters:
27
    - X (DataFrame): Returns data
28
    - MAR (float): Minimum acceptable return
29
    
30
    Returns:
31
    float: Semi-deviation
32
    """
33

34
def Kurtosis(X):
35
    """
36
    Square root of kurtosis.
37
    
38
    Parameters:
39
    - X (DataFrame): Returns data
40
    
41
    Returns:
42
    float: Square root of kurtosis
43
    """
44

45
def SemiKurtosis(X, MAR=0):
46
    """
47
    Square root of semi-kurtosis.
48
    
49
    Parameters:
50
    - X (DataFrame): Returns data  
51
    - MAR (float): Minimum acceptable return
52
    
53
    Returns:
54
    float: Square root of semi-kurtosis
55
    """
56

57
def GMD(X):
58
    """
59
    Gini Mean Difference.
60
    
61
    Parameters:
62
    - X (DataFrame): Returns data
63
    
64
    Returns:
65
    float: Gini Mean Difference
66
    """
67
```
68

69
### Downside Risk Measures
70

71
Risk measures focusing on negative returns and tail risks.
72

73
```python { .api }
74
def VaR_Hist(X, alpha=0.05):
75
    """
76
    Historical Value at Risk.
77
    
78
    Parameters:
79
    - X (DataFrame): Returns data
80
    - alpha (float): Significance level
81
    
82
    Returns:
83
    float: Value at Risk
84
    """
85

86
def CVaR_Hist(X, alpha=0.05):
87
    """
88
    Historical Conditional Value at Risk (Expected Shortfall).
89
    
90
    Parameters:
91
    - X (DataFrame): Returns data
92
    - alpha (float): Significance level
93
    
94
    Returns:
95
    float: Conditional Value at Risk
96
    """
97

98
def WR(X):
99
    """
100
    Worst Realization (minimum return).
101
    
102
    Parameters:
103
    - X (DataFrame): Returns data
104
    
105
    Returns:
106
    float: Worst realization
107
    """
108

109
def LPM(X, MAR=0, p=1):
110
    """
111
    Lower Partial Moment.
112
    
113
    Parameters:
114
    - X (DataFrame): Returns data
115
    - MAR (float): Minimum acceptable return
116
    - p (float): Moment order
117
    
118
    Returns:
119
    float: Lower partial moment
120
    """
121

122
def Entropic_RM(X, z=1, alpha=0.05):
123
    """
124
    Entropic Risk Measure.
125
    
126
    Parameters:
127
    - X (DataFrame): Returns data
128
    - z (float): Entropic parameter
129
    - alpha (float): Significance level
130
    
131
    Returns:  
132
    float: Entropic risk measure
133
    """
134

135
def EVaR_Hist(X, alpha=0.05, solver="CLARABEL"):
136
    """
137
    Entropic Value at Risk.
138
    
139
    Parameters:
140
    - X (DataFrame): Returns data
141
    - alpha (float): Significance level
142
    - solver (str): Optimization solver (default: "CLARABEL")
143
    
144
    Returns:
145
    float: Entropic Value at Risk
146
    """
147

148
def RLVaR_Hist(X, alpha=0.05, kappa=0.30, solver="CLARABEL"):
149
    """
150
    Relativistic Value at Risk.
151
    
152
    Parameters:
153
    - X (DataFrame): Returns data
154
    - alpha (float): Significance level
155
    - kappa (float): Deformation parameter
156
    - solver (str): Optimization solver (default: "CLARABEL")
157
    
158
    Returns:
159
    float: Relativistic Value at Risk
160
    """
161
```
162

163
### Drawdown Risk Measures
164

165
Risk measures based on peak-to-trough declines in portfolio value.
166

167
```python { .api }
168
def MDD_Abs(X):
169
    """
170
    Maximum Drawdown (absolute).
171
    
172
    Parameters:
173
    - X (DataFrame): Returns data
174
    
175
    Returns:
176
    float: Maximum drawdown
177
    """
178

179
def ADD_Abs(X):
180
    """
181
    Average Drawdown (absolute).
182
    
183
    Parameters:
184
    - X (DataFrame): Returns data
185
    
186
    Returns:
187
    float: Average drawdown
188
    """
189

190
def DaR_Abs(X, alpha=0.05):
191
    """
192
    Drawdown at Risk (absolute).
193
    
194
    Parameters:
195
    - X (DataFrame): Returns data
196
    - alpha (float): Significance level
197
    
198
    Returns:
199
    float: Drawdown at Risk
200
    """
201

202
def CDaR_Abs(X, alpha=0.05):
203
    """
204
    Conditional Drawdown at Risk (absolute).
205
    
206
    Parameters:
207
    - X (DataFrame): Returns data
208
    - alpha (float): Significance level
209
    
210
    Returns:
211
    float: Conditional Drawdown at Risk
212
    """
213

214
def EDaR_Abs(X, alpha=0.05):
215
    """
216
    Entropic Drawdown at Risk (absolute).
217
    
218
    Parameters:
219
    - X (DataFrame): Returns data
220
    - alpha (float): Significance level
221
    
222
    Returns:
223
    float: Entropic Drawdown at Risk
224
    """
225

226
def RLDaR_Abs(X, alpha=0.05, kappa=0.30):
227
    """
228
    Relativistic Drawdown at Risk (absolute).
229
    
230
    Parameters:
231
    - X (DataFrame): Returns data
232
    - alpha (float): Significance level
233
    - kappa (float): Deformation parameter
234
    
235
    Returns:
236
    float: Relativistic Drawdown at Risk
237
    """
238

239
def UCI_Abs(X):
240
    """
241
    Ulcer Index (absolute).
242
    
243
    Parameters:
244
    - X (DataFrame): Returns data
245
    
246
    Returns:
247
    float: Ulcer Index
248
    """
249

250
# Relative Drawdown Functions
251
def MDD_Rel(X):
252
    """
253
    Maximum Drawdown (relative/compounded).
254
    
255
    Parameters:
256
    - X (DataFrame): Returns data
257
    
258
    Returns:
259
    float: Relative maximum drawdown
260
    """
261

262
def ADD_Rel(X):
263
    """
264
    Average Drawdown (relative/compounded).
265
    
266
    Parameters:
267
    - X (DataFrame): Returns data
268
    
269
    Returns:
270
    float: Relative average drawdown
271
    """
272

273
def DaR_Rel(X, alpha=0.05):
274
    """
275
    Drawdown at Risk (relative/compounded).
276
    
277
    Parameters:
278
    - X (DataFrame): Returns data
279
    - alpha (float): Significance level
280
    
281
    Returns:
282
    float: Relative Drawdown at Risk
283
    """
284

285
def CDaR_Rel(X, alpha=0.05):
286
    """
287
    Conditional Drawdown at Risk (relative/compounded).
288
    
289
    Parameters:
290
    - X (DataFrame): Returns data
291
    - alpha (float): Significance level
292
    
293
    Returns:
294
    float: Relative Conditional Drawdown at Risk
295
    """
296

297
def EDaR_Rel(X, alpha=0.05, solver="CLARABEL"):
298
    """
299
    Entropic Drawdown at Risk (relative/compounded).
300
    
301
    Parameters:
302
    - X (DataFrame): Returns data
303
    - alpha (float): Significance level
304
    - solver (str): Optimization solver
305
    
306
    Returns:
307
    float: Relative Entropic Drawdown at Risk
308
    """
309

310
def RLDaR_Rel(X, alpha=0.05, kappa=0.30, solver="CLARABEL"):
311
    """
312
    Relativistic Drawdown at Risk (relative/compounded).
313
    
314
    Parameters:
315
    - X (DataFrame): Returns data
316
    - alpha (float): Significance level
317
    - kappa (float): Deformation parameter
318
    - solver (str): Optimization solver
319
    
320
    Returns:
321
    float: Relative Relativistic Drawdown at Risk
322
    """
323

324
def UCI_Rel(X):
325
    """
326
    Ulcer Index (relative/compounded).
327
    
328
    Parameters:
329
    - X (DataFrame): Returns data
330
    
331
    Returns:
332
    float: Relative Ulcer Index
333
    """
334

335
# Additional Missing Functions
336
def VRG(X, alpha=0.05, beta=0.05):
337
    """
338
    VaR Range (VaR of gains - VaR of losses).
339
    
340
    Parameters:
341
    - X (DataFrame): Returns data
342
    - alpha (float): Significance level for losses
343
    - beta (float): Significance level for gains
344
    
345
    Returns:
346
    float: VaR Range
347
    """
348
```
349

350
### Range Risk Measures  
351

352
Risk measures based on the range and spread of returns distribution.
353

354
```python { .api }
355
def TG(X, alpha=0.05):
356
    """
357
    Tail Gini coefficient.
358
    
359
    Parameters:
360
    - X (DataFrame): Returns data
361
    - alpha (float): Significance level
362
    
363
    Returns:
364
    float: Tail Gini
365
    """
366

367
def RG(X):
368
    """
369
    Range (max - min).
370
    
371
    Parameters:
372
    - X (DataFrame): Returns data
373
    
374
    Returns:
375
    float: Range
376
    """
377

378
def CVRG(X, alpha=0.05, beta=0.05):
379
    """
380
    CVaR Range (CVaR of gains - CVaR of losses).
381
    
382
    Parameters:
383
    - X (DataFrame): Returns data
384
    - alpha (float): Significance level for losses
385
    - beta (float): Significance level for gains
386
    
387
    Returns:
388
    float: CVaR Range
389
    """
390

391
def TGRG(X, alpha=0.05, a_sim=100):
392
    """
393
    Tail Gini Range.
394
    
395
    Parameters:
396
    - X (DataFrame): Returns data
397
    - alpha (float): Significance level
398
    - a_sim (int): Number of simulations
399
    
400
    Returns:
401
    float: Tail Gini Range
402
    """
403

404
def EVRG(X, alpha=0.05, beta=0.05):
405
    """
406
    Entropic Value at Risk Range.
407
    
408
    Parameters:
409
    - X (DataFrame): Returns data
410
    - alpha (float): Significance level for losses
411
    - beta (float): Significance level for gains
412
    
413
    Returns:
414
    float: Entropic VaR Range
415
    """
416

417
def RVRG(X, alpha=0.05, beta=0.05, kappa=0.30):
418
    """
419
    Relativistic Value at Risk Range.
420
    
421
    Parameters:
422
    - X (DataFrame): Returns data
423
    - alpha (float): Significance level for losses
424
    - beta (float): Significance level for gains
425
    - kappa (float): Deformation parameter
426
    
427
    Returns:
428
    float: Relativistic VaR Range
429
    """
430
```
431

432
### Portfolio Analysis Functions
433

434
Functions for portfolio performance analysis and risk decomposition.
435

436
```python { .api }
437
def Sharpe(X, rf=0):
438
    """
439
    Sharpe ratio.
440
    
441
    Parameters:
442
    - X (DataFrame): Returns data
443
    - rf (float): Risk-free rate
444
    
445
    Returns:
446
    float: Sharpe ratio
447
    """
448

449
def Sharpe_Risk(X, rm='MV', rf=0, alpha=0.05):
450
    """
451
    Sharpe ratio with custom risk measure.
452
    
453
    Parameters:
454
    - X (DataFrame): Returns data
455
    - rm (str): Risk measure code
456
    - rf (float): Risk-free rate
457
    - alpha (float): Significance level
458
    
459
    Returns:
460
    float: Risk-adjusted Sharpe ratio
461
    """
462

463
def Risk_Contribution(w, cov, rm='MV', alpha=0.05):
464
    """
465
    Risk contribution analysis.
466
    
467
    Parameters:
468
    - w (DataFrame): Portfolio weights
469
    - cov (DataFrame): Covariance matrix
470
    - rm (str): Risk measure
471
    - alpha (float): Significance level
472
    
473
    Returns:
474
    DataFrame: Risk contributions by asset
475
    """
476

477
def Risk_Margin(w, cov, alpha=0.05):
478
    """
479
    Risk margin calculation.
480
    
481
    Parameters:
482
    - w (DataFrame): Portfolio weights
483
    - cov (DataFrame): Covariance matrix
484
    - alpha (float): Significance level
485
    
486
    Returns:
487
    DataFrame: Risk margins
488
    """
489

490
def Factors_Risk_Contribution(w, cov, B, rm='MV'):
491
    """
492
    Factor risk contribution analysis.
493
    
494
    Parameters:
495
    - w (DataFrame): Portfolio weights
496
    - cov (DataFrame): Factor covariance matrix
497
    - B (DataFrame): Factor loadings
498
    - rm (str): Risk measure
499
    
500
    Returns:
501
    DataFrame: Factor risk contributions
502
    """
503

504
def BrinsonAttribution(Ra, Rb, Wa, Wb):
505
    """
506
    Brinson performance attribution analysis.
507
    
508
    Parameters:
509
    - Ra (DataFrame): Portfolio returns
510
    - Rb (DataFrame): Benchmark returns
511
    - Wa (DataFrame): Portfolio weights
512
    - Wb (DataFrame): Benchmark weights
513
    
514
    Returns:
515
    DataFrame: Attribution analysis results
516
    """
517

518
def NEA(w):
519
    """
520
    Number of Effective Assets.
521
    
522
    Parameters:
523
    - w (DataFrame): Portfolio weights
524
    
525
    Returns:
526
    float: Number of effective assets
527
    """
528

529
def L_Moment(X, k=4):
530
    """
531
    L-moments calculation.
532
    
533
    Parameters:
534
    - X (DataFrame): Returns data
535
    - k (int): Number of L-moments
536
    
537
    Returns:
538
    DataFrame: L-moments
539
    """
540

541
def L_Moment_CRM(X, w, k=4):
542
    """
543
    L-moment coherent risk measure.
544
    
545
    Parameters:
546
    - X (DataFrame): Returns data
547
    - w (DataFrame): L-moment weights
548
    - k (int): Number of L-moments
549
    
550
    Returns:
551
    float: L-moment risk measure
552
    """
553
```
554

555
## Usage Example
556

557
```python
558
import riskfolio as rp
559
import pandas as pd
560
import numpy as np
561

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

565
# Calculate various risk measures
566
portfolio_returns = returns.mean(axis=1)  # Equal-weighted portfolio
567

568
# Dispersion measures
569
mad_risk = rp.MAD(portfolio_returns)
570
semi_dev = rp.SemiDeviation(portfolio_returns, MAR=0)
571
gmd_risk = rp.GMD(portfolio_returns)
572

573
# Downside measures  
574
var_95 = rp.VaR_Hist(portfolio_returns, alpha=0.05)
575
cvar_95 = rp.CVaR_Hist(portfolio_returns, alpha=0.05)
576
worst_return = rp.WR(portfolio_returns)
577

578
# Drawdown measures
579
max_dd = rp.MDD_Abs(portfolio_returns)
580
avg_dd = rp.ADD_Abs(portfolio_returns)
581
cdar_95 = rp.CDaR_Abs(portfolio_returns, alpha=0.05)
582

583
# Performance measures
584
sharpe_ratio = rp.Sharpe(portfolio_returns, rf=0.02)
585
sharpe_cvar = rp.Sharpe_Risk(portfolio_returns, rm='CVaR', rf=0.02)
586

587
print(f"MAD: {mad_risk:.4f}")
588
print(f"VaR (95%): {var_95:.4f}")
589
print(f"CVaR (95%): {cvar_95:.4f}")
590
print(f"Max Drawdown: {max_dd:.4f}")
591
print(f"Sharpe Ratio: {sharpe_ratio:.4f}")
592

593
# Portfolio risk contribution analysis
594
port = rp.Portfolio(returns=returns)
595
port.assets_stats()
596
w = port.optimization(obj='Sharpe', rm='CVaR')
597

598
# Calculate risk contributions
599
risk_contrib = rp.Risk_Contribution(w, port.cov, rm='CVaR')
600
print("\nRisk Contributions:")
601
print(risk_contrib.sort_values('Risk', ascending=False).head())
602
```
603

604
## Risk Measure Codes
605

606
```python
607
# Available risk measures
608
rmeasures = [
609
    "MV",      # Mean Variance (Standard Deviation)
610
    "KT",      # Square Root Kurtosis  
611
    "MAD",     # Mean Absolute Deviation
612
    "GMD",     # Gini Mean Difference
613
    "MSV",     # Mean Square Variation
614
    "SKT",     # Square Root Semi-Kurtosis
615
    "FLPM",    # First Lower Partial Moment
616
    "SLPM",    # Second Lower Partial Moment
617
    "CVaR",    # Conditional Value at Risk
618
    "TG",      # Tail Gini
619
    "EVaR",    # Entropic Value at Risk
620
    "RLVaR",   # Relativistic Value at Risk
621
    "WR",      # Worst Realization
622
    "CVRG",    # CVaR Range
623
    "TGRG",    # Tail Gini Range
624
    "EVRG",    # Entropic VaR Range
625
    "RVRG",    # Relativistic VaR Range
626
    "RG",      # Range
627
    "MDD",     # Maximum Drawdown
628
    "ADD",     # Average Drawdown
629
    "CDaR",    # Conditional Drawdown at Risk
630
    "EDaR",    # Entropic Drawdown at Risk
631
    "RLDaR",   # Relativistic Drawdown at Risk
632
    "UCI"      # Ulcer Index
633
]
634
```