diff --git a/README.rst b/README.rst index 0c473d080..ea1da4d0d 100644 --- a/README.rst +++ b/README.rst @@ -1,174 +1,177 @@ -.. image:: https://media.quantopian.com/logos/open_source/zipline-logo-03_.png - :target: http://www.zipline.io - :width: 212px - :align: center - :alt: Zipline - -============= +Catalyst +======== -|Gitter| |version status| -|travis status| -|appveyor status| -|Coverage Status| -Zipline is a Pythonic algorithmic trading library. It is an event-driven -system that supports both backtesting and live-trading. Zipline is currently used in production as the backtesting and live-trading -engine powering `Quantopian `_ -- a free, -community-centered, hosted platform for building and executing trading -strategies. +Catalyst is an algorithmic trading library for crypto-assets written in Python. +It allows trading strategies to be easily expressed and backtested against historical data, providing analytics and insights regarding a particular strategy's performance. +Catalyst will be expanded to support live-trading of crypto-assets in the coming months. +Please visit ``_ to learn about Catalyst, or refer to the +`whitepaper `_ for further technical details. -`Join our -community! `_ +Interested in getting involved? +`Join our slack! `_ -`Documentation `_ -Want to contribute? See our `development guidelines`__ +Installation +============ -__ http://zipline.io/development-guidelines.html +At the moment, Catalyst has some fairly specific and strict depedency requirements. +We recommend the use of Python virtual environments if you wish to simplify the installation process, or otherwise isolate Catalyst's dependencies from your other projects. +If you don't have ``virtualenv`` installed, see our later section on Virtual Environments. -Features -======== +.. code-block:: bash -- Ease of use: Zipline tries to get out of your way so that you can - focus on algorithm development. See below for a code example. -- Zipline comes "batteries included" as many common statistics like - moving average and linear regression can be readily accessed from - within a user-written algorithm. -- Input of historical data and output of performance statistics are - based on Pandas DataFrames to integrate nicely into the existing - PyData eco-system. -- Statistic and machine learning libraries like matplotlib, scipy, - statsmodels, and sklearn support development, analysis, and - visualization of state-of-the-art trading systems. + $ virtualenv catalyst-venv + $ source ./catalyst-venv/bin/activate + $ pip install enigma-catalyst -Installation -============ +**Note:** A successful installation will require several minutes in order to compile dependencies that expose C APIs. + +Dependencies +------------ + +Catalyst's depedencies can be found in the ``etc/requirements.txt`` file. +If you need to install them outside of a typical ``pip install``, this is done using: + +.. code-block:: bash -Installing With ``pip`` ------------------------ + $ pip install -r etc/requirements.txt -Assuming you have all required (see note below) non-Python dependencies, you -can install Zipline with ``pip`` via: +Though not required by Catalyst directly, our example algorithms use matplotlib to visually display backtest results. +If you wish to run any examples or use matplotlib during development, it can be installed using: .. code-block:: bash - $ pip install zipline + $ pip install matplotlib -**Note:** Installing Zipline via ``pip`` is slightly more involved than the -average Python package. Simply running ``pip install zipline`` will likely -fail if you've never installed any scientific Python packages before. +Virtual Environments +-------------------- -There are two reasons for the additional complexity: +Here we will provide a brief tutorial for installing ``virtualenv`` and its basic usage. +For more information regarding ``virtualenv``, please refer to this `virtualenv guide `_. -1. Zipline ships several C extensions that require access to the CPython C API. - In order to build the C extensions, ``pip`` needs access to the CPython - header files for your Python installation. +The ``virtualenv`` command can be installed using: -2. Zipline depends on `numpy `_, the core library for - numerical array computing in Python. Numpy depends on having the `LAPACK - `_ linear algebra routines available. +.. code-block:: bash -Because LAPACK and the CPython headers are binary dependencies, the correct way -to install them varies from platform to platform. On Linux, users generally -acquire these dependencies via a package manager like ``apt``, ``yum``, or -``pacman``. On OSX, `Homebrew `_ is a popular choice -providing similar functionality. + $ pip install virtualenv -See the full `Zipline Install Documentation`_ for more information on acquiring -binary dependencies for your specific platform. +To create a new virtual environment, choose a directory, e.g. ``/path/to/venv-dir``, where project-specific packages and files will be stored. The environment is created by running: -conda ------ +.. code-block:: bash -Another way to install Zipline is via the ``conda`` package manager, which -comes as part of `Anaconda `_ or can be -installed via ``pip install conda``. + $ virtualenv /path/to/venv-dir -Once set up, you can install Zipline from our ``Quantopian`` channel: +To enter an environment, run the ``bin/activate`` script located in ``/path/to/venv-dir`` using: .. code-block:: bash - $ conda install -c Quantopian zipline + $ source /path/to/venv-dir/bin/activate -Currently supported platforms include: +Exiting an environment is accomplished using ``deactivate``, and removing it entirely is done by deleting ``/path/to/venv-dir``. -- GNU/Linux 64-bit -- OSX 64-bit -- Windows 64-bit +Using virtualenv & matplotlib on OS X +------------------------------------- -.. note:: +A note about using matplotlib in virtual enviroments on OS X: it may be necessary to add - Windows 32-bit may work; however, it is not currently included in - continuous integration tests. +.. code-block:: python + + backend : TkAgg + +to your ``~/.matplotlib/matplotlibrc`` file, in order to override the default ``macosx`` backend for your system, which may not be accessible from inside the virtual environment. +This will allow Catalyst to open matplotlib charts from within a virtual environment, which is useful for displaying the performance of your backtests. To learn more about matplotlib backends, please refer to the +`matplotlib backend documentation `_. Quickstart ========== -See our `getting started -tutorial `_. +See our `getting started tutorial `_. -The following code implements a simple dual moving average algorithm. +The following code implements a simple buy and hodl algorithm. .. code:: python - from zipline.api import order_target, record, symbol + import numpy as np + + from catalyst.api import ( + order_target_value, + symbol, + record, + cancel_order, + get_open_orders, + ) + + ASSET = 'USDT_BTC' + + TARGET_HODL_RATIO = 0.8 + RESERVE_RATIO = 1.0 - TARGET_HODL_RATIO def initialize(context): - context.i = 0 - context.asset = symbol('AAPL') - + context.is_hodling = True + context.asset = symbol(ASSET) def handle_data(context, data): - # Skip first 300 days to get full windows - context.i += 1 - if context.i < 300: - return - - # Compute averages - # data.history() has to be called with the same params - # from above and returns a pandas dataframe. - short_mavg = data.history(context.asset, 'price', bar_count=100, frequency="1d").mean() - long_mavg = data.history(context.asset, 'price', bar_count=300, frequency="1d").mean() - - # Trading logic - if short_mavg > long_mavg: - # order_target orders as many shares as needed to - # achieve the desired number of shares. - order_target(context.asset, 100) - elif short_mavg < long_mavg: - order_target(context.asset, 0) - - # Save values for later inspection - record(AAPL=data.current(context.asset, 'price'), - short_mavg=short_mavg, - long_mavg=long_mavg) - - -You can then run this algorithm using the Zipline CLI. From the command + cash = context.portfolio.cash + target_hodl_value = TARGET_HODL_RATIO * context.portfolio.starting_cash + reserve_value = RESERVE_RATIO * context.portfolio.starting_cash + + # Cancel any outstanding orders from the previous day + orders = get_open_orders(context.asset) or [] + for order in orders: + cancel_order(order) + + # Stop hodling after passing reserve threshold + if cash <= reserve_value: + context.is_hodling = False + + # Retrieve current price from pricing data + price = data[context.asset].price + + # Check if still hodling and could afford another purchase + if context.is_hodling and cash > price: + order_target_value( + context.asset, + target_hodl_value, + limit_price=1.1 * price, + stop_price=0.9 * price, + ) + + # Record any state for later analysis + record( + price=price, + cash=context.portfolio.cash, + leverage=context.account.leverage, + ) + + +You can then run this algorithm using the Catalyst CLI. From the command line, run: .. code:: bash - $ zipline ingest - $ zipline run -f dual_moving_average.py --start 2011-1-1 --end 2012-1-1 -o dma.pickle + $ catalyst ingest + $ catalyst run -f buy_and_hodl.py --start 2015-1-1 --end 2016-6-25 --captial-base 100000 + +This will download the crypto-asset price data from a poloniex bundle +curated by Enigma in the specified time range and stream it through +the algorithm and plot the resulting performance using matplotlib. + +You can find other examples in the ``catalyst/examples`` directory. + +Disclaimer +========== + +Keep in mind that this project is still under active development, and is not recommended for production use in its current state. +We are deeply committed to improving the overall user experience, reliability, and feature-set offered by Catalyst. +If you have any suggestions, feedback, or general improvements regarding any of these topics, please let us know! -This will download the AAPL price data from `quantopian-quandl` in the -specified time range and stream it through the algorithm and save the -resulting performance dataframe to dma.pickle which you can then load -and analyze from within python. +Hello World, -You can find other examples in the ``zipline/examples`` directory. +The Enigma Team -.. |Gitter| image:: https://badges.gitter.im/Join%20Chat.svg - :target: https://gitter.im/quantopian/zipline?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge -.. |version status| image:: https://img.shields.io/pypi/pyversions/zipline.svg - :target: https://pypi.python.org/pypi/zipline -.. |travis status| image:: https://travis-ci.org/quantopian/zipline.png?branch=master - :target: https://travis-ci.org/quantopian/zipline -.. |appveyor status| image:: https://ci.appveyor.com/api/projects/status/3dg18e6227dvstw6/branch/master?svg=true - :target: https://ci.appveyor.com/project/quantopian/zipline/branch/master -.. |Coverage Status| image:: https://coveralls.io/repos/quantopian/zipline/badge.png - :target: https://coveralls.io/r/quantopian/zipline +.. |version status| image:: https://img.shields.io/pypi/pyversions/catalyst-hf.svg + :target: https://testpypi.python.org/pypi/catalyst-hf -.. _`Zipline Install Documentation` : http://www.zipline.io/install.html +.. _`Catalyst Install Documentation` : https://enigma.co/catalyst/install.html