0
# Risk Assessment
1

2
Advanced risk metrics and measures for comprehensive portfolio risk evaluation including Value at Risk (VaR), tail risk measures, drawdown analysis, stress testing indicators, and risk-adjusted performance metrics.
3

4
## Capabilities
5

6
### Value at Risk (VaR) and Expected Shortfall
7

8
Quantify potential losses at specific confidence levels and tail risk measures.
9

10
```python { .api }
11
def value_at_risk(returns, sigma=1, confidence=0.95, prepare_returns=True):
12
    """
13
    Calculate Value at Risk (VaR) at specified confidence level.
14
    
15
    Parameters:
16
    - returns: pandas Series of returns
17
    - sigma: int, number of standard deviations (1=parametric, 2=cornish-fisher)
18
    - confidence: float, confidence level (e.g., 0.95 for 95%)
19
    - prepare_returns: bool, whether to prepare returns data
20
    
21
    Returns:
22
    float: VaR as negative percentage
23
    """
24

25
def var(returns, sigma=1, confidence=0.95, prepare_returns=True):
26
    """
27
    Alias for value_at_risk function.
28
    
29
    Parameters:
30
    - returns: pandas Series of returns
31
    - sigma: int, number of standard deviations
32
    - confidence: float, confidence level
33
    - prepare_returns: bool, whether to prepare returns data
34
    
35
    Returns:
36
    float: VaR as negative percentage
37
    """
38

39
def conditional_value_at_risk(returns, sigma=1, confidence=0.95, prepare_returns=True):
40
    """
41
    Calculate Conditional Value at Risk (CVaR) - expected loss beyond VaR.
42
    
43
    Parameters:
44
    - returns: pandas Series of returns
45
    - sigma: int, number of standard deviations
46
    - confidence: float, confidence level
47
    - prepare_returns: bool, whether to prepare returns data
48
    
49
    Returns:
50
    float: CVaR as negative percentage
51
    """
52

53
def cvar(returns, sigma=1, confidence=0.95, prepare_returns=True):
54
    """
55
    Alias for conditional_value_at_risk function.
56
    
57
    Parameters:
58
    - returns: pandas Series of returns
59
    - sigma: int, number of standard deviations
60
    - confidence: float, confidence level
61
    - prepare_returns: bool, whether to prepare returns data
62
    
63
    Returns:
64
    float: CVaR as negative percentage
65
    """
66

67
def expected_shortfall(returns, sigma=1, confidence=0.95):
68
    """
69
    Calculate Expected Shortfall (ES) - another name for CVaR.
70
    
71
    Parameters:
72
    - returns: pandas Series of returns
73
    - sigma: int, number of standard deviations
74
    - confidence: float, confidence level
75
    
76
    Returns:
77
    float: Expected shortfall as negative percentage
78
    """
79
```
80

81
### Tail Risk Measures
82

83
Assess extreme risk scenarios and tail behavior of return distributions.
84

85
```python { .api }
86
def tail_ratio(returns, cutoff=0.95, prepare_returns=True):
87
    """
88
    Calculate tail ratio - ratio of right tail to left tail returns.
89
    
90
    Parameters:
91
    - returns: pandas Series of returns
92
    - cutoff: float, percentile cutoff (e.g., 0.95 for 95th percentile)
93
    - prepare_returns: bool, whether to prepare returns data
94
    
95
    Returns:
96
    float: Tail ratio
97
    """
98

99
def outlier_win_ratio(returns, quantile=0.99, prepare_returns=True):
100
    """
101
    Calculate ratio of outlier wins to total wins.
102
    
103
    Parameters:
104
    - returns: pandas Series of returns
105
    - quantile: float, quantile threshold for outliers
106
    - prepare_returns: bool, whether to prepare returns data
107
    
108
    Returns:
109
    float: Outlier win ratio
110
    """
111

112
def outlier_loss_ratio(returns, quantile=0.01, prepare_returns=True):
113
    """
114
    Calculate ratio of outlier losses to total losses.
115
    
116
    Parameters:
117
    - returns: pandas Series of returns
118
    - quantile: float, quantile threshold for outliers
119
    - prepare_returns: bool, whether to prepare returns data
120
    
121
    Returns:
122
    float: Outlier loss ratio
123
    """
124

125
def outliers(returns, quantile=0.95):
126
    """
127
    Identify outlier returns beyond specified quantile.
128
    
129
    Parameters:
130
    - returns: pandas Series of returns
131
    - quantile: float, quantile threshold
132
    
133
    Returns:
134
    pandas Series: Boolean series identifying outliers
135
    """
136

137
def remove_outliers(returns, quantile=0.95):
138
    """
139
    Remove outlier returns beyond specified quantile.
140
    
141
    Parameters:
142
    - returns: pandas Series of returns
143
    - quantile: float, quantile threshold
144
    
145
    Returns:
146
    pandas Series: Returns with outliers removed
147
    """
148
```
149

