empyrical computes performance and risk statistics commonly used in quantitative finance

## Project description

Common financial return and risk metrics in Python.

## Installation

empyrical requires Python 3.9+. You can install it using pip:

pip install empyrical-reloaded


or conda from the conda-forge channel

conda install empyrical-reloaded -c conda-forge


empyrical requires and installs the following packages while executing the above commands:

• numpy>=1.9.2
• pandas>=1.0.0
• scipy>=0.15.1

Optional dependencies include yfinance to download price data from Yahoo! Finance and pandas-datareader to access Fama-French risk factors and FRED treasury yields.

Note that pandas-datareader is not compatible with Python>=3.12.

To install the optional dependencies, use:

pip install empyrical-reloaded[yfinance]


or

pip install empyrical-reloaded[datreader]


or

pip install empyrical-reloaded[yfinance,datreader]


## Usage

### Simple Statistics

Empyrical computes basic metrics from returns and volatility to alpha and beta, Value at Risk, and Shorpe or Sortino ratios.

import numpy as np
from empyrical import max_drawdown, alpha_beta

returns = np.array([.01, .02, .03, -.4, -.06, -.02])
benchmark_returns = np.array([.02, .02, .03, -.35, -.05, -.01])

# calculate the max drawdown
max_drawdown(returns)

# calculate alpha and beta
alpha, beta = alpha_beta(returns, benchmark_returns)


### Rolling Measures

Empyrical also aggregates return and risk metrics for rolling windows:

import numpy as np
from empyrical import roll_max_drawdown

returns = np.array([.01, .02, .03, -.4, -.06, -.02])

# calculate the rolling max drawdown
roll_max_drawdown(returns, window=3)


### Pandas Support

Empyrical also works with both NumPy arrays and Pandas data structures:

import pandas as pd
from empyrical import roll_up_capture, capture

returns = pd.Series([.01, .02, .03, -.4, -.06, -.02])
factor_returns = pd.Series([.02, .01, .03, -.01, -.02, .02])

# calculate a capture ratio
capture(returns, factor_returns)
-0.147387712263491


### Fama-French Risk Factors

Note: requires optional dependency pandas-datareader - see installation instructions above.gst

import pandas as pd
import empyrical as emp

risk_factors = emp.utils.get_fama_french()

Mkt-RF     SMB     HML       RF     Mom
Date
1970-01-02 00:00:00+00:00  0.0118  0.0129  0.0101  0.00029 -0.0340
1970-01-05 00:00:00+00:00  0.0059  0.0067  0.0072  0.00029 -0.0153
1970-01-06 00:00:00+00:00 -0.0074  0.0010  0.0021  0.00029  0.0038
1970-01-07 00:00:00+00:00 -0.0015  0.0040 -0.0033  0.00029  0.0011
1970-01-08 00:00:00+00:00  0.0004  0.0018 -0.0017  0.00029  0.0033
2024-03-22 00:00:00+00:00 -0.0023 -0.0087 -0.0053  0.00021  0.0043
2024-03-25 00:00:00+00:00 -0.0026 -0.0024  0.0088  0.00021 -0.0034
2024-03-26 00:00:00+00:00 -0.0026  0.0009 -0.0013  0.00021  0.0009
2024-03-27 00:00:00+00:00  0.0088  0.0104  0.0091  0.00021 -0.0134
2024-03-28 00:00:00+00:00  0.0010  0.0029  0.0048  0.00021 -0.0044


### Asset Prices and Benchmark Returns

Empyrical use yfinance to download price data from Yahoo! Finance. To obtain the S&P returns since 1950, use:

Note: requires optional dependency yfinance - see installation instructions above.

import empyrical as emp

symbol = '^GSPC'
returns = emp.utils.get_symbol_returns_from_yahoo(symbol,
start='1950-01-01')

import seaborn as sns  # requires separate installation
import matplotlib.pyplot as plt  # requires separate installation

fig, axes = plt.subplots(ncols=2, figsize=(14, 5))

with sns.axes_style('whitegrid'):
returns.plot(ax=axes[0], rot=0, title='Time Series', legend=False)
sns.histplot(returns, ax=axes[1], legend=False)
axes[1].set_title('Histogram')
sns.despine()
plt.tight_layout()
plt.suptitle('Daily S&P 500 Returns')


### Documentation

See the documentation for details on the API.

## Support

Please open an issue for support.

## Contributing

Please contribute using Github Flow. Create a branch, add commits, and open a pull request.

## Testing

• install requirements
• "pytest>=6.2.0",
pytest tests


## Project details

Uploaded Source
Uploaded Python 3