Performance & Risk Metrics

The module empyrical.stats includes various return and risk metrics, such as the computation of returns and volatility, alpha and beta, Value at Risk, and Shorpe or Sortino ratios.

empyrical.stats.aggregate_returns(returns, convert_to)

Aggregates returns by week, month, or year.

Parameters
returnspd.Series
Daily returns of the strategy, noncumulative.
convert_tostr

Can be ‘weekly’, ‘monthly’, or ‘yearly’.

Returns
aggregated_returnspd.Series
empyrical.stats.alpha(returns, factor_returns, risk_free=0.0, period='daily', annualization=None, out=None, _beta=None)

Calculates annualized alpha.

Parameters
returnspd.Series

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.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_freeint, float, optional

Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

periodstr, 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
annualizationint, 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().

_betafloat, optional

The beta for the given inputs, if already known. Will be calculated internally if not provided.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
float

Alpha.

empyrical.stats.alpha_aligned(returns, factor_returns, risk_free=0.0, period='daily', annualization=None, out=None, _beta=None)

Calculates annualized alpha.

If they are pd.Series, expects returns and factor_returns have already been aligned on their labels. If np.ndarray, these arguments should have the same shape.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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_freeint, float, optional

Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

periodstr, 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
annualizationint, 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().

_betafloat, optional

The beta for the given inputs, if already known. Will be calculated internally if not provided.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
alphafloat
empyrical.stats.alpha_beta(returns, factor_returns, risk_free=0.0, period='daily', annualization=None, out=None)

Calculates annualized alpha and beta.

Parameters
returnspd.Series

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.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_freeint, float, optional

Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
alphafloat
betafloat
empyrical.stats.alpha_beta_aligned(returns, factor_returns, risk_free=0.0, period='daily', annualization=None, out=None)

Calculates annualized alpha and beta.

If they are pd.Series, expects returns and factor_returns have already been aligned on their labels. If np.ndarray, these arguments should have the same shape.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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_freeint, float, optional

Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
alphafloat
betafloat
empyrical.stats.annual_return(returns, period='daily', annualization=None)

Determines the mean annual growth rate of returns. This is equivilent to the compound annual growth rate.

Parameters
returnspd.Series or np.ndarray

Periodic returns of the strategy, noncumulative. - See full explanation in cum_returns().

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns
annual_returnfloat

Annual Return as CAGR (Compounded Annual Growth Rate).

empyrical.stats.annual_volatility(returns, period='daily', alpha=2.0, annualization=None, out=None)

Determines the annual volatility of a strategy.

Parameters
returnspd.Series or np.ndarray

Periodic returns of the strategy, noncumulative. - See full explanation in cum_returns().

periodstr, 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
alphafloat, optional

Scaling relation (Levy stability exponent).

annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
annual_volatilityfloat
empyrical.stats.annualization_factor(period, annualization)

Return annualization factor from period entered or if a custom value is passed in.

Parameters
periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns
annualization_factorfloat
empyrical.stats.beta(returns, factor_returns, risk_free=0.0, out=None)

Calculates beta.

Parameters
returnspd.Series

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.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_freeint, float, optional

Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
betafloat
empyrical.stats.beta_aligned(returns, factor_returns, risk_free=0.0, out=None)

Calculates beta.

If they are pd.Series, expects returns and factor_returns have already been aligned on their labels. If np.ndarray, these arguments should have the same shape.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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_freeint, float, optional

Constant risk-free return throughout the period. For example, the interest rate on a three month us treasury bill.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
betafloat

Beta.

empyrical.stats.beta_fragility_heuristic(returns, factor_returns)

Estimate fragility to drops in beta.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

Returns
float, np.nan

The beta fragility of the strategy.

empyrical.stats.beta_fragility_heuristic_aligned(returns, factor_returns)

Estimate fragility to drops in beta

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

Returns
float, np.nan

The beta fragility of the strategy.

empyrical.stats.cagr(returns, period='daily', annualization=None)

Compute compound annual growth rate. Alias function for annual_return()

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

periodstr, 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
annualizationint, 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
cagrfloat

The CAGR value.

empyrical.stats.calmar_ratio(returns, period='daily', annualization=None)

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

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

Returns
calmar_ratiofloat

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

empyrical.stats.capture(returns, factor_returns, period='daily')

Compute capture ratio.

Parameters
returnspd.Series or np.ndarray

Returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