150
### Ulcer Index and Pain Measures
151

152
Metrics focusing on downside volatility and sustained losses.
153

154
```python { .api }
155
def ulcer_index(returns):
156
    """
157
    Calculate Ulcer Index - measure of downside risk and drawdown magnitude.
158
    
159
    Parameters:
160
    - returns: pandas Series of returns
161
    
162
    Returns:
163
    float: Ulcer Index percentage
164
    """
165

166
def ulcer_performance_index(returns, rf=0):
167
    """
168
    Calculate Ulcer Performance Index - risk-adjusted return using Ulcer Index.
169
    
170
    Parameters:
171
    - returns: pandas Series of returns
172
    - rf: float, risk-free rate
173
    
174
    Returns:
175
    float: Ulcer Performance Index
176
    """
177

178
def upi(returns, rf=0):
179
    """
180
    Alias for ulcer_performance_index function.
181
    
182
    Parameters:
183
    - returns: pandas Series of returns
184
    - rf: float, risk-free rate
185
    
186
    Returns:
187
    float: UPI value
188
    """
189

190
def serenity_index(returns, rf=0):
191
    """
192
    Calculate Serenity Index - CAGR to Ulcer Index ratio.
193
    
194
    Parameters:
195
    - returns: pandas Series of returns
196
    - rf: float, risk-free rate
197
    
198
    Returns:
199
    float: Serenity Index
200
    """
201
```
202

203
### Risk of Ruin
204

205
Probability and metrics related to catastrophic losses.
206

207
```python { .api }
208
def risk_of_ruin(returns, prepare_returns=True):
209
    """
210
    Calculate risk of ruin - probability of losing entire capital.
211
    
212
    Parameters:
213
    - returns: pandas Series of returns
214
    - prepare_returns: bool, whether to prepare returns data
215
    
216
    Returns:
217
    float: Risk of ruin probability (0-1)
218
    """
219

220
def ror(returns):
221
    """
222
    Alias for risk_of_ruin function.
223
    
224
    Parameters:
225
    - returns: pandas Series of returns
226
    
227
    Returns:
228
    float: Risk of ruin probability
229
    """
230
```
231

232
### Performance vs Risk Ratios
233

234
Ratios that balance return generation against various risk measures.
235

236
```python { .api }
237
def smart_sharpe(returns, rf=0.0, periods=252, annualize=True):
238
    """
239
    Calculate Smart Sharpe ratio with autocorrelation penalty.
240
    
241
    Parameters:
242
    - returns: pandas Series of returns
243
    - rf: float, risk-free rate
244
    - periods: int, number of periods per year
245
    - annualize: bool, whether to annualize the result
246
    
247
    Returns:
248
    float: Smart Sharpe ratio
249
    """
250

251
def smart_sortino(returns, rf=0, periods=252, annualize=True):
252
    """
253
    Calculate Smart Sortino ratio with autocorrelation penalty.
254
    
255
    Parameters:
256
    - returns: pandas Series of returns
257
    - rf: float, risk-free rate
258
    - periods: int, number of periods per year
259
    - annualize: bool, whether to annualize the result
260
    
261
    Returns:
262
    float: Smart Sortino ratio
263
    """
264

265
def adjusted_sortino(returns, rf=0, periods=252, annualize=True, smart=False):
266
    """
267
    Calculate Adjusted Sortino ratio using downside deviation.
268
    
269
    Parameters:
270
    - returns: pandas Series of returns
271
    - rf: float, risk-free rate
272
    - periods: int, number of periods per year
273
    - annualize: bool, whether to annualize the result
274
    - smart: bool, whether to apply autocorrelation penalty
275
    
276
    Returns:
277
    float: Adjusted Sortino ratio
278
    """
279

280
def recovery_factor(returns, rf=0.0, prepare_returns=True):
281
    """
282
    Calculate Recovery Factor - net profit to maximum drawdown ratio.
283
    
284
    Parameters:
285
    - returns: pandas Series of returns
286
    - rf: float, risk-free rate
287
    - prepare_returns: bool, whether to prepare returns data
288
    
289
    Returns:
290
    float: Recovery factor
291
    """
292

293
def risk_return_ratio(returns, prepare_returns=True):
294
    """
295
    Calculate risk-return ratio.
296
    
297
    Parameters:
298
    - returns: pandas Series of returns
299
    - prepare_returns: bool, whether to prepare returns data
300
    
301
    Returns:
302
    float: Risk-return ratio
303
    """
304
```
305

