Skip to content

Commit ff79a03

Browse files
kMutagenekMutagene
committed
update docs
1 parent 50d608e commit ff79a03

5 files changed

Lines changed: 126 additions & 24 deletions

File tree

‎Plotly.NET.sln‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11

22
Microsoft Visual Studio Solution File, Format Version 12.00
3-
# Visual Studio Version 17
4-
VisualStudioVersion = 17.0.31903.59
3+
# Visual Studio Version 18
4+
VisualStudioVersion = 18.5.11709.299 stable
55
MinimumVisualStudioVersion = 10.0.40219.1
66
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "project", "project", "{BF60BC93-E09B-4E5F-9D85-95A519479D54}"
77
ProjectSection(SolutionItems) = preProject
88
.editorconfig = .editorconfig
9+
AGENTS.md = AGENTS.md
910
CITATION.cff = CITATION.cff
1011
.config\dotnet-tools.json = .config\dotnet-tools.json
1112
LICENSE = LICENSE
@@ -135,9 +136,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "04_distribution-charts", "0
135136
docs\distribution-charts\histograms.fsx = docs\distribution-charts\histograms.fsx
136137
docs\distribution-charts\pareto-chart.fsx = docs\distribution-charts\pareto-chart.fsx
137138
docs\distribution-charts\point-density.fsx = docs\distribution-charts\point-density.fsx
139+
docs\distribution-charts\residual.fsx = docs\distribution-charts\residual.fsx
138140
docs\distribution-charts\splom.fsx = docs\distribution-charts\splom.fsx
139141
docs\distribution-charts\violin-plots.fsx = docs\distribution-charts\violin-plots.fsx
140-
docs\distribution-charts\residual.fsx = docs\distribution-charts\residual.fsx
141142
EndProjectSection
142143
EndProject
143144
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "01_chart-layout", "01_chart-layout", "{C7D0EF67-9A18-49DD-AC79-944E384BD8D0}"
@@ -169,6 +170,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "00_general", "00_general",
169170
docs\general\chart-config.fsx = docs\general\chart-config.fsx
170171
docs\general\defaults.fsx = docs\general\defaults.fsx
171172
docs\general\display-options.fsx = docs\general\display-options.fsx
173+
docs\general\encoded-arrays.fsx = docs\general\encoded-arrays.fsx
172174
docs\general\image-export.fsx = docs\general\image-export.fsx
173175
docs\general\multi-arguments.fsx = docs\general\multi-arguments.fsx
174176
docs\general\styling-markers.fsx = docs\general\styling-markers.fsx

‎docs/_head.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,6 @@
2020
<meta name="twitter:image" content="{{root}}img/logo_meta_tags.png">
2121

2222
<link rel="shortcut icon" type="image/x-icon" href="{{root}}/img/favicon.ico">
23-
<script src="https://cdn.plot.ly/plotly-2.27.1.min.js"></script>
23+
<script src="https://cdn.plot.ly/plotly-2.28.0.min.js"></script>
2424
<script>MathJax = { tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] } };</script>
2525
<script src="https://cdn.jsdelivr.net/npm/[email protected]/es5/tex-svg.js"></script>

‎docs/_template.ipynb‎

Whitespace-only changes.

‎docs/general/encoded-arrays.fsx‎

