Merge pull request freqtrade#12170 from mrpabloyeah/some-improvements-to-backtest-summary-metrics

xmatthias · web-flow · commit 2fd703fcc50c · 2025-08-30T15:40:35.000+02:00
Some improvements to backtest summary metrics
diff --git a/docs/backtesting.md b/docs/backtesting.md
diff --git a/docs/developer.md b/docs/developer.md
@@ -408,6 +408,22 @@ jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace freqtrade/tem
 jupyter nbconvert --ClearOutputPreprocessor.enabled=True --to markdown freqtrade/templates/strategy_analysis_example.ipynb --stdout > docs/strategy_analysis_example.md
 ```
 
+## Backtest documentation results
+
+To generate backtest outputs, please use the following commands:
+
+``` bash
+# Assume a dedicated user directory for this output
+freqtrade create-userdir --userdir user_data_bttest/
+# set can_short = True
+sed -i "s/can_short: bool = False/can_short: bool = True/" user_data_bttest/strategies/sample_strategy.py
+
+freqtrade download-data --timerange 20250625-20250801 --config tests/testdata/config.tests.usdt.json --userdir user_data_bttest/ -t 5m
+
+freqtrade backtesting --config tests/testdata/config.tests.usdt.json -s SampleStrategy --userdir user_data_bttest/ --cache none --timerange 20250701-20250801
+```
+
+
 ## Continuous integration
 
 This documents some decisions taken for the CI Pipeline.
diff --git a/freqtrade/optimize/optimize_reports/bt_output.py b/freqtrade/optimize/optimize_reports/bt_output.py
@@ -194,6 +194,7 @@ def text_table_strategy(strategy_results, stake_currency: str, title: str):
 
 
 def text_table_add_metrics(strat_results: dict) -> None:
+    stake = strat_results["stake_currency"]
     if len(strat_results["trades"]) > 0:
         best_trade = max(strat_results["trades"], key=lambda x: x["profit_ratio"])
         worst_trade = min(strat_results["trades"], key=lambda x: x["profit_ratio"])
@@ -202,23 +203,19 @@ def text_table_add_metrics(strat_results: dict) -> None:
             [
                 ("", ""),  # Empty line to improve readability
                 (
-                    "Long / Short",
+                    "Long / Short trades",
                     f"{strat_results.get('trade_count_long', 'total_trades')} / "
                     f"{strat_results.get('trade_count_short', 0)}",
                 ),
-                ("Total profit Long %", f"{strat_results['profit_total_long']:.2%}"),
-                ("Total profit Short %", f"{strat_results['profit_total_short']:.2%}"),
                 (
-                    "Absolute profit Long",
-                    fmt_coin(
-                        strat_results["profit_total_long_abs"], strat_results["stake_currency"]
-                    ),
+                    "Long / Short profit %",
+                    f"{strat_results['profit_total_long']:.2%} / "
+                    f"{strat_results['profit_total_short']:.2%}",
                 ),
                 (
-                    "Absolute profit Short",
-                    fmt_coin(
-                        strat_results["profit_total_short_abs"], strat_results["stake_currency"]
-                    ),
+                    f"Long / Short profit {stake}",
+                    f"{strat_results['profit_total_long_abs']:.{decimals_per_coin(stake)}f} / "
+                    f"{strat_results['profit_total_short_abs']:.{decimals_per_coin(stake)}f}",
                 ),
             ]
             if strat_results.get("trade_count_short", 0) > 0
@@ -231,27 +228,34 @@ def text_table_add_metrics(strat_results: dict) -> None:
             drawdown_metrics.append(
                 ("Max % of account underwater", f"{strat_results['max_relative_drawdown']:.2%}")
             )
+        drawdown_account = (
+            strat_results["max_drawdown_account"]
+            if "max_drawdown_account" in strat_results
+            else strat_results["max_drawdown"]
+        )
         drawdown_metrics.extend(
             [
                 (
-                    ("Absolute Drawdown (Account)", f"{strat_results['max_drawdown_account']:.2%}")
-                    if "max_drawdown_account" in strat_results
-                    else ("Drawdown", f"{strat_results['max_drawdown']:.2%}")
+                    "Absolute drawdown",
+                    f"{fmt_coin(strat_results['max_drawdown_abs'], stake)} "
+                    f"({drawdown_account:.2%})",
                 ),
                 (
-                    "Absolute Drawdown",
-                    fmt_coin(strat_results["max_drawdown_abs"], strat_results["stake_currency"]),
+                    "Drawdown duration",
+                    strat_results["drawdown_duration"]
+                    if "drawdown_duration" in strat_results
+                    else "N/A",
                 ),
                 (
-                    "Drawdown high",
-                    fmt_coin(strat_results["max_drawdown_high"], strat_results["stake_currency"]),
+                    "Profit at drawdown start",
+                    fmt_coin(strat_results["max_drawdown_high"], stake),
                 ),
                 (
-                    "Drawdown low",
-                    fmt_coin(strat_results["max_drawdown_low"], strat_results["stake_currency"]),
+                    "Profit at drawdown end",
+                    fmt_coin(strat_results["max_drawdown_low"], stake),
                 ),
-                ("Drawdown Start", strat_results["drawdown_start"]),
-                ("Drawdown End", strat_results["drawdown_end"]),
+                ("Drawdown start", strat_results["drawdown_start"]),
+                ("Drawdown end", strat_results["drawdown_end"]),
             ]
         )
 
@@ -299,15 +303,15 @@ def text_table_add_metrics(strat_results: dict) -> None:
             ),
             (
                 "Starting balance",
-                fmt_coin(strat_results["starting_balance"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["starting_balance"], stake),
             ),
             (
                 "Final balance",
-                fmt_coin(strat_results["final_balance"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["final_balance"], stake),
             ),
             (
                 "Absolute profit ",
-                fmt_coin(strat_results["profit_total_abs"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["profit_total_abs"], stake),
             ),
             ("Total profit %", f"{strat_results['profit_total']:.2%}"),
             ("CAGR %", f"{strat_results['cagr']:.2%}" if "cagr" in strat_results else "N/A"),
@@ -335,16 +339,16 @@ def text_table_add_metrics(strat_results: dict) -> None:
                 "Avg. daily profit",
                 fmt_coin(
                     (strat_results["profit_total_abs"] / strat_results["backtest_days"]),
-                    strat_results["stake_currency"],
+                    stake,
                 ),
             ),
             (
                 "Avg. stake amount",
-                fmt_coin(strat_results["avg_stake_amount"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["avg_stake_amount"], stake),
             ),
             (
                 "Total trade volume",
-                fmt_coin(strat_results["total_volume"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["total_volume"], stake),
             ),
             *short_metrics,
             ("", ""),  # Empty line to improve readability
@@ -362,11 +366,11 @@ def text_table_add_metrics(strat_results: dict) -> None:
             ("Worst trade", f"{worst_trade['pair']} {worst_trade['profit_ratio']:.2%}"),
             (
                 "Best day",
-                fmt_coin(strat_results["backtest_best_day_abs"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["backtest_best_day_abs"], stake),
             ),
             (
                 "Worst day",
-                fmt_coin(strat_results["backtest_worst_day_abs"], strat_results["stake_currency"]),
+                fmt_coin(strat_results["backtest_worst_day_abs"], stake),
             ),
             (
                 "Days win/draw/lose",
@@ -404,17 +408,17 @@ def text_table_add_metrics(strat_results: dict) -> None:
             ),
             *entry_adjustment_metrics,
             ("", ""),  # Empty line to improve readability
-            ("Min balance", fmt_coin(strat_results["csum_min"], strat_results["stake_currency"])),
-            ("Max balance", fmt_coin(strat_results["csum_max"], strat_results["stake_currency"])),
+            ("Min balance", fmt_coin(strat_results["csum_min"], stake)),
+            ("Max balance", fmt_coin(strat_results["csum_max"], stake)),
             *drawdown_metrics,
             ("Market change", f"{strat_results['market_change']:.2%}"),
         ]
         print_rich_table(metrics, ["Metric", "Value"], summary="SUMMARY METRICS", justify="left")
 
     else:
-        start_balance = fmt_coin(strat_results["starting_balance"], strat_results["stake_currency"])
+        start_balance = fmt_coin(strat_results["starting_balance"], stake)
         stake_amount = (
-            fmt_coin(strat_results["stake_amount"], strat_results["stake_currency"])
+            fmt_coin(strat_results["stake_amount"], stake)
             if strat_results["stake_amount"] != UNLIMITED_STAKE_AMOUNT
             else "unlimited"
         )
diff --git a/freqtrade/optimize/optimize_reports/optimize_reports.py b/freqtrade/optimize/optimize_reports/optimize_reports.py
@@ -627,6 +627,7 @@ def generate_strategy_stats(
         underwater = calculate_max_drawdown(
             results, value_col="profit_abs", starting_balance=start_balance, relative=True
         )
+        drawdown_duration = drawdown.low_date - drawdown.high_date
 
         strat_stats.update(
             {
@@ -637,6 +638,8 @@ def generate_strategy_stats(
                 "drawdown_start_ts": drawdown.high_date.timestamp() * 1000,
                 "drawdown_end": drawdown.low_date.strftime(DATETIME_PRINT_FORMAT),
                 "drawdown_end_ts": drawdown.low_date.timestamp() * 1000,
+                "drawdown_duration": drawdown_duration,
+                "drawdown_duration_s": drawdown_duration.total_seconds(),
                 "max_drawdown_low": drawdown.low_value,
                 "max_drawdown_high": drawdown.high_value,
             }
diff --git a/tests/testdata/config.tests.json b/tests/testdata/config.tests.json
@@ -1,4 +1,5 @@
 {
+    "$schema": "https://schema.freqtrade.io/schema.json",
     "max_open_trades": 3,
     "stake_currency": "BTC",
     "stake_amount": 0.05,
diff --git a/tests/testdata/config.tests.usdt.json b/tests/testdata/config.tests.usdt.json
@@ -0,0 +1,77 @@
+{
+    "$schema": "https://schema.freqtrade.io/schema.json",
+    "max_open_trades": 3,
+    "stake_currency": "USDT",
+    "stake_amount": "unlimited",
+    "tradable_balance_ratio": 0.99,
+    "fiat_display_currency": "USD",
+    "trading_mode": "futures",
+    "margin_mode": "isolated",
+    "timeframe": "5m",
+    "dry_run": true,
+    "cancel_open_orders_on_exit": false,
+    "unfilledtimeout": {
+        "entry": 5,
+        "exit": 5,
+        "exit_timeout_count": 0,
+        "unit": "minutes"
+    },
+    "entry_pricing": {
+        "price_side": "same",
+        "use_order_book": true,
+        "order_book_top": 1,
+        "price_last_balance": 0.0,
+        "check_depth_of_market": {
+            "enabled": false,
+            "bids_to_ask_delta": 1
+        }
+    },
+    "exit_pricing":{
+        "price_side": "same",
+        "use_order_book": true,
+        "order_book_top": 1
+    },
+    "exchange": {
+        "name": "bybit",
+        "key": "your_exchange_key",
+        "secret": "your_exchange_secret",
+        "ccxt_config": {},
+        "ccxt_async_config": {},
+        "pair_whitelist": [
+            "BTC/USDT:USDT",
+            "ETH/USDT:USDT",
+            "LTC/USDT:USDT",
+            "ETC/USDT:USDT",
+            "XLM/USDT:USDT",
+            "XRP/USDT:USDT",
+            "ADA/USDT:USDT",
+            "DOT/USDT:USDT"
+        ],
+        "pair_blacklist": [
+        ]
+    },
+    "pairlists": [
+        {"method": "StaticPairList"}
+    ],
+    "telegram": {
+        "enabled": false,
+        "token": "your_telegram_token",
+        "chat_id": "your_telegram_chat_id"
+    },
+    "api_server": {
+        "enabled": false,
+        "listen_ip_address": "127.0.0.1",
+        "listen_port": 8080,
+        "verbosity": "error",
+        "jwt_secret_key": "somethingrandom",
+        "CORS_origins": [],
+        "username": "freqtrader",
+        "password": "SuperSecurePassword"
+    },
+    "bot_name": "freqtrade",
+    "initial_state": "running",
+    "force_entry_enable": false,
+    "internals": {
+        "process_throttle_secs": 5
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -627,6 +627,7 @@ def generate_strategy_stats(`
`627`	`627`	`underwater = calculate_max_drawdown(`
`628`	`628`	`results, value_col="profit_abs", starting_balance=start_balance, relative=True`
`629`	`629`	`)`
	`630`	`+ drawdown_duration = drawdown.low_date - drawdown.high_date`
`630`	`631`
`631`	`632`	`strat_stats.update(`
`632`	`633`	`{`
`@@ -637,6 +638,8 @@ def generate_strategy_stats(`
`637`	`638`	`"drawdown_start_ts": drawdown.high_date.timestamp() * 1000,`
`638`	`639`	`"drawdown_end": drawdown.low_date.strftime(DATETIME_PRINT_FORMAT),`
`639`	`640`	`"drawdown_end_ts": drawdown.low_date.timestamp() * 1000,`
	`641`	`+ "drawdown_duration": drawdown_duration,`
	`642`	`+ "drawdown_duration_s": drawdown_duration.total_seconds(),`
`640`	`643`	`"max_drawdown_low": drawdown.low_value,`
`641`	`644`	`"max_drawdown_high": drawdown.high_value,`
`642`	`645`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,5 @@`
`1`	`1`	`{`
	`2`	`+ "$schema": "https://schema.freqtrade.io/schema.json",`
`2`	`3`	`"max_open_trades": 3,`
`3`	`4`	`"stake_currency": "BTC",`
`4`	`5`	`"stake_amount": 0.05,`