0
# Parameter Estimation
1

2
Statistical methods for estimating expected returns, covariance matrices, factor models, and implementing Black-Litterman and other advanced estimation techniques for portfolio optimization input parameters.
3

4
## Capabilities
5

6
### Expected Returns Estimation
7

8
Methods for estimating expected returns using various statistical approaches.
9

10
```python { .api }
11
def mean_vector(X, method='hist', d=0.94, **kwargs):
12
    """
13
    Calculate expected returns vector.
14
    
15
    Parameters:
16
    - X (DataFrame): Returns data
17
    - method (str): Estimation method ('hist', 'ewma1', 'ewma2')
18
    - d (float): Decay factor for EWMA methods
19
    
20
    Returns:
21
    DataFrame: Expected returns vector
22
    """
23
```
24

25
### Covariance Matrix Estimation
26

27
Methods for estimating covariance matrices with various shrinkage and robust estimation techniques.
28

29
```python { .api }
30
def covar_matrix(X, method='hist', d=0.94, **kwargs):
31
    """
32
    Calculate covariance matrix.
33
    
34
    Parameters:
35
    - X (DataFrame): Returns data
36
    - method (str): Estimation method ('hist', 'ewma1', 'ewma2', 'ledoit', 'oas', 
37
                   'shrunk', 'gl', 'jlogo', 'fixed', 'spectral', 'shrink')
38
    - d (float): Decay factor for EWMA methods
39
    
40
    Returns:
41
    DataFrame: Covariance matrix
42
    """
43

44
def cokurt_matrix(X, method='hist', **kwargs):
45
    """
46
    Calculate cokurtosis matrix.
47
    
48
    Parameters:
49
    - X (DataFrame): Returns data
50
    - method (str): Estimation method
51
    
52
    Returns:
53
    DataFrame: Cokurtosis matrix
54
    """
55
```
56

57
### Factor Models
58

59
Methods for factor model construction and factor loading estimation.
60

61
```python { .api }
62
def loadings_matrix(X, Y, method='stepwise', p_value=0.05, **kwargs):
63
    """
64
    Calculate factor loadings matrix using regression methods.
65
    
66
    Parameters:
67
    - X (DataFrame): Asset returns
68
    - Y (DataFrame): Factor returns
69
    - method (str): Regression method ('stepwise', 'PCR', 'forward', 'backward')
70
    - p_value (float): P-value threshold for stepwise methods
71
    
72
    Returns:
73
    DataFrame: Factor loadings matrix
74
    """
75

76
def risk_factors(X, B=None, method="stepwise", p_value=0.05, **kwargs):
77
    """
78
    Estimate risk factors from returns data.
79
    
80
    Parameters:
81
    - X (DataFrame): Asset returns
82
    - B (DataFrame): Factor loadings (optional)
83
    - method (str): Factor estimation method
84
    - p_value (float): P-value threshold
85
    
86
    Returns:
87
    DataFrame: Risk factors
88
    """
89

90
def forward_regression(X, Y, criterion='pvalue', threshold=0.05, verbose=False):
91
    """
92
    Forward stepwise regression for factor selection.
93
    
94
    Parameters:
95
    - X (DataFrame): Predictor variables (factors)
96
    - Y (DataFrame): Response variable (returns)
97
    - criterion (str): Selection criterion ('pvalue', 'AIC', 'BIC', 'R2')
98
    - threshold (float): Threshold for inclusion
99
    - verbose (bool): Print progress
100
    
101
    Returns:
102
    tuple: (selected_factors, regression_results)
103
    """
104

105
def backward_regression(X, Y, criterion='pvalue', threshold=0.05, verbose=False):
106
    """
107
    Backward stepwise regression for factor selection.
108
    
109
    Parameters:
110
    - X (DataFrame): Predictor variables (factors)
111
    - Y (DataFrame): Response variable (returns)
112
    - criterion (str): Selection criterion ('pvalue', 'AIC', 'BIC', 'R2')
113
    - threshold (float): Threshold for removal
114
    - verbose (bool): Print progress
115
    
116
    Returns:
117
    tuple: (selected_factors, regression_results)
118
    """
119

120
def PCR(X, Y, n_components=0.95):
121
    """
122
    Principal Component Regression.
123
    
124
    Parameters:
125
    - X (DataFrame): Predictor variables
126
    - Y (DataFrame): Response variable
127
    - n_components (float or int): Number of components or variance ratio
128
    
129
    Returns:
130
    tuple: (loadings, principal_components, explained_variance)
131
    """
132
```
133

134
### Black-Litterman Models
135

