empyrical Documentation

Install the empyrical package using pip to access common financial risk metrics.

pip install empyrical

Support for data reading via pandas-datareader and other third-party libraries is deprecated due to instability in Yahoo Finance and Google Finance APIs. The following functions in empyrical.utils are deprecated and may fail regularly:

• empyrical.utils.cache_dir
• empyrical.utils.data_path
• empyrical.utils.ensure_directory
• empyrical.utils.get_fama_french
• empyrical.utils.load_portfolio_risk_factors
• empyrical.utils.default_returns_func
• empyrical.utils.get_symbol_returns_from_yahoo

The library supports Pandas Series for calculating capture ratios. Use capture for a single ratio and roll_up_capture to calculate capture for up markets on a rolling basis (e.g., a 60-day window).

import pandas as pd
from empyrical import roll_up_capture, capture

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

# calculate a capture ratio
capture(returns)

# calculate capture for up markets on a rolling 60 day basis
roll_up_capture(returns, window=60)

Use roll_max_drawdown to calculate the maximum drawdown over a rolling window. The window parameter specifies the size of the rolling window.

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)

Use max_drawdown to find the maximum drawdown of a returns series and alpha_beta to calculate the alpha and beta coefficients relative to a benchmark. These functions accept NumPy arrays as input.

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)