Catalyst Beginner Tutorial

Basics

Catalyst is an open-source algorithmic trading simulator for crypto assets written in Python. The source code can be found at: https://github.com/enigmampc/catalyst

Some benefits include:

  • Support for several of the top crypto-exchanges by trading volume.
  • Realistic: slippage, transaction costs, order delays.
  • Stream-based: Process each event individually, avoids look-ahead bias.
  • Batteries included: Common transforms (moving average) as well as common risk calculations (Sharpe).
  • Developed and continuously updated by Enigma MPC which is building the Enigma data marketplace protocol as well as Catalyst, the first application that will run on our protocol. Powered by our financial data marketplace, Catalyst empowers users to share and curate data and build profitable, data-driven investment strategies.

This tutorial assumes that you have Catalyst correctly installed, see the Install section if you haven’t set up Catalyst yet.

Every catalyst algorithm consists of at least two functions you have to define:

  • initialize(context)
  • handle_data(context, data)

Before the start of the algorithm, catalyst calls the initialize() function and passes in a context variable. context is a persistent namespace for you to store variables you need to access from one algorithm iteration to the next.

After the algorithm has been initialized, catalyst calls the handle_data() function on each iteration, that’s one per day (daily) or once every minute (minute), depending on the frequency we choose to run our simulation. On every iteration, handle_data() passes the same context variable and an event-frame called data containing the current trading bar with open, high, low, and close (OHLC) prices as well as volume for each crypto asset in your universe.

My first algorithm

Lets take a look at a very simple algorithm from the examples directory: buy_btc_simple.py:

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'))

As you can see, we first have to import some functions we would like to use. All functions commonly used in your algorithm can be found in catalyst.api. Here we are using order() which takes two arguments: a cryptoasset object, and a number specifying how many assets you would like to order (if negative, order() will sell assets). In this case we want to order 1 bitcoin at each iteration.

Finally, the record() function allows you to save the value of a variable at each iteration. You provide it with a name for the variable together with the variable itself: varname=var. After the algorithm finished running you will have access to each variable value you tracked with record() under the name you provided (we will see this further below). You also see how we can access the current price data of a bitcoin in the data event frame.

Ingesting data

Before you can backtest your algorithm, you first need to load the historical pricing data that Catalyst needs to run your simulation through a process called ingestion. When you ingest data, Catalyst downloads that data in compressed form from the Enigma servers (which eventually will migrate to the Enigma Data Marketplace), and stores it locally to make it available at runtime.

In order to ingest data, you need to run a command like the following:

catalyst ingest-exchange -x bitfinex -i btc_usd

This instructs Catalyst to download pricing data from the Bitfinex exchange for the btc_usd currency pair (this follows from the simple algorithm presented above where we want to trade btc_usd), and we’re choosing to test our algorithm using historical pricing data from the Bitfinex exchange. By default, Catalyst assumes that you want data with daily frequency (one candle bar per day). If you want instead minute frequency (one candle bar for every minute), you would need to specify it as follows:

catalyst ingest-exchange -x bitfinex -i btc_usd -f minute
Ingesting exchange bundle bitfinex...
  [====================================]  Ingesting daily price data on bitfinex:  100%

We believe it is important for you to have a high-level understanding of how data is managed, hence the following overview:

  • Pricing data is split and packaged into bundles: chunks of data organized as time series that are kept up to date daily on Enigma’s servers. Catalyst downloads the requested bundles and reconstructs the full dataset in your hard drive.
  • Pricing data is provided in daily and minute resolution. Those are different bundle datasets, and are managed separately.
  • Bundles are exchange-specific, as the pricing data is specific to the trades that happen in each exchange. As a result, you must specify which exchange you want pricing data from when ingesting data.
  • Catalyst keeps track of all the downloaded bundles, so that it only has to download them once, and will do incremental updates as needed.
  • When running in live trading mode, Catalyst will first look for historical pricing data in the locally stored bundles. If there is anything missing, Catalyst will hit the exchange for the most recent data, and merge it with the local bundle to optimize the number of requests it needs to make to the exchange.

The ingest-exchange command in catalyst offers additional parameters to further tweak the data ingestion process. You can learn more by running the following from the command line:

catalyst ingest-exchange --help

Running the algorithm

You can now test your algorithm using cryptoassets’ historical pricing data, catalyst provides three interfaces:

  • A command-line interface (CLI),
  • a run_algorithm() that you can call from other Python scripts,
  • and the Jupyter Notebook magic.

