Skip to content

Commit f78f599

Browse files
kMutagenekMutagene
committed
add docs for legends
1 parent 27acde4 commit f78f599

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎docs/chart-layout/legends.fsx

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
(**
2+
---
3+
title: Legends
4+
category: Chart Layout
5+
categoryindex: 2
6+
index: 9
7+
---
8+
*)
9+
10+
(*** hide ***)
11+
12+
(*** condition: prepare ***)
13+
#r "nuget: Newtonsoft.JSON, 13.0.1"
14+
#r "nuget: DynamicObj, 2.0.0"
15+
#r "nuget: Giraffe.ViewEngine.StrongName, 2.0.0-alpha1"
16+
#r "../../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll"
17+
18+
Plotly.NET.Defaults.DefaultDisplayOptions <-
19+
Plotly.NET.DisplayOptions.init (PlotlyJSReference = Plotly.NET.PlotlyJSReference.NoReference)
20+
21+
(*** condition: ipynb ***)
22+
#if IPYNB
23+
#r "nuget: Plotly.NET, {{fsdocs-package-version}}"
24+
#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}"
25+
#endif // IPYNB
26+
27+
(**
28+
# Legends
29+
30+
[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/plotly.net/gh-pages?urlpath=/tree/home/jovyan/{{fsdocs-source-basename}}.ipynb)&emsp;
31+
[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb)
32+
33+
*Summary:* This example shows how to create Legends and add them to the Charts in F#.
34+
35+
Let's first create some data for the purpose of creating example charts:
36+
37+
*)
38+
39+
open Plotly.NET
40+
41+
let x = [ 1.; 2.; 3.; 4.; 5.; 6.; 7.; 8.; 9.; 10. ]
42+
let y = [ 2.; 1.5; 5.; 1.5; 3.; 2.5; 2.5; 1.5; 3.5; 1. ]
43+
44+
// note that legends are not shown on charts with only one trace,
45+
// which is why we need to set the trace to visible manually on this chart
46+
let simple_chart = Chart.Point(x, y, ShowLegend = true, Name = "test_chart")
47+
48+
(**
49+
## Creating a legend
50+
51+
Legends are `LayoutObjects` that can be added to a chart's `Layout`. The `LayoutLegend.init` function is used to create a legend object, which can then be added to a chart using the `Chart.withLegend` function:
52+
*)
53+
open Plotly.NET.LayoutObjects
54+
55+
let my_legend =
56+
Legend.init (
57+
Title = Title.init("my first legend!"),
58+
BorderColor = Color.fromString "black",
59+
BorderWidth = 1
60+
)
61+
62+
let first_legend_chart =
63+
simple_chart
64+
|> Chart.withLegend my_legend
65+
66+
(*** condition: ipynb ***)
67+
#if IPYNB
68+
first_legend_chart
69+
#endif // IPYNB
70+
71+
(***hide***)
72+
first_legend_chart |> GenericChart.toChartHTML
73+
(***include-it-raw***)
74+
75+
(**
76+
## Styling existing legends
77+
78+
The `Chart.withLegendStyle` function can be used to update the style of an existing legend.
79+
The following code will move the existing legend to the center bottom of the chart:
80+
*)
81+
82+
let styled_legend_chart =
83+
first_legend_chart
84+
|> Chart.withLegendStyle(
85+
Orientation = StyleParam.Orientation.Horizontal,
86+
X = 0.5,
87+
XAnchor = StyleParam.XAnchorPosition.Center
88+
)
89+
90+
(*** condition: ipynb ***)
91+
#if IPYNB
92+
styled_legend_chart
93+
#endif // IPYNB
94+
95+
(***hide***)
96+
styled_legend_chart |> GenericChart.toChartHTML
97+
(***include-it-raw***)
98+
99+
(**
100+
## Grouping legend items
101+
102+
You can group multiple traces as a single legend item by setting the `LegendGroup` property of the individual traces to the same value:
103+
*)
104+
105+
let grouped_legend_chart =
106+
[
107+
Chart.Point(x, y)
108+
|> GenericChart.mapTrace (
109+
Trace2DStyle.Scatter(
110+
LegendGroup = "Group A",
111+
LegendGroupTitle = (Title.init (Text = "Group A"))
112+
)
113+
)
114+
Chart.Point(y, x)
115+
|> GenericChart.mapTrace (
116+
Trace2DStyle.Scatter(
117+
LegendGroup = "Group A"
118+
)
119+
)
120+
Chart.Point(y, y)
121+
|> GenericChart.mapTrace (
122+
Trace2DStyle.Scatter(
123+
LegendGroup = "Group B",
124+
LegendGroupTitle = (Title.init (Text = "Group B"))
125+
)
126+
)
127+
]
128+
|> Chart.combine
129+
130+
(*** condition: ipynb ***)
131+
#if IPYNB
132+
grouped_legend_chart
133+
#endif // IPYNB
134+
135+
(***hide***)
136+
grouped_legend_chart |> GenericChart.toChartHTML
137+
(***include-it-raw***)
138+
139+
(**
140+
## Multiple legends
141+
142+
Starting with Plotly.NET 5.0.0, the multiple legends feature from plotl.js v2.22+ is supported.
143+
144+
Similarily to how multiple axes are handled, multiple legends are added by providing an additional `Id` argument when using the `Chart.withLegend` function:
145+
146+
To select which legend a trace should belong to, use `Chart.withLegendAnchor` with the corresponding `id` argument.
147+
*)
148+
149+
let multi_legend_chart =
150+
[
151+
Chart.Point(x, y)
152+
|> Chart.withLegendAnchor 1
153+
Chart.Point(y, x)
154+
|> Chart.withLegendAnchor 2
155+
]
156+
|> Chart.combine
157+
|> Chart.withLegend(
158+
Legend.init(
159+
BorderColor = Color.fromKeyword Blue,
160+
BorderWidth = 2,
161+
Title = Title.init(
162+
Text = "Legend 1"
163+
)
164+
)
165+
)
166+
|> Chart.withLegend(
167+
Legend.init(
168+
X = 0.75,
169+
Y = 0.75,
170+
BorderColor = Color.fromKeyword Red,
171+
BorderWidth = 2,
172+
Title = Title.init(
173+
Text = "Legend 2"
174+
)
175+
),
176+
Id = 2
177+
)
178+
179+
(*** condition: ipynb ***)
180+
#if IPYNB
181+
multi_legend_chart
182+
#endif // IPYNB
183+
184+
(***hide***)
185+
multi_legend_chart |> GenericChart.toChartHTML
186+
(***include-it-raw***)

0 commit comments

Comments
 (0)