periodstr, 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
Returns
capture_ratiofloat
empyrical.stats.conditional_value_at_risk(returns, cutoff=0.05)

Conditional value at risk (CVaR) of a returns stream.

CVaR measures the expected single-day returns of an asset on that asset’s worst performing days, where “worst-performing” is defined as falling below cutoff as a percentile of all daily returns.

Parameters
returnspandas.Series or 1-D numpy.array

Non-cumulative daily returns.

cutofffloat, optional

Decimal representing the percentage cutoff for the bottom percentile of returns. Defaults to 0.05.

Returns
CVaRfloat

The CVaR value.

empyrical.stats.cum_returns(returns, starting_value=0, out=None)

Compute cumulative returns from simple returns.

Parameters
returnspd.Series, np.ndarray, or pd.DataFrame
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

  • Also accepts two dimensional data. In this case, each column is cumulated.

starting_valuefloat, optional

The starting returns.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
cumulative_returnsarray-like

Series of cumulative returns.

empyrical.stats.cum_returns_final(returns, starting_value=0)

Compute total returns from simple returns.

Parameters
returnspd.DataFrame, pd.Series, or np.ndarray

Noncumulative simple returns of one or more timeseries.

starting_valuefloat, optional

The starting returns.

Returns
total_returnspd.Series, np.ndarray, or float

If input is 1-dimensional (a Series or 1D numpy array), the result is a scalar.

If input is 2-dimensional (a DataFrame or 2D numpy array), the result is a 1D array containing cumulative returns for each column of input.

empyrical.stats.down_alpha_beta(returns, factor_returns, **kwargs)

Computes alpha and beta for periods when the benchmark return is negative.

Parameters
see documentation for `alpha_beta`.
Returns
alphafloat
betafloat
empyrical.stats.down_capture(returns, factor_returns, **kwargs)

Compute the capture ratio for periods when the benchmark return is negative

Parameters
returnspd.Series or np.ndarray

Returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

periodstr, 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
Returns
down_capturefloat
empyrical.stats.downside_risk(returns, required_return=0, period='daily', annualization=None, out=None)

Determines the downside deviation below a threshold

Parameters
returnspd.Series or np.ndarray or pd.DataFrame

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

required_return: float / series

minimum acceptable return

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
downside_deviationfloat or pd.Series

depends on input type series ==> float DataFrame ==> pd.Series

empyrical.stats.excess_sharpe(returns, factor_returns, out=None)

Determines the Excess Sharpe of a strategy.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returns: float / series

Benchmark return to compare returns against.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
excess_sharpefloat
empyrical.stats.gpd_es_calculator(var_estimate, threshold, scale_param, shape_param)
empyrical.stats.gpd_loglikelihood(params, price_data)
empyrical.stats.gpd_loglikelihood_factory(price_data)
empyrical.stats.gpd_loglikelihood_minimizer_aligned(price_data)
empyrical.stats.gpd_loglikelihood_scale_and_shape(scale, shape, price_data)
empyrical.stats.gpd_loglikelihood_scale_and_shape_factory(price_data)
empyrical.stats.gpd_loglikelihood_scale_only(scale, price_data)
empyrical.stats.gpd_loglikelihood_scale_only_factory(price_data)
empyrical.stats.gpd_risk_estimates(returns, var_p=0.01)

Estimate VaR and ES using the Generalized Pareto Distribution (GPD)

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

var_pfloat

The percentile to use for estimating the VaR and ES

Returns
[threshold, scale_param, shape_param, var_estimate, es_estimate]

: list[float] threshold - the threshold use to cut off exception tail losses scale_param - a parameter (often denoted by sigma, capturing the

scale, related to variance)

shape_param - a parameter (often denoted by xi, capturing the shape

or type of the distribution)

var_estimate - an estimate for the VaR for the given percentile es_estimate - an estimate for the ES for the given percentile

empyrical.stats.gpd_risk_estimates_aligned(returns, var_p=0.01)

Estimate VaR and ES using the Generalized Pareto Distribution (GPD)

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

var_pfloat

The percentile to use for estimating the VaR and ES

Returns
[threshold, scale_param, shape_param, var_estimate, es_estimate]

: list[float] threshold - the threshold use to cut off exception tail losses scale_param - a parameter (often denoted by sigma, capturing the

scale, related to variance)

shape_param - a parameter (often denoted by xi, capturing the shape or type of the distribution) var_estimate - an estimate for the VaR for the given percentile es_estimate - an estimate for the ES for the given percentile

