DOC: Add tutorial and update examples to use history.

README.md

@@ -99,38 +99,42 @@ Quickstart
 The following code implements a simple dual moving average algorithm.
 
 ```python
-from zipline.api import order_target, record, symbol
-from collections import deque as moving_window
-import numpy as np
+from zipline.api import order_target, record, symbol, history, add_history
 
 
 def initialize(context):
-    # Add 2 windows, one with a long window, one
-    # with a short window.
-    # Note that this is bound to change soon and will be easier.
-    context.short_window = moving_window(maxlen=100)
-    context.long_window = moving_window(maxlen=300)
+    # Register 2 histories that track daily prices,
+    # one with a 100 window and one with a 300 day window
+    add_history(100, '1d', 'price')
+    add_history(300, '1d', 'price')
+
+    context.i = 0
 
 
 def handle_data(context, data):
-    # Save price to window
-    context.short_window.append(data[symbol('AAPL')].price)
-    context.long_window.append(data[symbol('AAPL')].price)
+    # Skip first 300 days to get full windows
+    context.i += 1
+    if context.i < 300:
+        return
 
     # Compute averages
-    short_mavg = np.mean(context.short_window)
-    long_mavg = np.mean(context.long_window)
+    # history() has to be called with the same params
+    # from above and returns a pandas dataframe.
+    short_mavg = history(100, '1d', 'price').mean()
+    long_mavg = history(300, '1d', 'price').mean()
 
     # Trading logic
     if short_mavg > long_mavg:
+        # order_target orders as many shares as needed to
+        # achieve the desired number of shares.
         order_target(symbol('AAPL'), 100)
     elif short_mavg < long_mavg:
         order_target(symbol('AAPL'), 0)
 
     # Save values for later inspection
     record(AAPL=data[symbol('AAPL')].price,
-           short_mavg=short_mavg,
-           long_mavg=long_mavg)
+           short_mavg=short_mavg[0],
+           long_mavg=long_mavg[0])
 ```
 
 You can then run this algorithm using the Zipline CLI. From the

zipline/examples/buyapple.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright 2012 Quantopian, Inc.
+# Copyright 2014 Quantopian, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from zipline.api import order, record
+from zipline.api import order, record, symbol
 
 
 def initialize(context):
@@ -22,5 +22,5 @@ def initialize(context):
 
 
 def handle_data(context, data):
-    order('AAPL', 10)
-    record(AAPL=data['AAPL'].price)
+    order(symbol('AAPL'), 10)
+    record(AAPL=data[symbol('AAPL')].price)

zipline/examples/dual_ema_talib.py

@@ -27,6 +27,7 @@ import pytz
 
 
 class DualEMATaLib(TradingAlgorithm):
+
     """Dual Moving Average Crossover algorithm.
 
     This algorithm buys apple once its short moving average crosses
@@ -35,6 +36,7 @@ class DualEMATaLib(TradingAlgorithm):
     momentum).
 
     """
+
     def initialize(self, short_window=20, long_window=40):
         # Add 2 mavg transforms, one with a long window, one
         # with a short window.

zipline/examples/dual_moving_average.conf

@@ -0,0 +1,5 @@
+[Defaults]
+algofile=dual_moving_average.py
+symbols=AAPL
+start=2000-1-1
+end=2012-1-1

zipline/examples/dual_moving_average.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 #
-# Copyright 2013 Quantopian, Inc.
+# Copyright 2014 Quantopian, Inc.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -22,35 +22,39 @@ its shares once the averages cross again (indicating downwards
 momentum).
 """
 
-from zipline.api import order_target, record, symbol
-from collections import deque as moving_window
-import numpy as np
+from zipline.api import order_target, record, symbol, history, add_history
 
 
 def initialize(context):
-    # Add 2 windows, one with a long window, one
-    # with a short window.
-    # Note that this is bound to change soon and will be easier.
-    context.short_window = moving_window(maxlen=100)
-    context.long_window = moving_window(maxlen=300)
+    # Register 2 histories that track daily prices,
+    # one with a 100 window and one with a 300 day window
+    add_history(100, '1d', 'price')
+    add_history(300, '1d', 'price')
+
+    context.i = 0
 
 
 def handle_data(context, data):
-    # Save price to window
-    context.short_window.append(data[symbol('AAPL')].price)
-    context.long_window.append(data[symbol('AAPL')].price)
+    # Skip first 300 days to get full windows
+    context.i += 1
+    if context.i < 300:
+        return
 
     # Compute averages
-    short_mavg = np.mean(context.short_window)
-    long_mavg = np.mean(context.long_window)
+    # history() has to be called with the same params
+    # from above and returns a pandas dataframe.
+    short_mavg = history(100, '1d', 'price').mean()
+    long_mavg = history(300, '1d', 'price').mean()
 
     # Trading logic
     if short_mavg > long_mavg:
+        # order_target orders as many shares as needed to
+        # achieve the desired number of shares.
         order_target(symbol('AAPL'), 100)
     elif short_mavg < long_mavg:
         order_target(symbol('AAPL'), 0)
 
     # Save values for later inspection
     record(AAPL=data[symbol('AAPL')].price,
-           short_mavg=short_mavg,
-           long_mavg=long_mavg)
+           short_mavg=short_mavg[0],
+           long_mavg=long_mavg[0])

zipline/examples/dual_moving_average_analyze.py

@@ -5,6 +5,7 @@ def analyze(context, perf):
     fig = plt.figure()
     ax1 = fig.add_subplot(211)
     perf.portfolio_value.plot(ax=ax1)
+    ax1.set_ylabel('portfolio value in $')
 
     ax2 = fig.add_subplot(212)
     perf['AAPL'].plot(ax=ax2)
@@ -18,5 +19,6 @@ def analyze(context, perf):
              '^', markersize=10, color='m')
     ax2.plot(sells.index, perf.short_mavg.ix[sells.index],
              'v', markersize=10, color='k')
+    ax2.set_ylabel('price in $')
     plt.legend(loc=0)
     plt.show()