Summary

Added a few helper methods in the utils file that allow us to stack some transformation logic together before calling an actual metric. For example, if we want to calculate the rolling up capture of a strategy vs its benchmark, we want to be able to do something like [roll,up, capture] where roll, up, capture, are each methods that perform either a series deconstruction (roll), a filter (up), or a calculation (capture). Doing it this why is more DRY than embedding roll and filter logic in each method, but does add some complication.

I elected to add a variety of small methods to the stats file that wrap the complexity described above. This way we keep the API the user is used to calling the same. e.g there is actually a method called rolling_up_capture that takes the expected "returns, factor_returns" arguments. That function simply calls the more complex stacked function to get the results.

Details

• added new methods details below.
• added roll, up, and down as stackable methods to use in future calculations
• added a handful of tests for new methods
• corrected an issue with the max_drawdown. See note below
• updated nose_parameterized to just parameterized
• move date/period symbols into a separate file
• added some examples to the README

Not Done

• add information_ratio per #41
• bump empyrical version
• add remainder of tests.

Max Drawdown

The max_drawdown code was not considering the first return in the array. The max_return array did not consider the starting value of 100 used in the function. In cases where ALL the returns in the array are negative, the max value in the array will be the 100 * (1+ the first negative return). For e.g if the first return in the array is -0.02, then the max value in the array will be 98. This will cause max drawdowns to appear less severe than if they started at 100.

The max drawdown code was masquerading as correct because the negative_returns Series in the test suite starts with a 0. (i.e they aren't all negative).

I've corrected that by ensuring that the cum_returns array starts with a value that matches the base value.

New Methods

    capture,
    up_capture,
    down_capture,
    up_down_capture,
    up_alpha_beta,
    down_alpha_beta,
    roll_max_drawdown,
    roll_up_capture,
    roll_down_capture,
    roll_up_down_capture,
    roll_alpha_beta,
    roll_sharpe_ratio,

Resolves #41 #46

Closes #96 #89 #65 #64

Deprecates all data-fetching functionality via pandas-datareader, and adds a simple_returns helper function to replace that functionality that was implicitly done in the data-fetchers.

To quote the REAME:

As of early 2018, Yahoo Finance has suffered major API breaks with no stable replacement, and the Google Finance API has not been stable since late 2017 (source). In recent months it has become a greater and greater strain on the empyrical development team to maintain support for fetching data through pandas-datareader and other third-party libraries, as these APIs are known to be unstable.

As a result, all empyrical support for data reading functionality has been deprecated and will be removed in a future version.

Users should beware that the following functions are now deprecated:

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

Users should expect regular failures from the following functions, pending patches to the Yahoo or Google Finance API:

• empyrical.utils.default_returns_func
• empyrical.utils.get_symbol_returns_from_yahoo

Hi,

I thought it'd be interesting to add some risk metrics to empyrical for use in zipline/pyfolio.

Here's the papers I used.

• Beta Fragility: https://www.imf.org/external/pubs/ft/wp/2012/wp12216.pdf

• GPD Risk Estimates: https://link.springer.com/article/10.1007/s10614-006-9025-7

I wasn't sure about whether or not docstrings and tests are required for subroutines. (I'm missing some docstrings and tests for subroutines of gpd_risk_estimates.)

If the above are required, please feel free to ping me back and I'll work on adding them.

Thanks!

Jeyan

In order for cum_returns to correctly support vector input, we need to check all columns using np.all.

Before, we were getting this error when passing some vector returns:

ValueError: The truth value of an array with more than one element is ambiguous. Use a.any() or a.all()

cc @twiecki

See this comment https://github.com/quantopian/alphalens/pull/183#issuecomment-321880108 and PR for context on this PR. Also this empyrical issue https://github.com/quantopian/empyrical/issues/55

To handle the case #43 where object to be returned from max_drawdown may be Series/ndarray, invoked min on it. If it is already a float scalar then AttributeError will be raised and appropriately handled.

FIXED for Pandas >= 1.0.0

• as_matrix() was deprecated then removed. to_numpy() works in this situation

• updated travis to include pandas 1.0.x, python 3.7 numpy 1.18 and scipy 1.4.x

  • previously travis only had very old pandas, and this change is not backwards compatible before Pandas 0.23

• kept a python 2.7 build with the last supported versions of pydata.

