0
# Statistical Analysis
1

2
Core statistical functions for portfolio performance analysis including return calculations, risk metrics, performance ratios, drawdown analysis, benchmarking, and advanced statistical measures. These functions form the foundation of quantitative portfolio analysis.
3

4
## Capabilities
5

6
### Performance Ratios
7

8
Essential risk-adjusted return metrics for evaluating portfolio performance.
9

10
```python { .api }
11
def sharpe(returns, rf=0.0, periods=252, annualize=True, smart=False):
12
    """
13
    Calculate Sharpe ratio - risk-adjusted return metric.
14
    
15
    Parameters:
16
    - returns: pandas Series of returns
17
    - rf: float, risk-free rate (default 0.0)
18
    - periods: int, number of periods per year (default 252 for daily)
19
    - annualize: bool, whether to annualize the result
20
    - smart: bool, whether to use smart Sharpe with autocorrelation penalty
21
    
22
    Returns:
23
    float: Sharpe ratio
24
    """
25

26
def sortino(returns, rf=0, periods=252, annualize=True, smart=False):
27
    """
28
    Calculate Sortino ratio - downside deviation-adjusted return metric.
29
    
30
    Parameters:
31
    - returns: pandas Series of returns
32
    - rf: float, risk-free rate (default 0.0)
33
    - periods: int, number of periods per year
34
    - annualize: bool, whether to annualize the result
35
    - smart: bool, whether to use smart Sortino
36
    
37
    Returns:
38
    float: Sortino ratio
39
    """
40

41
def calmar(returns, prepare_returns=True, periods=252):
42
    """
43
    Calculate Calmar ratio - CAGR to max drawdown ratio.
44
    
45
    Parameters:
46
    - returns: pandas Series of returns
47
    - prepare_returns: bool, whether to prepare returns data
48
    - periods: int, number of periods per year
49
    
50
    Returns:
51
    float: Calmar ratio
52
    """
53

54
def treynor_ratio(returns, benchmark, periods=252.0, rf=0.0):
55
    """
56
    Calculate Treynor ratio - beta-adjusted return metric.
57
    
58
    Parameters:
59
    - returns: pandas Series of portfolio returns
60
    - benchmark: pandas Series of benchmark returns
61
    - periods: float, number of periods per year
62
    - rf: float, risk-free rate
63
    
64
    Returns:
65
    float: Treynor ratio
66
    """
67

68
def omega(returns, rf=0.0, required_return=0.0, periods=252):
69
    """
70
    Calculate Omega ratio - probability-weighted ratio of gains vs losses.
71
    
72
    Parameters:
73
    - returns: pandas Series of returns
74
    - rf: float, risk-free rate
75
    - required_return: float, required return threshold
76
    - periods: int, number of periods per year
77
    
78
    Returns:
79
    float: Omega ratio
80
    """
81
```
82

83
### Rolling Performance Metrics
84

85
Time-varying performance metrics calculated over rolling windows.
86

87
```python { .api }
88
def rolling_sharpe(returns, rf=0, periods=252, window=126, annualize=True, prepare_returns=True):
89
    """
90
    Calculate rolling Sharpe ratio over a specified window.
91
    
92
    Parameters:
93
    - returns: pandas Series of returns
94
    - rf: float, risk-free rate
95
    - periods: int, number of periods per year
96
    - window: int, rolling window size
97
    - annualize: bool, whether to annualize the result
98
    - prepare_returns: bool, whether to prepare returns data
99
    
100
    Returns:
101
    pandas Series: Rolling Sharpe ratios
102
    """
103

104
def rolling_sortino(returns, rf=0, periods=252, window=126, annualize=True, prepare_returns=True):
105
    """
106
    Calculate rolling Sortino ratio over a specified window.
107
    
108
    Parameters:
109
    - returns: pandas Series of returns  
110
    - rf: float, risk-free rate
111
    - periods: int, number of periods per year
112
    - window: int, rolling window size
113
    - annualize: bool, whether to annualize the result
114
    - prepare_returns: bool, whether to prepare returns data
115
    
116
    Returns:
117
    pandas Series: Rolling Sortino ratios
118
    """
119

120
def rolling_volatility(returns, periods=252, window=126, min_periods=None, annualize=True, prepare_returns=True):
121
    """
122
    Calculate rolling volatility over a specified window.
123
    
124
    Parameters:
125
    - returns: pandas Series of returns
126
    - periods: int, number of periods per year
127
    - window: int, rolling window size
128
    - min_periods: int, minimum periods required for calculation
129
    - annualize: bool, whether to annualize the result
130
    - prepare_returns: bool, whether to prepare returns data
131
    
132
    Returns:
133
    pandas Series: Rolling volatilities
134
    """
135
```
136

