Merge pull request #4543 from brookmiles/fix-math-custom-stoploss-docs

correct math used in examples and clarify some terminology regarding …

docs/strategy-advanced.md

@@ -71,12 +71,13 @@ See `custom_stoploss` examples below on how to access the saved dataframe column
 
 ## Custom stoploss
 
-A stoploss can only ever move upwards - so if you set it to an absolute profit of 2%, you can never move it below this price.
+The stoploss price can only ever move upwards - if the stoploss value returned from `custom_stoploss` would result in a lower stoploss price than was previously set, it will be ignored. The traditional `stoploss` value serves as an absolute lower level and will be instated as the initial stoploss.
-Also, the traditional `stoploss` value serves as an absolute lower level and will be instated as the initial stoploss.
 
 The usage of the custom stoploss method must be enabled by setting `use_custom_stoploss=True` on the strategy object.
-The method must return a stoploss value (float / number) with a relative ratio below the current price.
+The method must return a stoploss value (float / number) as a percentage of the current price.
-E.g. `current_profit = 0.05` (5% profit) - stoploss returns `0.02` - then you "locked in" a profit of 3% (`0.05 - 0.02 = 0.03`).
+E.g. If the `current_rate` is 200 USD, then returning `0.02` will set the stoploss price 2% lower, at 196 USD.
+
+The absolute value of the return value is used (the sign is ignored), so returning `0.05` or `-0.05` have the same result, a stoploss 5% below the current price.
 
 To simulate a regular trailing stoploss of 4% (trailing 4% behind the maximum reached price) you would use the following very simple method:
 
@@ -206,18 +207,26 @@ class AwesomeStrategy(IStrategy):
         return max(min(desired_stoploss, 0.05), 0.025)
 ```
 
-#### Absolute stoploss
+#### Calculating stoploss relative to open price
 
-The below example sets absolute profit levels based on the current profit.
+Stoploss values returned from `custom_stoploss()` always specify a percentage relative to `current_rate`. In order to set a stoploss relative to the *open* price, we need to use `current_profit` to calculate what percentage relative to the `current_rate` will give you the same result as if the percentage was specified from the open price.
+
+The helper function [`stoploss_from_open()`](strategy-customization.md#stoploss_from_open) can be used to convert from an open price relative stop, to a current price relative stop which can be returned from `custom_stoploss()`.
+
+#### Stepped stoploss
+
+Instead of continuously trailing behind the current price, this example sets fixed stoploss price levels based on the current profit.
 
 * Use the regular stoploss until 20% profit is reached
-* Once profit is > 40%, stoploss will be at 25%, locking in at least 25% of the profit.
+* Once profit is > 20% - set stoploss to 7% above open price.
-* Once profit is > 25% - stoploss will be 15%.
+* Once profit is > 25% - set stoploss to 15% above open price.
-* Once profit is > 20% - stoploss will be set to 7%.
+* Once profit is > 40% - set stoploss to 25% above open price.
+
 
 ``` python
 from datetime import datetime
 from freqtrade.persistence import Trade
+from freqtrade.strategy import stoploss_from_open
 
 class AwesomeStrategy(IStrategy):
 
@@ -228,13 +237,15 @@ class AwesomeStrategy(IStrategy):
     def custom_stoploss(self, pair: str, trade: 'Trade', current_time: datetime,
                         current_rate: float, current_profit: float, **kwargs) -> float:
 
-        # Calculate as `-desired_stop_from_open + current_profit` to get the distance between current_profit and initial price
+        # evaluate highest to lowest, so that highest possible stop is used
         if current_profit > 0.40:
-            return (-0.25 + current_profit)
+            return stoploss_from_open(0.25, current_profit)
-        if current_profit > 0.25:
+        elif current_profit > 0.25:
-            return (-0.15 + current_profit)
+            return stoploss_from_open(0.15, current_profit)
-        if current_profit > 0.20:
+        elif current_profit > 0.20:
-            return (-0.07 + current_profit)
+            return stoploss_from_open(0.07, current_profit)
+
+        # return maximum stoploss value, keeping current stoploss price unchanged
         return 1
 ```
 #### Custom stoploss using an indicator from dataframe example
@@ -266,7 +277,7 @@ class AwesomeStrategy(IStrategy):
             # using current_time directly (like below) will only work in backtesting.
             # so check "runmode" to make sure that it's only used in backtesting/hyperopt
             if self.dp and self.dp.runmode.value in ('backtest', 'hyperopt'):
-              relative_sl = self.custom_info[pair].loc[current_time]['atr]
+              relative_sl = self.custom_info[pair].loc[current_time]['atr']
             # in live / dry-run, it'll be really the current time
             else:
               # but we can just use the last entry from an already analyzed dataframe instead

docs/strategy-customization.md

@@ -587,6 +587,43 @@ All columns of the informative dataframe will be available on the returning data
 
 ***
 
+### *stoploss_from_open()*
+
+Stoploss values returned from `custom_stoploss` must specify a percentage relative to `current_rate`, but sometimes you may want to specify a stoploss relative to the open price instead. `stoploss_from_open()` is a helper function to calculate a stoploss value that can be returned from `custom_stoploss` which will be equivalent to the desired percentage above the open price.
+
+??? Example "Returning a stoploss relative to the open price from the custom stoploss function"
+
+    Say the open price was $100, and `current_price` is $121 (`current_profit` will be `0.21`).  
+
+    If we want a stop price at 7% above the open price we can call `stoploss_from_open(0.07, current_profit)` which will return `0.1157024793`.  11.57% below $121 is $107, which is the same as 7% above $100.
+
+
+    ``` python
+
+    from datetime import datetime
+    from freqtrade.persistence import Trade
+    from freqtrade.strategy import IStrategy, stoploss_from_open
+
+    class AwesomeStrategy(IStrategy):
+
+        # ... populate_* methods
+
+        use_custom_stoploss = True
+
+        def custom_stoploss(self, pair: str, trade: 'Trade', current_time: datetime,
+                            current_rate: float, current_profit: float, **kwargs) -> float:
+
+            # once the profit has risin above 10%, keep the stoploss at 7% above the open price
+            if current_profit > 0.10:
+                return stoploss_from_open(0.07, current_profit)
+
+            return 1
+
+    ```
+
+    Full examples can be found in the [Custom stoploss](strategy-advanced.md#custom-stoploss) section of the Documentation.
+
+
 ## Additional data (Wallets)
 
 The strategy provides access to the `Wallets` object. This contains the current balances on the exchange.

freqtrade/strategy/__init__.py

@@ -2,4 +2,4 @@
 from freqtrade.exchange import (timeframe_to_minutes, timeframe_to_msecs, timeframe_to_next_date,
                                 timeframe_to_prev_date, timeframe_to_seconds)
 from freqtrade.strategy.interface import IStrategy
-from freqtrade.strategy.strategy_helper import merge_informative_pair
+from freqtrade.strategy.strategy_helper import merge_informative_pair, stoploss_from_open

freqtrade/strategy/strategy_helper.py

@@ -56,3 +56,30 @@ def merge_informative_pair(dataframe: pd.DataFrame, informative: pd.DataFrame,
         dataframe = dataframe.ffill()
 
     return dataframe
+
+
+def stoploss_from_open(open_relative_stop: float, current_profit: float) -> float:
+    """
+
+    Given the current profit, and a desired stop loss value relative to the open price,
+    return a stop loss value that is relative to the current price, and which can be
+    returned from `custom_stoploss`.
+
+    The requested stop can be positive for a stop above the open price, or negative for
+    a stop below the open price. The return value is always >= 0.
+
+    Returns 0 if the resulting stop price would be above the current price.
+
+    :param open_relative_stop: Desired stop loss percentage relative to open price
+    :param current_profit: The current profit percentage
+    :return: Positive stop loss value relative to current price
+    """
+
+    # formula is undefined for current_profit -1, return maximum value
+    if current_profit == -1:
+        return 1
+
+    stoploss = 1-((1+open_relative_stop)/(1+current_profit))
+
+    # negative stoploss values indicate the requested stop price is higher than the current price
+    return max(stoploss, 0.0)

tests/strategy/test_strategy_helpers.py

@@ -1,8 +1,10 @@
+from math import isclose
+
 import numpy as np
 import pandas as pd
 import pytest
 
-from freqtrade.strategy import merge_informative_pair, timeframe_to_minutes
+from freqtrade.strategy import merge_informative_pair, stoploss_from_open, timeframe_to_minutes
 
 
 def generate_test_data(timeframe: str, size: int):
@@ -95,3 +97,38 @@ def test_merge_informative_pair_lower():
 
     with pytest.raises(ValueError, match=r"Tried to merge a faster timeframe .*"):
         merge_informative_pair(data, informative, '1h', '15m', ffill=True)
+
+
+def test_stoploss_from_open():
+    open_price_ranges = [
+        [0.01, 1.00, 30],
+        [1, 100, 30],
+        [100, 10000, 30],
+    ]
+    current_profit_range = [-0.99, 2, 30]
+    desired_stop_range = [-0.50, 0.50, 30]
+
+    for open_range in open_price_ranges:
+        for open_price in np.linspace(*open_range):
+            for desired_stop in np.linspace(*desired_stop_range):
+
+                # -1 is not a valid current_profit, should return 1
+                assert stoploss_from_open(desired_stop, -1) == 1
+
+                for current_profit in np.linspace(*current_profit_range):
+                    current_price = open_price * (1 + current_profit)
+                    expected_stop_price = open_price * (1 + desired_stop)
+
+                    stoploss = stoploss_from_open(desired_stop, current_profit)
+
+                    assert stoploss >= 0
+                    assert stoploss <= 1
+
+                    stop_price = current_price * (1 - stoploss)
+
+                    # there is no correct answer if the expected stop price is above
+                    # the current price
+                    if expected_stop_price > current_price:
+                        assert stoploss == 0
+                    else:
+                        assert isclose(stop_price, expected_stop_price, rel_tol=0.00001)