wassname/catalyst
1
0
Fork 0
mirror of https://github.com/wassname/catalyst.git synced 2026-06-27 21:51:37 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d1faac04161e0f7b74228d681f224e93e5598da0
catalyst/beginner-tutorial.html
T
Victor Grau Serrat d1faac0416 DOC: improved beginner tutorial
2017-11-27 21:07:57 -07:00

1034 lines
76 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Catalyst Beginner Tutorial &mdash; Catalyst 0.3 documentation</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="top" title="Catalyst 0.3 documentation" href="index.html"/>
<link rel="next" title="Catalyst &amp; Jupyter Notebook" href="jupyter.html"/>
<link rel="prev" title="Install" href="install.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Catalyst
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="install.html">Install</a><ul>
<li class="toctree-l2"><a class="reference internal" href="install.html#installing-with-conda">Installing with <code class="docutils literal"><span class="pre">conda</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="install.html#troubleshooting-conda-install">Troubleshooting <code class="docutils literal"><span class="pre">conda</span></code> Install</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="install.html#installing-with-pip">Installing with <code class="docutils literal"><span class="pre">pip</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="install.html#troubleshooting-pip-install">Troubleshooting <code class="docutils literal"><span class="pre">pip</span></code> Install</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="install.html#gnu-linux-requirements">GNU/Linux Requirements</a><ul>
<li class="toctree-l3"><a class="reference internal" href="install.html#amazon-linux-ami-notes">Amazon Linux AMI Notes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="install.html#macos-requirements">MacOS Requirements</a><ul>
<li class="toctree-l3"><a class="reference internal" href="install.html#macos-virtualenv-matplotlib">MacOS + virtualenv + matplotlib</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="install.html#windows-requirements">Windows Requirements</a></li>
<li class="toctree-l2"><a class="reference internal" href="install.html#getting-help">Getting Help</a></li>
</ul>
</li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Catalyst Beginner Tutorial</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#basics">Basics</a></li>
<li class="toctree-l2"><a class="reference internal" href="#my-first-algorithm">My first algorithm</a></li>
<li class="toctree-l2"><a class="reference internal" href="#ingesting-data">Ingesting data</a></li>
<li class="toctree-l2"><a class="reference internal" href="#running-the-algorithm">Running the algorithm</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#command-line-interface">Command line interface</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#access-to-previous-prices-using-history">Access to previous prices using <code class="docutils literal"><span class="pre">history</span></code></a><ul>
<li class="toctree-l3"><a class="reference internal" href="#working-example-dual-moving-average-cross-over">Working example: Dual Moving Average Cross-Over</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#next-steps">Next steps</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="jupyter.html">Catalyst &amp; Jupyter Notebook</a><ul>
<li class="toctree-l2"><a class="reference internal" href="jupyter.html#install">Install</a></li>
<li class="toctree-l2"><a class="reference internal" href="jupyter.html#running-algorithms">Running Algorithms</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="live-trading.html">Live Trading</a><ul>
<li class="toctree-l2"><a class="reference internal" href="live-trading.html#supported-exchanges">Supported Exchanges</a></li>
<li class="toctree-l2"><a class="reference internal" href="live-trading.html#authentication">Authentication</a></li>
<li class="toctree-l2"><a class="reference internal" href="live-trading.html#currency-symbols">Currency Symbols</a></li>
<li class="toctree-l2"><a class="reference internal" href="live-trading.html#trading-an-algorithm">Trading an Algorithm</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="naming-convention.html">Naming Convention</a></li>
<li class="toctree-l1"><a class="reference internal" href="example-algos.html">Example Algorithms</a><ul>
<li class="toctree-l2"><a class="reference internal" href="example-algos.html#buy-and-hodl-algorithm">Buy and Hodl Algorithm</a></li>
<li class="toctree-l2"><a class="reference internal" href="example-algos.html#mean-reversion-algorithm">Mean Reversion Algorithm</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="utilities.html">Utilities</a><ul>
<li class="toctree-l2"><a class="reference internal" href="utilities.html#output-to-csv-file">Output to CSV file</a></li>
<li class="toctree-l2"><a class="reference internal" href="utilities.html#extracting-market-data">Extracting market data</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="videos.html">Videos</a><ul>
<li class="toctree-l2"><a class="reference internal" href="videos.html#installation-macos">Installation: MacOS</a></li>
<li class="toctree-l2"><a class="reference internal" href="videos.html#installation-windows">Installation: Windows</a></li>
<li class="toctree-l2"><a class="reference internal" href="videos.html#backtesting-a-strategy">Backtesting a Strategy</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="resources.html">Resources</a><ul>
<li class="toctree-l2"><a class="reference internal" href="resources.html#related-3rd-party-apis">Related 3rd Party APIs</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="development-guidelines.html">Development Guidelines</a><ul>
<li class="toctree-l2"><a class="reference internal" href="development-guidelines.html#creating-a-development-environment">Creating a Development Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="development-guidelines.html#git-branching-structure">Git Branching Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="development-guidelines.html#contributing-to-the-docs">Contributing to the Docs</a></li>
<li class="toctree-l2"><a class="reference internal" href="development-guidelines.html#commit-messages">Commit messages</a></li>
<li class="toctree-l2"><a class="reference internal" href="development-guidelines.html#formatting-docstrings">Formatting Docstrings</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="releases.html">Release Notes</a><ul>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-8">Version 0.3.8</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#bug-fixes">Bug Fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-7">Version 0.3.7</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id1">Bug Fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="releases.html#build">Build</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-6">Version 0.3.6</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id2">Bug Fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-5">Version 0.3.5</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id3">Bug Fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-4">Version 0.3.4</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id4">Bug Fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id5">Build</a></li>
<li class="toctree-l3"><a class="reference internal" href="releases.html#documentation">Documentation</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-3">Version 0.3.3</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id7">Bug Fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id8">Build</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-2">Version 0.3.2</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id9">Bug Fixes</a></li>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id10">Build</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3-1">Version 0.3.1</a><ul>
<li class="toctree-l3"><a class="reference internal" href="releases.html#id11">Bug Fixes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-3">Version 0.3</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-2-dev5">Version 0.2.dev5</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-2-dev4">Version 0.2.dev4</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-2-dev3">Version 0.2.dev3</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-2-dev2">Version 0.2.dev2</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-2-dev1">Version 0.2.dev1</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-1-dev9">Version 0.1.dev9</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-1-dev8">Version 0.1.dev8</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-1-dev7">Version 0.1.dev7</a></li>
<li class="toctree-l2"><a class="reference internal" href="releases.html#version-0-1-dev6">Version 0.1.dev6</a></li>
</ul>
</li>
</ul>
</div>
&nbsp;
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Catalyst</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> &raquo;</li>
<li>Catalyst Beginner Tutorial</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/beginner-tutorial.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document">
<div class="section" id="catalyst-beginner-tutorial">
<h1>Catalyst Beginner Tutorial<a class="headerlink" href="#catalyst-beginner-tutorial" title="Permalink to this headline"></a></h1>
<div class="section" id="basics">
<h2>Basics<a class="headerlink" href="#basics" title="Permalink to this headline"></a></h2>
<p>Catalyst is an open-source algorithmic trading simulator for crypto
assets written in Python. The source code can be found at:
<a class="reference external" href="https://github.com/enigmampc/catalyst">https://github.com/enigmampc/catalyst</a></p>
<p>Some benefits include:</p>
<ul class="simple">
<li>Support for several of the top crypto-exchanges by trading volume.</li>
<li>Realistic: slippage, transaction costs, order delays.</li>
<li>Stream-based: Process each event individually, avoids look-ahead
bias.</li>
<li>Batteries included: Common transforms (moving average) as well as
common risk calculations (Sharpe).</li>
<li>Developed and continuously updated by
<a class="reference external" href="https://www.enigma.co">Enigma MPC</a> 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.</li>
</ul>
<p>This tutorial assumes that you have Catalyst correctly installed, see the
<a class="reference internal" href="install.html"><em>Install</em></a> section if you haven&#8217;t set up Catalyst yet.</p>
<p>Every <code class="docutils literal"><span class="pre">catalyst</span></code> algorithm consists of at least two functions you have to
define:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">initialize(context)</span></code></li>
<li><code class="docutils literal"><span class="pre">handle_data(context,</span> <span class="pre">data)</span></code></li>
</ul>
<p>Before the start of the algorithm, <code class="docutils literal"><span class="pre">catalyst</span></code> calls the
<code class="docutils literal"><span class="pre">initialize()</span></code> function and passes in a <code class="docutils literal"><span class="pre">context</span></code> variable.
<code class="docutils literal"><span class="pre">context</span></code> is a persistent namespace for you to store variables you
need to access from one algorithm iteration to the next.</p>
<p>After the algorithm has been initialized, <code class="docutils literal"><span class="pre">catalyst</span></code> calls the
<code class="docutils literal"><span class="pre">handle_data()</span></code> function on each iteration, that&#8217;s one per day (daily) or
once every minute (minute), depending on the frequency we choose to run our
simulation. On every iteration, <code class="docutils literal"><span class="pre">handle_data()</span></code> passes the same <code class="docutils literal"><span class="pre">context</span></code>
variable and an event-frame called <code class="docutils literal"><span class="pre">data</span></code> containing the current trading bar
with open, high, low, and close (OHLC) prices as well as volume for each
crypto asset in your universe.</p>
</div>
<div class="section" id="my-first-algorithm">
<h2>My first algorithm<a class="headerlink" href="#my-first-algorithm" title="Permalink to this headline"></a></h2>
<p>Lets take a look at a very simple algorithm from the <code class="docutils literal"><span class="pre">examples</span></code> directory:
<a class="reference external" href="https://github.com/enigmampc/catalyst/blob/master/catalyst/examples/buy_btc_simple.py">buy_btc_simple.py</a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">catalyst.api</span> <span class="kn">import</span> <span class="n">order</span><span class="p">,</span> <span class="n">record</span><span class="p">,</span> <span class="n">symbol</span>
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="n">context</span><span class="o">.</span><span class="n">asset</span> <span class="o">=</span> <span class="n">symbol</span><span class="p">(</span><span class="s">&#39;btc_usd&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_data</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="n">order</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">record</span><span class="p">(</span><span class="n">btc</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">))</span>
</pre></div>
</div>
<p>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
<code class="docutils literal"><span class="pre">catalyst.api</span></code>. Here we are using <code class="xref py py-func docutils literal"><span class="pre">order()</span></code> which takes
twoarguments: a cryptoasset object, and a number specifying how many assets you
wouldlike to order (if negative, <code class="xref py py-func docutils literal"><span class="pre">order()</span></code> will sell/short
assets). In this case we want to order 1 bitcoin at each iteration.</p>
<p>Finally, the <code class="xref py py-func docutils literal"><span class="pre">record()</span></code> 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: <code class="docutils literal"><span class="pre">varname=var</span></code>. After the algorithm
finished running you will have access to each variable value you tracked
with <code class="xref py py-func docutils literal"><span class="pre">record()</span></code> 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 <code class="docutils literal"><span class="pre">data</span></code> event frame.</p>
</div>
<div class="section" id="ingesting-data">
<h2>Ingesting data<a class="headerlink" href="#ingesting-data" title="Permalink to this headline"></a></h2>
<p>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
<code class="docutils literal"><span class="pre">ingestion</span></code>. 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.</p>
<p>In order to ingest data, you need to run a command like the following:</p>
<div class="highlight-bash"><div class="highlight"><pre>catalyst ingest-exchange -x bitfinex -i btc_usd
</pre></div>
</div>
<p>This instructs Catalyst to download pricing data from the <code class="docutils literal"><span class="pre">Bitfinex</span></code> exchange
for the <code class="docutils literal"><span class="pre">btc_usd</span></code> currency pair (this follows from the simple algorithm
presented above where we want to trade <code class="docutils literal"><span class="pre">btc_usd</span></code>), and we&#8217;re choosing to test
our algorithm using historical pricing data from the Bitfinex exchange. By
default, Catalyst assumes that you want data with <code class="docutils literal"><span class="pre">daily</span></code> frequency (one candle
bar per day). If you want instead <code class="docutils literal"><span class="pre">minute</span></code> frequency (one candle bar for every
minute), you would need to specify it as follows:</p>
<div class="highlight-bash"><div class="highlight"><pre>catalyst ingest-exchange -x bitfinex -i btc_usd -f minute
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>Ingesting exchange bundle bitfinex...
[====================================] Ingesting daily price data on bitfinex: 100%
</pre></div>
</div>
<p>We believe it is important for you to have a high-level understanding of how
data is managed, hence the following overview:</p>
<ul class="simple">
<li>Pricing data is split and packaged into <code class="docutils literal"><span class="pre">bundles</span></code>: chunks of data organized
as time series that are kept up to date daily on Enigma&#8217;s servers. Catalyst
downloads the requested bundles and reconstructs the full dataset in your
hard drive.</li>
<li>Pricing data is provided in <code class="docutils literal"><span class="pre">daily</span></code> and <code class="docutils literal"><span class="pre">minute</span></code> resolution. Those are
different bundle datasets, and are managed separately.</li>
<li>Bundles are exchange-specific, as the pricing data is specific to the trades
that happen in each exchange. As a result, you can must specify which
exchange you want pricing data from when ingesting data</li>
<li>Catalyst keeps track of all the downloaded bundles, so that it only has to
download them once, and will do incremental updates as needed.</li>
<li>When running in <code class="docutils literal"><span class="pre">live</span> <span class="pre">trading</span></code> 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.</li>
</ul>
<p>The <code class="docutils literal"><span class="pre">ingest-exchange</span></code> 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:</p>
<div class="highlight-bash"><div class="highlight"><pre>catalyst ingest-exchange --help
</pre></div>
</div>
</div>
<div class="section" id="running-the-algorithm">
<h2>Running the algorithm<a class="headerlink" href="#running-the-algorithm" title="Permalink to this headline"></a></h2>
<p>You can now test your algorithm using cryptoassets&#8217; historical pricing data,
<code class="docutils literal"><span class="pre">catalyst</span></code> provides three interfaces:</p>
<ul class="simple">
<li>A command-line interface (CLI),</li>
<li>a <code class="xref py py-func docutils literal"><span class="pre">run_algorithm()</span></code> that you can call from other
Python scripts,</li>
<li>and the <code class="docutils literal"><span class="pre">Jupyter</span> <span class="pre">Notebook</span></code> magic.</li>
</ul>
<p>We&#8217;ll start with the CLI, and introduce the <code class="docutils literal"><span class="pre">run_algorithm()</span></code> in the last
example of this tutorial. Some of the <a class="reference internal" href="example-algos.html"><em>example algorithms</em></a>
provide instructions on how to run them both from the CLI, and using the
<code class="xref py py-func docutils literal"><span class="pre">run_algorithm()</span></code> function. For the third method, refer to the
corresponding section on <a class="reference internal" href="jupyter.html"><em>Catalyst &amp; Jupyter Notebook</em></a> after you
have assimilated the contents of this tutorial.</p>
<div class="section" id="command-line-interface">
<h3>Command line interface<a class="headerlink" href="#command-line-interface" title="Permalink to this headline"></a></h3>
<p>After you installed Catalyst, you should be able to execute the following
from your command line (e.g. <code class="docutils literal"><span class="pre">cmd.exe</span></code> or the <code class="docutils literal"><span class="pre">Anaconda</span> <span class="pre">Prompt</span></code> on Windows,
or the Terminal application on MacOS).</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>catalyst --help
</pre></div>
</div>
<p>This is the resulting output, simplified for eductional purposes:</p>
<div class="highlight-python"><div class="highlight"><pre>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.
</pre></div>
</div>
<p>There are three main modes you can run on Catalyst. The first being
<code class="docutils literal"><span class="pre">ingest-exchange</span></code> for data ingestion, which we have covered in the previous
section. The second is <code class="docutils literal"><span class="pre">live</span></code> to use your algorithm to trade live against a
given exchange, and the third mode <code class="docutils literal"><span class="pre">run</span></code> is to backtest your algorithm before
trading live with it.</p>
<p>Let&#8217;s start with backtesting, so run this other command to learn more about
the available options:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>catalyst run --help
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>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
&#39;-Dname=value&#39;. 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: &lt;current-time&gt;]
-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 &#39;-&#39; 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.
</pre></div>
</div>
<p>As you can see there are a couple of flags that specify where to find your
algorithm (<code class="docutils literal"><span class="pre">-f</span></code>) as well as a the <code class="docutils literal"><span class="pre">-x</span></code> flag to specify which exchange to
use. There are also arguments for the date range to run the algorithm over
(<code class="docutils literal"><span class="pre">--start</span></code> and <code class="docutils literal"><span class="pre">--end</span></code>). You also need to set the base currency for your
algorithm through the <code class="docutils literal"><span class="pre">-c</span></code> flag, and the <code class="docutils literal"><span class="pre">--capital_base</span></code>. 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 <code class="docutils literal"><span class="pre">--output</span></code> flag and will cause it to write the
performance <code class="docutils literal"><span class="pre">DataFrame</span></code> 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 <code class="docutils literal"><span class="pre">-c</span></code> option so that you don&#8217;t have to supply the
command line args all the time.</p>
<p>Thus, to execute our algorithm from above and save the results to
<code class="docutils literal"><span class="pre">buy_btc_simple_out.pickle</span></code> we would call <code class="docutils literal"><span class="pre">catalyst</span> <span class="pre">run</span></code> as follows:</p>
<div class="highlight-bash"><div class="highlight"><pre>catalyst run -f buy_btc_simple.py -x bitfinex --start 2016-1-1 --end 2017-9-30 -c usd --capital-base <span class="m">100000</span> -o buy_btc_simple_out.pickle
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre>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
</pre></div>
</div>
<p><code class="docutils literal"><span class="pre">run</span></code> first calls the <code class="docutils literal"><span class="pre">initialize()</span></code> function, and then
streams the historical asset price day-by-day through <code class="docutils literal"><span class="pre">handle_data()</span></code>.
After each call to <code class="docutils literal"><span class="pre">handle_data()</span></code> we instruct <code class="docutils literal"><span class="pre">catalyst</span></code> to order 1
bitcoin. After the call of the <code class="docutils literal"><span class="pre">order()</span></code> function, <code class="docutils literal"><span class="pre">catalyst</span></code>
enters the ordered stock and amount in the order book. After the
<code class="docutils literal"><span class="pre">handle_data()</span></code> function has finished, <code class="docutils literal"><span class="pre">catalyst</span></code> 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 <code class="docutils literal"><span class="pre">catalyst</span></code> uses).</p>
<p>Let&#8217;s take a quick look at the performance <code class="docutils literal"><span class="pre">DataFrame</span></code>. For this, we write
different Python script&#8211;let&#8217;s call it <code class="docutils literal"><span class="pre">print_results.py</span></code>&#8211;and we make use of
the fantastic <code class="docutils literal"><span class="pre">pandas</span></code> library to print the first ten rows. Note that
<code class="docutils literal"><span class="pre">catalyst</span></code> makes heavy usage of <a class="reference external" href="http://pandas.pydata.org/">pandas</a>,
especially for data analysis and outputting so it&#8217;s worth spending some time to
learn it.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pandas</span> <span class="kn">as</span> <span class="nn">pd</span>
<span class="n">perf</span> <span class="o">=</span> <span class="n">pd</span><span class="o">.</span><span class="n">read_pickle</span><span class="p">(</span><span class="s">&#39;buy_btc_simple_out.pickle&#39;</span><span class="p">)</span> <span class="c"># read in perf DataFrame</span>
<span class="k">print</span><span class="p">(</span><span class="n">perf</span><span class="o">.</span><span class="n">head</span><span class="p">())</span>
</pre></div>
</div>
<p>Which we execute by running:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>python print_results.py
</pre></div>
</div>
<div style="max-height:1000px;max-width:1500px;overflow:auto;">
<table border="1" class="dataframe">
<thead>
<tr style="text-align: right;">
<th></th>
<th>algo_volatility</th>
<th>algorithm_period_return</th>
<th>alpha</th>
<th>benchmark_period_return</th>
<th>benchmark_volatility</th>
<th>beta</th>
<th>btc</th>
<th>capital_used</th>
<th>ending_cash</th>
<th>ending_exposure</th>
<th>...</th>
<th>short_exposure</th>
<th>short_value</th>
<th>shorts_count</th>
<th>sortino</th>
<th>starting_cash</th>
<th>starting_exposure</th>
<th>starting_value</th>
<th>trading_days</th>
<th>transactions</th>
<th>treasury_period_return</th>
</tr>
</thead>
<tbody>
<tr>
<th>2016-01-01 23:59:00+00:00</th>
<td>NaN</td>
<td>0.000000e+00</td>
<td>NaN</td>
<td>-0.010937</td>
<td>NaN</td>
<td>NaN</td>
<td>433.979999</td>
<td>0.000000</td>
<td>1.000000e+07</td>
<td>0.00</td>
<td>...</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>NaN</td>
<td>1.000000e+07</td>
<td>0.00</td>
<td>0.00</td>
<td>1</td>
<td>[]</td>
<td>0.0227</td>
</tr>
<tr>
<th>2016-01-02 23:59:00+00:00</th>
<td>0.000011</td>
<td>-9.536708e-07</td>
<td>-0.000170</td>
<td>-0.006480</td>
<td>0.173338</td>
<td>-0.000062</td>
<td>432.700000</td>
<td>-442.236708</td>
<td>9.999558e+06</td>
<td>432.70</td>
<td>...</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>-11.224972</td>
<td>1.000000e+07</td>
<td>0.00</td>
<td>0.00</td>
<td>2</td>
<td>[{u'order_id': u'7869f7828fa140328eb40477bb7de...</td>
<td>0.0227</td>
</tr>
<tr>
<th>2016-01-03 23:59:00+00:00</th>
<td>0.000011</td>
<td>-2.328842e-06</td>
<td>-0.000176</td>
<td>-0.026512</td>
<td>0.197857</td>
<td>0.000009</td>
<td>428.390000</td>
<td>-437.831716</td>
<td>9.999120e+06</td>
<td>856.78</td>
<td>...</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>-12.754262</td>
<td>9.999558e+06</td>
<td>432.70</td>
<td>432.70</td>
<td>3</td>
<td>[{u'order_id': u'be62ff77760c4599abaac43be9cc9...</td>
<td>0.0227</td>
</tr>
<tr>
<th>2016-01-04 23:59:00+00:00</th>
<td>0.000011</td>
<td>-2.380954e-06</td>
<td>-0.000139</td>
<td>-0.008640</td>
<td>0.269790</td>
<td>0.000020</td>
<td>432.900000</td>
<td>-442.441116</td>
<td>9.998677e+06</td>
<td>1298.70</td>
<td>...</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>-11.287205</td>
<td>9.999120e+06</td>
<td>856.78</td>
<td>856.78</td>
<td>4</td>
<td>[{u'order_id': u'd6dca79513214346a646079213526...</td>
<td>0.0224</td>
</tr>
<tr>
<th>2016-01-05 23:59:00+00:00</th>
<td>0.000011</td>
<td>-3.650729e-06</td>
<td>-0.000158</td>
<td>-0.021426</td>
<td>0.245989</td>
<td>0.000024</td>
<td>431.840000</td>
<td>-441.357754</td>
<td>9.998236e+06</td>
<td>1727.36</td>
<td>...</td>
<td>0</td>
<td>0</td>
<td>0</td>
<td>-12.333847</td>
<td>9.998677e+06</td>
<td>1298.70</td>
<td>1298.70</td>
<td>5</td>
<td>[{u'order_id': u'505275d6646a41f3856b22b16678d...</td>
<td>0.0225</td>
</tr>
</tbody>
</table>
</div><div class="line-block">
<div class="line"><br /></div>
</div>
<p>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
<code class="docutils literal"><span class="pre">btc</span></code> was placed there by the <code class="docutils literal"><span class="pre">record()</span></code> 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.</p>
<p>Now we will run the simulation again, but this time we extend our original
algorithm with the addition of the <code class="docutils literal"><span class="pre">analyze()</span></code> function. Somewhat analogously
as how <code class="docutils literal"><span class="pre">initialize()</span></code> gets called once before the start of the algorith,
<code class="docutils literal"><span class="pre">analyze()</span></code> gets called once at the end of the algorithm, and receives two
variables: <code class="docutils literal"><span class="pre">context</span></code>, which we discussed at the very beginning, and <code class="docutils literal"><span class="pre">perf</span></code>,
which is the pandas dataframe containing the performance data for our algorithm
that we reviewed above. Inside the <code class="docutils literal"><span class="pre">analyze()</span></code> function is where we can
analyze and visualize the results of our strategy. Here&#8217;s the revised simple
algorithm (note the addition of Line 1, and Lines 11-18)</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="kn">from</span> <span class="nn">catalyst.api</span> <span class="kn">import</span> <span class="n">order</span><span class="p">,</span> <span class="n">record</span><span class="p">,</span> <span class="n">symbol</span>
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="n">context</span><span class="o">.</span><span class="n">asset</span> <span class="o">=</span> <span class="n">symbol</span><span class="p">(</span><span class="s">&#39;btc_usd&#39;</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">handle_data</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="n">order</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="n">record</span><span class="p">(</span><span class="n">btc</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">))</span>
<span class="k">def</span> <span class="nf">analyze</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">perf</span><span class="p">):</span>
<span class="n">ax1</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">211</span><span class="p">)</span>
<span class="n">perf</span><span class="o">.</span><span class="n">portfolio_value</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ax</span><span class="o">=</span><span class="n">ax1</span><span class="p">)</span>
<span class="n">ax1</span><span class="o">.</span><span class="n">set_ylabel</span><span class="p">(</span><span class="s">&#39;portfolio value&#39;</span><span class="p">)</span>
<span class="n">ax2</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">212</span><span class="p">,</span> <span class="n">sharex</span><span class="o">=</span><span class="n">ax1</span><span class="p">)</span>
<span class="n">perf</span><span class="o">.</span><span class="n">btc</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ax</span><span class="o">=</span><span class="n">ax2</span><span class="p">)</span>
<span class="n">ax2</span><span class="o">.</span><span class="n">set_ylabel</span><span class="p">(</span><span class="s">&#39;bitcoin price&#39;</span><span class="p">)</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
</pre></div>
</div>
<p>Here we make use of the external visualization library called
<a class="reference external" href="https://matplotlib.org/">matplotlib</a>, which you might recall we installed
alongside enigma-catalyst (with the exception of the <code class="docutils literal"><span class="pre">Conda</span></code> install, where it
was included by default inside the conda environment we created). If for any
reason you don&#8217;t have it installed, you can add it by running:</p>
<div class="highlight-python"><div class="highlight"><pre>(catalyst)$ pip install matplotlib
</pre></div>
</div>
<p>If everything works well, you&#8217;ll see the following chart:</p>
<img alt="https://s3.amazonaws.com/enigmaco-docs/github.io/buy_btc_simple_graph.png" src="https://s3.amazonaws.com/enigmaco-docs/github.io/buy_btc_simple_graph.png" />
<p>Our algorithm performance as assessed by the <code class="docutils literal"><span class="pre">portfolio_value</span></code> closely
matches that of the bitcoin price. This is not surprising as our algorithm
only bought bitcoin every chance it got.</p>
<blockquote>
<div><p>If you get an error when invoking matplotlib to visualize the performance
results refer to <a class="reference external" href="install.html#macos-virtualenv-matplotlib">MacOS + Matplotlib</a>.
Alternatively, some users have reported the following error when running an algo
in a Linux environment:</p>
<div class="highlight-python"><div class="highlight"><pre>ImportError: No module named _tkinter, please install the python-tk package
</pre></div>
</div>
<p>Which can easily solved by running (in Ubuntu/Debian-based systems):</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">sudo</span> <span class="n">apt</span> <span class="n">install</span> <span class="n">python</span><span class="o">-</span><span class="n">tk</span>
</pre></div>
</div>
</div></blockquote>
</div>
</div>
<div class="section" id="access-to-previous-prices-using-history">
<h2>Access to previous prices using <code class="docutils literal"><span class="pre">history</span></code><a class="headerlink" href="#access-to-previous-prices-using-history" title="Permalink to this headline"></a></h2>
<div class="section" id="working-example-dual-moving-average-cross-over">
<h3>Working example: Dual Moving Average Cross-Over<a class="headerlink" href="#working-example-dual-moving-average-cross-over" title="Permalink to this headline"></a></h3>
<p>The Dual Moving Average (DMA) is a classic momentum strategy. It&#8217;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) &#8211; 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.</p>
<p>As we need to have access to previous prices to implement this strategy
we need a new concept: History. <code class="docutils literal"><span class="pre">data.history()</span></code> 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 <code class="docutils literal"><span class="pre">'1d'</span></code>
for daily or <code class="docutils literal"><span class="pre">'1m'</span></code> for minute frequency, but note that you need to have
minute-level data when using <code class="docutils literal"><span class="pre">1m</span></code>). This is a function we use in the
<code class="docutils literal"><span class="pre">handle_data()</span></code> section.</p>
<p>You will note that the code below is substantially longer than the previous
examples. Don&#8217;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 <code class="docutils literal"><span class="pre">examples</span></code> directory:
<a class="reference external" href="https://github.com/enigmampc/catalyst/blob/master/catalyst/examples/dual_moving_average.py">dual_moving_average.py</a>.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">numpy</span> <span class="kn">as</span> <span class="nn">np</span>
<span class="kn">import</span> <span class="nn">pandas</span> <span class="kn">as</span> <span class="nn">pd</span>
<span class="kn">from</span> <span class="nn">logbook</span> <span class="kn">import</span> <span class="n">Logger</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="kn">as</span> <span class="nn">plt</span>
<span class="kn">from</span> <span class="nn">catalyst</span> <span class="kn">import</span> <span class="n">run_algorithm</span>
<span class="kn">from</span> <span class="nn">catalyst.api</span> <span class="kn">import</span> <span class="p">(</span><span class="n">order</span><span class="p">,</span> <span class="n">record</span><span class="p">,</span> <span class="n">symbol</span><span class="p">,</span> <span class="n">order_target_percent</span><span class="p">,</span>
<span class="n">get_open_orders</span><span class="p">)</span>
<span class="kn">from</span> <span class="nn">catalyst.exchange.stats_utils</span> <span class="kn">import</span> <span class="n">extract_transactions</span>
<span class="n">NAMESPACE</span> <span class="o">=</span> <span class="s">&#39;dual_moving_average&#39;</span>
<span class="n">log</span> <span class="o">=</span> <span class="n">Logger</span><span class="p">(</span><span class="n">NAMESPACE</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">context</span><span class="p">):</span>
<span class="n">context</span><span class="o">.</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">context</span><span class="o">.</span><span class="n">asset</span> <span class="o">=</span> <span class="n">symbol</span><span class="p">(</span><span class="s">&#39;ltc_usd&#39;</span><span class="p">)</span>
<span class="n">context</span><span class="o">.</span><span class="n">base_price</span> <span class="o">=</span> <span class="bp">None</span>
<span class="k">def</span> <span class="nf">handle_data</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="c"># define the windows for the moving averages</span>
<span class="n">short_window</span> <span class="o">=</span> <span class="mi">50</span>
<span class="n">long_window</span> <span class="o">=</span> <span class="mi">200</span>
<span class="c"># Skip as many bars as long_window to properly compute the average</span>
<span class="n">context</span><span class="o">.</span><span class="n">i</span> <span class="o">+=</span> <span class="mi">1</span>
<span class="k">if</span> <span class="n">context</span><span class="o">.</span><span class="n">i</span> <span class="o">&lt;</span> <span class="n">long_window</span><span class="p">:</span>
<span class="k">return</span>
<span class="c"># Compute moving averages calling data.history() for each</span>
<span class="c"># moving average with the appropriate parameters. We choose to use</span>
<span class="c"># minute bars for this simulation -&gt; freq=&quot;1m&quot;</span>
<span class="c"># Returns a pandas dataframe.</span>
<span class="n">short_mavg</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">history</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">,</span>
<span class="n">bar_count</span><span class="o">=</span><span class="n">short_window</span><span class="p">,</span> <span class="n">frequency</span><span class="o">=</span><span class="s">&quot;1m&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">mean</span><span class="p">()</span>
<span class="n">long_mavg</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">history</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">,</span>
<span class="n">bar_count</span><span class="o">=</span><span class="n">long_window</span><span class="p">,</span> <span class="n">frequency</span><span class="o">=</span><span class="s">&quot;1m&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">mean</span><span class="p">()</span>
<span class="c"># Let&#39;s keep the price of our asset in a more handy variable</span>
<span class="n">price</span> <span class="o">=</span> <span class="n">data</span><span class="o">.</span><span class="n">current</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">)</span>
<span class="c"># If base_price is not set, we use the current value. This is the</span>
<span class="c"># price at the first bar which we reference to calculate price_change.</span>
<span class="k">if</span> <span class="n">context</span><span class="o">.</span><span class="n">base_price</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
<span class="n">context</span><span class="o">.</span><span class="n">base_price</span> <span class="o">=</span> <span class="n">price</span>
<span class="n">price_change</span> <span class="o">=</span> <span class="p">(</span><span class="n">price</span> <span class="o">-</span> <span class="n">context</span><span class="o">.</span><span class="n">base_price</span><span class="p">)</span> <span class="o">/</span> <span class="n">context</span><span class="o">.</span><span class="n">base_price</span>
<span class="c"># Save values for later inspection</span>
<span class="n">record</span><span class="p">(</span><span class="n">price</span><span class="o">=</span><span class="n">price</span><span class="p">,</span>
<span class="n">cash</span><span class="o">=</span><span class="n">context</span><span class="o">.</span><span class="n">portfolio</span><span class="o">.</span><span class="n">cash</span><span class="p">,</span>
<span class="n">price_change</span><span class="o">=</span><span class="n">price_change</span><span class="p">,</span>
<span class="n">short_mavg</span><span class="o">=</span><span class="n">short_mavg</span><span class="p">,</span>
<span class="n">long_mavg</span><span class="o">=</span><span class="n">long_mavg</span><span class="p">)</span>
<span class="c"># Since we are using limit orders, some orders may not execute immediately</span>
<span class="c"># we wait until all orders are executed before considering more trades.</span>
<span class="n">orders</span> <span class="o">=</span> <span class="n">get_open_orders</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">)</span>
<span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">orders</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
<span class="k">return</span>
<span class="c"># Exit if we cannot trade</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">data</span><span class="o">.</span><span class="n">can_trade</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">):</span>
<span class="k">return</span>
<span class="c"># We check what&#39;s our position on our portfolio and trade accordingly</span>
<span class="n">pos_amount</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="n">portfolio</span><span class="o">.</span><span class="n">positions</span><span class="p">[</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">]</span><span class="o">.</span><span class="n">amount</span>
<span class="c"># Trading logic</span>
<span class="k">if</span> <span class="n">short_mavg</span> <span class="o">&gt;</span> <span class="n">long_mavg</span> <span class="ow">and</span> <span class="n">pos_amount</span> <span class="o">==</span> <span class="mi">0</span><span class="p">:</span>
<span class="c"># we buy 100% of our portfolio for this asset</span>
<span class="n">order_target_percent</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
<span class="k">elif</span> <span class="n">short_mavg</span> <span class="o">&lt;</span> <span class="n">long_mavg</span> <span class="ow">and</span> <span class="n">pos_amount</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">:</span>
<span class="c"># we sell all our positions for this asset</span>
<span class="n">order_target_percent</span><span class="p">(</span><span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">analyze</span><span class="p">(</span><span class="n">context</span><span class="p">,</span> <span class="n">perf</span><span class="p">):</span>
<span class="c"># Get the base_currency that was passed as a parameter to the simulation</span>
<span class="n">base_currency</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="n">exchanges</span><span class="o">.</span><span class="n">values</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">base_currency</span><span class="o">.</span><span class="n">upper</span><span class="p">()</span>
<span class="c"># First chart: Plot portfolio value using base_currency</span>
<span class="n">ax1</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">411</span><span class="p">)</span>
<span class="n">perf</span><span class="o">.</span><span class="n">loc</span><span class="p">[:,</span> <span class="p">[</span><span class="s">&#39;portfolio_value&#39;</span><span class="p">]]</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ax</span><span class="o">=</span><span class="n">ax1</span><span class="p">)</span>
<span class="n">ax1</span><span class="o">.</span><span class="n">legend_</span><span class="o">.</span><span class="n">remove</span><span class="p">()</span>
<span class="n">ax1</span><span class="o">.</span><span class="n">set_ylabel</span><span class="p">(</span><span class="s">&#39;Portfolio Value</span><span class="se">\n</span><span class="s">({})&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">base_currency</span><span class="p">))</span>
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">ax1</span><span class="o">.</span><span class="n">get_ylim</span><span class="p">()</span>
<span class="n">ax1</span><span class="o">.</span><span class="n">yaxis</span><span class="o">.</span><span class="n">set_ticks</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">start</span><span class="p">,</span> <span class="n">end</span><span class="p">,</span> <span class="p">(</span><span class="n">end</span><span class="o">-</span><span class="n">start</span><span class="p">)</span><span class="o">/</span><span class="mi">5</span><span class="p">))</span>
<span class="c"># Second chart: Plot asset price, moving averages and buys/sells</span>
<span class="n">ax2</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">412</span><span class="p">,</span> <span class="n">sharex</span><span class="o">=</span><span class="n">ax1</span><span class="p">)</span>
<span class="n">perf</span><span class="o">.</span><span class="n">loc</span><span class="p">[:,</span> <span class="p">[</span><span class="s">&#39;price&#39;</span><span class="p">,</span><span class="s">&#39;short_mavg&#39;</span><span class="p">,</span><span class="s">&#39;long_mavg&#39;</span><span class="p">]]</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ax</span><span class="o">=</span><span class="n">ax2</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="s">&#39;Price&#39;</span><span class="p">)</span>
<span class="n">ax2</span><span class="o">.</span><span class="n">legend_</span><span class="o">.</span><span class="n">remove</span><span class="p">()</span>
<span class="n">ax2</span><span class="o">.</span><span class="n">set_ylabel</span><span class="p">(</span><span class="s">&#39;{asset}</span><span class="se">\n</span><span class="s">({base})&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
<span class="n">asset</span> <span class="o">=</span> <span class="n">context</span><span class="o">.</span><span class="n">asset</span><span class="o">.</span><span class="n">symbol</span><span class="p">,</span>
<span class="n">base</span> <span class="o">=</span> <span class="n">base_currency</span>
<span class="p">))</span>
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">ax2</span><span class="o">.</span><span class="n">get_ylim</span><span class="p">()</span>
<span class="n">ax2</span><span class="o">.</span><span class="n">yaxis</span><span class="o">.</span><span class="n">set_ticks</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">start</span><span class="p">,</span> <span class="n">end</span><span class="p">,</span> <span class="p">(</span><span class="n">end</span><span class="o">-</span><span class="n">start</span><span class="p">)</span><span class="o">/</span><span class="mi">5</span><span class="p">))</span>
<span class="n">transaction_df</span> <span class="o">=</span> <span class="n">extract_transactions</span><span class="p">(</span><span class="n">perf</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">transaction_df</span><span class="o">.</span><span class="n">empty</span><span class="p">:</span>
<span class="n">buy_df</span> <span class="o">=</span> <span class="n">transaction_df</span><span class="p">[</span><span class="n">transaction_df</span><span class="p">[</span><span class="s">&#39;amount&#39;</span><span class="p">]</span> <span class="o">&gt;</span> <span class="mi">0</span><span class="p">]</span>
<span class="n">sell_df</span> <span class="o">=</span> <span class="n">transaction_df</span><span class="p">[</span><span class="n">transaction_df</span><span class="p">[</span><span class="s">&#39;amount&#39;</span><span class="p">]</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">]</span>
<span class="n">ax2</span><span class="o">.</span><span class="n">scatter</span><span class="p">(</span>
<span class="n">buy_df</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">to_pydatetime</span><span class="p">(),</span>
<span class="n">perf</span><span class="o">.</span><span class="n">loc</span><span class="p">[</span><span class="n">buy_df</span><span class="o">.</span><span class="n">index</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">],</span>
<span class="n">marker</span><span class="o">=</span><span class="s">&#39;^&#39;</span><span class="p">,</span>
<span class="n">s</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span>
<span class="n">c</span><span class="o">=</span><span class="s">&#39;green&#39;</span><span class="p">,</span>
<span class="n">label</span><span class="o">=</span><span class="s">&#39;&#39;</span>
<span class="p">)</span>
<span class="n">ax2</span><span class="o">.</span><span class="n">scatter</span><span class="p">(</span>
<span class="n">sell_df</span><span class="o">.</span><span class="n">index</span><span class="o">.</span><span class="n">to_pydatetime</span><span class="p">(),</span>
<span class="n">perf</span><span class="o">.</span><span class="n">loc</span><span class="p">[</span><span class="n">sell_df</span><span class="o">.</span><span class="n">index</span><span class="p">,</span> <span class="s">&#39;price&#39;</span><span class="p">],</span>
<span class="n">marker</span><span class="o">=</span><span class="s">&#39;v&#39;</span><span class="p">,</span>
<span class="n">s</span><span class="o">=</span><span class="mi">100</span><span class="p">,</span>
<span class="n">c</span><span class="o">=</span><span class="s">&#39;red&#39;</span><span class="p">,</span>
<span class="n">label</span><span class="o">=</span><span class="s">&#39;&#39;</span>
<span class="p">)</span>
<span class="c"># Third chart: Compare percentage change between our portfolio</span>
<span class="c"># and the price of the asset</span>
<span class="n">ax3</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">413</span><span class="p">,</span> <span class="n">sharex</span><span class="o">=</span><span class="n">ax1</span><span class="p">)</span>
<span class="n">perf</span><span class="o">.</span><span class="n">loc</span><span class="p">[:,</span> <span class="p">[</span><span class="s">&#39;algorithm_period_return&#39;</span><span class="p">,</span> <span class="s">&#39;price_change&#39;</span><span class="p">]]</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ax</span><span class="o">=</span><span class="n">ax3</span><span class="p">)</span>
<span class="n">ax3</span><span class="o">.</span><span class="n">legend_</span><span class="o">.</span><span class="n">remove</span><span class="p">()</span>
<span class="n">ax3</span><span class="o">.</span><span class="n">set_ylabel</span><span class="p">(</span><span class="s">&#39;Percent Change&#39;</span><span class="p">)</span>
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">ax3</span><span class="o">.</span><span class="n">get_ylim</span><span class="p">()</span>
<span class="n">ax3</span><span class="o">.</span><span class="n">yaxis</span><span class="o">.</span><span class="n">set_ticks</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="n">start</span><span class="p">,</span> <span class="n">end</span><span class="p">,</span> <span class="p">(</span><span class="n">end</span><span class="o">-</span><span class="n">start</span><span class="p">)</span><span class="o">/</span><span class="mi">5</span><span class="p">))</span>
<span class="c"># Fourth chart: Plot our cash</span>
<span class="n">ax4</span> <span class="o">=</span> <span class="n">plt</span><span class="o">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">414</span><span class="p">,</span> <span class="n">sharex</span><span class="o">=</span><span class="n">ax1</span><span class="p">)</span>
<span class="n">perf</span><span class="o">.</span><span class="n">cash</span><span class="o">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ax</span><span class="o">=</span><span class="n">ax4</span><span class="p">)</span>
<span class="n">ax4</span><span class="o">.</span><span class="n">set_ylabel</span><span class="p">(</span><span class="s">&#39;Cash</span><span class="se">\n</span><span class="s">({})&#39;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">base_currency</span><span class="p">))</span>
<span class="n">start</span><span class="p">,</span> <span class="n">end</span> <span class="o">=</span> <span class="n">ax4</span><span class="o">.</span><span class="n">get_ylim</span><span class="p">()</span>
<span class="n">ax4</span><span class="o">.</span><span class="n">yaxis</span><span class="o">.</span><span class="n">set_ticks</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">end</span><span class="p">,</span> <span class="n">end</span><span class="o">/</span><span class="mi">5</span><span class="p">))</span>
<span class="n">plt</span><span class="o">.</span><span class="n">show</span><span class="p">()</span>
<span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&#39;__main__&#39;</span><span class="p">:</span>
<span class="n">run_algorithm</span><span class="p">(</span>
<span class="n">capital_base</span><span class="o">=</span><span class="mi">1000</span><span class="p">,</span>
<span class="n">data_frequency</span><span class="o">=</span><span class="s">&#39;minute&#39;</span><span class="p">,</span>
<span class="n">initialize</span><span class="o">=</span><span class="n">initialize</span><span class="p">,</span>
<span class="n">handle_data</span><span class="o">=</span><span class="n">handle_data</span><span class="p">,</span>
<span class="n">analyze</span><span class="o">=</span><span class="n">analyze</span><span class="p">,</span>
<span class="n">exchange_name</span><span class="o">=</span><span class="s">&#39;bitfinex&#39;</span><span class="p">,</span>
<span class="n">algo_namespace</span><span class="o">=</span><span class="n">NAMESPACE</span><span class="p">,</span>
<span class="n">base_currency</span><span class="o">=</span><span class="s">&#39;usd&#39;</span><span class="p">,</span>
<span class="n">start</span><span class="o">=</span><span class="n">pd</span><span class="o">.</span><span class="n">to_datetime</span><span class="p">(</span><span class="s">&#39;2017-9-22&#39;</span><span class="p">,</span> <span class="n">utc</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
<span class="n">end</span><span class="o">=</span><span class="n">pd</span><span class="o">.</span><span class="n">to_datetime</span><span class="p">(</span><span class="s">&#39;2017-9-23&#39;</span><span class="p">,</span> <span class="n">utc</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
<span class="p">)</span>
</pre></div>
</div>
<p>In order to run the code above, you have to ingest the needed data first:</p>
<div class="highlight-bash"><div class="highlight"><pre>catalyst ingest-exchange -x bitfinex -f minute -i ltc_usd
</pre></div>
</div>
<p>And then run the code above with the following command:</p>
<div class="highlight-bash"><div class="highlight"><pre>catalyst run -f dual_moving_average.py -x bitfinex -s 2017-9-22 -e 2017-9-23 --capital-base <span class="m">1000</span> --base-currency usd --data-frequency minute -o out.pickle
</pre></div>
</div>
<p>Alternatively, we can make use of the <code class="docutils literal"><span class="pre">run_algorithm()</span></code> function included at
the end of the file, where we can specify all the simulation parameters, and
execute this file as a Python script:</p>
<div class="highlight-bash"><div class="highlight"><pre>python dual_moving_average.py
</pre></div>
</div>
<p>Either way, we obtain the following charts:</p>
<img alt="https://s3.amazonaws.com/enigmaco-docs/github.io/tutorial_dual_moving_average.png" src="https://s3.amazonaws.com/enigmaco-docs/github.io/tutorial_dual_moving_average.png" />
<p>A few comments on the code above:</p>
<blockquote>
<div><p>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&#8217;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.</p>
<p>Focus on the code that is inside <code class="docutils literal"><span class="pre">handle_data()</span></code> that is where all the
trading logic occurs. You can safely dismiss most of the code in the
<code class="docutils literal"><span class="pre">analyze()</span></code> 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.</p>
<p>Inside the <code class="docutils literal"><span class="pre">handle_data()</span></code>, we also used the <code class="docutils literal"><span class="pre">order_target_percent()</span></code>
function above. This and other functions like it can make order management
and portfolio rebalancing much easier.</p>
<p>The <code class="docutils literal"><span class="pre">ltc_usd</span></code> asset was arbitrarily chosen. The values of 50 and 200 for the
<code class="docutils literal"><span class="pre">short_window</span></code> and <code class="docutils literal"><span class="pre">long_window</span></code> 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 <code class="docutils literal"><span class="pre">start</span></code> and <code class="docutils literal"><span class="pre">end</span></code> dates have been chosen so as to demonstrate
how our strategy can both perform better (blue line above green line on the
<code class="docutils literal"><span class="pre">Percent</span> <span class="pre">Change</span></code> chart) and worse (green line above blue line towards the end) than the
price of the asset we are trading.</p>
<p>You can change any of these parameters: <code class="docutils literal"><span class="pre">asset</span></code>, <code class="docutils literal"><span class="pre">short_window</span></code>,
<code class="docutils literal"><span class="pre">long_window</span></code>, <code class="docutils literal"><span class="pre">start_date</span></code> and <code class="docutils literal"><span class="pre">end_date</span></code> 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.</p>
</div></blockquote>
<p>Although it might not be directly apparent, the power of <code class="docutils literal"><span class="pre">history()</span></code>
(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
<a class="reference external" href="http://scikit-learn.org/stable/">scikit-learn</a> which tries to
predict future market movements based on past prices (note, that most of
the <code class="docutils literal"><span class="pre">scikit-learn</span></code> functions require <code class="docutils literal"><span class="pre">numpy.ndarray</span></code>s rather than
<code class="docutils literal"><span class="pre">pandas.DataFrame</span></code>s, so you can simply pass the underlying
<code class="docutils literal"><span class="pre">ndarray</span></code> of a <code class="docutils literal"><span class="pre">DataFrame</span></code> via <code class="docutils literal"><span class="pre">.values</span></code>).</p>
</div>
</div>
<div class="section" id="next-steps">
<h2>Next steps<a class="headerlink" href="#next-steps" title="Permalink to this headline"></a></h2>
<p>We hope that this tutorial gave you a little insight into the
architecture, API, and features of Catalyst. For next steps, check
out some of the other <a class="reference internal" href="example-algos.html"><em>example algorithms</em></a>.</p>
<p>Feel free to ask questions on the <code class="docutils literal"><span class="pre">#catalyst_dev</span></code> channel of our
<a class="reference external" href="https://discord.gg/SJK32GY">Discord group</a> and report
problems on our <a class="reference external" href="https://github.com/enigmampc/catalyst/issues">GitHub issue tracker</a>.</p>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="jupyter.html" class="btn btn-neutral float-right" title="Catalyst &amp; Jupyter Notebook" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="install.html" class="btn btn-neutral" title="Install" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2017, Enigma MPC, Inc..
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'0.3',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink