Update documentation

2018-01-17 23:06:37 -08:00
parent be75522507
commit a5853681e3
5 changed files with 297 additions and 71 deletions
--- a/docs/bot-optimization.md
+++ b/docs/bot-optimization.md
@@ -3,21 +3,55 @@ This page explains where to customize your strategies, and add new
 indicators. 

 ## Table of Contents
- [Change your strategy](#change-your-strategy)
+- [Install a custom strategy file](#install-a-custom-strategy-file)
+- [Customize your strategy](#change-your-strategy)
 - [Add more Indicator](#add-more-indicator)
+- [Where is the default strategy](#where-is-the-default-strategy)
+
+Since the version `0.16.0` the bot allows using custom strategy file.
+
+## Install a custom strategy file
+This is very simple. Copy paste your strategy file into the folder 
+`user_data/strategies`.
+
+Let guess you have a strategy file `awesome-strategy.py`:
+1. Move your file into `user_data/strategies` (you should have `user_data/strategies/awesome-strategy.py`
+2. Start the bot with the param `--strategy awesome-strategy` (the parameter is the name of the file without '.py') 
+
+```bash
+python3 ./freqtrade/main.py --strategy awesome_strategy
+```

 ## Change your strategy
-The bot is using buy and sell strategies to buy and sell your trades. 
-Both are customizable.
+The bot includes a default strategy file. However, we recommend you to 
+use your own file to not have to lose your parameters everytime the default
+strategy file will be updated on Github. Put your custom strategy file
+into the folder `user_data/strategies`.

-### Buy strategy
-The default buy strategy is located in the file 
-[freqtrade/analyze.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/analyze.py#L73-L92). 
-Edit the function `populate_buy_trend()` to update your buy strategy.
+A strategy file contains all the information needed to build a good strategy:
+- Buy strategy rules
+- Sell strategy rules
+- Minimal ROI recommended
+- Stoploss recommended
+- Hyperopt parameter

-Sample:
+The bot also include a sample strategy you can update: `user_data/strategies/test_strategy.py`.  
+You can test it with the parameter: `--strategy test_strategy`
+ 
+```bash
+python3 ./freqtrade/main.py --strategy awesome_strategy
+```
+
+**For the following section we will use the [user_data/strategies/test_strategy.py](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py)
+file as reference.**
+
+### Buy strategy 
+Edit the method `populate_buy_trend()` into your strategy file to 
+update your buy strategy.
+
+Sample from `user_data/strategies/test_strategy.py`:  
 ```python
-def populate_buy_trend(dataframe: DataFrame) -> DataFrame:
+def populate_buy_trend(self, dataframe: DataFrame) -> DataFrame:
    """
    Based on TA indicators, populates the buy signal for the given dataframe
    :param dataframe: DataFrame
@@ -25,14 +59,9 @@ def populate_buy_trend(dataframe: DataFrame) -> DataFrame:
    """
    dataframe.loc[
        (
-            (dataframe['rsi'] < 35) &
-            (dataframe['fastd'] < 35) &
            (dataframe['adx'] > 30) &
-            (dataframe['plus_di'] > 0.5)
-        ) |
-        (
-            (dataframe['adx'] > 65) &
-            (dataframe['plus_di'] > 0.5)
+            (dataframe['tema'] <= dataframe['blower']) &
+            (dataframe['tema'] > dataframe['tema'].shift(1))
        ),
        'buy'] = 1

@@ -40,41 +69,31 @@ def populate_buy_trend(dataframe: DataFrame) -> DataFrame:
 ```

 ### Sell strategy
-The default buy strategy is located in the file 
-[freqtrade/analyze.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/analyze.py#L95-L115)
-Edit the function `populate_sell_trend()` to update your buy strategy.
+Edit the method `populate_sell_trend()` into your strategy file to 
+update your sell strategy.

-Sample:
+Sample from `user_data/strategies/test_strategy.py`:  
 ```python
-def populate_sell_trend(dataframe: DataFrame) -> DataFrame:
+def populate_sell_trend(self, dataframe: DataFrame) -> DataFrame:
    """
    Based on TA indicators, populates the sell signal for the given dataframe
    :param dataframe: DataFrame
    :return: DataFrame with buy column
    """
    dataframe.loc[
-        (
-            (
-                (crossed_above(dataframe['rsi'], 70)) |
-                (crossed_above(dataframe['fastd'], 70))
-            ) &
-            (dataframe['adx'] > 10) &
-            (dataframe['minus_di'] > 0)
-        ) |
        (
            (dataframe['adx'] > 70) &
-            (dataframe['minus_di'] > 0.5)
+            (dataframe['tema'] > dataframe['blower']) &
+            (dataframe['tema'] < dataframe['tema'].shift(1))
        ),
        'sell'] = 1
    return dataframe
 ```

 ## Add more Indicator
-As you have seen, buy and sell strategies need indicators. You can see 
-the indicators in the file 
-[freqtrade/analyze.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/analyze.py#L95-L115).
-Of course you can add more indicators by extending the list contained in
-the function `populate_indicators()`.
+As you have seen, buy and sell strategies need indicators. You can add 
+more indicators by extending the list contained in
+the method `populate_indicators()` from your strategy file.

 Sample:
 ```python
@@ -111,6 +130,15 @@ def populate_indicators(dataframe: DataFrame) -> DataFrame:
    return dataframe
 ```

+**Want more indicators example?**  
+Look into the [user_data/strategies/test_strategy.py](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py).  
+Then uncomment indicateur you need.
+
+
+### Where is the default strategy?
+The default buy strategy is located in the file 
+[freqtrade/default_strategy.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/strategy/default_strategy.py). 
+

 ## Next step
 Now you have a perfect strategy you probably want to backtesting it. 
--- a/docs/bot-usage.md
+++ b/docs/bot-usage.md
@@ -22,19 +22,21 @@ positional arguments:

 optional arguments:
  -h, --help            show this help message and exit
-  -c PATH, --config PATH
-                        specify configuration file (default: config.json)
  -v, --verbose         be verbose
  --version             show program's version number and exit
-  -dd PATH, --datadir PATH
-                        Path is from where backtesting and hyperopt will load the
-                        ticker data files (default freqdata/tests/testdata).
-  --dynamic-whitelist [INT]
-                        dynamically generate and update whitelist based on 24h
-                        BaseVolume (Default 20 currencies)
+  -c PATH, --config PATH
+                        specify configuration file (default: config.json)
+  -s PATH, --strategy PATH
+                        specify strategy file (default:
+                        freqtrade/strategy/default_strategy.py)
  --dry-run-db          Force dry run to use a local DB
                        "tradesv3.dry_run.sqlite" instead of memory DB. Work
                        only if dry_run is enabled.
+  -dd PATH, --datadir PATH
+                        path to backtest data (default freqdata/tests/testdata
+  --dynamic-whitelist [INT]
+                        dynamically generate and update whitelist based on 24h
+                        BaseVolume (Default 20 currencies)
 ```

 ### How to use a different config file?
@@ -45,6 +47,33 @@ default, the bot will load the file `./config.json`
 python3 ./freqtrade/main.py -c path/far/far/away/config.json 
 ```

+### How to use --strategy?
+This parameter will allow you to load your custom strategy file. Per 
+default without `--strategy` or `-s` the bol will load the 
+`default_strategy` included with the bot (`freqtrade/strategy/default_strategy.py`). 
+
+The bot will search your strategy file into `user_data/strategies` and 
+`freqtrade/strategy`.
+
+To load a strategy, simply pass the file name (without .py) in this 
+parameters.
+
+**Example:**  
+In `user_data/strategies` you have a file `my_awesome_strategy.py` to 
+load it:  
+```bash
+python3 ./freqtrade/main.py --strategy my_awesome_strategy
+```
+
+If the bot does not find your strategy file, it will fallback to the 
+`default_strategy`.
+
+Learn more about strategy file in [optimize your bot](https://github.com/gcarq/freqtrade/blob/develop/docs/bot-optimization.md).
+
+#### How to install a strategy?
+This is very simple. Copy paste your strategy file into the folder 
+`user_data/strategies`. And voila, the bot is ready to use it.
+
 ### How to use --dynamic-whitelist?
 Per default `--dynamic-whitelist` will retrieve the 20 currencies based 
 on BaseVolume. This value can be changed when you run the script.
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -20,8 +20,8 @@ The table below will list all configuration parameters.
 | `ticker_interval` | [1, 5, 30, 60, 1440] | No | The ticker interval to use (1min, 5 min, 30 min, 1 hour or 1 day). Defaut is 5 minutes
 | `fiat_display_currency` | USD | Yes | Fiat currency used to show your profits. More information below. 
 | `dry_run` | true | Yes | Define if the bot must be in Dry-run or production mode. 
-| `minimal_roi` | See below | Yes | Set the threshold in percent the bot will use to sell a trade. More information below. 
-| `stoploss` | -0.10 | No | Value of the stoploss in percent used by the bot. More information below. 
+| `minimal_roi` | See below | No | Set the threshold in percent the bot will use to sell a trade. More information below. If set, this parameter will override `minimal_roi` from your strategy file. 
+| `stoploss` | -0.10 | No | Value of the stoploss in percent used by the bot. More information below. If set, this parameter will override `stoploss` from your strategy file. 
 | `unfilledtimeout` | 0 | No | How long (in minutes) the bot will wait for an unfilled order to complete, after which the order will be cancelled.
 | `bid_strategy.ask_last_balance` | 0.0 | Yes | Set the bidding price. More information below.
 | `exchange.name` | bittrex | Yes | Name of the exchange class to use.
@@ -53,11 +53,19 @@ See the example below:
 },
 ```

+Most of the strategy files already include the optimal `minimal_roi`
+value. This parameter is optional. If you use it, it will take over the
+`minimal_roi` value from the strategy file.
+
 ### Understand stoploss
 `stoploss` is loss in percentage that should trigger a sale.
 For example value `-0.10` will cause immediate sell if the
 profit dips below -10% for a given trade. This parameter is optional.

+Most of the strategy files already include the optimal `stoploss`
+value. This parameter is optional. If you use it, it will take over the
+`stoploss` value from the strategy file.
+
 ### Understand initial_state
 `initial_state` is an optional field that defines the initial application state.
 Possible values are `running` or `stopped`. (default=`running`)
--- a/docs/hyperopt.md
+++ b/docs/hyperopt.md
@@ -14,14 +14,13 @@ parameters with Hyperopt.

 ## Prepare Hyperopt
 Before we start digging in Hyperopt, we recommend you to take a look at 
-out Hyperopt file 
-[freqtrade/optimize/hyperopt.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt.py)
+your strategy file located into [user_data/strategies/](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py)
 
 ### 1. Configure your Guards and Triggers
-There are two places you need to change to add a new buy strategy for 
-testing:
- Inside the [populate_buy_trend()](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt.py#L167-L207).
- Inside the [SPACE dict](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt.py#L47-L94).
+There are two places you need to change in your strategy file to add a 
+new buy strategy for testing:
+- Inside [populate_buy_trend()](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py#L278-L294).
+- Inside [hyperopt_space()](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py#L244-L297) known as `SPACE`.

 There you have two different type of indicators: 1. `guards` and 2. 
 `triggers`.
@@ -38,10 +37,10 @@ ADX > 10*".


 If you have updated the buy strategy, means change the content of
-`populate_buy_trend()` function you have to update the `guards` and 
+`populate_buy_trend()` method you have to update the `guards` and 
 `triggers` hyperopts must used.

-As for an example if your `populate_buy_trend()` function is:
+As for an example if your `populate_buy_trend()` method is:
 ```python
 def populate_buy_trend(dataframe: DataFrame) -> DataFrame:
    dataframe.loc[
@@ -56,10 +55,10 @@ Your hyperopt file must contains `guards` to find the right value for
 `(dataframe['adx'] > 65)` & and `(dataframe['plus_di'] > 0.5)`. That 
 means you will need to enable/disable triggers.
 
-In our case the `SPACE` and `populate_buy_trend` in hyperopt.py file 
+In our case the `SPACE` and `populate_buy_trend` in your strategy file 
 will be look like:
 ```python
-SPACE = {
+space = {
    'rsi': hp.choice('rsi', [
        {'enabled': False},
        {'enabled': True, 'value': hp.quniform('rsi-value', 20, 40, 1)}
@@ -82,7 +81,7 @@ SPACE = {

 ... 

-def populate_buy_trend(dataframe: DataFrame) -> DataFrame:
+def populate_buy_trend(self, dataframe: DataFrame) -> DataFrame:
        conditions = []
        # GUARDS AND TRENDS
        if params['adx']['enabled']:
@@ -111,13 +110,13 @@ cannot use your config file. It is also made on purpose to allow you
 testing your strategy with different configurations.

 The Hyperopt configuration is located in 
-[freqtrade/optimize/hyperopt_conf.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt_conf.py).
+[user_data/hyperopt_conf.py](https://github.com/gcarq/freqtrade/blob/develop/user_data/hyperopt_conf.py).


 ## Advanced notions
 ### Understand the Guards and Triggers
 When you need to add the new guards and triggers to be hyperopt 
-parameters, you do this by adding them into the [SPACE dict](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt.py#L47-L94).
+parameters, you do this by adding them into the [hyperopt_space()](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py#L244-L297).

 If it's a trigger, you add one line to the 'trigger' choice group and that's it.

@@ -149,9 +148,8 @@ for best working algo.

 ### Add a new Indicators
 If you want to test an indicator that isn't used by the bot currently, 
-you need to add it to 
-[freqtrade/analyze.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/analyze.py#L40-L70)
-inside the `populate_indicators` function.
+you need to add it to your strategy file (example: [user_data/strategies/test_strategy.py](https://github.com/gcarq/freqtrade/blob/develop/user_data/strategies/test_strategy.py))
+inside the `populate_indicators()` method.

 ## Execute Hyperopt
 Once you have updated your hyperopt configuration you can run it. 
@@ -165,8 +163,8 @@ python3 ./freqtrade/main.py -c config.json hyperopt

 ### Execute hyperopt with different ticker-data source
 If you would like to learn parameters using an alternate ticke-data that
-you have on-disk, use the --datadir PATH option. Default hyperopt will
-use data from directory freqtrade/tests/testdata.
+you have on-disk, use the `--datadir PATH` option. Default hyperopt will
+use data from directory `user_data/data`.

 ### Running hyperopt with smaller testset

@@ -270,15 +268,11 @@ customizable value.
 - and so on...


-You have to look from 
-[freqtrade/optimize/hyperopt.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt.py#L170-L200) 
-what those values match to.   
+You have to look inside your strategy file into `buy_strategy_generator()` 
+method, what those values match to.   
  
 So for example you had `adx:` with the `value: 15.0` so we would look 
-at `adx`-block from 
-[freqtrade/optimize/hyperopt.py](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/optimize/hyperopt.py#L178-L179). 
-That translates to the following code block to 
-[analyze.populate_buy_trend()](https://github.com/gcarq/freqtrade/blob/develop/freqtrade/analyze.py#L73)
+at `adx`-block, that translates to the following code block:
 ```
 (dataframe['adx'] > 15.0)
 ```
@@ -286,7 +280,7 @@ That translates to the following code block to
 So translating your whole hyperopt result to as the new buy-signal 
 would be the following:
 ```
-def populate_buy_trend(dataframe: DataFrame) -> DataFrame:
+def populate_buy_trend(self, dataframe: DataFrame) -> DataFrame:
    dataframe.loc[
        (
            (dataframe['adx'] > 15.0) & # adx-value