Catalyst Beginner Tutorial¶

Command line interface¶

After you installed Catalyst, you should be able to execute the following from your command line (e.g. cmd.exe or the Anaconda Prompt on Windows, or the Terminal application on MacOS).

$ catalyst --help

This is the resulting output, simplified for eductional purposes:

Usage: catalyst [OPTIONS] COMMAND [ARGS]...

  Top level catalyst entry point.

Options:
  --version               Show the version and exit.
  --help                  Show this message and exit.

Commands:
  ingest-exchange  Ingest data for the given exchange.
  live             Trade live with the given algorithm.
  run              Run a backtest for the given algorithm.

There are three main modes you can run on Catalyst. The first being ingest-exchange for data ingestion, which we have covered in the previous section. The second is live to use your algorithm to trade live against a given exchange, and the third mode run is to backtest your algorithm before trading live with it.

Let’s start with backtesting, so run this other command to learn more about the available options:

$ catalyst run --help

Usage: catalyst run [OPTIONS]

  Run a backtest for the given algorithm.

Options:
  -f, --algofile FILENAME         The file that contains the algorithm to run.
  -t, --algotext TEXT             The algorithm script to run.
  -D, --define TEXT               Define a name to be bound in the namespace
                                  before executing the algotext. For example
                                  '-Dname=value'. The value may be any python
                                  expression. These are evaluated in order so
                                  they may refer to previously defined names.
  --data-frequency [daily|minute]
                                  The data frequency of the simulation.
                                  [default: daily]
  --capital-base FLOAT            The starting capital for the simulation.
                                  [default: 10000000.0]
  -b, --bundle BUNDLE-NAME        The data bundle to use for the simulation.
                                  [default: poloniex]
  --bundle-timestamp TIMESTAMP    The date to lookup data on or before.
                                  [default: <current-time>]
  -s, --start DATE                The start date of the simulation.
  -e, --end DATE                  The end date of the simulation.
  -o, --output FILENAME           The location to write the perf data. If this
                                  is '-' the perf will be written to stdout.
                                  [default: -]
  --print-algo / --no-print-algo  Print the algorithm to stdout.
  -x, --exchange-name [poloniex|bitfinex|bittrex]
                                  The name of the targeted exchange
                                  (supported: bitfinex, bittrex, poloniex).
  -n, --algo-namespace TEXT       A label assigned to the algorithm for data
                                  storage purposes.
  -c, --base-currency TEXT        The base currency used to calculate
                                  statistics (e.g. usd, btc, eth).
  --help                          Show this message and exit.

As you can see there are a couple of flags that specify where to find your algorithm (-f) as well as a the -x flag to specify which exchange to use. There are also arguments for the date range to run the algorithm over (--start and --end). You also need to set the base currency for your algorithm through the -c flag, and the --capital_base. All the aforementioned parameters are required. Optionally, you will want to save the performance metrics of your algorithm so that you can analyze how it performed. This is done via the --output flag and will cause it to write the performance DataFrame in the pickle Python file format. Note that you can also define a configuration file with these parameters that you can then conveniently pass to the -c option so that you don’t have to supply the command line args all the time.

Thus, to execute our algorithm from above and save the results to buy_btc_simple_out.pickle we would call catalyst run as follows:

catalyst run -f buy_btc_simple.py -x bitfinex --start 2016-1-1 --end 2017-9-30 -c usd --capital-base 100000 -o buy_btc_simple_out.pickle

INFO: run_algo: running algo in backtest mode
INFO: exchange_algorithm: initialized trading algorithm in backtest mode
INFO: Performance: Simulated 639 trading days out of 639.
INFO: Performance: first open: 2016-01-01 00:00:00+00:00
INFO: Performance: last close: 2017-09-30 23:59:00+00:00

