Skip to content

Commit 263d751

Browse files
kMutageneclaude
kMutagene
and
claude
committed
Add documentation for encoded arrays and Sankey node alignment (Commit N)
- Add docs/general/encoded-arrays.fsx: new General doc page covering EncodedTypedArray constructors, dtype table, and examples for Chart.Scatter, Chart.Bar, and Chart.Heatmap encoded overloads - Update docs/categorical-charts/sankey.fsx: add NodeAlign section showing Chart.Sankey with StyleParam.SankeyNodeAlign.Left - Update PlotlyJS_2_28_Parity.md: mark Virtual-WebGL as no surface needed (AdditionalHeadTags covers it), mark Commit N done, update test count to 944 Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
1 parent 1f77536 commit 263d751

3 files changed

Lines changed: 203 additions & 1 deletion

File tree

‎docs/categorical-charts/sankey.fsx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,3 +79,31 @@ sankey1
7979
(***hide***)
8080
sankey1 |> GenericChart.toChartHTML
8181
(***include-it-raw***)
82+
83+
(**
84+
## Node alignment
85+
86+
The `NodeAlign` parameter controls how nodes are aligned horizontally. The available options are
87+
`Left`, `Right`, `Center`, and `Justify` (the default).
88+
89+
Use the `NodeAlign` parameter on `Chart.Sankey` to apply alignment via the convenience overload,
90+
or pass `Align` to `SankeyNodes.init` directly when building nodes manually:
91+
*)
92+
93+
let sankeyAligned =
94+
Chart.Sankey(
95+
nodeLabels = [ "Source A"; "Source B"; "Sink" ],
96+
linkedNodeIds = [ 0, 2; 1, 2 ],
97+
linkValues = [ 8; 4 ],
98+
NodeAlign = StyleParam.SankeyNodeAlign.Left,
99+
UseDefaults = false
100+
)
101+
102+
(*** condition: ipynb ***)
103+
#if IPYNB
104+
sankeyAligned
105+
#endif // IPYNB
106+
107+
(***hide***)
108+
sankeyAligned |> GenericChart.toChartHTML
109+
(***include-it-raw***)