Lines changed: 115 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ Plotly.NET.Defaults.DefaultDisplayOptions <-
3939
- [Using encoded arrays with Scatter](#Using-encoded-arrays-with-Scatter)
4040
- [Using encoded arrays with Bar and Column charts](#Using-encoded-arrays-with-Bar-and-Column-charts)
4141
- [Using encoded arrays with Heatmap](#Using-encoded-arrays-with-Heatmap)
42+
- [Using encoded arrays with 3D charts](#Using-encoded-arrays-with-3D-charts)
43+
- [Using encoded arrays with statistical charts](#Using-encoded-arrays-with-statistical-charts)
44+
- [Using encoded arrays for error bars and trace-level styling](#Using-encoded-arrays-for-error-bars-and-trace-level-styling)
4245
4346
## What are encoded typed arrays?
4447
@@ -119,8 +122,7 @@ let barEncoded =
119122
Chart.Bar(
120123
valuesEncoded = EncodedTypedArray.ofFloat64Array [| 5.0; 3.0; 7.0; 2.0 |],
121124
KeysEncoded = EncodedTypedArray.ofInt32Array [| 0; 1; 2; 3 |],
122-
Name = "encoded bar",
123-
UseDefaults = false
125+
Name = "encoded bar"
124126
)
125127

126128
(*** condition: ipynb ***)
@@ -137,12 +139,13 @@ The same pattern applies to `Chart.Column`, `Chart.StackedBar`, and `Chart.Stack
137139
138140
## Using encoded arrays with Heatmap
139141
140-
For heatmaps, the z matrix is required and encoded; x and y axes are optional and encoded:
142+
For heatmaps, the z matrix is required and encoded; x and y axes are optional and encoded.
143+
When `zEncoded` is given as a flat encoded array, `shape` must also be set so plotly.js can reconstruct the matrix:
141144
*)
142145

143146
let heatmapEncoded =
144147
Chart.Heatmap(
145-
zEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0; 7.0; 8.0; 9.0 |],
148+
zEncoded = EncodedTypedArray.ofFloat64Array([| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0; 7.0; 8.0; 9.0 |], shape = [ 3; 3 ]),
146149
Name = "encoded heatmap",
147150
UseDefaults = false
148151
)
@@ -155,18 +158,121 @@ heatmapEncoded
155158
(***hide***)
156159
heatmapEncoded |> GenericChart.toChartHTML
157160
(***include-it-raw***)
158-
159161
(**
160162
Note that for heatmaps the z data is passed as a flat 1D encoded array. plotly.js uses the `shape` field
161-
(rows × columns) to interpret the layout. If you need to specify the shape, build the `EncodedTypedArray`
162-
manually:
163+
(rows × columns) to interpret the layout, so `shape` must be specified:
163164
164-
```fsharp
165+
```
165166
// Explicit 3x3 shape
166167
let z3x3 =
167-
{ EncodedTypedArray.ofFloat64Array [| 1.0..9.0 |] with Shape = Some "3,3" }
168+
EncodedTypedArray.ofFloat64Array([| 1.0 .. 9.0 |], shape = [ 3; 3 ])
168169
```
169170
171+
The same `shape` requirement applies to other matrix-style traces such as `Chart.Surface`, `Chart.Contour`,
172+
`Chart.Histogram2D`, and `Chart.Histogram2DContour`.
173+
174+
## Using encoded arrays with 3D charts
175+
176+
Encoded typed arrays work the same way on 3D traces. For example, `Chart.Scatter3D` accepts encoded x, y, and z coordinates:
177+
*)
178+
179+
let scatter3DEncoded =
180+
Chart.Scatter3D(
181+
xEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0 |],
182+
yEncoded = EncodedTypedArray.ofFloat64Array [| 4.0; 5.0; 6.0 |],
183+
zEncoded = EncodedTypedArray.ofFloat64Array [| 7.0; 8.0; 9.0 |],
184+
mode = StyleParam.Mode.Markers,
185+
Name = "encoded scatter3d",
186+
UseDefaults = false
187+
)
188+
189+
(*** condition: ipynb ***)
190+
#if IPYNB
191+
scatter3DEncoded
192+
#endif // IPYNB
193+
194+
(***hide***)
195+
scatter3DEncoded |> GenericChart.toChartHTML
196+
(***include-it-raw***)
197+
198+
(**
199+
For matrix-based 3D traces such as `Chart.Surface` and `Chart.Volume`, encoded arrays are also supported,
200+
and `shape` must be set wherever plotly.js needs to reconstruct multi-dimensional data from a flat payload.
201+
202+
## Using encoded arrays with statistical charts
203+
204+
Distribution and statistical charts support encoded sample arrays as well. Here is a histogram example:
205+
*)
206+
207+
let histogramEncoded =
208+
Chart.Histogram(
209+
dataEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 2.0; 3.0; 3.0; 3.0; 4.0 |],
210+
orientation = StyleParam.Orientation.Vertical,
211+
Name = "encoded histogram",
212+
UseDefaults = false
213+
)
214+
215+
(*** condition: ipynb ***)
216+
#if IPYNB
217+
histogramEncoded
218+
#endif // IPYNB
219+
220+
(***hide***)
221+
histogramEncoded |> GenericChart.toChartHTML
222+
(***include-it-raw***)
223+
224+
(**
225+
The same pattern works for `Chart.BoxPlot`, `Chart.Violin`, and finance-style traces such as
226+
`Chart.OHLC` and `Chart.Candlestick`.
227+
228+
## Using encoded arrays for error bars and trace-level styling
229+
230+
Some features are available through trace-level styling rather than only through chart-root overloads.
231+
This is especially useful when you want encoded error bars, encoded metadata arrays, or other advanced options:
232+
*)
233+
234+
open Plotly.NET.TraceObjects
235+
236+
let scatterWithEncodedErrorBars =
237+
let xErrorEncoded = EncodedTypedArray.ofFloat64Array [| 0.1; 0.2; 0.3 |]
238+
let yErrorEncoded = EncodedTypedArray.ofFloat64Array [| 0.4; 0.5; 0.6 |]
239+
let yErrorMinusEncoded = EncodedTypedArray.ofFloat64Array [| 0.3; 0.2; 0.1 |]
240+
241+
Trace2D.initScatter(
242+
Trace2DStyle.Scatter(
243+
Name = "encoded scatter + error bars",
244+
Mode = StyleParam.Mode.Lines_Markers,
245+
XEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0 |],
246+
YEncoded = EncodedTypedArray.ofFloat64Array [| 4.0; 5.0; 6.0 |],
247+
XError =
248+
Error.init(
249+
Type = StyleParam.ErrorType.Data,
250+
ArrayEncoded = xErrorEncoded
251+
),
252+
YError =
253+
Error.init(
254+
Type = StyleParam.ErrorType.Data,
255+
ArrayEncoded = yErrorEncoded,
256+
ArrayminusEncoded = yErrorMinusEncoded
257+
)
258+
)
259+
)
260+
|> GenericChart.ofTraceObject true
261+
|> Chart.withDisplayOptionsStyle(PlotlyJSReference = PlotlyJSReference.NoReference)
262+
263+
(*** condition: ipynb ***)
264+
#if IPYNB
265+
scatterWithEncodedErrorBars
266+
#endif // IPYNB
267+
268+
(***hide***)
269+
scatterWithEncodedErrorBars |> GenericChart.toChartHTML
270+
(***include-it-raw***)
271+
272+
(**
273+
The trace-style modules (`Trace2DStyle`, `Trace3DStyle`, `TraceDomainStyle`, and others) also accept encoded arrays
274+
for many metadata fields such as ids, custom data, selected points, text, dimensions, and trace-specific attributes.
275+
170276
For more advanced usage including encoded arrays on 3D, domain, and map traces, see the trace-level
171277
style modules (`Trace2DStyle`, `Trace3DStyle`, `TraceDomainStyle`, etc.) which accept `*Encoded` optional parameters
172278
for most data-array fields.

‎tests/ConsoleApps/FSharpConsole/Program.fs‎

Lines changed: 5 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,10 @@ open Plotly.NET
33
[<EntryPoint>]
44
let main _ =
55

6-
let chartPointDensityEncodedHelpers =
7-
Chart.PointDensity(
8-
xEncoded = EncodedTypedArray.ofFloat64Array [| 0.0; 1.0; 2.0; 3.0; 4.0 |],
9-
yEncoded = EncodedTypedArray.ofFloat64Array [| 0.0; 1.0; 0.5; 2.0; 1.5 |],
10-
ContoursColoring = StyleParam.ContourColoring.Fill,
11-
Name = "encoded point density helper",
12-
UseDefaults = true
13-
)
14-
|> Chart.withTitle "PointDensity: encoded x/y at chart helper layer"
15-
16-
chartPointDensityEncodedHelpers |> Chart.show
6+
Chart.Heatmap(
7+
zEncoded = EncodedTypedArray.ofFloat64Array([| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0; 7.0; 8.0; 9.0 |], shape = [ 3; 3 ]),
8+
Name = "encoded heatmap",
9+
UseDefaults = false
10+
)|> Chart.show
1711

1812
0

0 commit comments

Comments
 (0)