Merge pull request #884 from quantopian/returns-factor

Adding a built in Returns factor to the pipeline API

.gitignore

@@ -58,3 +58,7 @@ benchmarks.db
 
 # Vagrant temp folder
 .vagrant
+
+# Intellij IDE temp project files
+.project
+zipline.iml

docs/source/appendix.rst

@@ -33,6 +33,27 @@ Pipeline API
    :exclude-members: dtype
    :member-order: bysource
 
+.. autoclass:: zipline.pipeline.factors.Latest
+   :members:
+
+.. autoclass:: zipline.pipeline.factors.MaxDrawdown
+   :members:
+
+.. autoclass:: zipline.pipeline.factors.Returns
+   :members:
+
+.. autoclass:: zipline.pipeline.factors.RSI
+   :members:
+
+.. autoclass:: zipline.pipeline.factors.SimpleMovingAverage
+   :members:
+
+.. autoclass:: zipline.pipeline.factors.VWAP
+   :members:
+
+.. autoclass:: zipline.pipeline.factors.WeightedAverageValue
+   :members:
+
 .. autoclass:: zipline.pipeline.filters.Filter
    :members: __and__, __or__
    :exclude-members: dtype

docs/source/whatsnew/0.8.4.txt

@@ -28,6 +28,9 @@ Enhancements
   :meth:`~zipline.pipeline.factors.Factor.isfinite` methods to
   :class:`zipline.pipeline.factors.Factor` (:issue:`861`).
 
+* Added :class:`zipline.pipeline.factors.Returns`, a built-in factor which
+  calculates the percent change in close price over the given window_length.
+
 Experimental Features
 ~~~~~~~~~~~~~~~~~~~~~
 

tests/pipeline/test_factor.py

@@ -8,7 +8,7 @@ from numpy.random import randn, seed
 
 from zipline.errors import UnknownRankMethod
 from zipline.pipeline import Factor, Filter, TermGraph
-from zipline.pipeline.factors import RSI
+from zipline.pipeline.factors import RSI, Returns
 from zipline.utils.test_utils import check_allclose, check_arrays
 
 from .base import BasePipelineTestCase
@@ -222,3 +222,27 @@ class FactorTestCase(BasePipelineTestCase):
         rsi.compute(today, assets, out, test_data)
 
         check_allclose(expected, out)
+
+    @parameterized.expand([
+        (100, 15),
+        (101, 4),
+        (102, 100),
+        ])
+    def test_returns(self, seed_value, window_length):
+
+        returns = Returns(window_length=window_length)
+
+        today = datetime64(1, 'ns')
+        assets = arange(3)
+        out = empty((3,), dtype=float)
+
+        seed(seed_value)  # Seed so we get deterministic results.
+        test_data = abs(randn(window_length, 3))
+
+        # Calculate the expected returns
+        expected = (test_data[-1] - test_data[0]) / test_data[0]
+
+        out = empty((3,), dtype=float)
+        returns.compute(today, assets, out, test_data)
+
+        check_allclose(expected, out)

zipline/pipeline/factors/__init__.py

@@ -6,6 +6,7 @@ from .latest import Latest
 from .technical import (
     MaxDrawdown,
     RSI,
+    Returns,
     SimpleMovingAverage,
     VWAP,
     WeightedAverageValue,
@@ -17,6 +18,7 @@ __all__ = [
     'Latest',
     'MaxDrawdown',
     'RSI',
+    'Returns',
     'SimpleMovingAverage',
     'VWAP',
     'WeightedAverageValue',

zipline/pipeline/factors/technical.py

@@ -25,6 +25,18 @@ from zipline.utils.control_flow import ignore_nanwarnings
 from .factor import CustomFactor
 
 
+class Returns(CustomFactor):
+    """
+    Calculates the percent change in close price over the given window_length.
+
+    **Default Inputs**: [USEquityPricing.close]
+    """
+    inputs = [USEquityPricing.close]
+
+    def compute(self, today, assets, out, close):
+        out[:] = (close[-1] - close[0]) / close[0]
+
+
 class RSI(CustomFactor, SingleInputMixin):
     """
     Relative Strength Index