run first calls the initialize() function, and then streams the historical asset price day-by-day through handle_data(). After each call to handle_data() we instruct catalyst to order 1 bitcoin. After the call of the order() function, catalyst enters the ordered stock and amount in the order book. After the handle_data() function has finished, catalyst looks for any open orders and tries to fill them. If the trading volume is high enough for this asset, the order is executed after adding the commission and applying the slippage model which models the influence of your order on the stock price, so your algorithm will be charged more than just the asset price. (Note, that you can also change the commission and slippage model that catalyst uses).

Let’s take a quick look at the performance DataFrame. For this, we write different Python script–let’s call it print_results.py–and we make use of the fantastic pandas library to print the first ten rows. Note that catalyst makes heavy usage of pandas, especially for data analysis and outputting so it’s worth spending some time to learn it.

import pandas as pd
perf = pd.read_pickle('buy_btc_simple_out.pickle') # read in perf DataFrame
print(perf.head())

Which we execute by running:

$ python print_results.py

There is a row for each trading day, starting on the first day of our simulation Jan 1st, 2016. In the columns you can find various information about the state of your algorithm. The column btc was placed there by the record() function mentioned earlier and allows us to plot the price of bitcoin. For example, we could easily examine now how our portfolio value changed over time compared to the bitcoin price.

Now we will run the simulation again, but this time we extend our original algorithm with the addition of the analyze() function. Somewhat analogously as how initialize() gets called once before the start of the algorith, analyze() gets called once at the end of the algorithm, and receives two variables: context, which we discussed at the very beginning, and perf, which is the pandas dataframe containing the performance data for our algorithm that we reviewed above. Inside the analyze() function is where we can analyze and visualize the results of our strategy. Here’s the revised simple algorithm (note the addition of Line 1, and Lines 11-18)

import matplotlib.pyplot as plt
from catalyst.api import order, record, symbol

def initialize(context):
    context.asset = symbol('btc_usd')

def handle_data(context, data):
    order(context.asset, 1)
    record(btc = data.current(context.asset, 'price'))

def analyze(context, perf):
    ax1 = plt.subplot(211)
    perf.portfolio_value.plot(ax=ax1)
    ax1.set_ylabel('portfolio value')
    ax2 = plt.subplot(212, sharex=ax1)
    perf.btc.plot(ax=ax2)
    ax2.set_ylabel('bitcoin price')
    plt.show()

Here we make use of the external visualization library called matplotlib, which you might recall we installed alongside enigma-catalyst (with the exception of the Conda install, where it was included by default inside the conda environment we created). If for any reason you don’t have it installed, you can add it by running:

(catalyst)$ pip install matplotlib

If everything works well, you’ll see the following chart:

Our algorithm performance as assessed by the portfolio_value closely matches that of the bitcoin price. This is not surprising as our algorithm only bought bitcoin every chance it got.

If you get an error when invoking matplotlib to visualize the performance results refer to MacOS + Matplotlib. Alternatively, some users have reported the following error when running an algo in a Linux environment:

ImportError: No module named _tkinter, please install the python-tk package

Which can easily solved by running (in Ubuntu/Debian-based systems):

sudo apt install python-tk

Working example: Dual Moving Average Cross-Over¶

The Dual Moving Average (DMA) is a classic momentum strategy. It’s probably not used by any serious trader anymore but is still very instructive. The basic idea is that we compute two rolling or moving averages (mavg) – one with a longer window that is supposed to capture long-term trends and one shorter window that is supposed to capture short-term trends. Once the short-mavg crosses the long-mavg from below we assume that the stock price has upwards momentum and long the stock. If the short-mavg crosses from above we exit the positions as we assume the stock to go down further.

As we need to have access to previous prices to implement this strategy we need a new concept: History. data.history() is a convenience function that keeps a rolling window of data for you. The first argument is the number of bars you want to collect, the second argument is the unit (either '1d' for daily or '1m' for minute frequency, but note that you need to have minute-level data when using 1m). This is a function we use in the handle_data() section.