Our Information Ratio calculation (https://github.com/quantopian/empyrical/blob/master/empyrical/stats.py#L590) is wrong as noted by @marketneutral: "The definition is wrong. You need a risk model to calc active risk to benchmark. And the benchmark look through to calc active return."

As this is still a ways off, we should rather delete it instead of having a wrong measure in here.

The Sortino Ratio is annualized in stats.py as follows: return sortino * ann_factor

where ann_factor is ann_factor = annualization_factor(period, annualization)

I believe you actually meant to return return sortino * np.sqrt(ann_factor)

just like you did with the Sharpe Ratio.

This is needed because if yearly data is given, then the Sortino ratio (sortino_ratio) can be overridden by setting the annualization value but when downside risk is calculated in the downside_risk function it will default to daily as annualization is not carried forward thus affecting the final value.

Empyrical is not generally used for the sample of a large population. Change the degrees of freedom(ddof) to 0 because that is how the standard deviation of a population is calculated. Regressive tests have been updated to reflect change in method.

Use nanstd instead of np.std for consistency.

There was a flapping test without sound logic that is being removed as well.

Hi,

This is the only error occurring while I'm running tests: python runtests.py

/usr/lib/python3.8/site-packages/pandas/util/__init__.py:12: FutureWarning: pandas.util.testing is deprecated. Use the functions in the public API at pandas.testing instead.
  import pandas.util.testing
.F...............................................................................................................................................................................................................................................................ssssssss.....s.s...s.ss.......................................................s................................................................................................................................................s...............ssssssss.....s.s...s.ss.......................................................s................................................................................................................................................s...............
======================================================================
FAIL: test_perf_attrib_simple (empyrical.tests.test_perf_attrib.PerfAttribTestCase)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/empyrical-0.5.5/empyrical/tests/test_perf_attrib.py", line 69, in test_perf_attrib_simple
    pd.util.testing.assert_frame_equal(expected_perf_attrib_output,
  File "/usr/lib/python3.8/site-packages/pandas/_testing.py", line 1611, in assert_frame_equal
    assert_series_equal(
  File "/usr/lib/python3.8/site-packages/pandas/_testing.py", line 1327, in assert_series_equal
    assert lidx.freq == ridx.freq, (lidx.freq, ridx.freq)
AssertionError: (<Day>, None)

----------------------------------------------------------------------
Ran 735 tests in 0.827s

FAILED (failures=1, skipped=30)

empyrical.stats.value_at_risk output is NaN. I cannot figure out what the problem is as all the other empyrical.stats functions work perfectly with the same data serie. Also, where I can access the source codes of the stats. This was provided in the earlier version of empyrical. Thanks,

I needed the expected maximum drawdown function for Brownian motion, as described in #90, so I decided to create a PR! It does not fully solve the issue, as I do not compute the Calmar ratio, but it should be trivial to build that on top of this function.

  File "/usr/local/bin/jesse", line 11, in <module>
    load_entry_point('jesse', 'console_scripts', 'jesse')()
  File "/usr/local/lib/python3.8/dist-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.8/dist-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.8/dist-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.8/dist-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.8/dist-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/home/src/jesse/jesse/__init__.py", line 307, in backtest
    from jesse.modes import backtest_mode
  File "/home/src/jesse/jesse/modes/backtest_mode/__init__.py", line 10, in <module>
    import jesse.services.statistics as stats
  File "/home/src/jesse/jesse/services/statistics.py", line 1, in <module>
    import empyrical
  File "/usr/local/lib/python3.8/dist-packages/empyrical/__init__.py", line 21, in <module>
    from .stats import (
  File "/usr/local/lib/python3.8/dist-packages/empyrical/stats.py", line 24, in <module>
    from .utils import nanmean, nanstd, nanmin, up, down, roll, rolling_window
  File "/usr/local/lib/python3.8/dist-packages/empyrical/utils.py", line 27, in <module>
    from pandas_datareader import data as web
  File "/usr/local/lib/python3.8/dist-packages/pandas_datareader/__init__.py", line 2, in <module>
    from .data import (
  File "/usr/local/lib/python3.8/dist-packages/pandas_datareader/data.py", line 11, in <module>
    from pandas_datareader.av.forex import AVForexReader
  File "/usr/local/lib/python3.8/dist-packages/pandas_datareader/av/__init__.py", line 5, in <module>
    from pandas_datareader._utils import RemoteDataError
  File "/usr/local/lib/python3.8/dist-packages/pandas_datareader/_utils.py", line 6, in <module>
    from pandas_datareader.compat import is_number
  File "/usr/local/lib/python3.8/dist-packages/pandas_datareader/compat/__init__.py", line 7, in <module>
    from pandas.util.testing import assert_frame_equal
  File "/usr/local/lib/python3.8/dist-packages/pandas/util/testing.py", line 5, in <module>
    warnings.warn(
=========================================================================
 Uncaught Exception: FutureWarning: pandas.util.testing is deprecated. Use the functions in the public API at pandas.testing instead.```

We have this annoying FutureWarning. Looks like its origin is empyrical.

Are open source contributions still welcomed/wanted? If so are there any active issues? I had a look at github issues, but they all seemed pretty outdated.