137
### Return Analysis
138

139
Functions for analyzing return characteristics and patterns.
140

141
```python { .api }
142
def cagr(returns, rf=0.0, compounded=True, periods=252):
143
    """
144
    Calculate Compound Annual Growth Rate.
145
    
146
    Parameters:
147
    - returns: pandas Series of returns
148
    - rf: float, risk-free rate
149
    - compounded: bool, whether returns are compounded
150
    - periods: int, number of periods per year
151
    
152
    Returns:
153
    float: CAGR
154
    """
155

156
def volatility(returns, periods=252, annualize=True, prepare_returns=True):
157
    """
158
    Calculate volatility (standard deviation of returns).
159
    
160
    Parameters:
161
    - returns: pandas Series of returns
162
    - periods: int, number of periods per year
163
    - annualize: bool, whether to annualize the result
164
    - prepare_returns: bool, whether to prepare returns data
165
    
166
    Returns:
167
    float: Volatility
168
    """
169

170
def expected_return(returns, aggregate=None, compounded=True, prepare_returns=True):
171
    """
172
    Calculate expected return of the asset.
173
    
174
    Parameters:
175
    - returns: pandas Series of returns
176
    - aggregate: str, aggregation method (None, 'M', 'Q', 'Y')
177
    - compounded: bool, whether returns are compounded
178
    - prepare_returns: bool, whether to prepare returns data
179
    
180
    Returns:
181
    float: Expected return
182
    """
183

184
def skew(returns, prepare_returns=True):
185
    """
186
    Calculate skewness of returns distribution.
187
    
188
    Parameters:
189
    - returns: pandas Series of returns
190
    - prepare_returns: bool, whether to prepare returns data
191
    
192
    Returns:
193
    float: Skewness
194
    """
195

196
def kurtosis(returns, prepare_returns=True):
197
    """
198
    Calculate kurtosis of returns distribution.
199
    
200
    Parameters:
201
    - returns: pandas Series of returns
202
    - prepare_returns: bool, whether to prepare returns data
203
    
204
    Returns:
205
    float: Kurtosis
206
    """
207
```
208

209
### Win/Loss Analysis
210

211
Analysis of winning and losing periods and their characteristics.
212

213
```python { .api }
214
def win_rate(returns, aggregate=None, compounded=True, prepare_returns=True):
215
    """
216
    Calculate win rate (percentage of positive returns).
217
    
218
    Parameters:
219
    - returns: pandas Series of returns
220
    - aggregate: str, aggregation method
221
    - compounded: bool, whether returns are compounded
222
    - prepare_returns: bool, whether to prepare returns data
223
    
224
    Returns:
225
    float: Win rate as percentage
226
    """
227

228
def avg_win(returns, aggregate=None, compounded=True, prepare_returns=True):
229
    """
230
    Calculate average winning return.
231
    
232
    Parameters:
233
    - returns: pandas Series of returns
234
    - aggregate: str, aggregation method
235
    - compounded: bool, whether returns are compounded
236
    - prepare_returns: bool, whether to prepare returns data
237
    
238
    Returns:
239
    float: Average winning return
240
    """
241

242
def avg_loss(returns, aggregate=None, compounded=True, prepare_returns=True):
243
    """
244
    Calculate average losing return.
245
    
246
    Parameters:
247
    - returns: pandas Series of returns
248
    - aggregate: str, aggregation method
249
    - compounded: bool, whether returns are compounded
250
    - prepare_returns: bool, whether to prepare returns data
251
    
252
    Returns:
253
    float: Average losing return
254
    """
255

256
def consecutive_wins(returns, aggregate=None, compounded=True, prepare_returns=True):
257
    """
258
    Calculate maximum consecutive winning periods.
259
    
260
    Parameters:
261
    - returns: pandas Series of returns
262
    - aggregate: str, aggregation method
263
    - compounded: bool, whether returns are compounded
264
    - prepare_returns: bool, whether to prepare returns data
265
    
266
    Returns:
267
    int: Maximum consecutive wins
268
    """
269

270
def consecutive_losses(returns, aggregate=None, compounded=True, prepare_returns=True):
271
    """
272
    Calculate maximum consecutive losing periods.
273
    
274
    Parameters:
275
    - returns: pandas Series of returns
276
    - aggregate: str, aggregation method
277
    - compounded: bool, whether returns are compounded
278
    - prepare_returns: bool, whether to prepare returns data
279
    
280
    Returns:
281
    int: Maximum consecutive losses
282
    """
283
```
284

285
### Drawdown Analysis
286

287
Analysis of portfolio drawdowns and recovery patterns.
288