136
Implementation of Black-Litterman and augmented Black-Litterman models for incorporating views into portfolio optimization.
137

138
```python { .api }
139
def black_litterman(X_hist, P, Q, delta=None, eq=True, rf=0, w=None, **kwargs):
140
    """
141
    Black-Litterman model for expected returns.
142
    
143
    Parameters:
144
    - X_hist (DataFrame): Historical returns
145
    - P (DataFrame): Picking matrix (views)
146
    - Q (DataFrame): Views vector (expected excess returns)
147
    - delta (float): Risk aversion parameter
148
    - eq (bool): Use equilibrium returns as prior
149
    - rf (float): Risk-free rate
150
    - w (DataFrame): Market cap weights for equilibrium returns
151
    
152
    Returns:
153
    tuple: (expected_returns, covariance_matrix)
154
    """
155

156
def augmented_black_litterman(X_hist, P, Q, delta=None, eq=True, rf=0, w=None, **kwargs):
157
    """
158
    Augmented Black-Litterman model with factor structure.
159
    
160
    Parameters:
161
    - X_hist (DataFrame): Historical returns
162
    - P (DataFrame): Picking matrix
163
    - Q (DataFrame): Views vector  
164
    - delta (float): Risk aversion parameter
165
    - eq (bool): Use equilibrium returns
166
    - rf (float): Risk-free rate
167
    - w (DataFrame): Market weights
168
    
169
    Returns:
170
    tuple: (expected_returns, covariance_matrix, factor_loadings)
171
    """
172

173
def black_litterman_bayesian(X_hist, P, Q, Omega, tau=0.05, rf=0, w=None):
174
    """
175
    Bayesian Black-Litterman model.
176
    
177
    Parameters:
178
    - X_hist (DataFrame): Historical returns
179
    - P (DataFrame): Picking matrix
180
    - Q (DataFrame): Views vector
181
    - Omega (DataFrame): Uncertainty matrix of views
182
    - tau (float): Scaling factor for prior uncertainty
183
    - rf (float): Risk-free rate
184
    - w (DataFrame): Market weights
185
    
186
    Returns:
187
    tuple: (posterior_returns, posterior_covariance)
188
    """
189
```
190

191
### Simulation and Resampling
192

193
Methods for bootstrapping and Monte Carlo simulation of portfolio parameters.
194

195
```python { .api }
196
def bootstrapping(X, size=1000, n_sim=1000, replace=True, random_state=None):
197
    """
198
    Bootstrap resampling of returns data.
199
    
200
    Parameters:
201
    - X (DataFrame): Returns data
202
    - size (int): Sample size for each bootstrap
203
    - n_sim (int): Number of bootstrap simulations
204
    - replace (bool): Sample with replacement
205
    - random_state (int): Random seed
206
    
207
    Returns:
208
    list: Bootstrap samples
209
    """
210

211
def normal_simulation(mu, cov, size=1000, n_sim=1000, random_state=None):
212
    """
213
    Normal distribution simulation.
214
    
215
    Parameters:
216
    - mu (DataFrame): Mean returns
217
    - cov (DataFrame): Covariance matrix
218
    - size (int): Sample size per simulation
219
    - n_sim (int): Number of simulations
220
    - random_state (int): Random seed
221
    
222
    Returns:
223
    DataFrame: Simulated returns
224
    """
225
```
226

227
## Usage Examples
228

229
### Basic Parameter Estimation
230

231
```python
232
import riskfolio as rp
233
import pandas as pd
234

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

238
# Historical estimates
239
mu_hist = rp.mean_vector(returns, method='hist')
240
cov_hist = rp.covar_matrix(returns, method='hist')
241

242
# EWMA estimates with custom decay
243
mu_ewma = rp.mean_vector(returns, method='ewma1', d=0.94)
244
cov_ewma = rp.covar_matrix(returns, method='ewma1', d=0.94)
245

246
# Ledoit-Wolf shrinkage covariance
247
cov_ledoit = rp.covar_matrix(returns, method='ledoit')
248

249
print("Historical Mean Returns:")
250
print(mu_hist.head())
251
print("\nEWMA Covariance (5x5):")
252
print(cov_ewma.iloc[:5, :5])
253
```
254

255
### Factor Model Construction
256

