Merge pull request #482 from plotly/update-docs-#481

update annotation docu

Author: kMutagene

Diff for: docs/chart-layout/annotations.fsx

@@ -71,3 +71,101 @@ annotations
 (***hide***)
 annotations |> GenericChart.toChartHTML
 (***include-it-raw***)
+
+
+(**
+## Annotations with logged axes
+
+When using log axes, the values for `X` or `Y` given in `Annotation.init` must be transformed as well even if the axis shows the expected value range.
+*)
+
+let y_highrange = [ 2.; 15_000.; 1_600.; 1.5; 3.; 25_000; 25_000.; 15_000; 350; 1. ]
+
+// The default log axis is base 10
+let a_log = Annotation.init (X = 5., Y = log10 2_500., Text = "I'm at position<br>x=5, y=2500")
+
+let annotations_log =
+    Chart.Line(x = x, y = y_highrange, Name = "log_line") 
+    |> Chart.withYAxis(LinearAxis.init(AxisType = StyleParam.AxisType.Log))
+    |> Chart.withAnnotation a_log
+
+(*** condition: ipynb ***)
+#if IPYNB
+annotations_log
+#endif // IPYNB
+
+(***hide***)
+annotations_log |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+
+
+(**
+## Multicharts
+
+Annotations can also be placed using coordinates proportional to the chart canvas, by setting the `XRef` and `YRef` to `"paper"`. 
+In multi-chart layouts, the reference can be set to the respective x, and y axis-component (e.g. `XRef = x3, YRef = y3` for the third chart within the chart grid).
+*)
+
+// setting no reference, the annotation will be placed at the given x and y values in the first chart
+let a_multichart1 = Annotation.init (X = 8,   Y = 5.0,                                 Text = "no ref defined")
+
+// setting the reference to specific x and y components, the annotation will be placed at the given x and y values in the chart defined by the ref-coordinates
+let a_multichart2 = Annotation.init (X = 7,   Y = 3.5, XRef = "x1",    YRef = "y1",    Text = "ref: x1 and y1")
+let a_multichart3 = Annotation.init (X = 7,   Y = 3.5, XRef = "x2",    YRef = "y2",    Text = "ref: x2 and y2")
+let a_multichart4 = Annotation.init (X = 7,   Y = 3.5, XRef = "x3",    YRef = "y3",    Text = "ref: x3 and y3")
+let a_multichart5 = Annotation.init (X = 7,   Y = 3.5, XRef = "x4",    YRef = "y4",    Text = "ref: x4 and y4")
+
+// setting the x and y reference to "paper", the annotation will be placed proportional to the chart canvas
+let a_multichart6 = Annotation.init (X = 1.1, Y = 1.1, XRef = "paper", YRef = "paper", Text = "ref: paper@1.1")
+let a_multichart7 = Annotation.init (X = 0.5, Y = 0.4, XRef = "paper", YRef = "paper", Text = "ref: paper@0.5")
+
+
+let annotations_multi =
+    [
+        Chart.Line(x = x, y = y, Name = "chart 1") 
+        Chart.Line(x = x, y = y, Name = "chart 2") 
+        Chart.Line(x = x, y = y, Name = "chart 3") 
+        Chart.Line(x = x, y = y, Name = "chart 4") 
+    ]
+    |> Chart.Grid(2, 2)
+    |> Chart.withAnnotations ([a_multichart1; a_multichart2; a_multichart3; a_multichart4; a_multichart5; a_multichart6; a_multichart7])
+
+(*** condition: ipynb ***)
+#if IPYNB
+annotations_multi
+#endif // IPYNB
+
+(***hide***)
+annotations_multi |> GenericChart.toChartHTML
+(***include-it-raw***)
+
+(**
+In multi-chart layouts *with coupled axis*, the reference can be set to the respective coupled x, and y axis-component (e.g. `XRef = x1, YRef = y2` for the leftmost chart in the second row).
+*)
+
+// setting the reference to specific x and y components with coupled axes, the annotation will be placed at the given x and y values in the chart defined by the ref-coordinates
+let a_multichart_coupled_1 = Annotation.init (X = 7,   Y = 3.5, XRef = "x1",    YRef = "y1",    Text = "ref: x1 and y1")
+let a_multichart_coupled_2 = Annotation.init (X = 7,   Y = 3.5, XRef = "x2",    YRef = "y1",    Text = "ref: x2 and y1")
+let a_multichart_coupled_3 = Annotation.init (X = 7,   Y = 3.5, XRef = "x2",    YRef = "y2",    Text = "ref: x2 and y2")
+let a_multichart_coupled_4 = Annotation.init (X = 7,   Y = 3.5, XRef = "x1",    YRef = "y2",    Text = "ref: x1 and y2")
+
+
+let annotations_paper_coupled =
+    [
+        Chart.Line(x = x, y = y, Name = "chart 1") 
+        Chart.Line(x = x, y = y, Name = "chart 2") 
+        Chart.Line(x = x, y = y, Name = "chart 3") 
+        Chart.Line(x = x, y = y, Name = "chart 4") 
+    ]
+    |> Chart.Grid(2, 2, Pattern = StyleParam.LayoutGridPattern.Coupled)
+    |> Chart.withAnnotations ([a_multichart_coupled_1; a_multichart_coupled_2; a_multichart_coupled_3; a_multichart_coupled_4])
+
+(*** condition: ipynb ***)
+#if IPYNB
+annotations_paper_coupled
+#endif // IPYNB
+
+(***hide***)
+annotations_paper_coupled |> GenericChart.toChartHTML
+(***include-it-raw***)