289
```python { .api }
290
def max_drawdown(prices):
291
    """
292
    Calculate maximum drawdown from peak to trough.
293
    
294
    Parameters:
295
    - prices: pandas Series of prices or cumulative returns
296
    
297
    Returns:
298
    float: Maximum drawdown as negative percentage
299
    """
300

301
def to_drawdown_series(returns):
302
    """
303
    Convert returns to drawdown series.
304
    
305
    Parameters:
306
    - returns: pandas Series of returns
307
    
308
    Returns:
309
    pandas Series: Drawdown series
310
    """
311

312
def drawdown_details(drawdown):
313
    """
314
    Analyze drawdown periods in detail.
315
    
316
    Parameters:
317
    - drawdown: pandas Series of drawdown values
318
    
319
    Returns:
320
    pandas DataFrame: Detailed drawdown analysis with start, end, duration, and magnitude
321
    """
322
```
323

324
### Benchmarking Functions
325

326
Functions for comparing portfolio performance against benchmarks.
327

328
```python { .api }
329
def r_squared(returns, benchmark, prepare_returns=True):
330
    """
331
    Calculate R-squared coefficient against benchmark.
332
    
333
    Parameters:
334
    - returns: pandas Series of portfolio returns
335
    - benchmark: pandas Series of benchmark returns
336
    - prepare_returns: bool, whether to prepare returns data
337
    
338
    Returns:
339
    float: R-squared value (0-1)
340
    """
341

342
def information_ratio(returns, benchmark, prepare_returns=True):
343
    """
344
    Calculate Information Ratio against benchmark.
345
    
346
    Parameters:
347
    - returns: pandas Series of portfolio returns
348
    - benchmark: pandas Series of benchmark returns
349
    - prepare_returns: bool, whether to prepare returns data
350
    
351
    Returns:
352
    float: Information ratio
353
    """
354

355
def greeks(returns, benchmark, periods=252.0, prepare_returns=True):
356
    """
357
    Calculate alpha and beta coefficients against benchmark.
358
    
359
    Parameters:
360
    - returns: pandas Series of portfolio returns
361
    - benchmark: pandas Series of benchmark returns
362
    - periods: float, number of periods per year
363
    - prepare_returns: bool, whether to prepare returns data
364
    
365
    Returns:
366
    dict: Dictionary with 'alpha' and 'beta' keys
367
    """
368

369
def rolling_greeks(returns, benchmark, periods=252, prepare_returns=True):
370
    """
371
    Calculate rolling alpha and beta coefficients.
372
    
373
    Parameters:
374
    - returns: pandas Series of portfolio returns
375
    - benchmark: pandas Series of benchmark returns
376
    - periods: int, number of periods per year
377
    - prepare_returns: bool, whether to prepare returns data
378
    
379
    Returns:
380
    pandas DataFrame: Rolling alpha and beta values
381
    """
382
```
383

384
### Advanced Statistical Measures
385

386
Sophisticated statistical metrics for in-depth analysis.
387

388
```python { .api }
389
def kelly_criterion(returns, prepare_returns=True):
390
    """
391
    Calculate Kelly Criterion for optimal position sizing.
392
    
393
    Parameters:
394
    - returns: pandas Series of returns
395
    - prepare_returns: bool, whether to prepare returns data
396
    
397
    Returns:
398
    float: Kelly Criterion percentage
399
    """
400

401
def gain_to_pain_ratio(returns, rf=0, resolution="D"):
402
    """
403
    Calculate gain-to-pain ratio.
404
    
405
    Parameters:
406
    - returns: pandas Series of returns
407
    - rf: float, risk-free rate
408
    - resolution: str, return resolution ('D', 'M', 'Q', 'Y')
409
    
410
    Returns:
411
    float: Gain-to-pain ratio
412
    """
413

414
def probabilistic_sharpe_ratio(returns, benchmark, periods=252.0, rf=0.0):
415
    """
416
    Calculate probabilistic Sharpe ratio.
417
    
418
    Parameters:
419
    - returns: pandas Series of portfolio returns
420
    - benchmark: pandas Series of benchmark returns
421
    - periods: float, number of periods per year
422
    - rf: float, risk-free rate
423
    
424
    Returns:
425
    float: Probabilistic Sharpe ratio
426
    """
427

428
def monthly_returns(returns, eoy=True, compounded=True, prepare_returns=True):
429
    """
430
    Generate monthly returns table.
431
    
432
    Parameters:
433
    - returns: pandas Series of returns
434
    - eoy: bool, whether to include end-of-year totals
435
    - compounded: bool, whether returns are compounded
436
    - prepare_returns: bool, whether to prepare returns data
437
    
438
    Returns:
439
    pandas DataFrame: Monthly returns table
440
    """
441
```