empyrical.stats.gpd_var_calculator(threshold, scale_param, shape_param, probability, total_n, exceedance_n)
empyrical.stats.max_drawdown(returns, out=None)

Determines the maximum drawdown of a strategy.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
max_drawdownfloat
empyrical.stats.omega_ratio(returns, risk_free=0.0, required_return=0.0, annualization=252)

Determines the Omega ratio of a strategy.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

risk_freeint, float

Constant risk-free return throughout the period

required_returnfloat, 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.

annualizationint, optional

Factor used to convert the required_return into a daily value. Enter 1 if no time period conversion is necessary.

Returns
omega_ratiofloat
empyrical.stats.roll_alpha(lhs, rhs, window, out=None, **kwargs)

Computes the alpha measure over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling alpha.

rhsarray-like

The second array to pass to the rolling alpha.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to alpha().

Returns
rolling_alphaarray-like

The rolling alpha.

empyrical.stats.roll_alpha_aligned(lhs, rhs, window, out=None, **kwargs)

Computes the alpha aligned measure over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling alpha aligned.

rhsarray-like

The second array to pass to the rolling alpha aligned.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to alpha_aligned().

Returns
rolling_alpha_alignedarray-like

The rolling alpha aligned.

empyrical.stats.roll_alpha_beta(returns, factor_returns, window=10, **kwargs)

Computes alpha and beta over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling alpha-beta.

rhsarray-like

The second array to pass to the rolling alpha-beta.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to alpha_beta().

empyrical.stats.roll_alpha_beta_aligned(lhs, rhs, window, out=None, **kwargs)

Computes the alpha beta aligned measure over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling alpha beta aligned.

rhsarray-like

The second array to pass to the rolling alpha beta aligned.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to alpha_beta_aligned().

Returns
rolling_alpha_beta_alignedarray-like

The rolling alpha beta aligned.

empyrical.stats.roll_annual_volatility(arr, window, out=None, **kwargs)

Computes the annual volatility measure over a rolling window.

Parameters
arrarray-like

The array to compute the rolling annual volatility over.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to annual_volatility().

Returns
rolling_annual_volatilityarray-like

The rolling annual volatility.

empyrical.stats.roll_beta(lhs, rhs, window, out=None, **kwargs)

Computes the beta measure over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling beta.

rhsarray-like

The second array to pass to the rolling beta.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to beta().

Returns
rolling_betaarray-like

The rolling beta.

empyrical.stats.roll_beta_aligned(lhs, rhs, window, out=None, **kwargs)

Computes the beta aligned measure over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling beta aligned.

rhsarray-like

The second array to pass to the rolling beta aligned.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to beta_aligned().

Returns
rolling_beta_alignedarray-like

The rolling beta aligned.

empyrical.stats.roll_cagr(arr, window, out=None, **kwargs)

Computes the cagr measure over a rolling window.

Parameters
arrarray-like

The array to compute the rolling cagr over.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to cagr().

Returns
rolling_cagrarray-like

The rolling cagr.

empyrical.stats.roll_down_capture(returns, factor_returns, window=10, **kwargs)

Computes the down capture measure over a rolling window. see documentation for down_capture(). (pass all args, kwargs required)

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

windowint, required

Size of the rolling window in terms of the periodicity of the data. - eg window = 60, periodicity=DAILY, represents a rolling 60 day window

empyrical.stats.roll_downsize_risk(arr, window, out=None, **kwargs)

Computes the downside risk measure over a rolling window.

Parameters
arrarray-like

The array to compute the rolling downside risk over.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to downside_risk().

Returns
rolling_downside_riskarray-like

The rolling downside risk.

empyrical.stats.roll_excess_sharpe(lhs, rhs, window, out=None, **kwargs)

Computes the excess sharpe measure over a rolling window.

Parameters
lhsarray-like

The first array to pass to the rolling excess sharpe.

rhsarray-like

The second array to pass to the rolling excess sharpe.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to excess_sharpe().

Returns
rolling_excess_sharpearray-like

The rolling excess sharpe.

empyrical.stats.roll_max_drawdown(arr, window, out=None, **kwargs)

Computes the max drawdown measure over a rolling window.

Parameters
arrarray-like

The array to compute the rolling max drawdown over.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to max_drawdown().

Returns
rolling_max_drawdownarray-like

The rolling max drawdown.

empyrical.stats.roll_sharpe_ratio(arr, window, out=None, **kwargs)