You will note that the code below is substantially longer than the previous examples. Don’t get overwhelmed by it as the logic is fairly simple and easy to follow. Most of the added some complexity has been added to beautify the output, which you can skim through for now. A copy of this algorithm is available in the examples directory: dual_moving_average.py.

import numpy as np
import pandas as pd
from logbook import Logger
import matplotlib.pyplot as plt

from catalyst import run_algorithm
from catalyst.api import (order, record, symbol, order_target_percent,
        get_open_orders)
from catalyst.exchange.stats_utils import extract_transactions

NAMESPACE = 'dual_moving_average'
log = Logger(NAMESPACE)

def initialize(context):
    context.i = 0
    context.asset = symbol('ltc_usd')
    context.base_price = None


def handle_data(context, data):
    # define the windows for the moving averages
    short_window = 50
    long_window = 200

    # Skip as many bars as long_window to properly compute the average
    context.i += 1
    if context.i < long_window:
       return

    # Compute moving averages calling data.history() for each
    # moving average with the appropriate parameters. We choose to use
    # minute bars for this simulation -> freq="1m"
    # Returns a pandas dataframe.
    short_mavg = data.history(context.asset, 'price',
                        bar_count=short_window, frequency="1m").mean()
    long_mavg = data.history(context.asset, 'price',
                        bar_count=long_window, frequency="1m").mean()

    # Let's keep the price of our asset in a more handy variable
    price = data.current(context.asset, 'price')

    # If base_price is not set, we use the current value. This is the
    # price at the first bar which we reference to calculate price_change.
    if context.base_price is None:
        context.base_price = price
    price_change = (price - context.base_price) / context.base_price

    # Save values for later inspection
    record(price=price,
           cash=context.portfolio.cash,
           price_change=price_change,
           short_mavg=short_mavg,
           long_mavg=long_mavg)

    # Since we are using limit orders, some orders may not execute immediately
    # we wait until all orders are executed before considering more trades.
    orders = get_open_orders(context.asset)
    if len(orders) > 0:
        return

    # Exit if we cannot trade
    if not data.can_trade(context.asset):
        return

    # We check what's our position on our portfolio and trade accordingly
    pos_amount = context.portfolio.positions[context.asset].amount

    # Trading logic
    if short_mavg > long_mavg and pos_amount == 0:
       # we buy 100% of our portfolio for this asset
       order_target_percent(context.asset, 1)
    elif short_mavg < long_mavg and pos_amount > 0:
       # we sell all our positions for this asset
       order_target_percent(context.asset, 0)


def analyze(context, perf):

    # Get the base_currency that was passed as a parameter to the simulation
    base_currency = context.exchanges.values()[0].base_currency.upper()

    # First chart: Plot portfolio value using base_currency
    ax1 = plt.subplot(411)
    perf.loc[:, ['portfolio_value']].plot(ax=ax1)
    ax1.legend_.remove()
    ax1.set_ylabel('Portfolio Value\n({})'.format(base_currency))
    start, end = ax1.get_ylim()
    ax1.yaxis.set_ticks(np.arange(start, end, (end-start)/5))

    # Second chart: Plot asset price, moving averages and buys/sells
    ax2 = plt.subplot(412, sharex=ax1)
    perf.loc[:, ['price','short_mavg','long_mavg']].plot(ax=ax2, label='Price')
    ax2.legend_.remove()
    ax2.set_ylabel('{asset}\n({base})'.format(
        asset = context.asset.symbol,
        base = base_currency
        ))
    start, end = ax2.get_ylim()
    ax2.yaxis.set_ticks(np.arange(start, end, (end-start)/5))

    transaction_df = extract_transactions(perf)
    if not transaction_df.empty:
        buy_df = transaction_df[transaction_df['amount'] > 0]
        sell_df = transaction_df[transaction_df['amount'] < 0]
        ax2.scatter(
            buy_df.index.to_pydatetime(),
            perf.loc[buy_df.index, 'price'],
            marker='^',
            s=100,
            c='green',
            label=''
        )
        ax2.scatter(
            sell_df.index.to_pydatetime(),
            perf.loc[sell_df.index, 'price'],
            marker='v',
            s=100,
            c='red',
            label=''
        )

    # Third chart: Compare percentage change between our portfolio
    # and the price of the asset
    ax3 = plt.subplot(413, sharex=ax1)
    perf.loc[:, ['algorithm_period_return', 'price_change']].plot(ax=ax3)
    ax3.legend_.remove()
    ax3.set_ylabel('Percent Change')
    start, end = ax3.get_ylim()
    ax3.yaxis.set_ticks(np.arange(start, end, (end-start)/5))

    # Fourth chart: Plot our cash
    ax4 = plt.subplot(414, sharex=ax1)
    perf.cash.plot(ax=ax4)
    ax4.set_ylabel('Cash\n({})'.format(base_currency))
    start, end = ax4.get_ylim()
    ax4.yaxis.set_ticks(np.arange(0, end, end/5))

    plt.show()


