Utilities
=========

This section covers a variety of utilites that provide complimentary 
functionality to your trading algorithms. These are code snippets that you can
add to any algorithm to add the desired functionality.

If you are looking for example trading algorithms, see the corresponding section.

Output to CSV file
~~~~~~~~~~~~~~~~~~

Add this script to the analyze method to create and save a CSV file with the 
results from the trading algorithm. This file will include the default 
parameters of the results DataFrame plus any recorded variables and will be 
saved in the same location where your trading algorithm is saved. The exact 
script that you need to use depends on the interface that you are using to run 
your trading algorithm, which could be the CLI or a Python Interpreter.

1. Script to use with CLI:

   .. code-block:: python

      def analyze(context=None, results=None):
          import sys
          import os
          from os.path import basename
          
          # Save results in CSV file
          filename = os.path.splitext(basename(sys.argv[3]))[0]
          results.to_csv(filename + '.csv')

2. Script to use with Python Interpreter:

   .. code-block:: python

      def analyze(context=None, results=None):
          import os
          from os.path import basename
          
          # Save results in CSV file
          filename = os.path.splitext(os.path.basename(__file__))[0]
          results.to_csv(filename + '.csv')

Extracting market data
~~~~~~~~~~~~~~~~~~~~~~

Use this script to save the price and volume data of one cryptoasset in a CSV 
file, which will be saved in the same location and with the same name as your 
Python file. To get custom data, simply modify the asset's symbol and the dates. 
Run this script directly from your development environment: python scriptname.py, 
where the contents of 'scriptname.py' are as follows. Two different version are 
provided as an example for daily- and minute-resolution data respectively:

Simpler case for daily data

.. code-block:: python

   import os
   import pytz
   from datetime import datetime

   from catalyst.api import record, symbol, symbols
   from catalyst.utils.run_algo import run_algorithm

   def initialize(context):
      # Portfolio assets list
      context.asset = symbol('btc_usdt') # Bitcoin on Poloniex
                          
   def handle_data(context, data):
      # Variables to record for a given asset: price and volume
      price = data.current(context.asset, 'price')
      volume = data.current(context.asset, 'volume')
      record(price=price, volume=volume)
      
   def analyze(context=None, results=None):
      
      # Generate DataFrame with Price and Volume only
      data = results[['price','volume']]
      
      # Save results in CSV file
      filename = os.path.splitext(os.path.basename(__file__))[0]
      data.to_csv(filename + '.csv')
      
   ''' Bitcoin data is available on Poloniex since 2015-3-1. 
       Dates vary for other tokens. In the example below, we choose the 
       full month of July of 2017.
   '''
   start = datetime(2017, 1, 1, 0, 0, 0, 0, pytz.utc)
   end = datetime(2017, 7, 31, 0, 0, 0, 0, pytz.utc) 
   results = run_algorithm(initialize=initialize, 
                           handle_data=handle_data, 
                           analyze=analyze, 
                           start=start, 
                           end=end, 
                           exchange_name='poloniex', 
                           capital_base=10000, 
                           base_currency = 'usdt')

More versatile case for minute data

.. code-block:: python

   import os
   import csv
   import pytz
   from datetime import datetime

   from catalyst.api import record, symbol, symbols
   from catalyst.utils.run_algo import run_algorithm


   def initialize(context):
   # Portfolio assets list
   context.asset     = symbol('btc_usdt') # Bitcoin on Poloniex

   # Creates a .CSV file with the same name as this script to store results
   context.csvfile   = open(os.path.splitext(
                            os.path.basename(__file__))[0]+'.csv', 'w+')
   context.csvwriter = csv.writer(context.csvfile)

   def handle_data(context, data):
   # Variables to record for a given asset: price and volume
   # Other options include 'open', 'high', 'open', 'close'
   # Please note that 'price' equals 'close'
   date   = context.blotter.current_dt     # current time in each iteration
   price  = data.current(context.asset, 'price')
   volume = data.current(context.asset, 'volume')

   # Writes one line to CSV on each iteration with the chosen variables    
   context.csvwriter.writerow([date,price,volume])

   def analyze(context=None, results=None):
   # Close open file properly at the end
   context.csvfile.close()


   # Bitcoin data is available from 2015-3-2. Dates vary for other tokens.    
   start = datetime(2017, 7, 30, 0, 0, 0, 0, pytz.utc)
   end = datetime(2017, 7, 31, 0, 0, 0, 0, pytz.utc) 
   results = run_algorithm(initialize=initialize, 
                           handle_data=handle_data,
                           analyze=analyze, 
                           start=start, 
                           end=end,
                           exchange_name='poloniex', 
                           data_frequency='minute',
                           base_currency ='usdt', 
                           capital_base=10000 )