mirror of
https://github.com/wassname/catalyst.git
synced 2026-06-27 17:29:56 +08:00
DOC: Add development guide .rst
This commit is contained in:
swacad
+9
-23
@@ -4,8 +4,7 @@
|
||||
:align: center
|
||||
:alt: Zipline
|
||||
|
||||
Zipline
|
||||
=======
|
||||
=============
|
||||
|
||||
|Gitter|
|
||||
|version status|
|
||||
@@ -14,9 +13,7 @@ Zipline
|
||||
|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
|
||||
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.
|
||||
@@ -26,11 +23,9 @@ community! <https://groups.google.com/forum/#!forum/zipline>`_
|
||||
|
||||
`Documentation <http://www.zipline.io>`_
|
||||
|
||||
Want to contribute? See our `open
|
||||
requests <https://github.com/quantopian/zipline/wiki/Contribution-Requests>`_
|
||||
and our `general
|
||||
guidelines <https://github.com/quantopian/zipline#contributions>`_
|
||||
below.
|
||||
Want to contribute? See our `development guidelines`__
|
||||
|
||||
__ http://zipline.io/development-guidelines.html
|
||||
|
||||
Features
|
||||
========
|
||||
@@ -94,7 +89,7 @@ Once set up, you can install Zipline from our ``Quantopian`` channel:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
conda install -c Quantopian zipline
|
||||
$ conda install -c Quantopian zipline
|
||||
|
||||
Currently supported platforms include:
|
||||
|
||||
@@ -155,24 +150,15 @@ line, run:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
zipline ingest
|
||||
|
||||
.. code:: bash
|
||||
|
||||
zipline run -f dual_moving_average.py --start 2011-1-1 --end 2012-1-1 -o dma.pickle
|
||||
$ zipline ingest
|
||||
$ zipline run -f dual_moving_average.py --start 2011-1-1 --end 2012-1-1 -o dma.pickle
|
||||
|
||||
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.
|
||||
|
||||
You can find other examples in the zipline/examples directory.
|
||||
|
||||
Contributions
|
||||
=============
|
||||
|
||||
If you would like to contribute, please see our Contribution Requests:
|
||||
https://github.com/quantopian/zipline/wiki/Contribution-Requests
|
||||
You can find other examples in the ``zipline/examples`` directory.
|
||||
|
||||
.. |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
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
Zipline beginner tutorial
|
||||
Zipline Beginner Tutorial
|
||||
-------------------------
|
||||
|
||||
Basics
|
||||
@@ -624,7 +624,7 @@ the stock to go down further.
|
||||
As we need to have access to previous prices to implement this strategy
|
||||
we need a new concept: History
|
||||
|
||||
``history()`` is a convenience function that keeps a rolling window of
|
||||
``data.history()`` is a convenience function that keeps a rolling window of
|
||||
data for you. The first argument is the number of bars you want to
|
||||
collect, the second argument is the unit (either ``'1d'`` for ``'1m'``
|
||||
but note that you need to have minute-level data for using ``1m``). For
|
||||
@@ -634,14 +634,14 @@ Let's look at the strategy which should make this clear:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
%%zipline --start 2000-1-1 --end 2014-1-1 -o perf_dma
|
||||
%%zipline --start 2000-1-1 --end 2012-1-1 -o dma.pickle
|
||||
|
||||
|
||||
from zipline.api import order_target, record, symbol, history
|
||||
import numpy as np
|
||||
from zipline.api import order_target, record, symbol
|
||||
|
||||
def initialize(context):
|
||||
context.i = 0
|
||||
context.asset = symbol('AAPL')
|
||||
|
||||
|
||||
def handle_data(context, data):
|
||||
@@ -651,23 +651,23 @@ Let's look at the strategy which should make this clear:
|
||||
return
|
||||
|
||||
# Compute averages
|
||||
# history() has to be called with the same params
|
||||
# data.history() has to be called with the same params
|
||||
# from above and returns a pandas dataframe.
|
||||
short_mavg = history(100, '1d', 'price').mean()
|
||||
long_mavg = history(300, '1d', 'price').mean()
|
||||
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[0] > long_mavg[0]:
|
||||
if short_mavg > long_mavg:
|
||||
# order_target orders as many shares as needed to
|
||||
# achieve the desired number of shares.
|
||||
order_target(symbol('AAPL'), 100)
|
||||
elif short_mavg[0] < long_mavg[0]:
|
||||
order_target(symbol('AAPL'), 0)
|
||||
order_target(context.asset, 100)
|
||||
elif short_mavg < long_mavg:
|
||||
order_target(context.asset, 0)
|
||||
|
||||
# Save values for later inspection
|
||||
record(AAPL=data[symbol('AAPL')].price,
|
||||
short_mavg=short_mavg[0],
|
||||
long_mavg=long_mavg[0])
|
||||
record(AAPL=data.current(context.asset, 'price'),
|
||||
short_mavg=short_mavg,
|
||||
long_mavg=long_mavg)
|
||||
|
||||
|
||||
def analyze(context, perf):
|
||||
|
||||
@@ -0,0 +1,210 @@
|
||||
Development Guidelines
|
||||
======================
|
||||
This page is intended for developers of Zipline, people who want to contribute to the Zipline codebase or documentation, or people who want to install from source and make local changes to their copy of Zipline.
|
||||
|
||||
All contributions, bug reports, bug fixes, documentation improvements, enhancements and ideas are welcome. We `track issues`__ on `GitHub`__ and also have a `mailing list`__ where you can ask questions.
|
||||
|
||||
__ https://github.com/quantopian/zipline/issues
|
||||
__ https://github.com/
|
||||
__ https://groups.google.com/forum/#!forum/zipline
|
||||
|
||||
Creating a Development Environment
|
||||
----------------------------------
|
||||
|
||||
First, you'll need to clone Zipline by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone git@github.com:your-github-username/zipline.git
|
||||
|
||||
Then check out to a new branch where you can make your changes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git checkout -b some-short-descriptive-name
|
||||
|
||||
If you don't already have them, you'll need some C library dependencies. You can follow the `install guide`__ to get the appropriate dependencies.
|
||||
|
||||
__ install.html
|
||||
|
||||
The following section assumes you already have virtualenvwrapper and pip installed on your system. Suggested installation of Python library dependencies used for development:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ mkvirtualenv zipline
|
||||
$ ./etc/ordered_pip.sh ./etc/requirements.txt
|
||||
$ pip install -r ./etc/requirements_dev.txt
|
||||
$ pip install -r ./etc/requirements_blaze.txt
|
||||
|
||||
Finally, you can build the C extensions by running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ python setup.py build_ext --inplace
|
||||
|
||||
To finish, make sure `tests`__ pass.
|
||||
|
||||
__ #style-guide-running-tests
|
||||
|
||||
If you get an error running nosetests after setting up a fresh virtualenv, please try running
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# where zipline is the name of your virtualenv
|
||||
$ deactivate zipline
|
||||
$ workon zipline
|
||||
|
||||
|
||||
Development with Docker
|
||||
-----------------------
|
||||
|
||||
If you want to work with zipline using a `Docker`__ container, you'll need to build the ``Dockerfile`` in the Zipline root directory, and then build ``Dockerfile-dev``. Instructions for building both containers can be found in ``Dockerfile`` and ``Dockerfile-dev``, respectively.
|
||||
|
||||
__ https://docs.docker.com/get-started/
|
||||
|
||||
|
||||
Style Guide & Running Tests
|
||||
---------------------------
|
||||
|
||||
We use `flake8`__ for checking style requirements and `nosetests`__ to run Zipline tests. Our `continuous integration`__ tools will run these commands.
|
||||
|
||||
__ http://flake8.pycqa.org/en/latest/
|
||||
__ http://nose.readthedocs.io/en/latest/
|
||||
__ https://en.wikipedia.org/wiki/Continuous_integration
|
||||
|
||||
Before submitting patches or pull requests, please ensure that your changes pass when running:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ flake8 zipline tests
|
||||
|
||||
In order to run tests locally, you'll need `TA-lib`__, which you can install on Linux by running:
|
||||
|
||||
__ https://mrjbq7.github.io/ta-lib/install.html
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ wget http://prdownloads.sourceforge.net/ta-lib/ta-lib-0.4.0-src.tar.gz
|
||||
$ tar -xvzf ta-lib-0.4.0-src.tar.gz
|
||||
$ cd ta-lib/
|
||||
$ ./configure --prefix=/usr
|
||||
$ make
|
||||
$ sudo make install
|
||||
|
||||
And for ``TA-lib`` on OS X you can just run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ brew install ta-lib
|
||||
|
||||
Then run ``pip install`` TA-lib:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pip install -r ./etc/requirements_talib.txt
|
||||
|
||||
You should now be free to run tests:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ nosetests
|
||||
|
||||
|
||||
Continuous Integration
|
||||
----------------------
|
||||
|
||||
We use `Travis CI`__ for Linux-64 bit builds and `AppVeyor`__ for Windows-64 bit builds.
|
||||
|
||||
.. note::
|
||||
|
||||
We do not currently have CI for OSX-64 bit builds. 32-bit builds may work but are not included in our integration tests.
|
||||
|
||||
__ https://travis-ci.org/quantopian/zipline
|
||||
__ https://ci.appveyor.com/project/quantopian/zipline
|
||||
|
||||
|
||||
Packaging
|
||||
---------
|
||||
To learn about how we build Zipline conda packages, you can read `this`__ section in our release process notes.
|
||||
|
||||
__ release-process.html#uploading-conda-packages
|
||||
|
||||
Contributing to the Docs
|
||||
------------------------
|
||||
|
||||
If you'd like to contribute to the documentation on zipline.io, you can navigate to ``docs/source/`` where each `reStructuredText`__ (``.rst``) file is a separate section there. To add a section, create a new file called ``some-descriptive-name.rst`` and add ``some-descriptive-name`` to ``appendix.rst``. To edit a section, simply open up one of the existing files, make your changes, and save them.
|
||||
|
||||
__ https://en.wikipedia.org/wiki/ReStructuredText
|
||||
|
||||
We use `Sphinx`__ to generate documentation for Zipline, which you will need to install by running:
|
||||
|
||||
__ http://www.sphinx-doc.org/en/stable/
|
||||
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ pip install -r ./etc/requirements_docs.txt
|
||||
|
||||
To build and view the docs locally, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# assuming you're in the Zipline root directory
|
||||
$ cd docs
|
||||
$ make html
|
||||
$ {BROWSER} build/html/index.html
|
||||
|
||||
|
||||
Commit messages
|
||||
---------------
|
||||
|
||||
Standard prefixes to start a commit message:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
BLD: change related to building Zipline
|
||||
BUG: bug fix
|
||||
DEP: deprecate something, or remove a deprecated object
|
||||
DEV: development tool or utility
|
||||
DOC: documentation
|
||||
ENH: enhancement
|
||||
MAINT: maintenance commit (refactoring, typos, etc)
|
||||
REV: revert an earlier commit
|
||||
STY: style fix (whitespace, PEP8, flake8, etc)
|
||||
TST: addition or modification of tests
|
||||
REL: related to releasing Zipline
|
||||
PERF: performance enhancements
|
||||
|
||||
|
||||
Some commit style guidelines:
|
||||
|
||||
Commit lines should be no longer than `72 characters`__. The first line of the commit should include one of the above prefixes. There should be an empty line between the commit subject and the body of the commit. In general, the message should be in the imperative tense. Best practice is to include not only what the change is, but why the change was made.
|
||||
|
||||
__ https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project
|
||||
|
||||
**Example:**
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
MAINT: Remove unused calculations of max_leverage, et al.
|
||||
|
||||
In the performance period the max_leverage, max_capital_used,
|
||||
cumulative_capital_used were calculated but not used.
|
||||
|
||||
At least one of those calculations, max_leverage, was causing a
|
||||
divide by zero error.
|
||||
|
||||
Instead of papering over that error, the entire calculation was
|
||||
a bit suspect so removing, with possibility of adding it back in
|
||||
later with handling the case (or raising appropriate errors) when
|
||||
the algorithm has little cash on hand.
|
||||
|
||||
|
||||
Formatting Docstrings
|
||||
---------------------
|
||||
|
||||
When adding or editing docstrings for classes, functions, etc, we use `numpy`__ as the canonical reference.
|
||||
|
||||
__ https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
|
||||
|
||||
|
||||
@@ -6,6 +6,7 @@
|
||||
install
|
||||
beginner-tutorial
|
||||
bundles
|
||||
releases
|
||||
development-guidelines
|
||||
appendix
|
||||
release-process
|
||||
releases
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
Zipline Release Process
|
||||
-----------------------
|
||||
Release Process
|
||||
---------------
|
||||
|
||||
.. include:: dev-doc-message.txt
|
||||
|
||||
|
||||
Reference in New Issue
Block a user