0
# FFN (Financial Functions for Python)
1

2
FFN is a comprehensive financial functions library for Python designed for quantitative finance professionals. It builds upon established data science libraries (Pandas, NumPy, SciPy) to offer utilities for performance measurement, evaluation, graphing, and common data transformations in financial analysis.
3

4
## Package Information
5

6
- **Package Name**: ffn
7
- **Package Type**: Library
8
- **Language**: Python
9
- **Installation**: `pip install ffn`
10

11
## Core Imports
12

13
```python
14
import ffn
15
```
16

17
Common usage patterns:
18

19
```python
20
# Import specific functions
21
from ffn import get, PerformanceStats, calc_perf_stats
22

23
# Data retrieval
24
import ffn.data as data
25

26
# Utils for formatting
27
from ffn.utils import fmtp, fmtn
28
```
29

30
## Basic Usage
31

32
```python
33
import ffn
34

35
# Download price data
36
prices = ffn.get('AAPL,MSFT,GOOGL', start='2020-01-01', end='2023-01-01')
37

38
# Calculate returns
39
returns = prices.to_returns().dropna()
40

41
# Performance analysis
42
perf = ffn.calc_perf_stats(prices['AAPL'])
43
print(perf.display())
44

45
# Portfolio optimization - equal risk contribution weights
46
weights = ffn.calc_erc_weights(returns)
47
print(weights)
48

49
# Risk metrics
50
sharpe = ffn.calc_sharpe(returns['AAPL'])
51
max_dd = ffn.calc_max_drawdown(prices['AAPL'])
52

53
print(f"AAPL Sharpe Ratio: {sharpe:.2f}")
54
print(f"AAPL Max Drawdown: {max_dd:.2%}")
55
```
56

57
## Architecture
58

59
FFN extends pandas objects automatically on import, enabling method chaining for functional composition:
60

61
```python
62
# Method chaining example
63
result = (prices
64
    .to_returns()
65
    .dropna()
66
    .calc_sharpe()
67
)
68
```
69

70
Key components:
71
- **PerformanceStats**: Comprehensive performance analysis for single series
72
- **GroupStats**: Comparative analysis for multiple series  
73
- **Data Module**: Financial data retrieval with Yahoo Finance integration
74
- **Pandas Extensions**: All functions available as pandas methods for chaining
75

76
## Capabilities
77

78
### Performance Analysis
79

80
Comprehensive performance evaluation with detailed statistics, risk metrics, and visualization capabilities for single assets or portfolios.
81

82
```python { .api }
83
class PerformanceStats:
84
    def __init__(self, prices, rf=0.0, annualization_factor=None): ...
85
    def display(self): ...
86
    def plot(self, freq='D', figsize=None, title=None, logy=False, **kwargs): ...
87

88
class GroupStats:
89
    def __init__(self, *prices): ...
90
    def display(self): ...
91
    def plot(self, freq='D', figsize=None, title=None, logy=False, **kwargs): ...
92

93
def calc_perf_stats(prices, risk_free_rate=0.0, annualization_factor=252): ...
94
def calc_stats(prices): ...
95
```
96

97
[Performance Analysis](./performance-analysis.md)
98

99
### Return Calculations
100

101
Convert between prices and returns using various methods, including simple returns, log returns, and price indexing with rebasing capabilities.
102

103
```python { .api }
104
def to_returns(prices): ...
105
def to_log_returns(prices): ...
106
def to_price_index(returns, start=100): ...
107
def rebase(prices, value=100): ...
108
```
109

110
[Return Calculations](./return-calculations.md)
111

112
### Risk Metrics
113

114
Calculate comprehensive risk measures including drawdowns, volatility-based ratios, and downside risk metrics for portfolio evaluation.
115

116
```python { .api }
117
def calc_max_drawdown(prices): ...
118
def to_drawdown_series(prices): ...
119
def calc_sharpe(returns, rf=0.0, nperiods=None, annualize=True): ...
120
def calc_sortino_ratio(returns, rf=0.0, nperiods=None, annualize=True): ...
121
def calc_calmar_ratio(prices): ...
122
def to_ulcer_index(prices): ...
123
```
124

125
[Risk Metrics](./risk-metrics.md)
126

127
### Portfolio Optimization
128

129
Modern portfolio theory implementations including mean-variance optimization, risk parity approaches, and weight constraint utilities.
130

131
```python { .api }
132
def calc_mean_var_weights(returns, weight_bounds=(0.0, 1.0), rf=0.0, covar_method="ledoit-wolf", options=None): ...
133
def calc_erc_weights(returns, initial_weights=None, risk_weights=None, covar_method="ledoit-wolf", risk_parity_method="ccd", maximum_iterations=100, tolerance=1e-8): ...
134
def calc_inv_vol_weights(returns): ...
135
def limit_weights(weights, limit=0.1): ...
136
```
137

138
[Portfolio Optimization](./portfolio-optimization.md)
139

140
### Data Retrieval
141

142
Financial data downloading with Yahoo Finance integration, CSV support, and flexible data provider architecture.
143

144
```python { .api }
145
def get(tickers, provider=None, common_dates=True, forward_fill=False, clean_tickers=True, column_names=None, ticker_field_sep=":", mrefresh=False, existing=None, **kwargs): ...
146

147
def yf(ticker, field, start=None, end=None, mrefresh=False): ...
148
def csv(ticker, path="data.csv", field="", mrefresh=False, **kwargs): ...
149
```
150

151
[Data Retrieval](./data-retrieval.md)
152

153
### Statistical Analysis
154

155
Advanced statistical tools including clustering algorithms, bootstrap resampling, and momentum calculations for quantitative research.
156

157
```python { .api }
158
def calc_clusters(returns, n=None, plot=False): ...
159
def calc_ftca(returns, threshold=0.5): ...
160
def calc_prob_mom(returns, other_returns): ...
161
def resample_returns(returns, func, seed=0, num_trials=100): ...
162
```
163

164
[Statistical Analysis](./statistical-analysis.md)
165

166
### Data Utilities
167

168
Data processing utilities including frequency conversion, merging, winsorization, and date calculations for financial time series.
169

170
```python { .api }
171
def merge(*series): ...
172
def to_monthly(series, method="ffill", how="end"): ...
173
def winsorize(x, axis=0, limits=0.01): ...
174
def year_frac(start, end): ...
175
def calc_mtd(daily_prices, monthly_prices): ...
176
def calc_ytd(daily_prices, yearly_prices): ...
177
def infer_freq(data): ...
178
def infer_nperiods(data, annualization_factor=None): ...
179
```
180

181
[Data Utilities](./data-utilities.md)
182

183
### Pandas Extensions
184

185
FFN automatically extends pandas Series and DataFrame objects with all financial analysis methods, enabling seamless method chaining and functional composition.
186

187
```python { .api }
188
def extend_pandas(): ...
189

190
# All FFN functions become available as pandas methods:
191
Series.to_returns(): ...
192
Series.calc_sharpe(rf=0.0, nperiods=None, annualize=True): ...
193
Series.calc_perf_stats(rf=0.0, annualization_factor=252): ...
194
DataFrame.calc_erc_weights(): ...
195
DataFrame.plot_corr_heatmap(): ...
196
# ... and 35+ additional methods
197
```
198

199
[Pandas Extensions](./pandas-extensions.md)
200

201
## Types
202

203
```python { .api }
204
# Core constant
205
TRADING_DAYS_PER_YEAR: int = 252
206

207
# Main classes (see Performance Analysis section for details)
208
class PerformanceStats: ...
209
class GroupStats: ...
210
```