‎docs/general/encoded-arrays.fsx‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
(**
2+
---
3+
title: Encoded typed arrays
4+
category: General
5+
categoryindex: 1
6+
index: 10
7+
---
8+
*)
9+
10+
(*** hide ***)
11+
12+
(*** condition: prepare ***)
13+
#r "nuget: Newtonsoft.JSON, 13.0.3"
14+
#r "nuget: DynamicObj, 7.0.1"
15+
#r "nuget: Giraffe.ViewEngine, 1.4.0"
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+
# Encoded typed arrays
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 page explains how to use `EncodedTypedArray` for efficient data transfer with plotly.js 2.28+.
34+
35+
### Table of contents
36+
37+
- [What are encoded typed arrays?](#What-are-encoded-typed-arrays)
38+
- [Creating EncodedTypedArray values](#Creating-EncodedTypedArray-values)
39+
- [Using encoded arrays with Scatter](#Using-encoded-arrays-with-Scatter)
40+
- [Using encoded arrays with Bar and Column charts](#Using-encoded-arrays-with-Bar-and-Column-charts)
41+
- [Using encoded arrays with Heatmap](#Using-encoded-arrays-with-Heatmap)
42+
43+
## What are encoded typed arrays?
44+
45+
plotly.js 2.28.0 introduced support for passing data arrays as **base64-encoded typed arrays** instead of plain JSON arrays.
46+
This format (`bdata`/`dtype`/`shape`) is significantly more compact and faster to parse for large numeric datasets,
47+
since it avoids the overhead of JSON number serialization.
48+
49+
For example, a float64 array `[1.0, 2.0, 3.0]` transmitted as plain JSON looks like `[1.0,2.0,3.0]`,
50+
while the encoded form is `{"bdata":"AAAAAAAA8D8AAAAAAAAAQA==...","dtype":"f8"}` — smaller and faster to deserialize in the browser.
51+
52+
Plotly.NET exposes this via the `EncodedTypedArray` type.
53+
54+
## Creating EncodedTypedArray values
55+
56+
`EncodedTypedArray` can be constructed from any standard .NET typed array:
57+
*)
58+
59+
open Plotly.NET
60+
61+
// Float64 (double) arrays — most common for continuous data
62+
let xEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0; 4.0; 5.0 |]
63+
let yEncoded = EncodedTypedArray.ofFloat64Array [| 2.0; 4.0; 1.0; 5.0; 3.0 |]
64+
65+
// Int32 arrays — for integer data like indices or counts
66+
let sourceEncoded = EncodedTypedArray.ofInt32Array [| 0; 1; 2 |]
67+
68+
// Float32 arrays — smaller footprint when full precision is not needed
69+
let valuesEncoded = EncodedTypedArray.ofFloat32Array [| 1.0f; 2.5f; 0.8f |]
70+
71+
(**
72+
Supported constructors:
73+
74+
| Constructor | .NET type | plotly.js dtype |
75+
|---|---|---|
76+
| `EncodedTypedArray.ofFloat64Array` | `float[]` | `f8` (64-bit float) |
77+
| `EncodedTypedArray.ofFloat32Array` | `float32[]` | `f4` (32-bit float) |
78+
| `EncodedTypedArray.ofInt32Array` | `int[]` | `i4` (32-bit int) |
79+
| `EncodedTypedArray.ofInt16Array` | `int16[]` | `i2` (16-bit int) |
80+
| `EncodedTypedArray.ofInt8Array` | `sbyte[]` | `i1` (8-bit int) |
81+
| `EncodedTypedArray.ofUInt32Array` | `uint32[]` | `u4` (unsigned 32-bit) |
82+
| `EncodedTypedArray.ofUInt16Array` | `uint16[]` | `u2` (unsigned 16-bit) |
83+
| `EncodedTypedArray.ofUInt8Array` | `byte[]` | `u1` (unsigned 8-bit) |
84+
85+
## Using encoded arrays with Scatter
86+
87+
The encoded convenience overload for `Chart.Scatter` takes `xEncoded` and `yEncoded` as required
88+
positional arguments instead of plain `x`/`y` sequences:
89+
*)
90+
91+
let scatterEncoded =
92+
Chart.Scatter(
93+
xEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0; 4.0; 5.0 |],
94+
yEncoded = EncodedTypedArray.ofFloat64Array [| 2.0; 4.0; 1.0; 5.0; 3.0 |],
95+
mode = StyleParam.Mode.Markers,
96+
Name = "encoded scatter",
97+
UseDefaults = false
98+
)
99+
100+
(*** condition: ipynb ***)
101+
#if IPYNB
102+
scatterEncoded
103+
#endif // IPYNB
104+
105+
(***hide***)
106+
scatterEncoded |> GenericChart.toChartHTML
107+
(***include-it-raw***)
108+
109+
(**
110+
The same encoded overload is available for `Chart.Point`, `Chart.Line`, `Chart.Bubble`, `Chart.Area`, `Chart.SplineArea`, and `Chart.StackedArea`.
111+
112+
## Using encoded arrays with Bar and Column charts
113+
114+
For bar and column charts, the main data array (`values`) is always required and encoded.
115+
The keys array is optional:
116+
*)
117+
118+
let barEncoded =
119+
Chart.Bar(
120+
valuesEncoded = EncodedTypedArray.ofFloat64Array [| 5.0; 3.0; 7.0; 2.0 |],
121+
KeysEncoded = EncodedTypedArray.ofInt32Array [| 0; 1; 2; 3 |],
122+
Name = "encoded bar",
123+
UseDefaults = false
124+
)
125+
126+
(*** condition: ipynb ***)
127+
#if IPYNB
128+
barEncoded
129+
#endif // IPYNB
130+
131+
(***hide***)
132+
barEncoded |> GenericChart.toChartHTML
133+
(***include-it-raw***)
134+
135+
(**
136+
The same pattern applies to `Chart.Column`, `Chart.StackedBar`, and `Chart.StackedColumn`.
137+
138+
## Using encoded arrays with Heatmap
139+
140+
For heatmaps, the z matrix is required and encoded; x and y axes are optional and encoded:
141+
*)
142+
143+
let heatmapEncoded =
144+
Chart.Heatmap(
145+
zEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0; 7.0; 8.0; 9.0 |],
146+
Name = "encoded heatmap",
147+
UseDefaults = false
148+
)
149+
150+
(*** condition: ipynb ***)
151+
#if IPYNB
152+
heatmapEncoded
153+
#endif // IPYNB
154+
155+
(***hide***)
156+
heatmapEncoded |> GenericChart.toChartHTML
157+
(***include-it-raw***)
158+
159+
(**
160+
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+
164+
```fsharp
165+
// Explicit 3x3 shape
166+
let z3x3 =
167+
{ EncodedTypedArray.ofFloat64Array [| 1.0..9.0 |] with Shape = Some "3,3" }
168+
```
169+
170+
For more advanced usage including encoded arrays on 3D, domain, and map traces, see the trace-level
171+
style modules (`Trace2DStyle`, `Trace3DStyle`, `TraceDomainStyle`, etc.) which accept `*Encoded` optional parameters
172+
for most data-array fields.
173+
*)

‎plans/PlotlyJS_2_28_Parity.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,10 @@ The fixes are JS-runtime-only and do not require Plotly.NET changes — they are
3232
|---------|:-:|:-:|:-:|:-:|---|
3333
| Encoded typed arrays | ✅ | ✅ | ✅ (foundational) | ✅ 944 passing | H3 done |
3434
| Sankey node `align` | ✅ | ✅ | ❌ | ✅ | Done (Commit I) |
35-
| Virtual-WebGL | ❌ | N/A | N/A | ❌ | Not started |
35+
| Virtual-WebGL | N/A | N/A | N/A | N/A | No surface needed — use `DisplayOptions.AdditionalHeadTags` |
3636
| Sankey encoded arrays (nodes + links) | ✅ | ✅ | ❌ | ✅ | Done (Commit K) |
3737
| ParallelCoord/Categories `keyValuesEncoded` | ✅ | ✅ | ❌ | ✅ | Done (Commit L) |
38+
| Documentation | ✅ | — | — | — | Done (Commit N) |
3839
| Bundled plotly.js 2.28.0 | ✅ | — | — | — | Done |
3940

4041
## Remaining Work Packages

0 commit comments

Comments
 (0)