From 9a3bad291aa70cec5aaf5e86ae11563dd255fc46 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 21 Sep 2019 10:27:43 +0200 Subject: [PATCH] Automatically generate documentation from jupyter notebook --- docs/data-analysis.md | 75 +----------------------- docs/developer.md | 8 +++ docs/strategy_analysis_example.md | 95 +++++++++++++++++++++++++++++++ mkdocs.yml | 6 +- requirements-dev.txt | 3 + setup.py | 1 + 6 files changed, 114 insertions(+), 74 deletions(-) create mode 100644 docs/strategy_analysis_example.md diff --git a/docs/data-analysis.md b/docs/data-analysis.md index cf292cacd..bc4f2e006 100644 --- a/docs/data-analysis.md +++ b/docs/data-analysis.md @@ -135,78 +135,9 @@ print(f"Loaded len(candles) rows of data for {pair} from {data_location}") candles.head() ``` -## Strategy debugging example +Further Data analysis documents: -Debugging a strategy can be time-consuming. FreqTrade offers helper functions to visualize raw data. - -### Define variables used in analyses - -You can override strategy settings as demonstrated below. - -```python -# Customize these according to your needs. - -# Define some constants -ticker_interval = "5m" -# Name of the strategy class -strategy_name = 'SampleStrategy' -# Path to user data -user_data_dir = 'user_data' -# Location of the strategy -strategy_location = Path(user_data_dir, 'strategies') -# Location of the data -data_location = Path(user_data_dir, 'data', 'binance') -# Pair to analyze - Only use one pair here -pair = "BTC_USDT" -``` - -### Load exchange data - -```python -from pathlib import Path -from freqtrade.data.history import load_pair_history - -# Load data using values set above -candles = load_pair_history(datadir=data_location, - ticker_interval=ticker_interval, - pair=pair) - -# Confirm success -print(f"Loaded {len(candles)} rows of data for {pair} from {data_location}") -candles.head() -``` - -### Load and run strategy - -* Rerun each time the strategy file is changed - -```python -from freqtrade.resolvers import StrategyResolver - -# Load strategy using values set above -strategy = StrategyResolver({'strategy': strategy_name, - 'user_data_dir': user_data_dir, - 'strategy_path': strategy_location}).strategy - -# Generate buy/sell signals using strategy -df = strategy.analyze_ticker(candles, {'pair': pair}) -``` - -### Display the trade details - -* Note that using `data.tail()` is preferable to `data.head()` as most indicators have some "startup" data at the top of the dataframe. -* Some possible problems - * Columns with NaN values at the end of the dataframe - * Columns used in `crossed*()` functions with completely different units -* Comparison with full backtest - * having 200 buy signals as output for one pair from `analyze_ticker()` does not necessarily mean that 200 trades will be made during backtesting. - * Assuming you use only one condition such as, `df['rsi'] < 30` as buy condition, this will generate multiple "buy" signals for each pair in sequence (until rsi returns > 29). The bot will only buy on the first of these signals (and also only if a trade-slot ("max_open_trades") is still available), or on one of the middle signals, as soon as a "slot" becomes available. - -```python -# Report results -print(f"Generated {df['buy'].sum()} buy signals") -data = df.set_index('date', drop=True) -data.tail() -``` +* [Strategy debugging](strategy_analysis_example.md) +* [Plotting](plotting.md) Feel free to submit an issue or Pull Request enhancing this document if you would like to share ideas on how to best analyze the data. diff --git a/docs/developer.md b/docs/developer.md index b048cf93f..4a3522147 100644 --- a/docs/developer.md +++ b/docs/developer.md @@ -149,6 +149,14 @@ print(datetime.utcnow()) The output will show the last entry from the Exchange as well as the current UTC date. If the day shows the same day, then the last candle can be assumed as incomplete and should be dropped (leave the setting `"ohlcv_partial_candle"` from the exchange-class untouched / True). Otherwise, set `"ohlcv_partial_candle"` to `False` to not drop Candles (shown in the example above). +## Updating example notebooks + +To keep the jupyter notebooks aligned with the documentation, the following should be ran after updating a example notebook. + +``` bash +jupyter nbconvert --to markdown user_data/notebooks/strategy_analysis_example.ipynb --stdout > docs/strategy_analysis_example.md +``` + ## Creating a release This part of the documentation is aimed at maintainers, and shows how to create a release. diff --git a/docs/strategy_analysis_example.md b/docs/strategy_analysis_example.md new file mode 100644 index 000000000..a685f5d52 --- /dev/null +++ b/docs/strategy_analysis_example.md @@ -0,0 +1,95 @@ +## Strategy debugging example + +Debugging a strategy can be time-consuming. FreqTrade offers helper functions to visualize raw data. + +## Setup + +```python +# Change directory +# Modify this cell to insure that the output shows the correct path. +import os +from pathlib import Path + +# Define all paths relative to the project root shown in the cell output +project_root = "somedir/freqtrade" +i=0 +try: + os.chdirdir(project_root) + assert Path('LICENSE').is_file() +except: + while i<4 and (not Path('LICENSE').is_file()): + os.chdir(Path(Path.cwd(), '../')) + i+=1 + project_root = Path.cwd() +print(Path.cwd()) +``` + + +```python +# Customize these according to your needs. + +# Define some constants +ticker_interval = "5m" +# Name of the strategy class +strategy_name = 'SampleStrategy' +# Path to user data +user_data_dir = 'user_data' +# Location of the strategy +strategy_location = Path(user_data_dir, 'strategies') +# Location of the data +data_location = Path(user_data_dir, 'data', 'binance') +# Pair to analyze - Only use one pair here +pair = "BTC_USDT" +``` + + +```python +# Load data using values set above +from pathlib import Path +from freqtrade.data.history import load_pair_history + +candles = load_pair_history(datadir=data_location, + ticker_interval=ticker_interval, + pair=pair) + +# Confirm success +print("Loaded " + str(len(candles)) + f" rows of data for {pair} from {data_location}") +candles.head() +``` + +## Load and run strategy +* Rerun each time the strategy file is changed + + +```python +# Load strategy using values set above +from freqtrade.resolvers import StrategyResolver +strategy = StrategyResolver({'strategy': strategy_name, + 'user_data_dir': user_data_dir, + 'strategy_path': strategy_location}).strategy + +# Generate buy/sell signals using strategy +df = strategy.analyze_ticker(candles, {'pair': pair}) +df.tail() +``` + +### Display the trade details + +* Note that using `data.head()` would also work, however most indicators have some "startup" data at the top of the dataframe. +* Some possible problems + * Columns with NaN values at the end of the dataframe + * Columns used in `crossed*()` functions with completely different units +* Comparison with full backtest + * having 200 buy signals as output for one pair from `analyze_ticker()` does not necessarily mean that 200 trades will be made during backtesting. + * Assuming you use only one condition such as, `df['rsi'] < 30` as buy condition, this will generate multiple "buy" signals for each pair in sequence (until rsi returns > 29). The bot will only buy on the first of these signals (and also only if a trade-slot ("max_open_trades") is still available), or on one of the middle signals, as soon as a "slot" becomes available. + + + +```python +# Report results +print(f"Generated {df['buy'].sum()} buy signals") +data = df.set_index('date', drop=True) +data.tail() +``` + +Feel free to submit an issue or Pull Request enhancing this document if you would like to share ideas on how to best analyze the data. diff --git a/mkdocs.yml b/mkdocs.yml index 869c6565c..027b009bc 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,8 +15,10 @@ nav: - Hyperopt: hyperopt.md - Edge positioning: edge.md - FAQ: faq.md - - Data Analysis: data-analysis.md - - Plotting: plotting.md + - Data Analysis: + - Jupyter Notebooks: data-analysis.md + - Strategy analysis: strategy_analysis_example.md + - Plotting: plotting.md - SQL Cheatsheet: sql_cheatsheet.md - Sandbox testing: sandbox-testing.md - Deprecated features: deprecated.md diff --git a/requirements-dev.txt b/requirements-dev.txt index 1b9bf7570..908ba2349 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -12,3 +12,6 @@ pytest-asyncio==0.10.0 pytest-cov==2.7.1 pytest-mock==1.10.4 pytest-random-order==1.0.4 + +# Convert jupyter notebooks to markdown documents +nbconvert==5.6.0 diff --git a/setup.py b/setup.py index ca94dd338..c4d8a3887 100644 --- a/setup.py +++ b/setup.py @@ -36,6 +36,7 @@ jupyter = [ 'jupyter', 'nbstripout', 'ipykernel', + 'nbconvert', ] all_extra = api + plot + develop + jupyter