Skip to main content

empyrical computes performance and risk statistics commonly used in quantitative finance

Project description

PyPI PyPI - Downloads

Conda Version Conda Downloads

PyPI Wheels Conda packages CI Tests

Common financial return and risk metrics in Python.

Installation

empyrical requires Python 3.10+. 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.23.5
  • pandas>=1.3.0
  • scipy>=0.15.1

Note that Numpy>=2.0 requires pandas>=2.2.2. If you are using an older version of pandas, you may need to upgrade accordingly, otherwise you may encounter compatibility issues.

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

Empyrical downloads Fama-French risk factors from 1970 onward:

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()

pd.concat([risk_factors.head(), risk_factors.tail()])

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 - 0
8
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


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

empyrical_reloaded-0.5.12.tar.gz (84.3 kB view details)

Uploaded Source

Built Distribution

empyrical_reloaded-0.5.12-py3-none-any.whl (33.0 kB view details)

Uploaded Python 3

File details

Details for the file empyrical_reloaded-0.5.12.tar.gz.

File metadata

  • Download URL: empyrical_reloaded-0.5.12.tar.gz
  • Upload date:
  • Size: 84.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for empyrical_reloaded-0.5.12.tar.gz
Algorithm Hash digest
SHA256 e01f0bbf24f0aaab2767c85a7dee8f05a59d25355cf50c3371efda056613e323
MD5 250231b3edd0dacce85eba636e548a34
BLAKE2b-256 97432dd510760e12fb9a07d2ab4dcf67f263e6eb103c73285d040005fe3d5da9

See more details on using hashes here.

File details

Details for the file empyrical_reloaded-0.5.12-py3-none-any.whl.

File metadata

File hashes

Hashes for empyrical_reloaded-0.5.12-py3-none-any.whl
Algorithm Hash digest
SHA256 1bd8b53810c760ae5a12a03f2cefc6af0e905f854b71e7d99074b673abdd4fd6
MD5 4329b69a33ed0e1f8c5c94b2f3116981
BLAKE2b-256 695423d8f6d36c66575b8d31e354c8bba2c857f9ca41e4b76388c6ca53938fd8

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page