306
### Advanced Risk Ratios
307

308
Sophisticated risk-adjusted performance measures.
309

310
```python { .api }
311
def payoff_ratio(returns, prepare_returns=True):
312
    """
313
    Calculate payoff ratio - average win to average loss ratio.
314
    
315
    Parameters:
316
    - returns: pandas Series of returns
317
    - prepare_returns: bool, whether to prepare returns data
318
    
319
    Returns:
320
    float: Payoff ratio
321
    """
322

323
def profit_ratio(returns, prepare_returns=True):
324
    """
325
    Calculate profit ratio - gross profit to gross loss ratio.
326
    
327
    Parameters:
328
    - returns: pandas Series of returns
329
    - prepare_returns: bool, whether to prepare returns data
330
    
331
    Returns:
332
    float: Profit ratio
333
    """
334

335
def profit_factor(returns, prepare_returns=True):
336
    """
337
    Calculate profit factor - total positive returns to total negative returns ratio.
338
    
339
    Parameters:
340
    - returns: pandas Series of returns
341
    - prepare_returns: bool, whether to prepare returns data
342
    
343
    Returns:
344
    float: Profit factor
345
    """
346

347
def win_loss_ratio(returns, prepare_returns=True):
348
    """
349
    Calculate win-loss ratio - ratio of winning periods to losing periods.
350
    
351
    Parameters:
352
    - returns: pandas Series of returns
353
    - prepare_returns: bool, whether to prepare returns data
354
    
355
    Returns:
356
    float: Win-loss ratio
357
    """
358

359
def cpc_index(returns, prepare_returns=True):
360
    """
361
    Calculate Common Performance Criteria (CPC) Index.
362
    
363
    Parameters:
364
    - returns: pandas Series of returns
365
    - prepare_returns: bool, whether to prepare returns data
366
    
367
    Returns:
368
    float: CPC Index
369
    """
370

371
def common_sense_ratio(returns, prepare_returns=True):
372
    """
373
    Calculate Common Sense Ratio.
374
    
375
    Parameters:
376
    - returns: pandas Series of returns
377
    - prepare_returns: bool, whether to prepare returns data
378
    
379
    Returns:
380
    float: Common Sense Ratio
381
    """
382
```
383

384
### Probabilistic Risk Measures
385

386
Risk measures incorporating probability distributions and confidence intervals.
387

388
```python { .api }
389
def probabilistic_sortino_ratio(returns, benchmark, periods=252.0, rf=0.0):
390
    """
391
    Calculate probabilistic Sortino ratio with confidence intervals.
392
    
393
    Parameters:
394
    - returns: pandas Series of portfolio returns
395
    - benchmark: pandas Series of benchmark returns
396
    - periods: float, number of periods per year
397
    - rf: float, risk-free rate
398
    
399
    Returns:
400
    float: Probabilistic Sortino ratio
401
    """
402

403
def probabilistic_adjusted_sortino_ratio(returns, benchmark, periods=252.0, rf=0.0):
404
    """
405
    Calculate probabilistic adjusted Sortino ratio.
406
    
407
    Parameters:
408
    - returns: pandas Series of portfolio returns
409
    - benchmark: pandas Series of benchmark returns
410
    - periods: float, number of periods per year
411
    - rf: float, risk-free rate
412
    
413
    Returns:
414
    float: Probabilistic adjusted Sortino ratio
415
    """
416

417
def implied_volatility(returns, periods=252, annualize=True):
418
    """
419
    Calculate implied volatility from returns.
420
    
421
    Parameters:
422
    - returns: pandas Series of returns
423
    - periods: int, number of periods per year
424
    - annualize: bool, whether to annualize the result
425
    
426
    Returns:
427
    float: Implied volatility
428
    """
429
```