if __name__ == '__main__':
    run_algorithm(
            capital_base=1000,
            data_frequency='minute',
            initialize=initialize,
            handle_data=handle_data,
            analyze=analyze,
            exchange_name='bitfinex',
            algo_namespace=NAMESPACE,
            base_currency='usd',
            start=pd.to_datetime('2017-9-22', utc=True),
            end=pd.to_datetime('2017-9-23', utc=True),
        )

In order to run the code above, you have to ingest the needed data first:

catalyst ingest-exchange -x bitfinex -f minute -i ltc_usd

And then run the code above with the following command:

catalyst run -f dual_moving_average.py -x bitfinex -s 2017-9-22 -e 2017-9-23 --capital-base 1000 --base-currency usd --data-frequency minute -o out.pickle

Alternatively, we can make use of the run_algorithm() function included at the end of the file, where we can specify all the simulation parameters, and execute this file as a Python script:

python dual_moving_average.py

Either way, we obtain the following charts:

A few comments on the code above:

At the beginning of our code, we import a number of Python libraries that we will be using in different parts of our script. It’s good practice to keep all imports at the beginning of the file, as they are available globally throughout our script. All the libraries imported in this example are already present in your environment since they are prerequisites for the Catalyst installation.

Focus on the code that is inside handle_data() that is where all the trading logic occurs. You can safely dismiss most of the code in the analyze() section, which is mostly to customize the visualization of the performance of our algorithm using the matplotlib library. You can copy and paste this whole section into other algorithms to obtain a similar display.

Inside the handle_data(), we also used the order_target_percent() function above. This and other functions like it can make order management and portfolio rebalancing much easier.

The ltc_usd asset was arbitrarily chosen. The values of 50 and 200 for the short_window and long_window parameters are fairly common for a dual moving average crossover strategy from the world of traditional stocks (but bear in mind that they are usually used with daily bars instead of minute bars). The start and end dates have been chosen so as to demonstrate how our strategy can both perform better (blue line above green line on the Percent Change chart) and worse (green line above blue line towards the end) than the price of the asset we are trading.

You can change any of these parameters: asset, short_window, long_window, start_date and end_date and compare the results, and you will see that in most cases, the performance is either worse than the price of the asset, or you are overfitting to one specific case. As we said at the beginning of this section, this strategy is probably not used by any serious trader anymore, but its educational purpose.

Although it might not be directly apparent, the power of history() (pun intended) can not be under-estimated as most algorithms make use of prior market developments in one form or another. You could easily devise a strategy that trains a classifier with scikit-learn which tries to predict future market movements based on past prices (note, that most of the scikit-learn functions require numpy.ndarrays rather than pandas.DataFrames, so you can simply pass the underlying ndarray of a DataFrame via .values).