Computes the sharpe ratio measure over a rolling window.

Parameters
arrarray-like

The array to compute the rolling sharpe ratio over.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to sharpe_ratio().

Returns
rolling_sharpe_ratioarray-like

The rolling sharpe ratio.

empyrical.stats.roll_sortino_ratio(arr, window, out=None, **kwargs)

Computes the sortino ratio measure over a rolling window.

Parameters
arrarray-like

The array to compute the rolling sortino ratio over.

windowint

Size of the rolling window in terms of the periodicity of the data.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

**kwargs

Forwarded to sortino_ratio().

Returns
rolling_sortino_ratioarray-like

The rolling sortino ratio.

empyrical.stats.roll_up_capture(returns, factor_returns, window=10, **kwargs)

Computes the up capture measure over a rolling window. see documentation for up_capture(). (pass all args, kwargs required)

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

windowint, required

Size of the rolling window in terms of the periodicity of the data. - eg window = 60, periodicity=DAILY, represents a rolling 60 day window

empyrical.stats.roll_up_down_capture(returns, factor_returns, window=10, **kwargs)

Computes the up/down capture measure over a rolling window. see documentation for up_down_capture(). (pass all args, kwargs required)

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

windowint, required

Size of the rolling window in terms of the periodicity of the data. - eg window = 60, periodicity=DAILY, represents a rolling 60 day window

empyrical.stats.sharpe_ratio(returns, risk_free=0, period='daily', annualization=None, out=None)

Determines the Sharpe ratio of a strategy.

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

risk_freeint, float

Constant daily risk-free return throughout the period.

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
sharpe_ratiofloat

nan if insufficient length of returns or if if adjusted returns are 0.

empyrical.stats.simple_returns(prices)

Compute simple returns from a timeseries of prices.

Parameters
pricespd.Series, pd.DataFrame or np.ndarray

Prices of assets in wide-format, with assets as columns, and indexed by datetimes.

Returns
returnsarray-like

Returns of assets in wide-format, with assets as columns, and index coerced to be tz-aware.

empyrical.stats.sortino_ratio(returns, required_return=0, period='daily', annualization=None, out=None, _downside_risk=None)

Determines the Sortino ratio of a strategy.

Parameters
returnspd.Series or np.ndarray or pd.DataFrame

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

required_return: float / series

minimum acceptable return

periodstr, 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
annualizationint, optional

Used to suppress default values available in period to convert returns into annual returns. Value should be the annual frequency of returns.

_downside_riskfloat, optional

The downside risk of the given inputs, if known. Will be calculated if not provided.

outarray-like, optional

Array to use as output buffer. If not passed, a new array will be created.

Returns
sortino_ratiofloat or pd.Series

depends on input type series ==> float DataFrame ==> pd.Series

empyrical.stats.stability_of_timeseries(returns)

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

Parameters
returnspd.Series or np.ndarray

Daily returns of the strategy, noncumulative. - See full explanation in cum_returns().

Returns
float

R-squared.

empyrical.stats.tail_ratio(returns)

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
returnspd.Series or np.ndarray
Daily returns of the strategy, noncumulative.
Returns
tail_ratiofloat
empyrical.stats.up_alpha_beta(returns, factor_returns, **kwargs)

Computes alpha and beta for periods when the benchmark return is positive.

Parameters
see documentation for `alpha_beta`.
Returns
float

Alpha.

float

Beta.

empyrical.stats.up_capture(returns, factor_returns, **kwargs)

Compute the capture ratio for periods when the benchmark return is positive

Parameters
returnspd.Series or np.ndarray

Returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

periodstr, 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
Returns
up_capturefloat
empyrical.stats.up_down_capture(returns, factor_returns, **kwargs)

Computes the ratio of up_capture to down_capture.

Parameters
returnspd.Series or np.ndarray

Returns of the strategy, noncumulative. - See full explanation in cum_returns().

factor_returnspd.Series or np.ndarray

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.

periodstr, 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
Returns
up_down_capturefloat

the updown capture ratio

empyrical.stats.value_at_risk(returns, cutoff=0.05)

Value at risk (VaR) of a returns stream.

Parameters
returnspandas.Series or 1-D numpy.array

Non-cumulative daily returns.

cutofffloat, optional

Decimal representing the percentage cutoff for the bottom percentile of returns. Defaults to 0.05.

Returns
VaRfloat

The VaR value.

Installation Performance Attribution