Add documentation

docs/configuration.md

@@ -11,7 +11,7 @@ Per default, the bot loads the configuration from the `config.json` file, locate
 
 You can specify a different configuration file used by the bot with the `-c/--config` command-line option.
 
-If you used the [Quick start](installation.md/#quick-start) method for installing 
+If you used the [Quick start](installation.md/#quick-start) method for installing
 the bot, the installation script should have already created the default configuration file (`config.json`) for you.
 
 If the default configuration file is not created we recommend to use `freqtrade new-config --config config.json` to generate a basic configuration file.
@@ -64,7 +64,7 @@ This is similar to using multiple `--config` parameters, but simpler in usage as
         "config-private.json"
     ]
     ```
-    
+
     ``` bash
     freqtrade trade --config user_data/config.json <...>
     ```
@@ -100,7 +100,7 @@ This is similar to using multiple `--config` parameters, but simpler in usage as
         "stake_amount": "unlimited",
     }
     ```
-    
+
     Resulting combined configuration:
 
     ``` json title="Result"
@@ -229,6 +229,7 @@ Mandatory parameters are marked as **Required**, which means that they are requi
 | `dataformat_trades` | Data format to use to store historical trades data. <br> *Defaults to `jsongz`*. <br> **Datatype:** String
 | `position_adjustment_enable` | Enables the strategy to use position adjustments (additional buys or sells). [More information here](strategy-callbacks.md#adjust-trade-position). <br> [Strategy Override](#parameters-in-the-strategy). <br>*Defaults to `false`.*<br> **Datatype:** Boolean
 | `max_entry_position_adjustment` | Maximum additional order(s) for each open trade on top of the first entry Order. Set it to `-1` for unlimited additional orders. [More information here](strategy-callbacks.md#adjust-trade-position). <br> [Strategy Override](#parameters-in-the-strategy). <br>*Defaults to `-1`.*<br> **Datatype:** Positive Integer or -1
+| `backtest_signal_candle_export_enable` | Enables the exporting of signal candles for use in post-backtesting analysis of buy tags. See [Strategy Analysis](strategy_analysis_example.md#analyse-the-buy-entry-and-sell-exit-tags). <br>*Defaults to `false`.*<br> **Datatype:** Boolean
 
 ### Parameters in the strategy
 

docs/strategy_analysis_example.md

@@ -93,7 +93,7 @@ from freqtrade.data.btanalysis import load_backtest_data, load_backtest_stats
 
 # if backtest_dir points to a directory, it'll automatically load the last backtest file.
 backtest_dir = config["user_data_dir"] / "backtest_results"
-# backtest_dir can also point to a specific file 
+# backtest_dir can also point to a specific file
 # backtest_dir = config["user_data_dir"] / "backtest_results/backtest-result-2020-07-01_20-04-22.json"
 ```
 
@@ -250,3 +250,75 @@ fig.show()
 ```
 
 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.
+
+## Analyse the buy/entry and sell/exit tags
+
+It can be helpful to understand how a strategy behaves according to the buy/entry tags used to
+mark up different buy conditions. You might want to see more complex statistics about each buy and
+sell condition above those provided by the default backtesting output. You may also want to
+determine indicator values on the signal candle that resulted in a trade opening.
+
+We first need to enable the exporting of trades from backtesting:
+
+```
+freqtrade backtesting -c <config.json> --timeframe <tf> --strategy <strategy_name> --timerange=<timerange> --export=trades --export-filename=user_data/backtest_results/<name>-<timerange>
+```
+
+To analyse the buy tags, we need to use the buy_reasons.py script in the `scripts/`
+folder. We need the signal candles for each opened trade so add the following option to your
+config file:
+
+```
+'backtest_signal_candle_export_enable': true,
+```
+
+This will tell freqtrade to output a pickled dictionary of strategy, pairs and corresponding
+DataFrame of the candles that resulted in buy signals. Depending on how many buys your strategy
+makes, this file may get quite large, so periodically check your `user_data/backtest_results`
+folder to delete old exports.
+
+Before running your next backtest, make sure you either delete your old backtest results or run
+backtesting with the `--cache none` option to make sure no cached results are used.
+
+If all goes well, you should now see a `backtest-result-{timestamp}_signals.pkl` file in the
+`user_data/backtest_results` folder.
+
+Now run the buy_reasons.py script, supplying a few options:
+
+```
+./scripts/buy_reasons.py -c <config.json> -s <strategy_name> -t <timerange> -g0,1,2,3,4
+```
+
+The `-g` option is used to specify the various tabular outputs, ranging from the simplest (0)
+to the most detailed per pair, per buy and per sell tag (4). More options are available by
+running with the `-h` option.
+
+### Tuning the buy tags and sell tags to display
+
+To show only certain buy and sell tags in the displayed output, use the following two options:
+
+```
+--buy_reason_list : Comma separated list of buy signals to analyse. Default: "all"
+--sell_reason_list : Comma separated list of sell signals to analyse. Default: "stop_loss,trailing_stop_loss"
+```
+
+For example:
+
+```
+./scripts/buy_reasons.py -c <config.json> -s <strategy_name> -t <timerange> -g0,1,2,3,4 --buy_reason_list "buy_tag_a,buy_tag_b" --sell_reason_list "roi,custom_sell_tag_a,stop_loss"
+```
+
+### Outputting signal candle indicators
+
+The real power of the buy_reasons.py script comes from the ability to print out the indicator
+values present on signal candles to allow fine-grained investigation and tuning of buy signal
+indicators. To print out a column for a given set of indicators, use the `--indicator-list`
+option:
+
+```
+./scripts/buy_reasons.py -c <config.json> -s <strategy_name> -t <timerange> -g0,1,2,3,4 --buy_reason_list "buy_tag_a,buy_tag_b" --sell_reason_list "roi,custom_sell_tag_a,stop_loss" --indicator_list "rsi,rsi_1h,bb_lowerband,ema_9,macd,macdsignal"
+```
+
+The indicators have to be present in your strategy's main dataframe (either for your main
+timeframe or for informatives) otherwise they will simply be ignored in the script
+output.