improve doc, update test strats, change function names

freqtrade/strategy/interface.py

@@ -611,40 +611,93 @@ class IStrategy(ABC, HyperStrategyMixin):
         """
         return df
 
-    def freqai_feature_engineering_indicator_periods(self, dataframe: DataFrame,
-                                                     period: int, **kwargs):
+    def feature_engineering_expand_all(self, dataframe: DataFrame,
+                                       period: int, **kwargs):
         """
-        This function will be called for all include_timeframes in each indicator_periods_candles
-        (including corr_pairs).
-        After that, the features will be shifted by the number of candles in the
-        include_shifted_candles.
+        *Only functional with FreqAI enabled strategies*
+        This function will automatically expand the defined features on the config defined
+        `indicator_periods_candles`, `include_timeframes`, `include_shifted_candles`, and
+        `include_corr_pairs`. In other words, a single feature defined in this function
+        will automatically expand to a total of
+        `indicator_periods_candles` * `include_timeframes` * `include_shifted_candles` *
+        `include_corr_pairs` numbers of features added to the model.
+
+        All features must be prepended with `%` to be recognized by FreqAI internals.
+
+        More details on how these config defined parameters accelerate feature engineering
+        in the documentation at:
+
+        https://www.freqtrade.io/en/latest/freqai-parameter-table/#feature-parameters
+
+        https://www.freqtrade.io/en/latest/freqai-feature-engineering/#defining-the-features
+
         :param df: strategy dataframe which will receive the features
         :param period: period of the indicator - usage example:
         dataframe["%-ema-period"] = ta.EMA(dataframe, timeperiod=period)
         """
         return dataframe
 
-    def freqai_feature_engineering_generic(self, dataframe: DataFrame, **kwargs):
+    def feature_engineering_expand_basic(self, dataframe: DataFrame, **kwargs):
         """
-        This optional function will be called for all include_timeframes (including corr_pairs).
-        After that, the features will be shifted by the number of candles in the
-        include_shifted_candles.
+        *Only functional with FreqAI enabled strategies*
+        This function will automatically expand the defined features on the config defined
+        `include_timeframes`, `include_shifted_candles`, and `include_corr_pairs`.
+        In other words, a single feature defined in this function
+        will automatically expand to a total of
+        `include_timeframes` * `include_shifted_candles` * `include_corr_pairs`
+        numbers of features added to the model.
+
+        Features defined here will *not* be automatically duplicated on user defined
+        `indicator_periods_candles`
+
+        All features must be prepended with `%` to be recognized by FreqAI internals.
+
+        More details on how these config defined parameters accelerate feature engineering
+        in the documentation at:
+
+        https://www.freqtrade.io/en/latest/freqai-parameter-table/#feature-parameters
+
+        https://www.freqtrade.io/en/latest/freqai-feature-engineering/#defining-the-features
+
         :param df: strategy dataframe which will receive the features
         dataframe["%-pct-change"] = dataframe["close"].pct_change()
+        dataframe["%-ema-200"] = ta.EMA(dataframe, timeperiod=200)
         """
         return dataframe
 
-    def freqai_feature_engineering_generalized_indicators(self, dataframe: DataFrame, **kwargs):
+    def feature_engineering_standard(self, dataframe: DataFrame, **kwargs):
         """
-        This optional function will be called once with the dataframe of the main timeframe.
+        *Only functional with FreqAI enabled strategies*
+        This optional function will be called once with the dataframe of the base timeframe.
+        This is the final function to be called, which means that the dataframe entering this
+        function will contain all the features and columns created by all other
+        freqai_feature_engineering_* functions.
+
+        This function is a good place to do custom exotic feature extractions (e.g. tsfresh).
+        This function is a good place for any feature that should not be auto-expanded upon
+        (e.g. day of the week).
+
+        All features must be prepended with `%` to be recognized by FreqAI internals.
+
+        More details about feature engineering available:
+
+        https://www.freqtrade.io/en/latest/freqai-feature-engineering
+
         :param df: strategy dataframe which will receive the features
         usage example: dataframe["%-day_of_week"] = (dataframe["date"].dt.dayofweek + 1) / 7
         """
         return dataframe
 
-    def freqai_set_targets(self, dataframe, **kwargs):
+    def set_freqai_targets(self, dataframe, **kwargs):
         """
+        *Only functional with FreqAI enabled strategies*
         Required function to set the targets for the model.
+        All targets must be prepended with `&` to be recognized by the FreqAI internals.
+
+        More details about feature engineering available:
+
+        https://www.freqtrade.io/en/latest/freqai-feature-engineering
+
         :param df: strategy dataframe which will receive the targets
         usage example: dataframe["&-target"] = dataframe["close"].shift(-1) / dataframe["close"]
         """