From e01c0ab4d680d72a4141ce5a5e60462027a67f31 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 18 Jul 2019 20:02:28 +0200 Subject: [PATCH] Improve doc wording --- docs/bot-usage.md | 40 +++++++++++++++++++--------- docs/hyperopt.md | 34 ++++++++++++----------- freqtrade/configuration/arguments.py | 3 ++- 3 files changed, 49 insertions(+), 28 deletions(-) diff --git a/docs/bot-usage.md b/docs/bot-usage.md index 85692ae14..aef91189a 100644 --- a/docs/bot-usage.md +++ b/docs/bot-usage.md @@ -213,19 +213,22 @@ to find optimal parameter values for your stategy. ``` usage: freqtrade hyperopt [-h] [-i TICKER_INTERVAL] [--timerange TIMERANGE] - [--max_open_trades MAX_OPEN_TRADES] - [--stake_amount STAKE_AMOUNT] [-r] - [--customhyperopt NAME] [--eps] [--dmmp] [-e INT] - [-s {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...]] - [--print-all] [-j JOBS] + [--max_open_trades INT] + [--stake_amount STAKE_AMOUNT] [-r] + [--customhyperopt NAME] [--eps] [-e INT] + [-s {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...]] + [--dmmp] [--print-all] [-j JOBS] + [--random-state INT] [--min-trades INT] [--continue] + [--hyperopt-loss-class NAME] optional arguments: -h, --help show this help message and exit -i TICKER_INTERVAL, --ticker-interval TICKER_INTERVAL - Specify ticker interval (1m, 5m, 30m, 1h, 1d). + Specify ticker interval (`1m`, `5m`, `30m`, `1h`, + `1d`). --timerange TIMERANGE Specify what timerange of data to use. - --max_open_trades MAX_OPEN_TRADES + --max_open_trades INT Specify max_open_trades to use. --stake_amount STAKE_AMOUNT Specify stake_amount. @@ -235,18 +238,18 @@ optional arguments: run your optimization commands with up-to-date data. --customhyperopt NAME Specify hyperopt class name (default: - DefaultHyperOpts). + `DefaultHyperOpts`). --eps, --enable-position-stacking Allow buying the same pair multiple times (position stacking). + -e INT, --epochs INT Specify number of epochs (default: 100). + -s {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...], --spaces {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...] + Specify which parameters to hyperopt. Space-separated + list. Default: `all`. --dmmp, --disable-max-market-positions Disable applying `max_open_trades` during backtest (same as setting `max_open_trades` to a very high number). - -e INT, --epochs INT Specify number of epochs (default: 100). - -s {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...], --spaces {all,buy,sell,roi,stoploss} [{all,buy,sell,roi,stoploss} ...] - Specify which parameters to hyperopt. Space separate - list. Default: all. --print-all Print all results, not only the best ones. -j JOBS, --job-workers JOBS The number of concurrently running jobs for @@ -254,6 +257,19 @@ optional arguments: (default), all CPUs are used, for -2, all CPUs but one are used, etc. If 1 is given, no parallel computing code is used at all. + --random-state INT Set random state to some positive integer for + reproducible hyperopt results. + --min-trades INT Set minimal desired number of trades for evaluations + in the hyperopt optimization path (default: 1). + --continue Continue hyperopt from previous runs. By default, + temporary files will be removed and hyperopt will + start from scratch. + --hyperopt-loss-class NAME + Specify the class name of the hyperopt loss function + class (IHyperOptLoss). Different functions can + generate completely different results, since the + target for optimization is different. (default: + `DefaultHyperOptLoss`). ``` ## Edge commands diff --git a/docs/hyperopt.md b/docs/hyperopt.md index 6be3d590f..5ff5310a3 100644 --- a/docs/hyperopt.md +++ b/docs/hyperopt.md @@ -144,7 +144,7 @@ it will end with telling you which paramter combination produced the best profit The search for best parameters starts with a few random combinations and then uses a regressor algorithm (currently ExtraTreesRegressor) to quickly find a parameter combination -that minimizes the value of the objective function `calculate_loss` in `hyperopt.py`. +that minimizes the value of the [loss function](#loss-functions). The above setup expects to find ADX, RSI and Bollinger Bands in the populated indicators. When you want to test an indicator that isn't used by the bot currently, remember to @@ -152,17 +152,19 @@ add it to the `populate_indicators()` method in `hyperopt.py`. ## Loss-functions -Each hyperparameter tuning requires a target. This is usually defined as a loss function, which get's closer to 0 for increasing values. +Each hyperparameter tuning requires a target. This is usually defined as a loss function (sometimes also called objective function), which should decrease for more desirable results, and increase for bad results. -FreqTrade uses a default loss function, which has been with freqtrade since the beginning and optimizes mostly for short trade duration and avoiding losses. +By default, FreqTrade uses a loss function, which has been with freqtrade since the beginning and optimizes mostly for short trade duration and avoiding losses. -A different version this can be used by using the `--hyperopt-loss ` argument. +A different version this can be used by using the `--hyperopt-loss-class ` argument. This class should be in it's own file within the `user_data/hyperopts/` directory. -### Using a custom loss function +Currently, the following loss-functions are builtin: `SharpeHyperOptLoss` and `DefaultHyperOptLoss`. -To use a custom loss Class, make sure that the function `hyperopt_loss_function` is defined in your custom hyperopt loss class. -For the sample below, you then need to add the command line parameter `--hyperoptloss SuperDuperHyperOptLoss` to your hyperopt call so this fuction is being used. +### Creating and using a custom loss function + +To use a custom loss function class, make sure that the function `hyperopt_loss_function` is defined in your custom hyperopt loss class. +For the sample below, you then need to add the command line parameter `--hyperopt-loss-class SuperDuperHyperOptLoss` to your hyperopt call so this fuction is being used. A sample of this can be found below, which is identical to the Default Hyperopt loss implementation. A full sample can be found [user_data/hyperopts/](https://github.com/freqtrade/freqtrade/blob/develop/user_data/hyperopts/sample_hyperopt_loss.py) @@ -209,7 +211,7 @@ Currently, the arguments are: * `min_date`: Start date of the hyperopting TimeFrame * `min_date`: End date of the hyperopting TimeFrame -This function needs to return a floating point number (`float`). The smaller that number, the better is the result. The parameters and balancing for this are up to you. +This function needs to return a floating point number (`float`). Smaller numbers will be interpreted as better results. The parameters and balancing for this is up to you. !!! Note This function is called once per iteration - so please make sure to have this as optimized as possible to not slow hyperopt down unnecessarily. @@ -220,7 +222,7 @@ This function needs to return a floating point number (`float`). The smaller tha ## Execute Hyperopt Once you have updated your hyperopt configuration you can run it. -Because hyperopt tries a lot of combinations to find the best parameters it will take time you will have the result (more than 30 mins). +Because hyperopt tries a lot of combinations to find the best parameters it will take time to get a good result. More time usually results in better results. We strongly recommend to use `screen` or `tmux` to prevent any connection loss. @@ -235,8 +237,11 @@ running at least several thousand evaluations. The `--spaces all` flag determines that all possible parameters should be optimized. Possibilities are listed below. +!!! Note + By default, hyperopt will erase previous results and start from scratch. Continuation can be archived by using `--continue`. + !!! Warning - When switching parameters or changing configuration options, the file `user_data/hyperopt_results.pickle` should be removed. It's used to be able to continue interrupted calculations, but does not detect changes to settings or the hyperopt file. + When switching parameters or changing configuration options, make sure to not use the argument `--continue` so temporary results can be removed. ### Execute Hyperopt with Different Ticker-Data Source @@ -246,12 +251,11 @@ use data from directory `user_data/data`. ### Running Hyperopt with Smaller Testset -Use the `--timerange` argument to change how much of the testset -you want to use. The last N ticks/timeframes will be used. -Example: +Use the `--timerange` argument to change how much of the testset you want to use. +To use one month of data, use the following parameter: ```bash -freqtrade hyperopt --timerange -200 +freqtrade hyperopt --timerange 20180401-20180501 ``` ### Running Hyperopt with Smaller Search Space @@ -319,7 +323,7 @@ method, what those values match to. So for example you had `rsi-value: 29.0` so we would look at `rsi`-block, that translates to the following code block: -``` +``` python (dataframe['rsi'] < 29.0) ``` diff --git a/freqtrade/configuration/arguments.py b/freqtrade/configuration/arguments.py index 1c1070507..891bf7d93 100644 --- a/freqtrade/configuration/arguments.py +++ b/freqtrade/configuration/arguments.py @@ -232,7 +232,8 @@ AVAILABLE_CLI_OPTIONS = { ), "hyperopt_loss": Arg( '--hyperopt-loss-class', - help='Specify hyperopt loss class name. Can generate completely different results, ' + help='Specify the class name of the hyperopt loss function class (IHyperOptLoss). ' + 'Different functions can generate completely different results, ' 'since the target for optimization is different. (default: `%(default)s`).', metavar='NAME', default=constants.DEFAULT_HYPEROPT_LOSS,