From 206888c8303eec91a17f453a2bafb32484a5cf0d Mon Sep 17 00:00:00 2001 From: Stefan Jansen Date: Mon, 17 Jul 2023 11:38:25 -0400 Subject: [PATCH] DOC: updating docs (#208) Update installation instructions Address some sphinx errors Update badges --- README.md | 9 ++-- docs/source/api-reference.rst | 2 +- docs/source/conf.py | 9 ++-- docs/source/development-guidelines.rst | 1 + docs/source/install.rst | 19 ++------ pyproject.toml | 2 +- src/zipline/_protocol.pyx | 14 +++--- src/zipline/algorithm.py | 46 ++++++++++--------- src/zipline/finance/blotter/blotter.py | 14 +++--- .../finance/blotter/simulation_blotter.py | 2 +- .../pipeline/loaders/earnings_estimates.py | 6 +-- src/zipline/pipeline/loaders/frame.py | 16 +++---- 12 files changed, 65 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 64722de2b4..98919f2ce8 100644 --- a/README.md +++ b/README.md @@ -6,14 +6,13 @@ # Backtest your Trading Strategies -| Version Info | [![Python](https://img.shields.io/pypi/pyversions/zipline-reloaded.svg?cacheSeconds=2592000)](https://pypi.python.org/pypi/zipline-reloaded) [![Anaconda-Server Badge](https://anaconda.org/ml4t/zipline-reloaded/badges/platforms.svg)](https://anaconda.org/ml4t/zipline-reloaded) [![Release](https://img.shields.io/pypi/v/zipline-reloaded.svg?cacheSeconds=2592000)](https://pypi.org/project/zipline-reloaded/) [![Anaconda-Server Badge](https://anaconda.org/ml4t/zipline-reloaded/badges/version.svg)](https://anaconda.org/ml4t/zipline-reloaded) | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Test** **Status** | [![CI Tests](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/ci_tests_full.yml/badge.svg)](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/unit_tests.yml) [![PyPI](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/build_wheels.yml) [![Anaconda](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/conda_package.yml/badge.svg)](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/conda_package.yml) [![codecov](https://codecov.io/gh/stefan-jansen/zipline-reloaded/branch/main/graph/badge.svg)](https://codecov.io/gh/stefan-jansen/zipline-reloaded) | -| **Community** | [![Discourse](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fexchange.ml4trading.io%2F)](https://exchange.ml4trading.io) [![ML4T](https://img.shields.io/badge/Powered%20by-ML4Trading-blue)](https://ml4trading.io) [![Twitter](https://img.shields.io/twitter/follow/ml4trading.svg?style=social)](https://twitter.com/ml4trading) | +| Version Info | [![Python](https://img.shields.io/pypi/pyversions/zipline-reloaded.svg?cacheSeconds=2592000)](https://pypi.python.org/pypi/zipline-reloaded) [![Anaconda-Server Badge](https://anaconda.org/ml4t/zipline-reloaded/badges/platforms.svg)](https://anaconda.org/ml4t/zipline-reloaded) ![PyPI](https://img.shields.io/pypi/v/zipline-reloaded) [![Anaconda-Server Badge](https://anaconda.org/conda-forge/zipline-reloaded/badges/version.svg)](https://anaconda.org/conda-forge/zipline-reloaded) | +| ------------------- | ---------- | +| **Test** **Status** | [![CI Tests](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/ci_tests_full.yml/badge.svg)](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/unit_tests.yml) [![PyPI](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/build_wheels.yml/badge.svg)](https://github.com/stefan-jansen/zipline-reloaded/actions/workflows/build_wheels.yml) [![codecov](https://codecov.io/gh/stefan-jansen/zipline-reloaded/branch/main/graph/badge.svg)](https://codecov.io/gh/stefan-jansen/zipline-reloaded) | +| **Community** | [![Discourse](https://img.shields.io/discourse/topics?server=https%3A%2F%2Fexchange.ml4trading.io%2F)](https://exchange.ml4trading.io) [![ML4T](https://img.shields.io/badge/Powered%20by-ML4Trading-blue)](https://ml4trading.io) [![Twitter](https://img.shields.io/twitter/follow/ml4trading.svg?style=social)](https://twitter.com/ml4trading) | Zipline is a Pythonic event-driven system for backtesting, developed and used as the backtesting and live-trading engine by [crowd-sourced investment fund Quantopian](https://www.bizjournals.com/boston/news/2020/11/10/quantopian-shuts-down-cofounders-head-elsewhere.html). Since it closed late 2020, the domain that had hosted these docs expired. The library is used extensively in the book [Machine Larning for Algorithmic Trading](https://ml4trading.io) by [Stefan Jansen](https://www.linkedin.com/in/applied-ai/) who is trying to keep the library up to date and available to his readers and the wider Python algotrading community. - - [Join our Community!](https://exchange.ml4trading.io) - [Documentation](https://zipline.ml4trading.io) diff --git a/docs/source/api-reference.rst b/docs/source/api-reference.rst index 88c5a6f13d..933fe0e78a 100644 --- a/docs/source/api-reference.rst +++ b/docs/source/api-reference.rst @@ -385,7 +385,7 @@ Data Loaders There are several loaders to feed data to a :class:`~zipline.pipeline.Pipeline` that need to implement the interface defined by the :class:`~zipline.pipeline.loaders.base.PipelineLoader`. -.. autoclass:: zipline.pipeline.loaders.based.PipelineLoader +.. autoclass:: zipline.pipeline.loaders.base.PipelineLoader :members: __init__, load_adjusted_array, currency_aware :member-order: bysource diff --git a/docs/source/conf.py b/docs/source/conf.py index bcef90eac1..9de078cdbc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -23,8 +23,8 @@ ] extlinks = { - "issue": ("https://github.com/stefan-jansen/zipline/issues/%s", "#"), - "commit": ("https://github.com/stefan-jansen/zipline/commit/%s", ""), + "issue": ("https://github.com/stefan-jansen/zipline/issues/%s", "%s"), + "commit": ("https://github.com/stefan-jansen/zipline/commit/%s", "%s"), } numpydoc_show_class_members = False @@ -59,7 +59,7 @@ html_theme_path = [] else: html_theme = "pydata_sphinx_theme" - html_theme_path = pydata_sphinx_theme.get_html_theme_path() + # html_theme_path = pydata_sphinx_theme.get_html_theme_path() # The name of the Pygments (syntax highlighting) style to use. highlight_language = "python" @@ -79,7 +79,6 @@ "google_analytics_id": "UA-74956955-3", } - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named 'default.css' will overwrite the builtin 'default.css'. @@ -98,7 +97,7 @@ htmlhelp_basename = "ziplinedoc" intersphinx_mapping = { - "https://docs.python.org/dev/": None, + "python": ("https://docs.python.org/3/", None), "numpy": ("https://numpy.org/doc/stable/", None), "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None), "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None), diff --git a/docs/source/development-guidelines.rst b/docs/source/development-guidelines.rst index 30ab43fb3b..f98a21c8a1 100644 --- a/docs/source/development-guidelines.rst +++ b/docs/source/development-guidelines.rst @@ -22,6 +22,7 @@ First, you'll need to clone Zipline by running: Then check out to a new branch where you can make your changes: .. code-block:: bash + $ cd zipline-reloaded $ git checkout -b some-short-descriptive-name diff --git a/docs/source/install.rst b/docs/source/install.rst index 5736c3589b..ac5b66f00c 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -9,7 +9,7 @@ that runs on Windows, macOS, and Linux. In case you are installing `zipline-relo encounter [conflict errors](https://github.com/conda/conda/issues/9707), consider using [mamba](https://github.com/mamba-org/mamba) instead. -Zipline runs on Python 3.8, 3.9 and 3.10. To install and use different Python versions in parallel as well as create +Zipline runs on Python 3.8, 3.9, 3.10 and 3.11. To install and use different Python versions in parallel as well as create a virtual environment, you may want to use `pyenv `_. Installing with ``pip`` @@ -144,21 +144,10 @@ dependencies. For instructions on how to install ``conda``, see the `Conda Installation Documentation `_. -Unfortunately, as of April 2021, ``conda`` produces numerous false -positive [conflict errors](https://github.com/conda/conda/issues/9707) -while working to identify dependencies. Should this be your experience, consider -[mamba](https://github.com/mamba-org/mamba) instead, which works much faster and -reliably in most cases. +Once ``conda`` has been set up you can install Zipline from the ``conda-forge`` channel. -Once ``conda`` has been set up you can install Zipline from the ``ml4t`` channel. -You'll also need to activate the `conda-forge` and `ranaroussi` channels to source various dependencies. -You can do so either by adding them to your -`.condarc `_ -configuration file, or as command line flags: +See [here](https://github.com/conda-forge/zipline-reloaded-feedstock) for the latest installation details. -.. code-block:: bash - - conda install -c ml4t -c conda-forge -c ranaroussi zipline-reloaded .. _managing-conda-environments: @@ -174,7 +163,7 @@ Assuming ``conda`` has been set up, you can create a ``conda`` environment: .. code-block:: bash - $ conda create -n env_zipline python=3.8 + $ conda create -n env_zipline python=3.10 Now you have set up an isolated environment called ``env_zipline``, a sandbox-like diff --git a/pyproject.toml b/pyproject.toml index bc55fe5198..6e498b3f14 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -110,7 +110,7 @@ docs = [ 'numpydoc >=0.5.0', 'sphinx-autobuild >=0.6.0', 'pydata-sphinx-theme', - 'sphinx-markdown-tables', + 'sphinx_markdown_tables', 'm2r2' ] diff --git a/src/zipline/_protocol.pyx b/src/zipline/_protocol.pyx index 25926e56c8..d3aef4919b 100644 --- a/src/zipline/_protocol.pyx +++ b/src/zipline/_protocol.pyx @@ -508,7 +508,7 @@ cdef class BarData: }) cdef bool _is_stale_for_asset(self, asset, dt, adjusted_dt, data_portal): - session_label = dt.normalize() # FIXME + session_label = dt.normalize() # FIXME if not asset.is_alive_for_session(session_label): return False @@ -580,11 +580,13 @@ cdef class BarData: :class:`pd.DatetimeIndex`, and its columns will be ``assets``. - If multiple assets and multiple fields are requested, the returned - value is a :class:`pd.DataFrame` with a pd.MultiIndex containing pairs of - :class:`pd.DatetimeIndex`, and ``assets``, while the columns while contain the field(s). - It has shape``(bar_count * len(assets), len(fields))``. The names of the pd.MultiIndex are - - ``date`` if frequency == '1d'`` or ``date_time`` if frequency == '1m``, and - - ``asset`` + value is a :class:`pd.DataFrame` with a pd.MultiIndex containing + pairs of :class:`pd.DatetimeIndex`, and ``assets``, while the columns + while contain the field(s). It has shape ``(bar_count * len(assets), + len(fields))``. The names of the pd.MultiIndex are + + - ``date`` if frequency == '1d'`` or ``date_time`` if frequency == '1m``, and + - ``asset`` If the current simulation time is not a valid market time, we use the last market close instead. """ diff --git a/src/zipline/algorithm.py b/src/zipline/algorithm.py index 4b7855ae82..dbccd82b18 100644 --- a/src/zipline/algorithm.py +++ b/src/zipline/algorithm.py @@ -717,28 +717,30 @@ def get_environment(self, field="platform"): Parameters ---------- - field : {'platform', 'arena', 'data_frequency', - 'start', 'end', 'capital_base', 'platform', '*'} - The field to query. The options have the following meanings: - arena : str - The arena from the simulation parameters. This will normally - be ``'backtest'`` but some systems may use this distinguish - live trading from backtesting. - data_frequency : {'daily', 'minute'} - data_frequency tells the algorithm if it is running with - daily data or minute data. - start : datetime - The start date for the simulation. - end : datetime - The end date for the simulation. - capital_base : float - The starting capital for the simulation. - platform : str - The platform that the code is running on. By default this - will be the string 'zipline'. This can allow algorithms to - know if they are running on the Quantopian platform instead. - * : dict[str -> any] - Returns all of the fields in a dictionary. + field : {'platform', 'arena', 'data_frequency', 'start', 'end', + 'capital_base', 'platform', '*'} + + The field to query. The options have the following meanings: + + - arena : str + The arena from the simulation parameters. This will normally + be ``'backtest'`` but some systems may use this distinguish + live trading from backtesting. + - data_frequency : {'daily', 'minute'} + data_frequency tells the algorithm if it is running with + daily data or minute data. + - start : datetime + The start date for the simulation. + - end : datetime + The end date for the simulation. + - capital_base : float + The starting capital for the simulation. + -platform : str + The platform that the code is running on. By default, this + will be the string 'zipline'. This can allow algorithms to + know if they are running on the Quantopian platform instead. + - * : dict[str -> any] + Returns all the fields in a dictionary. Returns ------- diff --git a/src/zipline/finance/blotter/blotter.py b/src/zipline/finance/blotter/blotter.py index 4a2583556c..781104c26f 100644 --- a/src/zipline/finance/blotter/blotter.py +++ b/src/zipline/finance/blotter/blotter.py @@ -51,13 +51,13 @@ def order(self, asset, amount, style, order_id=None): Notes ----- - amount > 0 :: Buy/Cover - amount < 0 :: Sell/Short - Market order: order(asset, amount) - Limit order: order(asset, amount, style=LimitOrder(limit_price)) - Stop order: order(asset, amount, style=StopOrder(stop_price)) - StopLimit order: order(asset, amount, style=StopLimitOrder(limit_price, - stop_price)) + amount > 0 : Buy/Cover + amount < 0 : Sell/Short + Market order : order(asset, amount) + Limit order : order(asset, amount, style=LimitOrder(limit_price)) + Stop order : order(asset, amount, style=StopOrder(stop_price)) + StopLimit order : order(asset, amount, + style=StopLimitOrder(limit_price, stop_price)) """ raise NotImplementedError("order") diff --git a/src/zipline/finance/blotter/simulation_blotter.py b/src/zipline/finance/blotter/simulation_blotter.py index 8744f6f349..632de383a1 100644 --- a/src/zipline/finance/blotter/simulation_blotter.py +++ b/src/zipline/finance/blotter/simulation_blotter.py @@ -126,7 +126,7 @@ def order(self, asset, amount, style, order_id=None): Limit order: order(asset, amount, style=LimitOrder(limit_price)) Stop order: order(asset, amount, style=StopOrder(stop_price)) StopLimit order: order(asset, amount, style=StopLimitOrder(limit_price, - stop_price)) + stop_price)) """ # something could be done with amount to further divide # between buy by share count OR buy shares up to a dollar amount diff --git a/src/zipline/pipeline/loaders/earnings_estimates.py b/src/zipline/pipeline/loaders/earnings_estimates.py index ce280bc0a8..3e815735b4 100644 --- a/src/zipline/pipeline/loaders/earnings_estimates.py +++ b/src/zipline/pipeline/loaders/earnings_estimates.py @@ -109,14 +109,13 @@ class EarningsEstimatesLoader(implements(PipelineLoader)): Parameters ---------- estimates : pd.DataFrame - The raw estimates data. - ``estimates`` must contain at least 5 columns: + The raw estimates data; must contain at least 5 columns: sid : int64 The asset id associated with each estimate. event_date : datetime64[ns] The date on which the event that the estimate is for will/has - occurred.. + occurred. timestamp : datetime64[ns] The datetime where we learned about the estimate. @@ -1266,7 +1265,6 @@ def _collect_adjustments( post_adjustments, requested_split_adjusted_columns, ): - pre_adjustments_dict = self.collect_pre_split_asof_date_adjustments( split_adjusted_asof_idx, sid_idx, diff --git a/src/zipline/pipeline/loaders/frame.py b/src/zipline/pipeline/loaders/frame.py index 1086e476cb..d725b54ecf 100644 --- a/src/zipline/pipeline/loaders/frame.py +++ b/src/zipline/pipeline/loaders/frame.py @@ -80,14 +80,14 @@ def format_adjustments(self, dates, assets): Returns a dict of the form: { - # Integer index into `dates` for the date on which we should - # apply the list of adjustments. - 1 : [ - Float64Multiply(first_row=2, last_row=4, col=3, value=0.5), - Float64Overwrite(first_row=3, last_row=5, col=1, value=2.0), - ... - ], - ... + # Integer index into `dates` for the date on which we should + # apply the list of adjustments. + 1 : [ + Float64Multiply(first_row=2, last_row=4, col=3, value=0.5), + Float64Overwrite(first_row=3, last_row=5, col=1, value=2.0), + ... + ], + ... } """ make_adjustment = partial(make_adjustment_from_labels, dates, assets)