Repository: freqtrade/freqtrade
Pull request: Add timeframe_to_minutes to ROI documentation
## Summary
sometimes using ROI based on candle can be useful (especially during strategy development when experimenting with different timeframes).

While easily possible, it's so far only been documented in a issue, but not in the documentation.

Closes #2463

## Quick changelog

- add sample for candle based ROI


Problem statement:
Idea : be able to use candle duration instead of minutes in minimal roi
As a trader
I want to easily test strategies on multi time frames without make any changes in the minimal roi duration and if i test on higher time frames and don't need to do something like `60*24*6` (sixth day after buy on 1 day timeframe)
So that i can focus on a one fits all easily and have clear overview of the minimal roi even on high timeframes

A solution could be to use candle duration as minimal roi keys (sell after 3 and 6 candle).

> {"3":0.02,"6",0.01}

And use this as an option in config file something like use_candle_as_roi_duration = True. (default False)

Have a nice day.

Hints from issue discussion:
we've discussed this before ...

the problem with using candle duration is that it limits you on longer timeframes / makes calculation difficult and odd - assuming you use 1h timeframes.

Maybe you want to sell after 2 hours and 30 minutes. - 2.5 is still okish - but what about after 2 hours 45 minutes? it's not 2.45, but 2.75. It's not obvious why it's not 2.45 (it's 2 hours 45 minutes ...).

Also, (more importantly) it's not something that can be changed easily without causing unexpected behaviours for users - since there is no difference in the code if i intend to say "3 days" - or "3 minutes" - it'll always be `3: 0.02`

you can however work around this rather easily:

```python
from freqtrade.exchange import timeframe_to_minutes

class AwesomeStrategy(IStrategy):
    ticker_interval = '1d'
    minimal_roi = {
     (timeframe_to_minutes(ticker_interval) * 3): "0.02,
     (timeframe_to_minutes(ticker_interval) * 6): "0.01,
  }
```
or, even simpler as the calculation is extracted:
```python
from freqtrade.exchange import timeframe_to_minutes

class AwesomeStrategy(IStrategy):
    ticker_interval = '1d'
    ticker_interval_mins = timeframe_to_minutes(ticker_interval)
    minimal_roi = {
     (ticker_interval_mins * 3): "0.02,
     (ticker_interval_mins * 6): "0.01,
  }
```
> Maybe you want to sell after 2 hours and 30 minutes. - 2.5 is still okish - but what about after 2 hours 45 minutes? it's not 2.45, but 2.75. It's not obvious why it's not 2.45 (it's 2 hours 45 minutes ...).

2.75 candles is okay for 2:45hrs in the same degree as 2.5 candles is okay for 2:30hrs.... 😎 

The proposal and the intention mentioned ('I want to easily test strategies on multi time frames without make any changes in the minimal roi') may have sense, sure.

The real problem here is that not only minutes should be scaled, but the ratios as well. 0.1 may be too tight for a longer timeframe and never be reached for shorter timeframes...

In my opinion, the ratios should also be scaled, but logarithmically. This was implemented this way for the roi ranges in IHyperopt. Implementing this from scratches in the custom strategy can be a pain.

This can be borrowed from IHyperopt (scaling of min_roi, both times and ratios) with modifications and a new 'experimental' feature be added, like `experimental.adapt_min_roi` or `experimental.scale_min_roi` (bool, with default to false for now)...

the problem with "adaptive" roi's is that you need to do math - so it's non intuitive.
The same problem exists with using "candle count" ... but as said - it's a change to the user interface i don't see any need for, as it'll break any configuration users did so far.

Adaptive ROI works well for hyperopt, because there, you mostly care about the result - not about what was inputted.

For a strategy on the other hand, users should have full control - so using an "adaptive" mode is counter-intuitive, and difficult to grasp.
As a user, I want to know where exactly my ROI's are so i can adapt this if i see problems with sells. 

If it's adaptive, then what does `20: 0.05` tell me? 
it may be at 5% for 5m tickers, but at 15% for 1d tickers? 
that makes ROI incontrollable / unusable.

Yes, changing timeframe may need changes to the ROI dict - but it'll most likely also need changes to other parts of the strategy... most strategies don't adapt well to completely different timeframes. 
Switching from 5m to 15m may work - but using a strategy developed for 5m on 1d timeframe will most likely result in pain and losses.

An indicator's lag may work with 5m - but will not work with 1d candles since then you're looking too far into the past, so this will need to be changed anyway - which takes away the argument of using adaptive ROI's.


(Comment was posted into wrong issue, moved to #2423 
@gaugau3000 you may also review the helper functions I described there...)
I'll add the above sample to the documentation - then everyone is free to use candles or minutes however they like - but currently working strategies do not need to be adapted.

The other direction (change to candles, provide method to convert candle to minute) would also be possible, but it's a disruptive method i do not see any point in doing.

Commit message: Add timeframe_to_minutes to ROI documentation

Patch to review:
diff --git a/docs/strategy-customization.md b/docs/strategy-customization.md
index 07833da34cc..0dfeb3978bd 100644
--- a/docs/strategy-customization.md
+++ b/docs/strategy-customization.md
@@ -249,6 +249,22 @@ minimal_roi = {
 
 While technically not completely disabled, this would sell once the trade reaches 10000% Profit.
 
+To use times based on candles, the following snippet can be handy.
+This will allow you to change the ticket_interval, and ROI will be set as candles (e.g. after 3 candles ...)
+
+``` python
+from freqtrade.exchange import timeframe_to_minutes
+
+class AwesomeStrategy(IStrategy):
+
+    ticker_interval = '1d'
+    ticker_interval_mins = timeframe_to_minutes(ticker_interval)
+    minimal_roi = {
+        (ticker_interval_mins * 3): 0.02,  # After 3 candles
+        (ticker_interval_mins * 6): 0.01,  # After 6 candles
+    }
+```
+
 ### Stoploss
 
 Setting a stoploss is highly recommended to protect your capital from strong moves against you.


Code review comments:
diff_hunk: @@ -249,6 +249,22 @@ minimal_roi = {
 
 While technically not completely disabled, this would sell once the trade reaches 10000% Profit.
 
+To use times based on candles, the following snippet can be handy.
+This will allow you to change the ticket_interval, and ROI will be set as candles (e.g. after 3 candles ...)
+
+``` python
+from freqtrade.exchange import timeframe_to_minutes
+
+class AwesomeStrategy(IStrategy):
+
+    ticker_interval = '1d'
+    ticker_interval_mins = timeframe_to_minutes(ticker_interval)
+    minimal_roi = {
+        (ticker_interval_mins * 3): 0.02,  # After 3 candles
path: docs/strategy-customization.md
text: @user1:
Has this been tested? It does not seem to work for me, also shouldn't it start with 0 minutes?

@author:
Yes i did - the 0 entry is not necessary - however there was a bug in this section - it needs explicit conversion to string as this is expected to be a string.

A sample configuration (it did a few trades in this config, too)

![2020-02-26-064243_492x258_scrot](https://user-images.githubusercontent.com/5024695/75315621-7e2b6080-5863-11ea-99e2-a1ca0cc8552b.png)