# 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. `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’. `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()`. `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. `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. `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. `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. `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. `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. 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. 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. `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. `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. `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. `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()`. `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()`. `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()`. `float`, numpy.nan The CAGR value.