We’ll start with the CLI, and introduce the run_algorithm() in the last example of this tutorial. Some of the example algorithms provide instructions on how to run them both from the CLI, and using the run_algorithm() function. For the third method, refer to the corresponding section on Catalyst & Jupyter Notebook after you have assimilated the contents of this 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 educational 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|binance]
                                  The name of the targeted exchange
                                  (supported: binance, bitfinex, bittrex, poloniex).
  -n, --algo-namespace TEXT       A label assigned to the algorithm for data
                                  storage purposes.
  -c, --quote-currency TEXT        The quote 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 quote 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
algo_volatility algorithm_period_return alpha benchmark_period_return benchmark_volatility beta btc capital_used ending_cash ending_exposure ... short_exposure short_value shorts_count sortino starting_cash starting_exposure starting_value trading_days transactions treasury_period_return
2016-01-01 23:59:00+00:00 NaN 0.000000e+00 NaN -0.010937 NaN NaN 433.979999 0.000000 1.000000e+07 0.00 ... 0 0 0 NaN 1.000000e+07 0.00 0.00 1 [] 0.0227
2016-01-02 23:59:00+00:00 0.000011 -9.536708e-07 -0.000170 -0.006480 0.173338 -0.000062 432.700000 -442.236708 9.999558e+06 432.70 ... 0 0 0 -11.224972 1.000000e+07 0.00 0.00 2 [{u'order_id': u'7869f7828fa140328eb40477bb7de... 0.0227
2016-01-03 23:59:00+00:00 0.000011 -2.328842e-06 -0.000176 -0.026512 0.197857 0.000009 428.390000 -437.831716 9.999120e+06 856.78 ... 0 0 0 -12.754262 9.999558e+06 432.70 432.70 3 [{u'order_id': u'be62ff77760c4599abaac43be9cc9... 0.0227
2016-01-04 23:59:00+00:00 0.000011 -2.380954e-06 -0.000139 -0.008640 0.269790 0.000020 432.900000 -442.441116 9.998677e+06 1298.70 ... 0 0 0 -11.287205 9.999120e+06 856.78 856.78 4 [{u'order_id': u'd6dca79513214346a646079213526... 0.0224
2016-01-05 23:59:00+00:00 0.000011 -3.650729e-06 -0.000158 -0.021426 0.245989 0.000024 431.840000 -441.357754 9.998236e+06 1727.36 ... 0 0 0 -12.333847 9.998677e+06 1298.70 1298.70 5 [{u'order_id': u'505275d6646a41f3856b22b16678d... 0.0225

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 algorithm, 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:

https://s3.amazonaws.com/enigmaco-docs/github.io/buy_btc_simple_graph.png

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

Access to previous prices using history

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 matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from logbook import Logger

from catalyst import run_algorithm
from catalyst.api import (record, symbol, order_target_percent,)
from catalyst.exchange.utils.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_data = data.history(context.asset,
                              'price',
                              bar_count=short_window,
                              frequency="1T",
                              )
    short_mavg = short_data.mean()
    long_data = data.history(context.asset,
                             'price',
                             bar_count=long_window,
                             frequency="1T",
                             )
    long_mavg = long_data.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 = context.blotter.open_orders
    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 quote_currency that was passed as a parameter to the simulation
    exchange = list(context.exchanges.values())[0]
    quote_currency = exchange.quote_currency.upper()

    # First chart: Plot portfolio value using quote_currency
    ax1 = plt.subplot(411)
    perf.loc[:, ['portfolio_value']].plot(ax=ax1)
    ax1.legend_.remove()
    ax1.set_ylabel('Portfolio Value\n({})'.format(quote_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({quote})'.format(
        asset=context.asset.symbol,
        quote=quote_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(quote_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,
            quote_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 --quote-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:

https://s3.amazonaws.com/enigmaco-docs/github.io/tutorial_dual_moving_average.png

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 it has an 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).

Jupyter Notebook

(This is actual Notebook referenced in the text below)

The Jupyter Notebook is a very powerful browser-based interface to a Python interpreter. As it is already the de-facto interface for most quantitative researchers, catalyst provides an easy way to run your algorithm inside the Notebook without requiring you to use the CLI. We include this section here as an alternative to running algorithms through the command line.

Install

In order to use Jupyter Notebook, you first have to install it inside your environment. It’s available as pip package, so regardless of how you installed Catalyst, go inside your catalyst environment and run:

(catalyst)$ pip install jupyter

Once you have Jupyter Notebook installed, every time you want to use it run:

(catalyst)$ jupyter notebook

A local server will launch, and will open a new window on your browser. That’s the interface through which you will interact with Jupyter Notebook.

Running Algorithms

Before running your algorithms inside the Jupyter Notebook, remember to ingest the data from the command line interface (CLI). In the example below, you would need to run first:

catalyst ingest-exchange -x bitfinex -i btc_usd

To use Catalyst inside a Jupyter Noebook, you have to write your algorithm in a cell and let the Jupyter know that it is supposed to execute this algorithm with Catalyst. This is done via the %%catalyst IPython magic command that is available after you import catalyst from within the Notebook. This magic takes the same arguments as the command line interface. Thus to run the algorithm just supply the same parameters as the CLI but without the -f and -o arguments. We just have to execute the following cell after importing catalyst to register the magic.

# Register the catalyst magic
%load_ext catalyst
# Setup matplotlib to display graphs inline in this Notebook
%matplotlib inline

Note below that we do not have to specify an input file (-f) since the magic will use the contents of the cell and look for your algorithm functions.

%%catalyst --start 2015-3-2 --end 2017-6-28 --capital-base 100000 -x bitfinex -c usd

from catalyst.finance.slippage import VolumeShareSlippage

from catalyst.api import (
    order_target_value,
    symbol,
    record,
    cancel_order,
    get_open_orders,
)

def initialize(context):
    context.ASSET_NAME = 'btc_usd'
    context.TARGET_HODL_RATIO = 0.8
    context.RESERVE_RATIO = 1.0 - context.TARGET_HODL_RATIO

    # For all trading pairs in the poloniex bundle, the default denomination
    # currently supported by Catalyst is 1/1000th of a full coin. Use this
    # constant to scale the price of up to that of a full coin if desired.
    context.TICK_SIZE = 1000.0

    context.is_buying = True
    context.asset = symbol(context.ASSET_NAME)

    context.i = 0

def handle_data(context, data):
    context.i += 1

    starting_cash = context.portfolio.starting_cash
    target_hodl_value = context.TARGET_HODL_RATIO * starting_cash
    reserve_value = context.RESERVE_RATIO * starting_cash

    # Cancel any outstanding orders
    orders = get_open_orders(context.asset) or []
    for order in orders:
        cancel_order(order)

    # Stop buying after passing the reserve threshold
    cash = context.portfolio.cash
    if cash <= reserve_value:
        context.is_buying = False

    # Retrieve current asset price from pricing data
    price = data.current(context.asset, 'price')

    # Check if still buying and could (approximately) afford another purchase
    if context.is_buying and cash > price:
        # Place order to make position in asset equal to target_hodl_value
        order_target_value(
            context.asset,
            target_hodl_value,
            limit_price=price*1.1,
        )

    record(
        price=price,
        volume=data.current(context.asset, 'volume'),
        cash=cash,
        starting_cash=context.portfolio.starting_cash,
        leverage=context.account.leverage,
    )

def analyze(context=None, results=None):
    import matplotlib.pyplot as plt

    # Plot the portfolio and asset data.
    ax1 = plt.subplot(611)
    results[['portfolio_value']].plot(ax=ax1)
    ax1.set_ylabel('Portfolio Value (USD)')

    ax2 = plt.subplot(612, sharex=ax1)
    ax2.set_ylabel('{asset} (USD)'.format(asset=context.ASSET_NAME))
    (context.TICK_SIZE * results[['price']]).plot(ax=ax2)

    trans = results.ix[[t != [] for t in results.transactions]]
    buys = trans.ix[
        [t[0]['amount'] > 0 for t in trans.transactions]
    ]
    ax2.plot(
        buys.index,
        context.TICK_SIZE * results.price[buys.index],
        '^',
        markersize=10,
        color='g',
    )

    ax3 = plt.subplot(613, sharex=ax1)
    results[['leverage', 'alpha', 'beta']].plot(ax=ax3)
    ax3.set_ylabel('Leverage ')

    ax4 = plt.subplot(614, sharex=ax1)
    results[['starting_cash', 'cash']].plot(ax=ax4)
    ax4.set_ylabel('Cash (USD)')

    results[[
        'treasury',
        'algorithm',
        'benchmark',
    ]] = results[[
        'treasury_period_return',
        'algorithm_period_return',
        'benchmark_period_return',
    ]]

    ax5 = plt.subplot(615, sharex=ax1)
    results[[
        'treasury',
        'algorithm',
        'benchmark',
    ]].plot(ax=ax5)
    ax5.set_ylabel('Percent Change')

    ax6 = plt.subplot(616, sharex=ax1)
    results[['volume']].plot(ax=ax6)
    ax6.set_ylabel('Volume (mCoins/5min)')

    plt.legend(loc=3)

    # Show the plot.
    plt.gcf().set_size_inches(18, 8)
    plt.show()
[2017-08-11 07:19:46.411748] INFO: Loader: Loading benchmark data for 'USDT_BTC' from 1989-12-31 00:00:00+00:00 to 2017-08-09 00:00:00+00:00
[2017-08-11 07:19:46.418983] INFO: Loader: Loading data for /Users/<snipped>/.catalyst/data/USDT_BTC_benchmark.csv failed with error [Unknown string format].
[2017-08-11 07:19:46.419740] INFO: Loader: Cache at /Users/<snipped>/.catalyst/data/USDT_BTC_benchmark.csv does not have data from 1990-01-01 00:00:00+00:00 to 2017-08-09 00:00:00+00:00.

[2017-08-11 07:19:46.420770] INFO: Loader: Downloading benchmark data for 'USDT_BTC' from 1989-12-31 00:00:00+00:00 to 2017-08-09 00:00:00+00:00
[2017-08-11 07:19:50.060244] WARNING: Loader: Still don't have expected data after redownload!
[2017-08-11 07:19:50.097334] WARNING: Loader: Refusing to download new treasury data because a download succeeded at 2017-08-11 06:56:49+00:00.
[2017-08-11 07:19:54.618399] INFO: Performance: Simulated 851 trading days out of 851.
[2017-08-11 07:19:54.619301] INFO: Performance: first open: 2015-03-01 00:00:00+00:00
[2017-08-11 07:19:54.620430] INFO: Performance: last close: 2017-06-28 23:59:00+00:00
png

algo_volatility

algorithm_period_return

alpha

benchmark_period_return

benchmark_volatility

beta

capital_used

cash

ending_cash

ending_exposure

starting_cash

starting_exposure

starting_value

trading_days

transactions

treasury_period_return

volume

treasury

algorithm

benchmark

2015-03-01 23:59:00+00:00

NaN

0.000000

NaN

0.045833

NaN

NaN

0.000000

100000.000000

100000.000000

0.000

100000.0

0.000

0.000

1

[]

0.0200

317

0.0200

0.000000

0.045833

2015-03-02 23:59:00+00:00

0.000278

-0.000025

0.011045

0.120833

0.290503

-0.000956

-85544.474955

14455.525045

14455.525045

85542.000

100000.0

0.000

0.000

2

[{u’commission’: None, u’amount’: 318, u’sid’:…

0.0208

98063

0.0208

-0.000025

0.120833

2015-03-03 23:59:00+00:00

0.051796

-0.005688

-1.197544

0.113416

0.633538

0.077239

0.000000

14455.525045

14455.525045

84975.642

100000.0

85542.000

85542.000

3

[]

0.0212

442983

0.0212

-0.005688

0.113416

2015-03-04 23:59:00+00:00

0.342118

0.034955

0.401861

0.166666

0.524400

0.181468

0.000000

14455.525045

14455.525045

89040.000

100000.0

84975.642

84975.642

4

[]

0.0212

245889

0.0212

0.034955

0.166666

2015-03-05 23:59:00+00:00

0.637226

-0.038185

-3.914003

0.070834

0.976896

0.550520

0.000000

14455.525045

14455.525045

81726.000

100000.0

89040.000

89040.000

5

[]

0.0211

117440

0.0211

-0.038185

0.070834

2015-03-06 23:59:00+00:00

0.580521

-0.028645

-3.100822

0.083333

0.874082

0.546703

0.000000

14455.525045

14455.525045

82680.000

100000.0

81726.000

81726.000

6

[]

0.0224

84197

0.0224

-0.028645

0.083333

2015-03-07 23:59:00+00:00

0.530557

-0.028645

-2.625704

0.083333

0.802793

0.536589

0.000000

14455.525045

14455.525045

82680.000

100000.0

82680.000

82680.000

7

[]

0.0224

181

0.0224

-0.028645

0.083333

2015-03-08 23:59:00+00:00

0.491628

-0.028645

-2.276841

0.083333

0.746605

0.529163

0.000000

14455.525045

14455.525045

82680.000

100000.0

82680.000

82680.000

8

[]

0.0224

30900

0.0224

-0.028645

0.083333

2015-03-09 23:59:00+00:00

0.467885

-0.015925

-1.895269

0.100000

0.698764

0.532652

0.000000

14455.525045

14455.525045

83952.000

100000.0

82680.000

82680.000

9

[]

0.0220

128367

0.0220

-0.015925

0.100000

2015-03-10 23:59:00+00:00

0.626552

0.069935

-1.625285

0.212500

0.800983

0.676289

0.000000

14455.525045

14455.525045

92538.000

100000.0

83952.000

83952.000

10

[]

0.0214

54961

0.0214

0.069935

0.212500

2015-03-11 23:59:00+00:00

0.644515

0.022235

-1.727710

0.150000

0.834650

0.684052

0.000000

14455.525045

14455.525045

87768.000

100000.0

92538.000

92538.000

11

[]

0.0211

42511

0.0211

0.022235

0.150000

2015-03-12 23:59:00+00:00

0.614650

0.022235

-1.573455

0.150000

0.798403

0.680882

0.000000

14455.525045

14455.525045

87768.000

100000.0

87768.000

87768.000

12

[]

0.0210

2909

0.0210

0.022235

0.150000

2015-03-13 23:59:00+00:00

0.588942

0.019405

-1.454733

0.146291

0.767688

0.677881

0.000000

14455.525045

14455.525045

87484.980

100000.0

87768.000

87768.000

13

[]

0.0213

57613

0.0213

0.019405

0.146291

2015-03-14 23:59:00+00:00

0.565911

0.019373

-1.344915

0.146250

0.739230

0.675665

0.000000

14455.525045

14455.525045

87481.800

100000.0

87484.980

87484.980

14

[]

0.0213

48310

0.0213

0.019373

0.146250

2015-03-15 23:59:00+00:00

0.551394

0.041659

-1.191436

0.175450

0.714876

0.680484

0.000000

14455.525045

14455.525045

89710.344

100000.0

87481.800

87481.800

15

[]

0.0213

29454

0.0213

0.041659

0.175450

2015-03-16 23:59:00+00:00

0.541846

0.019055

-1.188212

0.145833

0.706049

0.680281

0.000000

14455.525045

14455.525045

87450.000

100000.0

89710.344

89710.344

16

[]

0.0210

25564

0.0210

0.019055

0.145833

2015-03-17 23:59:00+00:00

0.524682

0.019055

-1.115149

0.145833

0.684599

0.678870

0.000000

14455.525045

14455.525045

87450.000

100000.0

87450.000

87450.000

17

[]

0.0206

9

0.0206

0.019055

0.145833

2015-03-18 23:59:00+00:00

0.532621

-0.021999

-1.180440

0.092041

0.696261

0.685307

0.000000

14455.525045

14455.525045

83344.620

100000.0

87450.000

87450.000

18

[]

0.0193

164911

0.0193

-0.021999

0.092041

2015-03-19 23:59:00+00:00

0.518811

-0.013234

-1.096387

0.103526

0.676861

0.686186

0.000000

14455.525045

14455.525045

84221.028

100000.0

83344.620

83344.620

19

[]

0.0198

713904

0.0198

-0.013234

0.103526

2015-03-20 23:59:00+00:00

0.505168

-0.017324

-1.050273

0.098170

0.659945

0.685070

0.000000

14455.525045

14455.525045

83812.080

100000.0

84221.028

84221.028

20

[]

0.0193

132725

0.0193

-0.017324

0.098170

2015-03-21 23:59:00+00:00

0.492384

-0.018494

-1.002051

0.096637

0.643679

0.684283

0.000000

14455.525045

14455.525045

83695.056

100000.0

83812.080

83812.080

21

[]

0.0193

201155

0.0193

-0.018494

0.096637

2015-03-22 23:59:00+00:00

0.482998

-0.004744

-0.927947

0.114653

0.629319

0.686478

0.000000

14455.525045

14455.525045

85070.088

100000.0

83695.056

83695.056

22

[]

0.0193

64378

0.0193

-0.004744

0.114653

2015-03-23 23:59:00+00:00

0.477523

-0.026505

-0.935352

0.086139

0.623502

0.687025

0.000000

14455.525045

14455.525045

82894.014

100000.0

85070.088

85070.088

23

[]

0.0192

61850

0.0192

-0.026505

0.086139

2015-03-24 23:59:00+00:00

0.504086

-0.084215

-1.021023

0.010523

0.655188

0.701025

0.000000

14455.525045

14455.525045

77122.950

100000.0

82894.014

82894.014

24

[]

0.0188

490180

0.0188

-0.084215

0.010523

2015-03-25 23:59:00+00:00

0.497690

-0.068474

-0.952786

0.031148

0.644272

0.704251

0.000000

14455.525045

14455.525045

78697.050

100000.0

77122.950

77122.950

25

[]

0.0193

90862

0.0193

-0.068474

0.031148

2015-03-26 23:59:00+00:00

0.489730

-0.084215

-0.943240

0.010523

0.634965

0.703738

0.000000

14455.525045

14455.525045

77122.950

100000.0

78697.050

78697.050

26

[]

0.0201

2299

0.0201

-0.084215

0.010523

2015-03-27 23:59:00+00:00

0.495916

-0.049785

-0.857592

0.055636

0.636644

0.713671

0.000000

14455.525045

14455.525045

80565.936

100000.0

77122.950

77122.950

27

[]

0.0195

663

0.0195

-0.049785

0.055636

2015-03-28 23:59:00+00:00

0.488469

-0.064490

-0.848769

0.036368

0.627920

0.713212

0.000000

14455.525045

14455.525045

79095.504

100000.0

80565.936

80565.936

28

[]

0.0195

7061

0.0195

-0.064490

0.036368

2015-03-29 23:59:00+00:00

0.479671

-0.066903

-0.822844

0.033205

0.616787

0.712868

0.000000

14455.525045

14455.525045

78854.142

100000.0

79095.504

79095.504

29

[]

0.0195

8526

0.0195

-0.066903

0.033205

2015-03-30 23:59:00+00:00

0.476306

-0.046605

-0.769239

0.059803

0.610002

0.716464

0.000000

14455.525045

14455.525045

80883.936

100000.0

78854.142

78854.142

30

[]

0.0196

29654

0.0196

-0.046605

0.059803

2017-05-30 23:59:00+00:00

0.495432

5.949752

-0.016611

7.916664

0.554369

0.888883

0.000000

14455.525045

14455.525045

680519.682

100000.0

701826.000

701826.000

822

[]

0.0221

40157964723

0.0221

5.949752

7.916664

2017-05-31 23:59:00+00:00

0.495243

6.102328

-0.017086

8.154164

0.554182

0.888844

0.000000

14455.525045

14455.525045

695777.322

100000.0

680519.682

680519.682

823

[]

0.0221

31098652109

0.0221

6.102328

8.154164

2017-06-01 23:59:00+00:00

0.495836

6.504967

-0.014668

8.644144

0.554541

0.889303

0.000000

14455.525045

14455.525045

736041.210

100000.0

695777.322

695777.322

824

[]

0.0221

40944880757

0.0221

6.504967

8.644144

2017-06-02 23:59:00+00:00

0.495948

6.801995

-0.013641

9.033331

0.554581

0.889440

0.000000

14455.525045

14455.525045

765744.000

100000.0

736041.210

736041.210

825

[]

0.0215

22364557424

0.0215

6.801995

9.033331

2017-06-03 23:59:00+00:00

0.495729

6.952409

-0.013100

9.230418

0.554317

0.889470

0.000000

14455.525045

14455.525045

780785.400

100000.0

765744.000

765744.000

826

[]

0.0215

23687278961

0.0215

6.952409

9.230418

2017-06-04 23:59:00+00:00

0.495450

7.042244

-0.012768

9.348122

0.553999

0.889479

0.000000

14455.525045

14455.525045

789768.900

100000.0

780785.400

780785.400

827

[]

0.0215

21332021248

0.0215

7.042244

9.348122

2017-06-05 23:59:00+00:00

0.496148

7.524987

-0.011320

9.980649

0.554578

0.889805

0.000000

14455.525045

14455.525045

838043.208

100000.0

789768.900

789768.900

828

[]

0.0218

22372229837

0.0218

7.524987

9.980649

2017-06-06 23:59:00+00:00

0.497592

8.194835

-0.009554

10.858330

0.555841

0.890368

0.000000

14455.525045

14455.525045

905028.000

100000.0

838043.208

838043.208

829

[]

0.0214

81923184446

0.0214

8.194835

10.858330

2017-06-07 23:59:00+00:00

0.498895

7.557258

-0.011975

10.022932

0.557003

0.890845

0.000000

14455.525045

14455.525045

841270.272

100000.0

905028.000

905028.000

830

[]

0.0218

49070430356

0.0218

7.557258

10.022932

2017-06-08 23:59:00+00:00

0.499349

8.010395

-0.010676

10.616664

0.557357

0.891092

0.000000

14455.525045

14455.525045

886584.000

100000.0

841270.272

841270.272

831

[]

0.0219

34013412940

0.0219

8.010395

10.616664

2017-06-09 23:59:00+00:00

0.499063

8.099750

-0.010386

10.733746

0.557033

0.891098

0.000000

14455.525045

14455.525045

895519.482

100000.0

886584.000

886584.000

832

[]

0.0221

25275425996

0.0221

8.099750

10.733746

2017-06-10 23:59:00+00:00

0.498769

8.086143

-0.010416

10.715915

0.556705

0.891098

0.000000

14455.525045

14455.525045

894158.760

100000.0

895519.482

895519.482

833

[]

0.0221

30620792046

0.0221

8.086143

10.715915

2017-06-11 23:59:00+00:00

0.498971

8.484533

-0.009305

11.237914

0.556827

0.891266

0.000000

14455.525045

14455.525045

933997.800

100000.0

894158.760

894158.760

834

[]

0.0221

30830678595

0.0221

8.484533

11.237914

2017-06-12 23:59:00+00:00

0.503448

7.320494

-0.014065

9.712706

0.560936

0.892695

0.000000

14455.525045

14455.525045

817593.900

100000.0

933997.800

933997.800

835

[]

0.0221

88704710635

0.0221

7.320494

9.712706

2017-06-13 23:59:00+00:00

0.503565

7.656697

-0.013054

10.153225

0.560981

0.892830

0.000000

14455.525045

14455.525045

851214.132

100000.0

817593.900

817593.900

836

[]

0.0221

42251296767

0.0221

7.656697

10.153225

2017-06-14 23:59:00+00:00

0.506845

6.734516

-0.016873

8.944917

0.563995

0.893862

0.000000

14455.525045

14455.525045

758996.040

100000.0

851214.132

851214.132

837

[]

0.0215

63183088135

0.0215

6.734516

8.944917

2017-06-15 23:59:00+00:00

0.506562

6.695367

-0.016991

8.893622

0.563678

0.893865

0.000000

14455.525045

14455.525045

755081.142

100000.0

758996.040

758996.040

838

[]

0.0216

104677533974

0.0216

6.695367

8.893622

2017-06-16 23:59:00+00:00

0.506404

6.887855

-0.016343

9.145831

0.563472

0.893913

0.000000

14455.525045

14455.525045

774330.000

100000.0

755081.142

755081.142

839

[]

0.0216

43479966625

0.0216

6.887855

9.145831

2017-06-17 23:59:00+00:00

0.507407

7.435283

-0.014812

9.863113

0.564341

0.894311

0.000000

14455.525045

14455.525045

829072.746

100000.0

774330.000

774330.000

840

[]

0.0216

36800919715

0.0216

7.435283

9.863113

2017-06-18 23:59:00+00:00

0.507740

7.070069

-0.016112

9.384581

0.564605

0.894482

0.000000

14455.525045

14455.525045

792551.400

100000.0

829072.746

829072.746

841

[]

0.0216

46411759478

0.0216

7.070069

9.384581

2017-06-19 23:59:00+00:00

0.507754

7.358645

-0.015226

9.762694

0.564557

0.894583

0.000000

14455.525045

14455.525045

821408.946

100000.0

792551.400

792551.400

842

[]

0.0219

28294406623

0.0219

7.358645

9.762694

2017-06-20 23:59:00+00:00

0.507705

7.628795

-0.014414

10.116664

0.564451

0.894665

0.000000

14455.525045

14455.525045

848424.000

100000.0

821408.946

821408.946

843

[]

0.0216

36903854052

0.0216

7.628795

10.116664

2017-06-21 23:59:00+00:00

0.507531

7.476155

-0.014900

9.916664

0.564238

0.894696

0.000000

14455.525045

14455.525045

833160.000

100000.0

848424.000

848424.000

844

[]

0.0216

43815656010

0.0216

7.476155

9.916664

2017-06-22 23:59:00+00:00

0.507315

7.645891

-0.014372

10.139065

0.563979

0.894725

0.000000

14455.525045

14455.525045

850133.568

100000.0

833160.000

833160.000

845

[]

0.0215

22304647568

0.0215

7.645891

10.139065

2017-06-23 23:59:00+00:00

0.507020

7.635155

-0.014388

10.124997

0.563652

0.894725

0.000000

14455.525045

14455.525045

849060.000

100000.0

850133.568

850133.568

846

[]

0.0215

13090231864

0.0215

7.635155

10.124997

2017-06-24 23:59:00+00:00

0.507936

7.105628

-0.016304

9.431173

0.564463

0.895061

0.000000

14455.525045

14455.525045

796107.276

100000.0

849060.000

849060.000

847

[]

0.0215

34088563732

0.0215

7.105628

9.431173

2017-06-25 23:59:00+00:00

0.507675

7.036714

-0.016515

9.340880

0.564168

0.895069

0.000000

14455.525045

14455.525045

789215.898

100000.0

796107.276

796107.276

848

[]

0.0215

41560204433

0.0215

7.036714

9.340880

2017-06-26 23:59:00+00:00

0.507780

6.761571

-0.017485

8.980368

0.564221

0.895175

0.000000

14455.525045

14455.525045

761701.584

100000.0

789215.898

789215.898

849

[]

0.0214

73840480752

0.0214

6.761571

8.980368

2017-06-27 23:59:00+00:00

0.508048

7.126355

-0.016390

9.458331

0.564409

0.895349

0.000000

14455.525045

14455.525045

798180.000

100000.0

761701.584

761701.584

850

[]

0.0221

62426319778

0.0221

7.126355

9.458331

2017-06-28 23:59:00+00:00

0.507750

7.135895

-0.016340

9.470831

0.564078

0.895349

0.000000

14455.525045

14455.525045

799134.000

100000.0

798180.000

798180.000

851

[]

0.0222

39676839183

0.0222

7.135895

9.470831

851 rows × 45 columns

Also, instead of defining an output file we are accessing it via the “_” variable that will be created in the name space and contain the performance DataFrame.

_.head()

algo_volatility

algorithm_period_return

alpha

benchmark_period_return

benchmark_volatility

beta

capital_used

cash

ending_cash

ending_exposure

starting_cash

starting_exposure

starting_value

trading_days

transactions

treasury_period_return

volume

treasury

algorithm

benchmark

2015-03-01 23:59:00+00:00

NaN

0.000000

NaN

0.045833

NaN

NaN

0.000000

100000.000000

100000.000000

0.000

100000.0

0.000

0.000

1

[]

0.0200

317

0.0200

0.000000

0.045833

2015-03-02 23:59:00+00:00

0.000278

-0.000025

0.011045

0.120833

0.290503

-0.000956

-85544.474955

14455.525045

14455.525045

85542.000

100000.0

0.000

0.000

2

[{u’commission’: None, u’amount’: 318, u’sid’:…

0.0208

98063

0.0208

-0.000025

0.120833

2015-03-03 23:59:00+00:00

0.051796

-0.005688

-1.197544

0.113416

0.633538

0.077239

0.000000

14455.525045

14455.525045

84975.642

100000.0

85542.000

85542.000

3

[]

0.0212

442983

0.0212

-0.005688

0.113416

2015-03-04 23:59:00+00:00

0.342118

0.034955

0.401861

0.166666

0.524400

0.181468

0.000000

14455.525045

14455.525045

89040.000

100000.0

84975.642

84975.642

4

[]

0.0212

245889

0.0212

0.034955

0.166666

2015-03-05 23:59:00+00:00

0.637226

-0.038185

-3.914003

0.070834

0.976896

0.550520

0.000000

14455.525045

14455.525045

81726.000

100000.0

89040.000

89040.000

5

[]

0.0211

117440

0.0211

-0.038185

0.070834

5 rows × 45 columns

Note

Currently, the quote currency of all trading pairs ordered by the algorithm must match the value of the quote_currency.

PyCharm IDE

PyCharm is an Integrated Development Environment (IDE) used in computer programming, specifically for the Python language. It streamlines the continuous development of Python code, and among other things includes a debugger that comes in handy to see the inner workings of Catalyst, and your trading algorithms.

Install

Install PyCharm from their Website. There is a free and open-source Community version.

Setup

  1. When creating a new project in PyCharm, right under where you specify the Location, click on Project Interpreter to display a drop down menu
  2. Select Existing interpreter, click the gear box right next to it and select ‘add local’. Depending on your installation, select either “Virtual Environment” or “Conda Environment” and click the ‘…’ button to navigate to your catalyst env and select the Python binary file: ``bin/python`` for Linux/MacOS installations or ‘python.exe’ for Windows installs (for example: ‘C:\Users\user\Anaconda2\envs\catalyst\python.exe’). Select OK. You may want to click on *Make available to all projects for your future reference. Click OK again, and create your new environment using the set up of your virtual environment.

Alternatively, if you already have your project created, in Windows do:

  1. File -> Default Settings -> Project Interpreter. Click the gear box next to the project interpreter and select ‘add local’, and follow the steps from the second step above.

On MacOS:

  1. PyCharm -> Preferences -> Settings -> Project:’NAME_OF_PROJECT’ -> Project Interpreter. Click the gear box next to the project interpreter and select ‘add local’, and follow the steps from the second step above.

You should now be able to run your project/scripts in PyCharm.

Next steps

We hope that this tutorial gave you a little insight into the architecture, API, and features of Catalyst. For your next step, check out some of the other example algorithms.

Feel free to ask questions on the #catalyst_dev channel of our Discord group and report problems on our GitHub issue tracker.