Skip to content

Commit

Permalink
Update README.rst
Browse files Browse the repository at this point in the history
  • Loading branch information
@cfromknecht
cfromknecht committed Jul 2, 2017
1 parent 2d26758 commit 4a977d8
Showing 1 changed file with 126 additions and 123 deletions.
249 changes: 126 additions & 123 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -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 <https://www.quantopian.com>`_ -- 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 `<enigma.co/catalyst>`_ to learn about Catalyst, or refer to the
`whitepaper <http://www.enigma.co/enigma_catalyst.pdf>`_ for further technical details.

`Join our
community! <https://groups.google.com/forum/#!forum/zipline>`_
Interested in getting involved?
`Join our slack! <https://join.slack.com/enigmacatalyst/shared_invite/MTkzMjQ0MTg1NTczLTE0OTY3MjE3MDEtZGZmMTI5YzI3ZA>`_

`Documentation <http://www.zipline.io>`_

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 <http://python-guide-pt-br.readthedocs.io/en/latest/dev/virtualenvs/>`_.

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 <http://www.numpy.org/>`_, the core library for
numerical array computing in Python. Numpy depends on having the `LAPACK
<http://www.netlib.org/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 <http://www.brew.sh>`_ 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 <http://continuum.io/downloads>`_ 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 <https://matplotlib.org/faq/usage_faq.html#what-is-a-backend>`_.

Quickstart
==========

See our `getting started
tutorial <http://www.zipline.io/#quickstart>`_.
See our `getting started tutorial <http://www.zipline.io/#quickstart>`_.

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

0 comments on commit 4a977d8

Please sign in to comment.