API Reference¶

empyrical.cum_returns(returns, starting_value=0)[source]¶

Compute cumulative returns from simple returns.

Parameters:	returns : pandas.Series Returns of the strategy as a percentage, noncumulative. Time series with decimal returns. Example: 2015-07-16 -0.012143 2015-07-17 0.045350 2015-07-20 0.030957 2015-07-21 0.004902. starting_value : float, optional The starting returns.
Returns:	pandas.Series Series of cumulative returns.

Notes

For increased numerical accuracy, convert input to log returns where it is possible to sum instead of multiplying. PI((1+r_i)) - 1 = exp(ln(PI(1+r_i))) # x = exp(ln(x))

= exp(SIGMA(ln(1+r_i)) # ln(a*b) = ln(a) + ln(b)

empyrical.aggregate_returns(returns, convert_to)[source]¶

Aggregates returns by week, month, or year.

Parameters:	returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). convert_to : str Can be ‘weekly’, ‘monthly’, or ‘yearly’.
Returns:	pandas.Series Aggregated returns.

empyrical.max_drawdown(returns)[source]¶

Determines the maximum drawdown of a strategy.

Parameters:	returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns().
Returns:	float Maximum drawdown.

empyrical.annual_return(returns, period='daily', annualization=None)[source]¶

Determines the mean annual growth rate of returns.

Parameters:

returns : pandas.Series Periodic returns of the strategy, noncumulative. See full explanation in cum_returns(). period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. Defaults are: {'monthly':12 'weekly': 52 'daily': 252} annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns:

float Annual Return as CAGR (Compounded Annual Growth Rate).

empyrical.annual_volatility(returns, period='daily', alpha=2.0, annualization=None)[source]¶

Determines the annual volatility of a strategy.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). alpha : float, optional Scaling relation (Levy stability exponent). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns:

float Annual volatility.

empyrical.calmar_ratio(returns, period='daily', annualization=None)[source]¶

Determines the Calmar ratio, or drawdown ratio, of a strategy.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns:

float Calmar ratio (drawdown ratio) as float. Returns numpy.nan if there is no calmar ratio.

empyrical.omega_ratio(returns, risk_free=0.0, required_return=0.0, annualization=252)[source]¶

Determines the Omega ratio of a strategy.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). risk_free : int, float Constant risk-free return throughout the period required_return : float, optional Minimum acceptance return of the investor. Threshold over which to consider positive vs negative returns. It will be converted to a value appropriate for the period of the returns. E.g. An annual minimum acceptable return of 100 will translate to a minimum acceptable return of 0.018. annualization : int, optional Factor used to convert the required_return into a daily value. Enter 1 if no time period conversion is necessary.

Returns:

float Omega ratio.

empyrical.sharpe_ratio(returns, risk_free=0, period='daily', annualization=None)[source]¶

Determines the Sharpe ratio of a strategy.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). risk_free : int, float Constant risk-free return throughout the period. period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns:

float Sharpe ratio. numpy.nan If insufficient length of returns or if if adjusted returns are 0.

empyrical.sortino_ratio(returns, required_return=0, period='daily', annualization=None, _downside_risk=None)[source]¶

Determines the Sortino ratio of a strategy.

Parameters:

returns : pandas.Series or pd.DataFrame Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). required_return: :class:`float` / :py:class:`pandas.Series` minimum acceptable return period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns. _downside_risk : float, optional The downside risk of the given inputs, if known. Will be calculated if not provided.

Returns:

float or pandas.Series Annualized Sortino ratio.

empyrical.downside_risk(returns, required_return=0, period='daily', annualization=None)[source]¶

Determines the downside deviation below a threshold

Parameters:

returns : pandas.Series or pd.DataFrame Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). required_return: :class:`float` / :py:class:`pandas.Series` minimum acceptable return period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns:

float, or pandas.Series Annualized downside deviation

empyrical.information_ratio(returns, factor_returns)[source]¶

Determines the Information ratio of a strategy.

Parameters:	returns : pandas.Series or pd.DataFrame Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). factor_returns: :class:`float` / :py:class:`pandas.Series` Benchmark return to compare returns against.
Returns:	float The information ratio.

empyrical.alpha_beta(returns, factor_returns, risk_free=0.0, period='daily', annualization=None)[source]¶

Calculates annualized alpha and beta.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). factor_returns : pandas.Series Daily noncumulative returns of the factor to which beta is computed. Usually a benchmark such as the market. This is in the same style as returns. risk_free : int, float, optional Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill. period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns:

float Alpha. float Beta.

empyrical.alpha(returns, factor_returns, risk_free=0.0, period='daily', annualization=None, _beta=None)[source]¶

Calculates annualized alpha.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). factor_returns : pandas.Series Daily noncumulative returns of the factor to which beta is computed. Usually a benchmark such as the market. This is in the same style as returns. risk_free : int, float, optional Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill. period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns. See full explanation in annual_return(). _beta : float, optional The beta for the given inputs, if already known. Will be calculated internally if not provided.

Returns:

float Alpha.

empyrical.beta(returns, factor_returns, risk_free=0.0)[source]¶

Calculates beta.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). factor_returns : pandas.Series Daily noncumulative returns of the factor to which beta is computed. Usually a benchmark such as the market. This is in the same style as returns. risk_free : int, float, optional Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

Returns:

float Beta.

empyrical.stability_of_timeseries(returns)[source]¶

Determines R-squared of a linear fit to the cumulative log returns. Computes an ordinary least squares linear fit, and returns R-squared.

Parameters:	returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns().
Returns:	float R-squared.

empyrical.tail_ratio(returns)[source]¶

Determines the ratio between the right (95%) and left tail (5%).

For example, a ratio of 0.25 means that losses are four times as bad as profits.

Parameters:	returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns().
Returns:	float tail ratio

empyrical.cagr(returns, period='daily', annualization=None)[source]¶

Compute compound annual growth rate.

Parameters:

returns : pandas.Series Daily returns of the strategy, noncumulative. See full explanation in cum_returns(). period : str, optional Defines the periodicity of the ‘returns’ data for purposes of annualizing. Value ignored if annualization parameter is specified. See full explanation in annual_return(). annualization : int, optional Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns. See full explanation in annual_return().

Returns:

float, numpy.nan The CAGR value.