257
```python
258
import riskfolio as rp
259
import pandas as pd
260

261
# Load asset and factor returns
262
returns = pd.read_csv('returns.csv', index_col=0, parse_dates=True)
263
factors = pd.read_csv('factors.csv', index_col=0, parse_dates=True)  # e.g., Fama-French factors
264

265
# Estimate factor loadings using stepwise regression
266
loadings = rp.loadings_matrix(
267
    X=returns,
268
    Y=factors,
269
    method='stepwise',
270
    p_value=0.05
271
)
272

273
# Forward regression for factor selection
274
selected_factors, results = rp.forward_regression(
275
    X=factors,
276
    Y=returns['AAPL'],  # Single asset example
277
    criterion='pvalue',
278
    threshold=0.05,
279
    verbose=True
280
)
281

282
print("Factor Loadings:")
283
print(loadings.head())
284
print(f"\nSelected Factors for AAPL: {selected_factors}")
285
```
286

287
### Black-Litterman Implementation
288

289
```python
290
import riskfolio as rp
291
import pandas as pd
292
import numpy as np
293

294
# Load returns and market cap data
295
returns = pd.read_csv('returns.csv', index_col=0, parse_dates=True)
296
market_caps = pd.read_csv('market_caps.csv', index_col=0)
297

298
# Create views: AAPL will outperform MSFT by 2% annually
299
P = pd.DataFrame(0, index=['View1'], columns=returns.columns)
300
P.loc['View1', 'AAPL'] = 1
301
P.loc['View1', 'MSFT'] = -1
302

303
Q = pd.DataFrame([0.02], index=['View1'], columns=['Views'])
304

305
# Market cap weights (equilibrium portfolio)
306
w_market = market_caps / market_caps.sum()
307

308
# Apply Black-Litterman
309
mu_bl, cov_bl = rp.black_litterman(
310
    X_hist=returns,
311
    P=P,
312
    Q=Q,
313
    delta=None,  # Will be estimated
314
    eq=True,
315
    rf=0.02,
316
    w=w_market
317
)
318

319
print("Black-Litterman Expected Returns:")
320
print(mu_bl.head())
321

322
# Use in portfolio optimization
323
port = rp.Portfolio(returns=returns)
324
port.mu = mu_bl
325
port.cov = cov_bl
326

327
w_bl = port.optimization(model='Classic', rm='MV', obj='Sharpe', rf=0.02)
328
print("\nBlack-Litterman Optimal Weights:")
329
print(w_bl.head())
330
```
331

332
### Bootstrap Analysis
333

334
```python
335
import riskfolio as rp
336
import pandas as pd
337
import numpy as np
338

339
# Load returns
340
returns = pd.read_csv('returns.csv', index_col=0, parse_dates=True)
341

342
# Bootstrap resampling
343
bootstrap_samples = rp.bootstrapping(
344
    X=returns,
345
    size=252,  # One year of daily returns
346
    n_sim=1000,
347
    replace=True,
348
    random_state=42
349
)
350

351
# Calculate bootstrap statistics
352
bootstrap_means = [sample.mean() for sample in bootstrap_samples]
353
bootstrap_vars = [sample.var() for sample in bootstrap_samples]
354

355
# Convert to DataFrame for analysis
356
bootstrap_stats = pd.DataFrame({
357
    'Mean': bootstrap_means,
358
    'Variance': bootstrap_vars
359
})
360

361
print("Bootstrap Statistics Summary:")
362
print(bootstrap_stats.describe())
363

364
# Monte Carlo simulation
365
mu = returns.mean()
366
cov = returns.cov()
367

368
simulated_returns = rp.normal_simulation(
369
    mu=mu,
370
    cov=cov,
371
    size=252,
372
    n_sim=1000,
373
    random_state=42
374
)
375

376
print("\nSimulated Returns Shape:", simulated_returns.shape)
377
print("Simulated vs Historical Mean:")
378
print(pd.DataFrame({
379
    'Historical': mu,
380
    'Simulated': simulated_returns.mean()
381
}).head())
382
```
383

384
## Estimation Methods
385

386
### Covariance Estimation Methods
387

388
- **hist**: Historical (sample) covariance
389
- **ewma1**: Exponentially weighted moving average (RiskMetrics)
390
- **ewma2**: Exponentially weighted moving average (alternative)
391
- **ledoit**: Ledoit-Wolf shrinkage estimator
392
- **oas**: Oracle Approximating Shrinkage estimator
393
- **shrunk**: Shrunk covariance estimator
394
- **gl**: Graphical Lasso (sparse inverse covariance)
395
- **jlogo**: J-LoGo robust estimator
396
- **fixed**: Fixed correlation structure
397
- **spectral**: Spectral risk model
398
- **shrink**: General shrinkage estimator
399

400
### Factor Selection Criteria
401

402
- **pvalue**: Statistical significance (p-value)
403
- **AIC**: Akaike Information Criterion
404
- **BIC**: Bayesian Information Criterion  
405
- **R2**: Coefficient of determination (R-squared)