From 66efc9a469cf5cdba29581b32c7c49ca5d95f4e5 Mon Sep 17 00:00:00 2001
From: Matthias <xmatthias@outlook.com>
Date: Sat, 28 Dec 2024 15:43:45 +0100
Subject: [PATCH] docs: add documentation for plot_annotations

---
 docs/strategy-callbacks.md | 60 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/docs/strategy-callbacks.md b/docs/strategy-callbacks.md
index 14e39a447..0672c9c68 100644
--- a/docs/strategy-callbacks.md
+++ b/docs/strategy-callbacks.md
@@ -1066,3 +1066,63 @@ class AwesomeStrategy(IStrategy):
         return None
 
 ```
+
+## Plot annotations callback
+
+The plot annotations callback is called whenever freqUI requests data to display a chart.
+The strategy can then return a list of `AnnotationType` objects to be displayed on the chart.
+Depending on the content returned - the chart can display horizontal areas, vertical areas, or boxes.
+
+The full object looks like this:
+
+``` json
+{
+    "type": "area", // Type of the annotation, currently only "area" is supported
+    "start": "2024-01-01 15:00:00", // Start date of the area
+    "end": "2024-01-01 16:00:00",  // End date of the area
+    "y_start": 94000.2,  // Price / y axis value
+    "y_end": 98000, // Price / y axis value
+    "color": "",
+    "label": "some label"
+}
+```
+
+The below example will mark the chart with areas for the hours 8 and 15, with a grey color, highlighting the market open and close hours.
+This is obviously a very basic example.
+
+``` python
+# Default imports
+
+class AwesomeStrategy(IStrategy):
+    def plot_annotations(
+        self, pair: str, start_date: datetime, end_date: datetime, dataframe: DataFrame, **kwargs
+    ) -> list[AnnotationType]:
+        """
+        Retrieve area annotations for a chart.
+        Must be returned as array, with label, start, end, y_start, y_end and color.
+        All settings are optional - though it usually makes sense to include either "start and end"
+        or "y_start and y_end" for either horizontal or vertical plots (or all 4 for boxes).
+        :param pair: Pair that's currently analyzed
+        :param start_date: Start date of the chart data being requested
+        :param end_date: End date of the chart data being requested
+        :param dataframe: DataFrame with the analyzed data for the chart
+        :param **kwargs: Ensure to keep this here so updates to this won't break your strategy.
+        :return: List of AnnotationType objects
+        """
+        while start_dt < end_date:
+            start_dt += timedelta(hours=1)
+            if start_dt.hour in (8, 15):
+                mark_areas.append(
+                    {
+                        "type": "area",
+                        "label": "Trade open and close hours",
+                        "start": start_dt,
+                        "end": start_dt + timedelta(hours=1),
+                        # Omitting y_start and y_end will result in a vertical area spanning the whole height of the main Chart
+                        "color": "rgba(133, 133, 133, 0.4)",
+                    }
+                )
+
+        return mark_areas
+
+```