diff --git a/AGENTS.md b/AGENTS.md index 2c70e290a..a021df454 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Guidance for AI coding agents working in the Plotly.NET repo. This is a first dr Plotly.NET is an interactive charting library for .NET, built on top of plotly.js. The core is written in F# and wraps the plotly.js JSON schema with multiple API layers (high-level type-safe `Chart` API down to low-level object manipulation). See [README.md](README.md) for user-facing docs and the [F1000Research paper](https://doi.org/10.12688/f1000research.123971.1) for design rationale. -Currently targeted plotly.js version: **2.27.1** (bundled at [src/Plotly.NET/plotly-2.27.1.min.js](src/Plotly.NET/plotly-2.27.1.min.js)). +Currently targeted plotly.js version: **2.28.0** (bundled at [src/Plotly.NET/plotly-2.28.0.min.js](src/Plotly.NET/plotly-2.28.0.min.js)). ## Packages (monorepo layout) diff --git a/Plotly.NET.sln b/Plotly.NET.sln index 1b00bd96d..093037539 100644 --- a/Plotly.NET.sln +++ b/Plotly.NET.sln @@ -1,11 +1,12 @@  Microsoft Visual Studio Solution File, Format Version 12.00 -# Visual Studio Version 17 -VisualStudioVersion = 17.0.31903.59 +# Visual Studio Version 18 +VisualStudioVersion = 18.5.11709.299 stable MinimumVisualStudioVersion = 10.0.40219.1 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "project", "project", "{BF60BC93-E09B-4E5F-9D85-95A519479D54}" ProjectSection(SolutionItems) = preProject .editorconfig = .editorconfig + AGENTS.md = AGENTS.md CITATION.cff = CITATION.cff .config\dotnet-tools.json = .config\dotnet-tools.json LICENSE = LICENSE @@ -135,9 +136,9 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "04_distribution-charts", "0 docs\distribution-charts\histograms.fsx = docs\distribution-charts\histograms.fsx docs\distribution-charts\pareto-chart.fsx = docs\distribution-charts\pareto-chart.fsx docs\distribution-charts\point-density.fsx = docs\distribution-charts\point-density.fsx + docs\distribution-charts\residual.fsx = docs\distribution-charts\residual.fsx docs\distribution-charts\splom.fsx = docs\distribution-charts\splom.fsx docs\distribution-charts\violin-plots.fsx = docs\distribution-charts\violin-plots.fsx - docs\distribution-charts\residual.fsx = docs\distribution-charts\residual.fsx EndProjectSection EndProject 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", docs\general\chart-config.fsx = docs\general\chart-config.fsx docs\general\defaults.fsx = docs\general\defaults.fsx docs\general\display-options.fsx = docs\general\display-options.fsx + docs\general\encoded-arrays.fsx = docs\general\encoded-arrays.fsx docs\general\image-export.fsx = docs\general\image-export.fsx docs\general\multi-arguments.fsx = docs\general\multi-arguments.fsx docs\general\styling-markers.fsx = docs\general\styling-markers.fsx diff --git a/docs/3D-charts/3d-isosurface-plots.fsx b/docs/3D-charts/3d-isosurface-plots.fsx index c22436319..82ddcd12f 100644 --- a/docs/3D-charts/3d-isosurface-plots.fsx +++ b/docs/3D-charts/3d-isosurface-plots.fsx @@ -10,8 +10,8 @@ index: 7 (*** hide ***) (*** condition: prepare ***) -#r "nuget: Newtonsoft.JSON, 13.0.1" -#r "nuget: DynamicObj, 2.0.0" +#r "nuget: Newtonsoft.JSON, 13.0.3" +#r "nuget: DynamicObj, 7.0.1" #r "nuget: Giraffe.ViewEngine, 1.4.0" #r "../../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll" diff --git a/docs/_head.html b/docs/_head.html index 70ba3ddc6..c8ed8f813 100644 --- a/docs/_head.html +++ b/docs/_head.html @@ -20,6 +20,6 @@ - + \ No newline at end of file diff --git a/docs/_template.ipynb b/docs/_template.ipynb deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/categorical-charts/sankey.fsx b/docs/categorical-charts/sankey.fsx index b7d9a2fab..02e70ea0f 100644 --- a/docs/categorical-charts/sankey.fsx +++ b/docs/categorical-charts/sankey.fsx @@ -79,3 +79,31 @@ sankey1 (***hide***) sankey1 |> GenericChart.toChartHTML (***include-it-raw***) + +(** +## Node alignment + +The `NodeAlign` parameter controls how nodes are aligned horizontally. The available options are +`Left`, `Right`, `Center`, and `Justify` (the default). + +Use the `NodeAlign` parameter on `Chart.Sankey` to apply alignment via the convenience overload, +or pass `Align` to `SankeyNodes.init` directly when building nodes manually: +*) + +let sankeyAligned = + Chart.Sankey( + nodeLabels = [ "Source A"; "Source B"; "Sink" ], + linkedNodeIds = [ 0, 2; 1, 2 ], + linkValues = [ 8; 4 ], + NodeAlign = StyleParam.SankeyNodeAlign.Left, + UseDefaults = false + ) + +(*** condition: ipynb ***) +#if IPYNB +sankeyAligned +#endif // IPYNB + +(***hide***) +sankeyAligned |> GenericChart.toChartHTML +(***include-it-raw***) diff --git a/docs/general/encoded-arrays.fsx b/docs/general/encoded-arrays.fsx new file mode 100644 index 000000000..c834c3b8a --- /dev/null +++ b/docs/general/encoded-arrays.fsx @@ -0,0 +1,415 @@ +(** +--- +title: Encoded typed arrays +category: General +categoryindex: 1 +index: 10 +--- +*) + +(*** hide ***) + +(*** condition: prepare ***) +#r "nuget: Newtonsoft.JSON, 13.0.3" +#r "nuget: DynamicObj, 7.0.1" +#r "nuget: Giraffe.ViewEngine, 1.4.0" +#r "../../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll" + +Plotly.NET.Defaults.DefaultDisplayOptions <- + Plotly.NET.DisplayOptions.init (PlotlyJSReference = Plotly.NET.PlotlyJSReference.NoReference) + +(*** condition: ipynb ***) +#if IPYNB +#r "nuget: Plotly.NET, {{fsdocs-package-version}}" +#r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}" +#endif // IPYNB + +(** +# Encoded typed arrays + +[![Binder]({{root}}img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/plotly.net/gh-pages?urlpath=/tree/home/jovyan/{{fsdocs-source-basename}}.ipynb)  +[![Notebook]({{root}}img/badge-notebook.svg)]({{root}}{{fsdocs-source-basename}}.ipynb) + +*Summary:* This page explains numeric encoded arrays in Plotly.NET and the selected C# chart overloads, using plotly.js 2.28.0. + +### Table of contents + +- [What are encoded typed arrays?](#What-are-encoded-typed-arrays) +- [Creating EncodedTypedArray values](#Creating-EncodedTypedArray-values) +- [Using encoded arrays with Scatter](#Using-encoded-arrays-with-Scatter) +- [Using encoded arrays with Bar and Column charts](#Using-encoded-arrays-with-Bar-and-Column-charts) +- [Using encoded arrays with Heatmap](#Using-encoded-arrays-with-Heatmap) +- [Using encoded arrays with 3D charts](#Using-encoded-arrays-with-3D-charts) +- [Using encoded arrays with statistical charts](#Using-encoded-arrays-with-statistical-charts) +- [Using encoded arrays for error bars and trace-level styling](#Using-encoded-arrays-for-error-bars-and-trace-level-styling) +- [Using encoded arrays from C#](#Using-encoded-arrays-from-C) +- [Nested data and precedence](#Nested-data-and-precedence) +- [Supported scope and limitations](#Supported-scope-and-limitations) +- [Loading Virtual-WebGL](#Loading-Virtual-WebGL) + +## What are encoded typed arrays? + +plotly.js 2.28.0 introduced support for passing data arrays as **base64-encoded typed arrays** instead of plain JSON arrays. +The representation contains a base64 byte payload (`bdata`), a numeric type tag (`dtype`), and an optional +matrix shape (`shape`). Its size and parsing cost depend on the data and dtype; this release does not +provide a benchmark or guarantee that it is smaller or faster than JSON arrays. + +The core Plotly.NET assembly owns `EncodedTypedArray`, its factories, and serialization. Both F# and C# +use this same representation. + +## Creating EncodedTypedArray values + +`EncodedTypedArray` can be constructed from the supported numeric arrays listed below: +*) + +open Plotly.NET + +// Float64 (double) arrays — most common for continuous data +let xEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0; 4.0; 5.0 |] +let yEncoded = EncodedTypedArray.ofFloat64Array [| 2.0; 4.0; 1.0; 5.0; 3.0 |] + +// Int32 arrays — for integer data like indices or counts +let sourceEncoded = EncodedTypedArray.ofInt32Array [| 0; 1; 2 |] + +// Float32 arrays — smaller footprint when full precision is not needed +let valuesEncoded = EncodedTypedArray.ofFloat32Array [| 1.0f; 2.5f; 0.8f |] + +(** +Supported constructors: + +| Constructor | F# array type | plotly.js dtype | +|---|---|---| +| `EncodedTypedArray.ofFloat64Array` | `float[]` | `f8` (64-bit float) | +| `EncodedTypedArray.ofFloat32Array` | `float32[]` | `f4` (32-bit float) | +| `EncodedTypedArray.ofInt32Array` | `int[]` | `i4` (32-bit int) | +| `EncodedTypedArray.ofInt16Array` | `int16[]` | `i2` (16-bit int) | +| `EncodedTypedArray.ofInt8Array` | `sbyte[]` | `i1` (8-bit int) | +| `EncodedTypedArray.ofUInt32Array` | `uint32[]` | `u4` (unsigned 32-bit) | +| `EncodedTypedArray.ofUInt16Array` | `uint16[]` | `u2` (unsigned 16-bit) | +| `EncodedTypedArray.ofUInt8Array` | `byte[]` | `u1` (unsigned 8-bit) | +| `EncodedTypedArray.ofUInt8ClampedArray` | `byte[]` | `u1c` (clamped unsigned 8-bit) | + +There are no factories for strings, arbitrary objects, decimal, or signed/unsigned 64-bit integers. +Choose a supported dtype explicitly when converting data, accounting for its range and precision. + +## Using encoded arrays with Scatter + +The encoded convenience overload for `Chart.Scatter` takes `xEncoded` and `yEncoded` as required +positional arguments instead of plain `x`/`y` sequences: +*) + +let scatterEncoded = + Chart.Scatter( + xEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0; 4.0; 5.0 |], + yEncoded = EncodedTypedArray.ofFloat64Array [| 2.0; 4.0; 1.0; 5.0; 3.0 |], + mode = StyleParam.Mode.Markers, + Name = "encoded scatter", + UseDefaults = false + ) + +(*** condition: ipynb ***) +#if IPYNB +scatterEncoded +#endif // IPYNB + +(***hide***) +scatterEncoded |> GenericChart.toChartHTML +(***include-it-raw***) + +(** +The same encoded overload is available for `Chart.Point`, `Chart.Line`, `Chart.Bubble`, `Chart.Area`, `Chart.SplineArea`, and `Chart.StackedArea`. + +## Using encoded arrays with Bar and Column charts + +For bar and column charts, the main data array (`values`) is always required and encoded. +The keys array is optional: +*) + +let barEncoded = + Chart.Bar( + valuesEncoded = EncodedTypedArray.ofFloat64Array [| 5.0; 3.0; 7.0; 2.0 |], + KeysEncoded = EncodedTypedArray.ofInt32Array [| 0; 1; 2; 3 |], + Name = "encoded bar", + UseDefaults = false + ) + +(*** condition: ipynb ***) +#if IPYNB +barEncoded +#endif // IPYNB + +(***hide***) +barEncoded |> GenericChart.toChartHTML +(***include-it-raw***) + +(** +The same pattern applies to `Chart.Column`, `Chart.StackedBar`, and `Chart.StackedColumn`. + +## Using encoded arrays with Heatmap + +For heatmaps, the z matrix is required and encoded; x and y axes are optional and encoded. +When `zEncoded` is given as a flat encoded array, `shape` must also be set so plotly.js can reconstruct the matrix: +*) + +let heatmapEncoded = + Chart.Heatmap( + zEncoded = EncodedTypedArray.ofFloat64Array([| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0 |], shape = [ 2; 3 ]), + Name = "encoded heatmap", + UseDefaults = false + ) + +(*** condition: ipynb ***) +#if IPYNB +heatmapEncoded +#endif // IPYNB + +(***hide***) +heatmapEncoded |> GenericChart.toChartHTML +(***include-it-raw***) +(** +Note that for heatmaps the z data is passed as a flat 1D encoded array. plotly.js uses the `shape` field +(rows × columns) to interpret the layout, so `shape` must be specified: + +``` +// Row-major 2x3 matrix: [[1; 2; 3]; [4; 5; 6]] +let z2x3 = + EncodedTypedArray.ofFloat64Array([| 1.0 .. 6.0 |], shape = [ 2; 3 ]) +``` + +Supply a matching row count and column count for matrix-valued inputs such as the z grid of +`Chart.Surface` or `Chart.Contour`. The factories preserve the supplied shape; they do not validate +that its dimensions match the payload length. + +`Chart.Histogram2D` and `Chart.Histogram2DContour` instead consume one-dimensional x/y samples and +optional z aggregation values, one per sample. Do not reshape those sample arrays into a matrix; +plotly.js computes the bins. + +## Using encoded arrays with 3D charts + +Encoded typed arrays work the same way on 3D traces. For example, `Chart.Scatter3D` accepts encoded x, y, and z coordinates: +*) + +let scatter3DEncoded = + Chart.Scatter3D( + xEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0 |], + yEncoded = EncodedTypedArray.ofFloat64Array [| 4.0; 5.0; 6.0 |], + zEncoded = EncodedTypedArray.ofFloat64Array [| 7.0; 8.0; 9.0 |], + mode = StyleParam.Mode.Markers, + Name = "encoded scatter3d", + UseDefaults = false + ) + +(*** condition: ipynb ***) +#if IPYNB +scatter3DEncoded +#endif // IPYNB + +(***hide***) +scatter3DEncoded |> GenericChart.toChartHTML +(***include-it-raw***) + +(** +`Chart.Surface` uses a two-dimensional z grid. `Chart.Volume` and `Chart.IsoSurface` use parallel +one-dimensional x/y/z/value arrays describing samples in space; their coordinates and values do not +require a matrix shape simply because the chart is three-dimensional. + +## Using encoded arrays with statistical charts + +Distribution and statistical charts support encoded sample arrays as well. Here is a histogram example: +*) + +let histogramEncoded = + Chart.Histogram( + dataEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 2.0; 3.0; 3.0; 3.0; 4.0 |], + orientation = StyleParam.Orientation.Vertical, + Name = "encoded histogram", + UseDefaults = false + ) + +(*** condition: ipynb ***) +#if IPYNB +histogramEncoded +#endif // IPYNB + +(***hide***) +histogramEncoded |> GenericChart.toChartHTML +(***include-it-raw***) + +(** +The same pattern works for `Chart.BoxPlot`, `Chart.Violin`, and finance-style traces such as +`Chart.OHLC` and `Chart.Candlestick`. + +## Using encoded arrays for error bars and trace-level styling + +Some features are available through trace-level styling rather than only through chart-root overloads. +This is especially useful when you want encoded error bars, encoded metadata arrays, or other advanced options: +*) + +open Plotly.NET.TraceObjects + +let scatterWithEncodedErrorBars = + let xErrorEncoded = EncodedTypedArray.ofFloat64Array [| 0.1; 0.2; 0.3 |] + let yErrorEncoded = EncodedTypedArray.ofFloat64Array [| 0.4; 0.5; 0.6 |] + let yErrorMinusEncoded = EncodedTypedArray.ofFloat64Array [| 0.3; 0.2; 0.1 |] + + Trace2D.initScatter( + Trace2DStyle.Scatter( + Name = "encoded scatter + error bars", + Mode = StyleParam.Mode.Lines_Markers, + XEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0 |], + YEncoded = EncodedTypedArray.ofFloat64Array [| 4.0; 5.0; 6.0 |], + XError = + Error.init( + Type = StyleParam.ErrorType.Data, + ArrayEncoded = xErrorEncoded + ), + YError = + Error.init( + Type = StyleParam.ErrorType.Data, + ArrayEncoded = yErrorEncoded, + ArrayminusEncoded = yErrorMinusEncoded + ) + ) + ) + |> GenericChart.ofTraceObject false + |> Chart.withDisplayOptions(DisplayOptions.init(PlotlyJSReference = PlotlyJSReference.NoReference)) + +(*** condition: ipynb ***) +#if IPYNB +scatterWithEncodedErrorBars +#endif // IPYNB + +(***hide***) +scatterWithEncodedErrorBars |> GenericChart.toChartHTML +(***include-it-raw***) + +(** +The trace-style modules (`Trace2DStyle`, `Trace3DStyle`, `TraceDomainStyle`, and others) also accept encoded arrays +for many metadata fields such as ids, custom data, selected points, text, dimensions, and trace-specific attributes. + +For more advanced usage including encoded arrays on 3D, domain, and map traces, see the trace-level +style modules (`Trace2DStyle`, `Trace3DStyle`, `TraceDomainStyle`, etc.) which accept `*Encoded` optional parameters +for selected data-array fields. An encoded option only changes the transport representation; the +underlying plotly.js field must still accept the resulting values. +*) + +(** +## Using encoded arrays from C# + +Reference both `Plotly.NET` and `Plotly.NET.CSharp`. The factories are F# methods in the shared core: +C# supplies `shape: default` for a one-dimensional array, or an explicit +`FSharpOption>` for a matrix. The remaining generic type argument on Scatter/Heatmap +describes optional text; specify it even when no text is supplied. + +This 1D example is compiled and checked in `EncodedArrayExamplesTests`: + +```csharp +[lang=csharp] +using Plotly.NET; +using Chart = Plotly.NET.CSharp.Chart; + +var x = EncodedTypedArray.ofInt32Array(new[] { 0, 1, 2 }, shape: default); +var y = EncodedTypedArray.ofFloat32Array(new[] { 1.5f, 4.5f, 2.5f }, shape: default); +var scatter = Chart.Scatter( + xEncoded: x, yEncoded: y, mode: StyleParam.Mode.Markers, + Name: "encoded scatter", UseDefaults: false); +``` + +For a 2-by-3 heatmap, flatten the rows in order and supply three x coordinates and two y coordinates. +This example is also compiled and checked in the C# tests: + +```csharp +[lang=csharp] +using System.Collections.Generic; +using Microsoft.FSharp.Core; +using Plotly.NET; +using Chart = Plotly.NET.CSharp.Chart; + +var z = EncodedTypedArray.ofFloat32Array( + new[] { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f }, + shape: new FSharpOption>(new[] { 2, 3 })); +var heatmap = Chart.Heatmap( + zEncoded: z, + xEncoded: EncodedTypedArray.ofInt32Array(new[] { 10, 20, 30 }, shape: default), + yEncoded: EncodedTypedArray.ofInt32Array(new[] { 100, 200 }, shape: default), + ReverseYAxis: true, ShowScale: false, UseDefaults: false); +``` + +## Nested data and precedence + +Use `Dimension.initSplom` / `Dimension.initParallel` with `ValuesEncoded` for nested dimension data. +Existing F# and C# SPLOM/parallel chart wrappers accept these objects. ParallelCoord and +ParallelCategories also offer label/encoded-value pair conveniences. + +For Sankey, use `SankeyNodes.init` with `XEncoded` / `YEncoded` and `SankeyLinks.init` with +`SourceEncoded` / `TargetEncoded` / `ValueEncoded`, then pass the objects to `Chart.Sankey(nodes, links, ...)`. +Labels remain plain strings. These shared object APIs also expose numeric `CustomDataEncoded` and +`ColorEncoded`; numeric encoding does not turn color names or other strings into supported typed arrays, +and each field retains its plotly.js value requirements. + +At the trace/object layer, if one init/style call supplies both the plain and encoded parameter for +the same property, the encoded value wins. For example, `Value = [ 99.0 ]` together with +`ValueEncoded = EncodedTypedArray.ofFloat64Array [| 8.0 |]` serializes a single encoded `value` property. +A later style call can replace that property again. The explicit chart overloads instead take +encoded primary inputs directly. + +## Supported scope and limitations + +The examples earlier on this page use the F# API. Direct encoded C# chart overloads currently cover: + +- `Scatter`, `Bar`, `StackedBar`, `Column`, `StackedColumn`, `Heatmap`, `Histogram2D`, and `Scatter3D`. +- `ParallelCoord` / `ParallelCategories` label/encoded-value pairs. +- Nested objects through existing wrappers, including SPLOM and Sankey. + +Other direct C# wrappers, including Histogram, Surface, and map/polar/carpet families, are a later +milestone. C# can also use the shared low-level core types. Existing plain overloads remain available. + +Encoded primary arrays do not make every accompanying input encoded. For example, the encoded F# +Bubble convenience still takes plain sizes, and labels/styles stay plain where the signature says so. +Bar keys and Heatmap axes in these encoded overloads are numeric encoded arrays; there is no matching +plain string-key argument on those overloads. Use existing plain chart overloads when needed, or +compose the supported fields through the shared trace API. + +Image pixel arrays and helpers that compute from the input values, such as Pareto, Residual, and +AnnotatedHeatmap, are outside the direct encoded-overload scope. Neither a metadata option nor the +existence of a numeric factory establishes support for every field or chart type. + +## Loading Virtual-WebGL + +Virtual-WebGL is a separate plotly.js 2.28 feature for sharing WebGL contexts. It is optional and +does not enable encoded arrays. To use the WebGL 1 script (`src/virtual-webgl.js` from Virtual-WebGL +1.0.6, the version used for this integration check), serve the files below with your page +and load Virtual-WebGL before plotly.js, as described by the +[Virtual-WebGL project](https://github.com/greggman/virtual-webgl#how-to-use). + +Existing display options can set that order without a new wrapper API: + +```fsharp +open Giraffe.ViewEngine + +let displayOptions = + DisplayOptions.init( + PlotlyJSReference = PlotlyJSReference.NoReference, + AdditionalHeadTags = [ + script [ _src "/lib/virtual-webgl.js" ] [] + script [ _src "/lib/plotly-2.28.0.min.js" ] [] + ] + ) + +let standaloneHtml = + Chart.Scatter( + xEncoded = EncodedTypedArray.ofInt32Array [| 0; 1; 2 |], + yEncoded = EncodedTypedArray.ofFloat32Array [| 1.5f; 4.5f; 2.5f |], + mode = StyleParam.Mode.Markers, + UseWebGL = true, + UseDefaults = false + ) + |> Chart.withDisplayOptions displayOptions + |> GenericChart.toEmbeddedHTML +``` + +`NoReference` prevents an earlier automatic plotly.js script tag. Replace the paths with your +hosted files and use a WebGL chart, such as Scatter with `UseWebGL = true`, when exercising the +virtualized contexts. `toEmbeddedHTML` emits the head tags; `toChartHTML` emits only a fragment +and requires the host page to supply the scripts. +*) diff --git a/docs/general/image-export.fsx b/docs/general/image-export.fsx index 5650d59eb..167cce253 100644 --- a/docs/general/image-export.fsx +++ b/docs/general/image-export.fsx @@ -14,7 +14,7 @@ index: 2 #r "nuget: Newtonsoft.JSON, 13.0.3" #r "nuget: DynamicObj, 7.0.1" #r "nuget: Giraffe.ViewEngine, 1.4.0" -#r "nuget: PuppeteerSharp, 9.0.2" +#r "nuget: PuppeteerSharp, 24.40.0" #r "../../src/Plotly.NET/bin/Release/netstandard2.0/Plotly.NET.dll" #r "../../src/Plotly.NET.ImageExport/bin/Release/netstandard2.0/Plotly.NET.ImageExport.dll" diff --git a/docs/index.fsx b/docs/index.fsx index be96959ec..5c37ca8d3 100644 --- a/docs/index.fsx +++ b/docs/index.fsx @@ -86,7 +86,8 @@ Plotly.NET packages are available on NuGet to plug into your favorite package ma You can include the package via an inline package reference: -``` +```text +[lang=text] #r "nuget: Plotly.NET, {{fsdocs-package-version}}" ``` @@ -95,7 +96,8 @@ You can include the package via an inline package reference: You can use the same inline package reference as in scripts, but as an additional goodie the interactive extensions for dotnet interactive have you covered for seamless chart rendering: -``` +```text +[lang=text] #r "nuget: Plotly.NET.Interactive, {{fsdocs-package-version}}" ``` diff --git a/plans/EncodedArraySupport.md b/plans/EncodedArraySupport.md index 176205544..383c4e747 100644 --- a/plans/EncodedArraySupport.md +++ b/plans/EncodedArraySupport.md @@ -6,18 +6,18 @@ Encoded-array support is a shared Plotly.NET feature, not a C#-only feature. The The upstream context is [Plotly.NET issue #441](https://github.com/plotly/Plotly.NET/issues/441) and [plotly.js 2.28.0](https://github.com/plotly/plotly.js/releases/tag/v2.28.0). The wire representation contains `dtype`, base64 `bdata`, and optional `shape`; it is shared by both languages. This plan does not claim a measured performance improvement. -Reviewed on 2026-09-10, with `origin` fetched and `dev` at `bca20de4` merged into `C#-refactor` in `51c744b0`. Status means present in this checkout unless another ref is named explicitly. +Updated on 2026-09-10 after merging `dev` at `41f2f88c` (C# refactor PR #503) into `plotly2.28` (PR #502) and completing the agreed follow-up scope. Status means present on this branch unless another ref is named explicitly. Integration and completion verification are recorded separately below. | Layer / scope | Status in this checkout | Remaining work | |---|---|---| -| Shared `EncodedTypedArray`, numeric factories, JSON representation | Implemented | Check C# factory ergonomics as part of H3; reuse the shared type | +| Shared `EncodedTypedArray`, numeric factories, JSON representation | Implemented; C# factory syntax compiled in regression tests and documented | Reuse the shared type for further wrappers | | Bundled plotly.js 2.28.0 and selected trace fields (A–G2) | Implemented | Preserve existing serialization and precedence coverage | | Selected foundational F# chart constructors (H1) | Implemented and committed | No repeat implementation; exclusions are listed below | | Selected derived F# constructors (H2) | Implemented and committed | No repeat implementation | -| C# direct encoded chart overloads (H3) | Absent here; a subset exists on `origin/plotly2.28` | Adapt existing work to the completed C# file split and add C# tests | -| Encoded dimensions | `Dimension.initSplom`, `initParallel`, and `style` support `ValuesEncoded` | Existing dimensions-based charts work; direct parallel-chart pair conveniences exist on the other ref | -| Encoded Sankey flow data | Top-level trace metadata only | Nested node/link support is shared-core work; candidate implementation exists on the other ref | -| User documentation for encoded arrays | Absent here; draft exists on the other ref | Review, adapt, and include tested F# and C# usage | +| C# direct encoded chart overloads (H3) | Eight overloads in split files with C# regression tests and documented examples | Further families remain in the separately scoped backlog | +| Encoded dimensions | Shared Dimension support, F#/C# parallel pairs, and C# encoded SPLOM are tested | No work remaining in the selected dimension scope | +| Encoded Sankey flow data | Shared node/link support, existing C# wrapper, and init/style precedence are tested | No work remaining in the selected nested-data scope | +| User documentation for encoded arrays | F# and compiled C# examples, scope/limits, and script loading are documented; docs build and strict reevaluation passed | No work remaining in the selected documentation scope | The structural [F# chart split](ChartAPIFileSplit.md) and [C# chart split](CSharpChartApiFileSplit.md) are separate plans. Their completion does not imply C# encoded-array coverage or full plotly.js feature parity. @@ -72,44 +72,60 @@ H2 adds `StackedBar`, `Column`, `StackedColumn`, `PointDensity`, `StackedFunnel` Encoded dimensions are implemented in [Dimensions.fs](../src/Plotly.NET/Traces/ObjectAbstractions/Dimensions.fs), and the F# SPLOM overload is in [Chart2D_Splom.fs](../src/Plotly.NET/ChartAPI/Chart2D/Chart2D_Splom.fs). Existing `Splom(dimensions, ...)`, `ParallelCoord(dimensions, ...)`, and `ParallelCategories(dimensions, ...)` can carry encoded dimension values, including through their existing C# wrappers. A missing pair convenience is not a missing encoding capability. -Historical verification recorded for H1/H2: `runTestsCore`, 933 passing. The full clean `runTestsAll` pipeline passed for merge `51c744b0` on 2026-09-10: core tests 945 passed, C# tests 105 passed, and ImageExportTests 6 passed with 2 already marked pending. These C# tests cover the existing wrapper surface, not the proposed encoded overloads. Only plan files changed after that verification. +Historical verification recorded for H1/H2: `runTestsCore`, 933 passing. The full clean `runTestsAll` pipeline passed for refactor merge `51c744b0` on 2026-09-10: core tests 945 passed, C# tests 105 passed, and ImageExportTests 6 passed with 2 already marked pending. Those C# tests covered the plain wrapper surface; the current integration adds explicit regression coverage for the moved encoded and domain additions. -## Existing work to reuse before implementing more +Verification for the resolved `dev` → `plotly2.28` merge on 2026-09-10: full clean `./build.cmd runTestsAll` passed with **958 core tests, 123 C# tests, and 6 ImageExportTests passed / 2 already pending**. The 18 new C# cases in `htmlcodegen/UpstreamFeatures/PlotlyJS228Tests.cs` cover all 11 moved additions and the existing nested-object Sankey path. Expected data/layout came from actual C# chart rendering through the canonical baseline harness, which was restored afterwards. A read-only comparison confirmed preservation of all 99 original branch C# methods and all 88 `dev` methods. The resolved F# console was also type-checked with FSI. No new browser-rendering verification is claimed by this merge. -The locally tracked `origin/plotly2.28` at `fd862365` diverges from this branch at `ef10dedb`. The following commits are not ancestors of current HEAD: +## Implementations retained during integration -| Candidate commit | Useful work | Integration concern | +The following commits are already ancestors of the `plotly2.28` branch. The merge retains their implementations while adopting the C# file split from `dev`; do not reimplement or cherry-pick them again. + +| Existing commit | Retained work | Integration concern | |---|---|---| -| `f1e362a4` | Eight C# encoded overloads: Scatter, Bar, StackedBar, Column, StackedColumn, Heatmap, Histogram2D, Scatter3D | Written in the removed `Chart2D.cs` / `Chart3D.cs`; move methods into the current partial files and add C# tests | +| `f1e362a4` | Eight C# encoded overloads: Scatter, Bar, StackedBar, Column, StackedColumn, Heatmap, Histogram2D, Scatter3D | Moved out of the removed umbrella files into current partial files, preserving signatures and forwarding calls | | `d91fe84a` | Shared Sankey node/link encoded fields; also node alignment | Review nested-field behavior; node alignment is a separate upstream feature, not a prerequisite for encoding | | `1f775369` | F# ParallelCoord/ParallelCategories `keyValuesEncoded` conveniences | Reuse existing Dimension encoding; these are additive conveniences | | `fd862365` | Matching C# parallel-chart pair overloads and a plain Sankey helper with NodeAlign | Parallel wrappers depend on the shared F# conveniences; the plain Sankey helper is not an encoded overload | | `263d7518` | Encoded-array documentation and Sankey examples | Adapt to selected integrated APIs and add compiled C# examples | -That ref also contains `plans/PlotlyJS_2_28_Parity.md`. Its completion claim must not be copied into this plan: the C# encoded additions are a selected subset, and the candidate commits do not add C# encoded tests. Neither a successful wrapper build nor F# tests prove C# forwarding behavior across all families. +The accompanying [2.28 integration status](PlotlyJS_2_28_Parity.md) records the same selected C# scope. The original feature commits did not add C# encoded tests; these are part of the merge validation. Neither a successful wrapper build nor F# tests prove C# forwarding behavior across all families. -Review and port the relevant changes; do not restore the removed umbrella files or import unrelated solution/docs changes just to obtain these methods. Recheck branch ancestry before integration so work already merged later is not duplicated. +Keep the removed umbrella files deleted and all overloads grouped in their per-chart files. Unrelated existing changes on PR #502 remain outside the conflict-resolution scope. ## Next commit packages +### Completion pass agreed on 2026-09-10 [done] + +This self-contained follow-up closes the selected 2.28 scope after the refactor integration: + +- [x] Add shared Sankey init/style collision fixtures and assertions, plus C# encoded-SPLOM coverage. +- [x] Add compiled C# documentation examples for a 1D chart and a non-square matrix. +- [x] Correct the encoded-array guide and both package release notes; document the selected wrappers and numeric/shape limits. +- [x] Smoke-test real generated charts with bundled plotly.js 2.28.0, including nested data and Virtual-WebGL loading, and record the observed results. +- [x] Run the documentation build and full clean FAKE test suite, then update both plans with completion evidence. + +Additional C# chart families remain the separately scoped backlog below. + +Final verification on 2026-09-10: **full clean `./build.cmd runTestsAll` passed with 960 core tests, 126 C# tests, and 6 ImageExport tests passed / 2 already pending**. `./build.cmd BuildDocs` completed, followed by successful strict reevaluation of the edited pages with `dotnet fsdocs build --eval --strict --properties Configuration=Release --parameters fsdocs-package-version 6.0.0`. This also verified the installation-example formatting fix in `docs/index.fsx`. The guide's C# examples are compiled in `EncodedArrayExamplesTests.cs`. Browser checks for Scatter, a 2x3 Heatmap, nested Sankey, SPLOM, and four Virtual-WebGL charts passed; environment, scope, and observations are recorded in [the 2.28 integration status](PlotlyJS_2_28_Parity.md#browser-verification-2026-09-10). + Each package includes implementation and its tests in the same independently buildable commit. Mark it done only after integration and verification on the working branch. The packages below define an initial C# milestone plus separate shared-core/convenience follow-ups; they do not require mirroring every F# overload. -### Next 1: C# Scatter and factory interoperability [pending] +### Next 1: C# Scatter and factory interoperability [done in integration merge] - Adapt the encoded `Scatter` overload from `f1e362a4` into `ChartAPI/Chart2D/Scatter.cs`. - Compile C# examples creating encoded arrays with the shared factories, including 1D data without a declared shape (passing `None` explicitly if C# requires it) and shaped data. Resolve factory/generic ergonomics using the rules above before expanding the surface. - Add C# tests calling the C# wrapper with encoded coordinates, an omitted optional style, and a nondefault style. Assert dtype/base64 preservation and retain a representative plain call to verify overload resolution. -- Reuse the current `htmlcodegen/Chart2D` test organization and `UseDefaults: false`. +- Use `UseDefaults: false`; the integration regressions live in `htmlcodegen/UpstreamFeatures/PlotlyJS228Tests.cs` alongside the existing per-chart plain tests. - Verify with `RunCSharpTestsFast`. -### Next 2: C# bar family [pending] +### Next 2: C# bar family [done in integration merge] - Adapt `Bar`, `StackedBar`, `Column`, and `StackedColumn` from `f1e362a4` into their existing files. - Add C# serialization tests for values/key forwarding, absent optional keys, an encoded width option where exposed, orientation, and stacked layout behavior. Exercise the remaining generic style arguments explicitly. - Keep the plain wrappers and their current tests unchanged. - Verify with `RunCSharpTestsFast`. -### Next 3: C# matrix and 3D representatives [pending] +### Next 3: C# matrix and 3D representatives [done in integration merge] - Adapt `Heatmap`, `Histogram2D`, and `Scatter3D` from `f1e362a4`. - Add a non-square shaped heatmap test, histogram sample/optional aggregation tests, and a 3D coordinate forwarding test. Check both omitted and supplied optional encoded inputs where they change behavior. @@ -117,7 +133,9 @@ Each package includes implementation and its tests in the same independently bui Next 1–3 cover exactly the eight existing C# candidate methods. This is the initial H3 implementation milestone, not full F# chart parity. Additional roots are tracked separately below. -### Next 4: Shared Sankey node/link support [pending; separate core follow-up] +### Next 4: Shared Sankey node/link support [done] + +Integration retains the shared implementation and C# coverage for node positions and link source/target/value. The completion pass adds shared fixtures and tests for init and style collisions across all nine encoded node/link fields, verifies plain labels/alignment survive, and rejects duplicate JSON properties. The style fixture starts from existing objects to cover replacement of earlier values. - Review and adapt the encoded portion of `d91fe84a` in `Traces/ObjectAbstractions/Sankey.fs`. - Cover the meaningful nested numeric inputs first: node positions and link source/target/value, plus supported metadata fields. Preserve existing plain inputs and encoded precedence. @@ -126,7 +144,9 @@ Next 1–3 cover exactly the eight existing C# candidate methods. This is the in - Keep the node-alignment API change separate from the encoded-array completion criteria. - Verify with `RunTestsCoreFast` and `RunCSharpTestsFast`. -### Next 5: Parallel dimension conveniences [pending; optional convenience milestone] +### Next 5: Parallel dimension conveniences [done] + +Integration retains both pair conveniences and C# serialization/option-forwarding tests. The completion pass adds a C# test through the existing SPLOM wrapper, covering encoded dimension values, replacement of plain values, labels, axis matching, marker color, and diagonal/upper-half options. No new SPLOM wrapper is needed. - Adapt shared F# pair constructors from `1f775369`, then matching C# wrappers from `fd862365` in the existing `ParallelCoord.cs` and `ParallelCategories.cs` files. - Use the candidate C# `IEnumerable<(string, EncodedTypedArray)>` shape and delegate to the shared Dimension-based implementation. @@ -134,7 +154,7 @@ Next 1–3 cover exactly the eight existing C# candidate methods. This is the in - Exercise C# `Splom(dimensions, ...)` with encoded dimensions as well; a new SPLOM pair overload is optional, not required to enable encoded values. - Verify with `RunTestsCoreFast` and `RunCSharpTestsFast`. -### Next 6: Usage documentation and completion record [pending] +### Next 6: Usage documentation and completion record [done] - Adapt `docs/general/encoded-arrays.fsx` from `263d7518` to APIs actually integrated on this branch. - Explain the shared representation, numeric dtype limits, matrix shape, plain/encoded precedence at the object layer, and the distinction between direct wrappers and nested-object support. diff --git a/plans/PlotlyJS_2_28_Parity.md b/plans/PlotlyJS_2_28_Parity.md new file mode 100644 index 000000000..760fc633c --- /dev/null +++ b/plans/PlotlyJS_2_28_Parity.md @@ -0,0 +1,77 @@ +# plotly.js 2.28.0 integration status + +Updated on 2026-09-10 for the `dev` → `plotly2.28` integration (`81c30c61`, after C# refactor PR #503) and the agreed completion pass for PR #502. + +The branch bundles plotly.js 2.28.0 and implements shared encoded-array support, Sankey node alignment, and selected F# and C# chart conveniences. The C# additions cover a selected subset of the F# surface. This document records that scope; the remaining encoded-array work is tracked in [EncodedArraySupport.md](EncodedArraySupport.md). + +Upstream context: [plotly.js 2.28.0 release](https://github.com/plotly/plotly.js/releases/tag/v2.28.0), [encoded typed arrays](https://github.com/plotly/plotly.js/pull/5230), [Sankey alignment](https://github.com/plotly/plotly.js/pull/6800), and [Virtual-WebGL integration](https://github.com/plotly/plotly.js/pull/6784). + +## Delivered scope + +| Feature | Implementation | Verification / remaining work | +|---|---|---| +| Bundled runtime | `plotly-2.28.0.min.js`, introduced in `62a96500` | Retained by this merge | +| Shared encoded arrays | `EncodedTypedArray`, serialization, selected trace fields and F# chart constructors | Existing core coverage; exclusions and later families are listed in the encoded-array plan | +| C# direct encoded chart overloads | Scatter, Bar, StackedBar, Column, StackedColumn, Heatmap, Histogram2D, Scatter3D | Moved into split files; new C# regression tests are part of merge validation | +| Parallel dimension pairs | F# and C# ParallelCoord / ParallelCategories conveniences | Existing F# coverage plus new C# regression tests | +| Encoded Sankey node/link data | Shared nested objects, consumed by existing F# and C# object-based Sankey wrappers | Existing F# coverage plus a new C# nested-data regression test | +| Sankey node alignment | StyleParam, SankeyNodes, F# convenience and plain C# convenience | Existing F# coverage plus a new C# forwarding regression test | +| Virtual-WebGL loading | Existing display options load Virtual-WebGL before plotly.js | Four WebGL charts rendered in the browser smoke check below; no dedicated API added | +| Documentation | F# examples, compiled C# examples, numeric/shape limits, selected scope, and Virtual-WebGL loading | Guide and both package release notes updated; documentation build and strict reevaluation passed | + +## Resolution of the C# file-split conflicts + +The deleted `Chart2D.cs`, `Chart3D.cs`, and `ChartDomain.cs` umbrella files remain deleted. Their additions from PR #502 now live beside the existing plain overloads: + +- `src/Plotly.NET.CSharp/ChartAPI/Chart2D/{Scatter,Bar,StackedBar,Column,StackedColumn,Heatmap,Histogram2D}.cs` +- `src/Plotly.NET.CSharp/ChartAPI/Chart3D/Scatter3D.cs` +- `src/Plotly.NET.CSharp/ChartAPI/ChartDomain/{ParallelCoord,ParallelCategories,Sankey}.cs` + +The public signatures, generic constraints, documentation, and forwarding calls from `f1e362a4` and `fd862365` are preserved. The domain files retain the LINQ import needed to convert C# value tuples to F# tuples. The existing plain Sankey test supplies explicit defaults for the new F# optional parameters so it compiles against the merged core. + +The F# console retains the encoded heatmap from `plotly2.28` and the Venn/UpSet examples from `dev`. + +## Shared domain support + +`Traces/ObjectAbstractions/Sankey.fs` implements the following encoded options in node/link initialization and styling: + +- Nodes: `ColorEncoded`, `CustomDataEncoded`, `XEncoded`, `YEncoded`. +- Links: `ColorEncoded`, `CustomDataEncoded`, `SourceEncoded`, `TargetEncoded`, `ValueEncoded`. + +Labels remain plain strings. There is no `LabelEncoded` option. Existing `Chart.Sankey(nodes, links, ...)` APIs accept these objects, including the C# wrapper; a separate encoded Sankey overload is unnecessary. The new plain C# label/link convenience exposes `NodeAlign`, which is independent of encoded data support. + +Parallel pair constructors reuse `Dimension.initParallel(ValuesEncoded = ...)`. Existing dimensions-based APIs, including SPLOM, can already carry encoded values. The pair conveniences are additive. + +## Completion pass + +The follow-up to the refactor merge adds two shared Sankey precedence cases and three C# cases (documented Scatter/Heatmap and existing SPLOM with encoded dimensions). It corrects the shape guidance for histogram/volume samples, supplies C# factory examples, documents script order, and removes all-chart/performance overclaims from the release notes. + +Additional direct C# wrappers remain a separate milestone in [EncodedArraySupport.md](EncodedArraySupport.md). Histogram, other 3D roots, and map/polar/carpet families are not included in the selected eight-wrapper scope. No new wrapper families were added in this completion pass. + +## Merge verification + +Full clean `./build.cmd runTestsAll` passed on 2026-09-10 for the resolved merge: **958 core tests, 123 C# tests, and 6 ImageExportTests passed / 2 already pending**. The 18 new C# cases cover the 11 moved additions and the existing nested-object Sankey path; data/layout baselines were generated through the canonical harness and checked in the rendered HTML. The harness was restored after generation. + +A read-only comparison confirmed that all 99 original `plotly2.28` C# methods and documentation were retained, including unchanged signatures and bodies for all 88 `dev` methods. The resolved F# console was type-checked with FSI. At that point, nested Sankey precedence, C# encoded-SPLOM tests, and browser checks were still follow-ups; the completion pass below adds that evidence. + +## Browser verification, 2026-09-10 + +Generated actual charts through the canonical baseline harness and rendered complete documents with `GenericChart.toEmbeddedHTML`. The harness was restored after generation. Checks used headless Chrome **152.0.7977.83** on Windows with SwiftShader (`--use-angle=swiftshader --enable-unsafe-swiftshader`), and confirmed `Plotly.version === "2.28.0"` in every page. DOM/calculated-data assertions and screenshots were checked together so a WebGL fallback message could not count as successful rendering. + +| Case | Observed result | +|---|---| +| Encoded C# Scatter documentation example | Three visible markers; x `[0,1,2]`, y `[1.5,4.5,2.5]` decoded correctly | +| Encoded C# Heatmap documentation example | Six cells in two rows and three columns; z `[[1,2,3],[4,5,6]]`, x `[10,20,30]`, y `[100,200]`; reversed y-axis preserved | +| Encoded Sankey nested data | Three visible nodes and two links; source `[0,1]`, target `[2,2]`, value `[8,4]`; encoded node positions and right alignment preserved | +| Existing C# SPLOM wrapper | Two labeled dimensions decoded correctly; WebGL points visible, upper half hidden, diagonal retained | +| Virtual-WebGL loading | The documented display-option pattern loaded each script once, in order; four encoded ScatterGL charts rendered on one page and each exported a PNG successfully; virtual context `dispose()` was present and no WebGL fallback was displayed | + +Virtual-WebGL used the upstream-tested WebGL 1 source from [v1.0.6](https://github.com/greggman/virtual-webgl/blob/v1.0.6/src/virtual-webgl.js), tag commit `858e3980299a64027e0f3614075feedaa31376de`. Both scripts were served locally; the other pages embedded the bundled plotly.js directly. There were no uncaught JavaScript exceptions. Virtual-WebGL logged warnings for newer context properties it does not implement; they did not prevent these charts from rendering. + +This is representative runtime evidence, not validation of every encoded field, all browsers/GPUs, maximum WebGL context counts, or performance. In particular, the numeric Sankey color/metadata collision fixtures prove serialization precedence; the browser Sankey case exercises positions and flow values with ordinary labels/colors. + +## Completion verification + +Both incremental `./build.cmd RunTestsAllFast` and final full clean `./build.cmd runTestsAll` passed: **960 core, 126 C#, and 6 ImageExport tests passed / 2 already pending**. The agreed completion pass is done; the broader direct C# wrapper backlog remains a separate milestone. + +`./build.cmd BuildDocs` completed. Its first pass exposed an existing installation-example placeholder diagnostic in `docs/index.fsx`. Explicit language directives now keep those examples and the new C# snippets out of F# reference resolution. Both edited pages were then forced to regenerate with `dotnet fsdocs build --eval --strict --properties Configuration=Release --parameters fsdocs-package-version 6.0.0` against the FAKE-built assemblies; this passed without errors. Rendered HTML was checked for the expected guide content and for hidden formatting directives. diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Bar.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Bar.cs index 6df927dee..5f63f0f47 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Bar.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Bar.cs @@ -88,4 +88,61 @@ public static GenericChart Bar( MultiTextPosition: MultiTextPosition.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a bar chart from encoded values, with bars plotted horizontally. + /// Sets the bar lengths as an encoded typed array. + /// Sets the bar keys as an encoded typed array. + /// Sets where the bar base is drawn (in position axis units). + /// Sets the bar width (in position axis units) of all bars. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart Bar( + EncodedTypedArray valuesEncoded, + Optional KeysEncoded = default, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional> MultiOpacity = default, + Optional Text = default, + Optional> MultiText = default, + Optional MarkerColor = default, + Optional MarkerColorScale = default, + Optional MarkerOutline = default, + Optional MarkerPatternShape = default, + Optional> MultiMarkerPatternShape = default, + Optional MarkerPattern = default, + Optional Marker = default, + Optional Base = default, + Optional Width = default, + Optional MultiWidthEncoded = default, + Optional TextPosition = default, + Optional> MultiTextPosition = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + where BaseType : IConvertible + where WidthType : IConvertible + => + Plotly.NET.Chart2D_Bar.Chart.Bar( + valuesEncoded: valuesEncoded, + KeysEncoded: KeysEncoded.ToOption(), + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + MultiOpacity: MultiOpacity.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + MarkerColor: MarkerColor.ToOption(), + MarkerColorScale: MarkerColorScale.ToOption(), + MarkerOutline: MarkerOutline.ToOption(), + MarkerPatternShape: MarkerPatternShape.ToOption(), + MultiMarkerPatternShape: MultiMarkerPatternShape.ToOption(), + MarkerPattern: MarkerPattern.ToOption(), + Marker: Marker.ToOption(), + Base: Base.ToOption(), + Width: Width.ToOption(), + MultiWidthEncoded: MultiWidthEncoded.ToOption(), + TextPosition: TextPosition.ToOption(), + MultiTextPosition: MultiTextPosition.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Column.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Column.cs index 7cd3e5f1f..c25e59bb6 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Column.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Column.cs @@ -88,4 +88,61 @@ public static GenericChart Column( MultiTextPosition: MultiTextPosition.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a column chart from encoded values, with bars plotted vertically. + /// Sets the bar lengths as an encoded typed array. + /// Sets the bar keys as an encoded typed array. + /// Sets where the bar base is drawn (in position axis units). + /// Sets the bar width (in position axis units) of all bars. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart Column( + EncodedTypedArray valuesEncoded, + Optional KeysEncoded = default, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional> MultiOpacity = default, + Optional Text = default, + Optional> MultiText = default, + Optional MarkerColor = default, + Optional MarkerColorScale = default, + Optional MarkerOutline = default, + Optional MarkerPatternShape = default, + Optional> MultiMarkerPatternShape = default, + Optional MarkerPattern = default, + Optional Marker = default, + Optional Base = default, + Optional Width = default, + Optional MultiWidthEncoded = default, + Optional TextPosition = default, + Optional> MultiTextPosition = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + where BaseType : IConvertible + where WidthType : IConvertible + => + Plotly.NET.Chart2D_Bar.Chart.Column( + valuesEncoded: valuesEncoded, + KeysEncoded: KeysEncoded.ToOption(), + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + MultiOpacity: MultiOpacity.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + MarkerColor: MarkerColor.ToOption(), + MarkerColorScale: MarkerColorScale.ToOption(), + MarkerOutline: MarkerOutline.ToOption(), + MarkerPatternShape: MarkerPatternShape.ToOption(), + MultiMarkerPatternShape: MultiMarkerPatternShape.ToOption(), + MarkerPattern: MarkerPattern.ToOption(), + Marker: Marker.ToOption(), + Base: Base.ToOption(), + Width: Width.ToOption(), + MultiWidthEncoded: MultiWidthEncoded.ToOption(), + TextPosition: TextPosition.ToOption(), + MultiTextPosition: MultiTextPosition.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Heatmap.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Heatmap.cs index 412c8f52f..cf25605f1 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Heatmap.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Heatmap.cs @@ -86,4 +86,54 @@ public static GenericChart Heatmap( ReverseYAxis: ReverseYAxis.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a heatmap from encoded z data and optional encoded axes. + /// Sets the z matrix as an encoded typed array. + /// Sets the x coordinates as an encoded typed array. + /// Sets the y coordinates as an encoded typed array. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart Heatmap( + EncodedTypedArray zEncoded, + Optional xEncoded = default, + Optional yEncoded = default, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional XGap = default, + Optional YGap = default, + Optional Text = default, + Optional> MultiText = default, + Optional ColorBar = default, + Optional ColorScale = default, + Optional ShowScale = default, + Optional ReverseScale = default, + Optional ZSmooth = default, + Optional Transpose = default, + Optional UseWebGL = default, + Optional ReverseYAxis = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + => + Plotly.NET.Chart2D_Heatmap.Chart.Heatmap( + zEncoded: zEncoded, + xEncoded: xEncoded.ToOption(), + yEncoded: yEncoded.ToOption(), + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + XGap: XGap.ToOption(), + YGap: YGap.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + ColorBar: ColorBar.ToOption(), + ColorScale: ColorScale.ToOption(), + ShowScale: ShowScale.ToOption(), + ReverseScale: ReverseScale.ToOption(), + ZSmooth: ZSmooth.ToOption(), + Transpose: Transpose.ToOption(), + UseWebGL: UseWebGL.ToOption(), + ReverseYAxis: ReverseYAxis.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Histogram2D.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Histogram2D.cs index f3c1c1646..6743b71e8 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Histogram2D.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Histogram2D.cs @@ -82,4 +82,55 @@ public static GenericChart Histogram2D( ZSmooth: ZSmooth.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a 2D histogram from encoded x and y data. + /// Sets the x sample data as an encoded typed array. + /// Sets the y sample data as an encoded typed array. + /// Sets the z aggregation data as an encoded typed array. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart Histogram2D( + EncodedTypedArray xEncoded, + EncodedTypedArray yEncoded, + Optional zEncoded = default, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional XGap = default, + Optional YGap = default, + Optional HistFunc = default, + Optional HistNorm = default, + Optional NBinsX = default, + Optional NBinsY = default, + Optional XBins = default, + Optional YBins = default, + Optional ColorBar = default, + Optional ColorScale = default, + Optional ShowScale = default, + Optional ReverseScale = default, + Optional ZSmooth = default, + Optional UseDefaults = default + ) + => + Plotly.NET.Chart2D_Histogram.Chart.Histogram2D( + xEncoded: xEncoded, + yEncoded: yEncoded, + zEncoded: zEncoded.ToOption(), + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + XGap: XGap.ToOption(), + YGap: YGap.ToOption(), + HistFunc: HistFunc.ToOption(), + HistNorm: HistNorm.ToOption(), + NBinsX: NBinsX.ToOption(), + NBinsY: NBinsY.ToOption(), + XBins: XBins.ToOption(), + YBins: YBins.ToOption(), + ColorBar: ColorBar.ToOption(), + ColorScale: ColorScale.ToOption(), + ShowScale: ShowScale.ToOption(), + ReverseScale: ReverseScale.ToOption(), + ZSmooth: ZSmooth.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Scatter.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Scatter.cs index dae44c71d..c71fb098f 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Scatter.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/Scatter.cs @@ -118,4 +118,80 @@ public static GenericChart Scatter( UseWebGL: UseWebGL.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a Scatter plot from encoded x and y typed arrays. + /// Sets the x coordinates as an encoded typed array. + /// Sets the y coordinates as an encoded typed array. + /// Determines the drawing mode for this scatter trace. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart Scatter( + EncodedTypedArray xEncoded, + EncodedTypedArray yEncoded, + StyleParam.Mode mode, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional> MultiOpacity = default, + Optional Text = default, + Optional> MultiText = default, + Optional TextPosition = default, + Optional> MultiTextPosition = default, + Optional MarkerColor = default, + Optional MarkerColorScale = default, + Optional MarkerOutline = default, + Optional MarkerSymbol = default, + Optional> MultiMarkerSymbol = default, + Optional Marker = default, + Optional LineColor = default, + Optional LineColorScale = default, + Optional LineWidth = default, + Optional LineDash = default, + Optional Line = default, + Optional AlignmentGroup = default, + Optional OffsetGroup = default, + Optional StackGroup = default, + Optional Orientation = default, + Optional GroupNorm = default, + Optional Fill = default, + Optional FillColor = default, + Optional FillPattern = default, + Optional UseWebGL = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + => + Plotly.NET.Chart2D_Scatter.Chart.Scatter( + xEncoded: xEncoded, + yEncoded: yEncoded, + mode: mode, + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + MultiOpacity: MultiOpacity.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + TextPosition: TextPosition.ToOption(), + MultiTextPosition: MultiTextPosition.ToOption(), + MarkerColor: MarkerColor.ToOption(), + MarkerColorScale: MarkerColorScale.ToOption(), + MarkerOutline: MarkerOutline.ToOption(), + MarkerSymbol: MarkerSymbol.ToOption(), + MultiMarkerSymbol: MultiMarkerSymbol.ToOption(), + Marker: Marker.ToOption(), + LineColor: LineColor.ToOption(), + LineColorScale: LineColorScale.ToOption(), + LineWidth: LineWidth.ToOption(), + LineDash: LineDash.ToOption(), + Line: Line.ToOption(), + AlignmentGroup: AlignmentGroup.ToOption(), + OffsetGroup: OffsetGroup.ToOption(), + StackGroup: StackGroup.ToOption(), + Orientation: Orientation.ToOption(), + GroupNorm: GroupNorm.ToOption(), + Fill: Fill.ToOption(), + FillColor: FillColor.ToOption(), + FillPattern: FillPattern.ToOption(), + UseWebGL: UseWebGL.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedBar.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedBar.cs index f947f254a..765f79560 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedBar.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedBar.cs @@ -89,4 +89,61 @@ public static GenericChart StackedBar( MultiTextPosition: MultiTextPosition.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a stacked bar chart from encoded values, with bars plotted horizontally. + /// Sets the bar lengths as an encoded typed array. + /// Sets the bar keys as an encoded typed array. + /// Sets where the bar base is drawn (in position axis units). + /// Sets the bar width (in position axis units) of all bars. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart StackedBar( + EncodedTypedArray valuesEncoded, + Optional KeysEncoded = default, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional> MultiOpacity = default, + Optional Text = default, + Optional> MultiText = default, + Optional MarkerColor = default, + Optional MarkerColorScale = default, + Optional MarkerOutline = default, + Optional MarkerPatternShape = default, + Optional> MultiMarkerPatternShape = default, + Optional MarkerPattern = default, + Optional Marker = default, + Optional Base = default, + Optional Width = default, + Optional MultiWidthEncoded = default, + Optional TextPosition = default, + Optional> MultiTextPosition = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + where BaseType : IConvertible + where WidthType : IConvertible + => + Plotly.NET.Chart2D_Bar.Chart.StackedBar( + valuesEncoded: valuesEncoded, + KeysEncoded: KeysEncoded.ToOption(), + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + MultiOpacity: MultiOpacity.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + MarkerColor: MarkerColor.ToOption(), + MarkerColorScale: MarkerColorScale.ToOption(), + MarkerOutline: MarkerOutline.ToOption(), + MarkerPatternShape: MarkerPatternShape.ToOption(), + MultiMarkerPatternShape: MultiMarkerPatternShape.ToOption(), + MarkerPattern: MarkerPattern.ToOption(), + Marker: Marker.ToOption(), + Base: Base.ToOption(), + Width: Width.ToOption(), + MultiWidthEncoded: MultiWidthEncoded.ToOption(), + TextPosition: TextPosition.ToOption(), + MultiTextPosition: MultiTextPosition.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedColumn.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedColumn.cs index 49be4f91e..9e27943f0 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedColumn.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart2D/StackedColumn.cs @@ -89,4 +89,61 @@ public static GenericChart StackedColumn( MultiTextPosition: MultiTextPosition.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a stacked column chart from encoded values, with bars plotted vertically. + /// Sets the bar lengths as an encoded typed array. + /// Sets the bar keys as an encoded typed array. + /// Sets where the bar base is drawn (in position axis units). + /// Sets the bar width (in position axis units) of all bars. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart StackedColumn( + EncodedTypedArray valuesEncoded, + Optional KeysEncoded = default, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional> MultiOpacity = default, + Optional Text = default, + Optional> MultiText = default, + Optional MarkerColor = default, + Optional MarkerColorScale = default, + Optional MarkerOutline = default, + Optional MarkerPatternShape = default, + Optional> MultiMarkerPatternShape = default, + Optional MarkerPattern = default, + Optional Marker = default, + Optional Base = default, + Optional Width = default, + Optional MultiWidthEncoded = default, + Optional TextPosition = default, + Optional> MultiTextPosition = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + where BaseType : IConvertible + where WidthType : IConvertible + => + Plotly.NET.Chart2D_Bar.Chart.StackedColumn( + valuesEncoded: valuesEncoded, + KeysEncoded: KeysEncoded.ToOption(), + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + MultiOpacity: MultiOpacity.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + MarkerColor: MarkerColor.ToOption(), + MarkerColorScale: MarkerColorScale.ToOption(), + MarkerOutline: MarkerOutline.ToOption(), + MarkerPatternShape: MarkerPatternShape.ToOption(), + MultiMarkerPatternShape: MultiMarkerPatternShape.ToOption(), + MarkerPattern: MarkerPattern.ToOption(), + Marker: Marker.ToOption(), + Base: Base.ToOption(), + Width: Width.ToOption(), + MultiWidthEncoded: MultiWidthEncoded.ToOption(), + TextPosition: TextPosition.ToOption(), + MultiTextPosition: MultiTextPosition.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/Chart3D/Scatter3D.cs b/src/Plotly.NET.CSharp/ChartAPI/Chart3D/Scatter3D.cs index fcd6934b6..3ed97068f 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/Chart3D/Scatter3D.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/Chart3D/Scatter3D.cs @@ -106,4 +106,71 @@ public static GenericChart Scatter3D( Camera: Camera.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// Creates a Scatter3D plot from encoded x, y, and z typed arrays. + /// Sets the x coordinates as an encoded typed array. + /// Sets the y coordinates as an encoded typed array. + /// Sets the z coordinates as an encoded typed array. + /// Determines the drawing mode for this scatter trace. + /// If set to false, ignore the global default settings set in Defaults + public static GenericChart Scatter3D( + EncodedTypedArray xEncoded, + EncodedTypedArray yEncoded, + EncodedTypedArray zEncoded, + StyleParam.Mode mode, + Optional Name = default, + Optional ShowLegend = default, + Optional Opacity = default, + Optional> MultiOpacity = default, + Optional Text = default, + Optional> MultiText = default, + Optional TextPosition = default, + Optional> MultiTextPosition = default, + Optional MarkerColor = default, + Optional MarkerColorScale = default, + Optional MarkerOutline = default, + Optional MarkerSymbol = default, + Optional> MultiMarkerSymbol = default, + Optional Marker = default, + Optional LineColor = default, + Optional LineColorScale = default, + Optional LineWidth = default, + Optional LineDash = default, + Optional Line = default, + Optional CameraProjectionType = default, + Optional Camera = default, + Optional Projection = default, + Optional UseDefaults = default + ) + where TextType : IConvertible + => + Plotly.NET.Chart3D_Scatter.Chart.Scatter3D( + xEncoded: xEncoded, + yEncoded: yEncoded, + zEncoded: zEncoded, + mode: mode, + Name: Name.ToOption(), + ShowLegend: ShowLegend.ToOption(), + Opacity: Opacity.ToOption(), + MultiOpacity: MultiOpacity.ToOption(), + Text: Text.ToOption(), + MultiText: MultiText.ToOption(), + TextPosition: TextPosition.ToOption(), + MultiTextPosition: MultiTextPosition.ToOption(), + MarkerColor: MarkerColor.ToOption(), + MarkerColorScale: MarkerColorScale.ToOption(), + MarkerOutline: MarkerOutline.ToOption(), + MarkerSymbol: MarkerSymbol.ToOption(), + MultiMarkerSymbol: MultiMarkerSymbol.ToOption(), + Marker: Marker.ToOption(), + LineColor: LineColor.ToOption(), + LineColorScale: LineColorScale.ToOption(), + LineWidth: LineWidth.ToOption(), + LineDash: LineDash.ToOption(), + Line: Line.ToOption(), + CameraProjectionType: CameraProjectionType.ToOption(), + Camera: Camera.ToOption(), + Projection: Projection.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCategories.cs b/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCategories.cs index 64afc17a3..ca309dccf 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCategories.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCategories.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.Linq; using Plotly.NET; using Plotly.NET.LayoutObjects; using Plotly.NET.TraceObjects; @@ -67,4 +68,61 @@ public static GenericChart ParallelCategories( TickFont: TickFont.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// + /// Creates a parallel categories plot from encoded dimension values. + /// + /// The parallel categories diagram (also known as parallel sets or alluvial diagram) is a visualization of + /// multi-dimensional categorical data sets. + /// + /// Sets the values for each dimension as (dimensionKey, encodedDimensionValues) pairs. + /// Sets the trace name. The trace name appear as the legend item and on hover + /// The number of observations represented by each state. Defaults to 1 so that each state represents one observation + /// Sets the color of the lines that are connecting the datums on the dimensions + /// Sets the shape of the lines that are connecting the datums on the dimensions + /// Sets the colorscale of the lines that are connecting the datums on the dimensions + /// Whether or not to show the colorbar of the lines that are connecting the datums on the dimensions + /// Whether or not to reverse the colorscale of the lines that are connecting the datums on the dimensions + /// Sets the lines that are connecting the datums on the dimensions (use this for more finegrained control than the other line-associated arguments). + /// Sets the drag interaction mode for categories and dimensions. If `perpendicular`, the categories can only move along a line perpendicular to the paths. If `freeform`, the categories can freely move on the plane. If `fixed`, the categories and dimensions are stationary. + /// Sort paths so that like colors are bundled together within each category. + /// Sets the path sorting algorithm. If `forward`, sort paths based on dimension categories from left to right. If `backward`, sort paths based on dimensions categories from right to left. + /// Sets the label font of this trace. + /// Sets the tick font of this trace. + /// If set to false, ignore the global default settings set in `Defaults` + public static GenericChart ParallelCategories( + IEnumerable<(string, EncodedTypedArray)> keyValuesEncoded, + Optional Name = default, + Optional Counts = default, + Optional LineColor = default, + Optional LineShape = default, + Optional LineColorScale = default, + Optional ShowLineColorScale = default, + Optional ReverseLineColorScale = default, + Optional Line = default, + Optional Arrangement = default, + Optional BundleColors = default, + Optional SortPaths = default, + Optional LabelFont = default, + Optional TickFont = default, + Optional UseDefaults = default + ) + => + Plotly.NET.ChartDomain_Relations.Chart.ParallelCategories( + keyValuesEncoded: keyValuesEncoded.Select(kv => kv.ToTuple()), + Name: Name.ToOption(), + Counts: Counts.ToOption(), + LineColor: LineColor.ToOption(), + LineShape: LineShape.ToOption(), + LineColorScale: LineColorScale.ToOption(), + ShowLineColorScale: ShowLineColorScale.ToOption(), + ReverseLineColorScale: ReverseLineColorScale.ToOption(), + Line: Line.ToOption(), + Arrangement: Arrangement.ToOption(), + BundleColors: BundleColors.ToOption(), + SortPaths: SortPaths.ToOption(), + LabelFont: LabelFont.ToOption(), + TickFont: TickFont.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCoord.cs b/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCoord.cs index ed8739775..e02e2433f 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCoord.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/ParallelCoord.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.Linq; using Plotly.NET; using Plotly.NET.LayoutObjects; using Plotly.NET.TraceObjects; @@ -62,4 +63,54 @@ public static GenericChart ParallelCoord( TickFont: TickFont.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// + /// Creates a parallel coordinates plot from encoded dimension values. + /// + /// Parallel coordinates are a common way of visualizing and analyzing high-dimensional datasets. + /// + /// Sets the values for each dimension as (dimensionKey, encodedDimensionValues) pairs. + /// Sets the trace name. The trace name appear as the legend item and on hover + /// Sets the color of the lines that are connecting the datums on the dimensions + /// Sets the colorscale of the lines that are connecting the datums on the dimensions + /// Whether or not to show the colorbar of the lines that are connecting the datums on the dimensions + /// Whether or not to reverse the colorscale of the lines that are connecting the datums on the dimensions + /// Sets the lines that are connecting the datums on the dimensions (use this for more finegrained control than the other line-associated arguments). + /// Sets the angle of the labels with respect to the horizontal. + /// Sets the label font of this trace. + /// Specifies the location of the `label`. + /// Sets the range font of this trace. + /// Sets the tick font of this trace. + /// If set to false, ignore the global default settings set in `Defaults` + public static GenericChart ParallelCoord( + IEnumerable<(string, EncodedTypedArray)> keyValuesEncoded, + Optional Name = default, + Optional LineColor = default, + Optional LineColorScale = default, + Optional ShowLineColorScale = default, + Optional ReverseLineColorScale = default, + Optional Line = default, + Optional LabelAngle = default, + Optional LabelFont = default, + Optional LabelSide = default, + Optional RangeFont = default, + Optional TickFont = default, + Optional UseDefaults = default + ) + => + Plotly.NET.ChartDomain_Relations.Chart.ParallelCoord( + keyValuesEncoded: keyValuesEncoded.Select(kv => kv.ToTuple()), + Name: Name.ToOption(), + LineColor: LineColor.ToOption(), + LineColorScale: LineColorScale.ToOption(), + ShowLineColorScale: ShowLineColorScale.ToOption(), + ReverseLineColorScale: ReverseLineColorScale.ToOption(), + Line: Line.ToOption(), + LabelAngle: LabelAngle.ToOption(), + LabelFont: LabelFont.ToOption(), + LabelSide: LabelSide.ToOption(), + RangeFont: RangeFont.ToOption(), + TickFont: TickFont.ToOption(), + UseDefaults: UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/Sankey.cs b/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/Sankey.cs index ef35be2e2..6db0f8dd4 100644 --- a/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/Sankey.cs +++ b/src/Plotly.NET.CSharp/ChartAPI/ChartDomain/Sankey.cs @@ -1,5 +1,6 @@ using System; using System.Collections.Generic; +using System.Linq; using Plotly.NET; using Plotly.NET.LayoutObjects; using Plotly.NET.TraceObjects; @@ -52,4 +53,83 @@ public static GenericChart Sankey( ValueSuffix: ValueSuffix.ToOption(), UseDefaults: UseDefaults.ToOption() ); + + /// + /// Creates a sankey diagram. + /// + /// A Sankey diagram is a flow diagram, in which the width of arrows is proportional to the flow quantity. + /// + /// Sets the labels of the nodes in the sankey diagram + /// (source, target) tuples which indicate connected nodes. These values map to the index in `nodeLabels` + /// The values for the links in the sankey diagram. + /// Sets the color of the nodes in the sankey diagram. + /// Sets the color of the node outlines in the sankey diagram. + /// Sets the outline width of the nodes in the sankey diagram. + /// Sets the thickness of the nodes in the sankey diagram. + /// Sets groups of nodes. Each group is defined by an array with the indices of the nodes it contains. Multiple groups can be specified. + /// Sets the color of the links in the sankey diagram. + /// Sets the colorscale of the links in the sankey diagram. + /// Sets the outline color of the links in the sankey diagram. + /// Sets the outline width of the links in the sankey diagram. + /// Sets the labels of the links in the sankey diagram. + /// Sets the trace name. The trace name appear as the legend item and on hover. + /// Assigns id labels to each datum. + /// Sets the orientation of the Sankey diagram. + /// Sets the text font of this trace. + /// If value is `snap` (the default), the node arrangement is assisted by automatic snapping of elements to preserve space between nodes specified via `nodepad`. If value is `perpendicular`, the nodes can only move along a line perpendicular to the flow. If value is `freeform`, the nodes can freely move on the plane. If value is `fixed`, the nodes are stationary. + /// Sets the horizontal alignment of the nodes in the Sankey diagram. If value is `justify` (the default), the nodes are spread to fill the width. If value is `left`, `right`, or `center`, the nodes are aligned accordingly. + /// Sets the value formatting rule using d3 formatting mini-languages which are very similar to those in Python. For numbers, see: https://github.com/d3/d3-format/tree/v1.4.5#d3-format. + /// Adds a unit to follow the value in the hover tooltip. Add a space if a separation is necessary from the value. + /// If set to false, ignore the global default settings set in `Defaults` + public static GenericChart Sankey( + IEnumerable nodeLabels, + IEnumerable<(int, int)> linkedNodeIds, + IEnumerable linkValues, + Optional NodeColor = default, + Optional NodeOutlineColor = default, + Optional NodeOutlineWidth = default, + Optional NodeThickness = default, + Optional>> NodeGroups = default, + Optional LinkColor = default, + Optional> LinkColorScales = default, + Optional LinkOutlineColor = default, + Optional LinkOutlineWidth = default, + Optional> LinkLabels = default, + Optional Name = default, + Optional> Ids = default, + Optional Orientation = default, + Optional TextFont = default, + Optional Arrangement = default, + Optional NodeAlign = default, + Optional ValueFormat = default, + Optional ValueSuffix = default, + Optional UseDefaults = default + ) + where LinkValuesType : IConvertible + where IdsType : IConvertible + => + Plotly.NET.ChartDomain_Relations.Chart.Sankey, IdsType>( + nodeLabels, + linkedNodeIds.Select(link => link.ToTuple()), + linkValues, + NodeColor.ToOption(), + NodeOutlineColor.ToOption(), + NodeOutlineWidth.ToOption(), + NodeThickness.ToOption(), + NodeGroups.ToOption(), + LinkColor.ToOption(), + LinkColorScales.ToOption(), + LinkOutlineColor.ToOption(), + LinkOutlineWidth.ToOption(), + LinkLabels.ToOption(), + Name.ToOption(), + Ids.ToOption(), + Orientation.ToOption(), + TextFont.ToOption(), + Arrangement.ToOption(), + NodeAlign.ToOption(), + ValueFormat.ToOption(), + ValueSuffix.ToOption(), + UseDefaults.ToOption() + ); } diff --git a/src/Plotly.NET.CSharp/RELEASE_NOTES.md b/src/Plotly.NET.CSharp/RELEASE_NOTES.md index 56ce5fe26..a2a70d8c3 100644 --- a/src/Plotly.NET.CSharp/RELEASE_NOTES.md +++ b/src/Plotly.NET.CSharp/RELEASE_NOTES.md @@ -1,5 +1,11 @@ ### 0.14.0 - TBD +- Add direct encoded-array overloads for `Scatter`, `Bar`, `StackedBar`, `Column`, `StackedColumn`, `Heatmap`, `Histogram2D`, and `Scatter3D`, reusing `Plotly.NET.EncodedTypedArray`. +- Add `ParallelCoord` / `ParallelCategories` conveniences accepting label/encoded-value pairs. Existing SPLOM and Sankey wrappers also accept shared dimension/node/link objects containing encoded values. +- Add a Sankey label/link convenience with `NodeAlign` for Left, Right, Center, or Justify alignment. +- Document and test C# factory syntax for 1D arrays and shaped matrices. Additional direct encoded wrappers remain outside this release's selected C# scope; existing plain overloads are preserved. +- Split the C# chart implementation and tests into per-chart files without changing the existing API. + - bump version range of Plotly.NET to [6.0.0, 7.0.0) - **Breaking:** Plotly.NET.CSharp assemblies are no longer strong-named. See the Plotly.NET 6.0.0 release notes for context and migration options. - Dev tooling: target framework updated to `net10.0`; xunit 2.9.3, xunit.runner.visualstudio 3.1.5, coverlet.collector 8.0.1 @@ -196,4 +202,4 @@ C# bindings for basic charts and styling for usage in ML.NET notebooks: - [x] ChartDomain - [x] Pie - [x] ChartSmith - - [x] ScatterSmith \ No newline at end of file + - [x] ScatterSmith diff --git a/src/Plotly.NET/ChartAPI/ChartDomain/ChartDomain_Relations.fs b/src/Plotly.NET/ChartAPI/ChartDomain/ChartDomain_Relations.fs index 798eec8fc..2d07fdead 100644 --- a/src/Plotly.NET/ChartAPI/ChartDomain/ChartDomain_Relations.fs +++ b/src/Plotly.NET/ChartAPI/ChartDomain/ChartDomain_Relations.fs @@ -141,6 +141,61 @@ module ChartDomain_Relations = ?UseDefaults = UseDefaults ) + /// + /// Creates a parallel coordinates plot from encoded dimension values. + /// + /// Parallel coordinates are a common way of visualizing and analyzing high-dimensional datasets. + /// + /// Sets the values for each dimension as (dimensionKey, encodedDimensionValues) pairs. + /// Sets the trace name. The trace name appear as the legend item and on hover + /// Sets the color of the lines that are connecting the datums on the dimensions + /// Sets the colorscale of the lines that are connecting the datums on the dimensions + /// Whether or not to show the colorbar of the lines that are connecting the datums on the dimensions + /// Whether or not to reverse the colorscale of the lines that are connecting the datums on the dimensions + /// Sets the lines that are connecting the datums on the dimensions (use this for more finegrained control than the other line-associated arguments). + /// Sets the angle of the labels with respect to the horizontal. + /// Sets the label font of this trace. + /// Specifies the location of the `label`. + /// Sets the range font of this trace. + /// Sets the tick font of this trace. + /// If set to false, ignore the global default settings set in `Defaults` + [] + static member ParallelCoord + ( + keyValuesEncoded: seq, + ?Name: string, + ?LineColor: Color, + ?LineColorScale: StyleParam.Colorscale, + ?ShowLineColorScale: bool, + ?ReverseLineColorScale: bool, + ?Line: Line, + ?LabelAngle: int, + ?LabelFont: Font, + ?LabelSide: StyleParam.Side, + ?RangeFont: Font, + ?TickFont: Font, + ?UseDefaults: bool + ) = + + let dims = + keyValuesEncoded |> Seq.map (fun (key, encodedVals) -> Dimension.initParallel (Label = key, ValuesEncoded = encodedVals)) + + Chart.ParallelCoord( + dimensions = dims, + ?Name = Name, + ?LineColor = LineColor, + ?LineColorScale = LineColorScale, + ?ShowLineColorScale = ShowLineColorScale, + ?ReverseLineColorScale = ReverseLineColorScale, + ?Line = Line, + ?LabelAngle = LabelAngle, + ?LabelFont = LabelFont, + ?LabelSide = LabelSide, + ?RangeFont = RangeFont, + ?TickFont = TickFont, + ?UseDefaults = UseDefaults + ) + /// /// Creates a parallel categories plot. /// @@ -289,6 +344,68 @@ module ChartDomain_Relations = ) |> GenericChart.ofTraceObject useDefaults + /// + /// Creates a parallel categories plot from encoded dimension values. + /// + /// The parallel categories diagram (also known as parallel sets or alluvial diagram) is a visualization of + /// multi-dimensional categorical data sets. + /// + /// Sets the values for each dimension as (dimensionKey, encodedDimensionValues) pairs. + /// Sets the trace name. The trace name appear as the legend item and on hover + /// The number of observations represented by each state. Defaults to 1 so that each state represents one observation + /// Sets the color of the lines that are connecting the datums on the dimensions + /// Sets the shape of the lines that are connecting the datums on the dimensions + /// Sets the colorscale of the lines that are connecting the datums on the dimensions + /// Whether or not to show the colorbar of the lines that are connecting the datums on the dimensions + /// Whether or not to reverse the colorscale of the lines that are connecting the datums on the dimensions + /// Sets the lines that are connecting the datums on the dimensions (use this for more finegrained control than the other line-associated arguments). + /// Sets the drag interaction mode for categories and dimensions. + /// Sort paths so that like colors are bundled together within each category. + /// Sets the path sorting algorithm. + /// Sets the label font of this trace. + /// Sets the tick font of this trace. + /// If set to false, ignore the global default settings set in `Defaults` + [] + static member ParallelCategories + ( + keyValuesEncoded: seq, + ?Name: string, + ?Counts: int, + ?LineColor: Color, + ?LineShape: StyleParam.Shape, + ?LineColorScale: StyleParam.Colorscale, + ?ShowLineColorScale: bool, + ?ReverseLineColorScale: bool, + ?Line: Line, + ?Arrangement: StyleParam.CategoryArrangement, + ?BundleColors: bool, + ?SortPaths: StyleParam.SortAlgorithm, + ?LabelFont: Font, + ?TickFont: Font, + ?UseDefaults: bool + ) = + + let dims = + keyValuesEncoded |> Seq.map (fun (key, encodedVals) -> Dimension.initParallel (Label = key, ValuesEncoded = encodedVals)) + + Chart.ParallelCategories( + dimensions = dims, + ?Name = Name, + ?Counts = Counts, + ?LineColor = LineColor, + ?LineShape = LineShape, + ?LineColorScale = LineColorScale, + ?ShowLineColorScale = ShowLineColorScale, + ?ReverseLineColorScale = ReverseLineColorScale, + ?Line = Line, + ?Arrangement = Arrangement, + ?BundleColors = BundleColors, + ?SortPaths = SortPaths, + ?LabelFont = LabelFont, + ?TickFont = TickFont, + ?UseDefaults = UseDefaults + ) + /// /// Creates a sankey diagram. /// @@ -364,6 +481,7 @@ module ChartDomain_Relations = /// Sets the orientation of the Sankey diagram. /// Sets the text font of this trace. /// If value is `snap` (the default), the node arrangement is assisted by automatic snapping of elements to preserve space between nodes specified via `nodepad`. If value is `perpendicular`, the nodes can only move along a line perpendicular to the flow. If value is `freeform`, the nodes can freely move on the plane. If value is `fixed`, the nodes are stationary. + /// Sets the horizontal alignment of the nodes in the Sankey diagram. If value is `justify` (the default), the nodes are spread to fill the width. If value is `left`, `right`, or `center`, the nodes are aligned accordingly. /// Sets the value formatting rule using d3 formatting mini-languages which are very similar to those in Python. For numbers, see: https://github.com/d3/d3-format/tree/v1.4.5#d3-format. /// Adds a unit to follow the value in the hover tooltip. Add a space if a separation is necessary from the value. /// If set to false, ignore the global default settings set in `Defaults` @@ -388,6 +506,7 @@ module ChartDomain_Relations = ?Orientation: StyleParam.Orientation, ?TextFont: Font, ?Arrangement: StyleParam.CategoryArrangement, + ?NodeAlign: StyleParam.SankeyNodeAlign, ?ValueFormat: string, ?ValueSuffix: string, ?UseDefaults: bool @@ -400,6 +519,7 @@ module ChartDomain_Relations = SankeyNodes.init ( Label = nodeLabels, Line = nodeOutline, + ?Align = NodeAlign, ?Color = NodeColor, ?Thickness = NodeThickness, ?Groups = NodeGroups diff --git a/src/Plotly.NET/CommonAbstractions/StyleParams.fs b/src/Plotly.NET/CommonAbstractions/StyleParams.fs index 77438ba31..74c91ed89 100644 --- a/src/Plotly.NET/CommonAbstractions/StyleParams.fs +++ b/src/Plotly.NET/CommonAbstractions/StyleParams.fs @@ -2684,6 +2684,24 @@ module StyleParam = // #S# //-------------------------- + [] + type SankeyNodeAlign = + | Left + | Right + | Center + | Justify + + static member toString = + function + | Left -> "left" + | Right -> "right" + | Center -> "center" + | Justify -> "justify" + + static member convert = SankeyNodeAlign.toString >> box + override this.ToString() = this |> SankeyNodeAlign.toString + member this.Convert() = this |> SankeyNodeAlign.convert + [] type ScaleAnchor = | False diff --git a/src/Plotly.NET/RELEASE_NOTES.md b/src/Plotly.NET/RELEASE_NOTES.md index 4dbfbb181..d9743ba31 100644 --- a/src/Plotly.NET/RELEASE_NOTES.md +++ b/src/Plotly.NET/RELEASE_NOTES.md @@ -10,12 +10,19 @@ As a consequence, the html dsl dependency switches back from `Giraffe.ViewEngine - Bump bundled plotly.js to **2.28.0** -- [#441](https://github.com/plotly/Plotly.NET/issues/441): **Encoded typed array support** — plotly.js 2.28 introduced base64-encoded typed arrays as a high-performance alternative to JSON arrays for trace data fields. Plotly.NET now exposes this fully: +- [#441](https://github.com/plotly/Plotly.NET/issues/441): **Encoded typed array support** — plotly.js 2.28 introduced a base64 representation for numeric arrays. Plotly.NET supports it for selected trace fields and chart constructors: - New `EncodedTypedArray` type (in `Plotly.NET`) carrying a base64 payload (`bdata`), a dtype tag (`dtype`), and an optional shape for multi-dimensional data. Supported dtypes: `Float64`, `Float32`, `Int32`, `UInt32`, `Int16`, `UInt16`, `Int8`, `UInt8`, `UInt8Clamped`. - Convenience constructors: `EncodedTypedArray.ofFloat64Array`, `ofFloat32Array`, `ofInt32Array`, `ofUInt32Array`, `ofInt16Array`, `ofUInt16Array`, `ofInt8Array`, `ofUInt8Array`, `ofUInt8ClampedArray` — all accept a 1-D .NET array and an optional `shape` parameter for multi-dimensional layouts. - - Encoded fields added to **all trace style modules** (`Trace2DStyle`, `Trace3DStyle`, `TracePolarStyle`, `TraceGeoStyle`, `TraceMapboxStyle`, `TraceTernaryStyle`, `TraceCarpetStyle`, `TraceDomainStyle`, `TraceSmithStyle`), covering data arrays (`XEncoded`, `YEncoded`, `ZEncoded`, etc.), metadata arrays (`IdsEncoded`, `CustomDataEncoded`, `MultiTextEncoded`, `SelectedPointsEncoded`), error bar arrays (`ArrayEncoded`, `ArrayminusEncoded`), and trace-specific fields (e.g. `Q1Encoded`/`MedianEncoded`/`Q3Encoded` on BoxPlot, `OpenEncoded`/`HighEncoded`/`LowEncoded`/`CloseEncoded` on OHLC/Candlestick, `OpacityScaleEncoded` on Surface/Volume/IsoSurface, `IntensityEncoded`/`IEncoded`/`JEncoded`/`KEncoded` on Mesh3D, dimension `ValuesEncoded` on Splom/ParallelCoord). - - Encoded overloads added to **all `Chart` module root functions** (e.g. `Chart.Scatter`, `Chart.Bar`, `Chart.Waterfall`, `Chart.Histogram`, `Chart.BoxPlot`, `Chart.Violin`, `Chart.OHLC`, `Chart.Candlestick`, `Chart.Splom`, `Chart.Histogram2D`, `Chart.Heatmap`, `Chart.Contour`, `Chart.Scatter3D`, `Chart.Surface`, `Chart.Mesh3D`, `Chart.Cone`, `Chart.StreamTube`, `Chart.Volume`, `Chart.IsoSurface`, `Chart.ScatterPolar`, `Chart.BarPolar`, `Chart.ScatterGeo`, `Chart.ChoroplethMap`, `Chart.ScatterMapbox`, `Chart.ChoroplethMapbox`, `Chart.DensityMapbox`, `Chart.ScatterTernary`, `Chart.Carpet`, `Chart.ScatterCarpet`, `Chart.ContourCarpet`, `Chart.ScatterSmith`, `Chart.Pie`, `Chart.FunnelArea`, `Chart.Sunburst`, `Chart.Treemap`, `Chart.Icicle`) and to all **H1/H2 convenience helpers** (e.g. `Chart.Point`, `Chart.Line`, `Chart.Spline`, `Chart.Bubble`, `Chart.Area`, `Chart.SplineArea`, `Chart.StackedArea`, `Chart.Range`, `Chart.Funnel`, `Chart.Histogram`, `Chart.StackedBar`, `Chart.PointDensity`, `Chart.PointPolar`, `Chart.PointGeo`, `Chart.PointMapbox`, `Chart.PointTernary`, `Chart.PointSmith`, `Chart.PointCarpet`, `Chart.Doughnut`). + - Encoded fields added across the trace style modules (`Trace2DStyle`, `Trace3DStyle`, `TracePolarStyle`, `TraceGeoStyle`, `TraceMapboxStyle`, `TraceTernaryStyle`, `TraceCarpetStyle`, `TraceDomainStyle`, `TraceSmithStyle`), covering data arrays (`XEncoded`, `YEncoded`, `ZEncoded`, etc.), metadata arrays (`IdsEncoded`, `CustomDataEncoded`, `MultiTextEncoded`, `SelectedPointsEncoded`), error bar arrays (`ArrayEncoded`, `ArrayminusEncoded`), and trace-specific fields (e.g. `Q1Encoded`/`MedianEncoded`/`Q3Encoded` on BoxPlot, `OpenEncoded`/`HighEncoded`/`LowEncoded`/`CloseEncoded` on OHLC/Candlestick, `OpacityScaleEncoded` on Surface/Volume/IsoSurface, `IntensityEncoded`/`IEncoded`/`JEncoded`/`KEncoded` on Mesh3D, dimension `ValuesEncoded` on Splom/ParallelCoord). + - Encoded overloads added to **selected F# `Chart` root functions** (e.g. `Chart.Scatter`, `Chart.Bar`, `Chart.Waterfall`, `Chart.Histogram`, `Chart.BoxPlot`, `Chart.Violin`, `Chart.OHLC`, `Chart.Candlestick`, `Chart.Splom`, `Chart.Histogram2D`, `Chart.Heatmap`, `Chart.Contour`, `Chart.Scatter3D`, `Chart.Surface`, `Chart.Mesh3D`, `Chart.Cone`, `Chart.StreamTube`, `Chart.Volume`, `Chart.IsoSurface`, `Chart.ScatterPolar`, `Chart.BarPolar`, `Chart.ScatterGeo`, `Chart.ChoroplethMap`, `Chart.ScatterMapbox`, `Chart.ChoroplethMapbox`, `Chart.DensityMapbox`, `Chart.ScatterTernary`, `Chart.Carpet`, `Chart.ScatterCarpet`, `Chart.ContourCarpet`, `Chart.ScatterSmith`, `Chart.Pie`, `Chart.FunnelArea`, `Chart.Sunburst`, `Chart.Treemap`, `Chart.Icicle`) and selected derived convenience helpers (e.g. `Chart.Point`, `Chart.Line`, `Chart.Spline`, `Chart.Bubble`, `Chart.Area`, `Chart.SplineArea`, `Chart.StackedArea`, `Chart.Range`, `Chart.Funnel`, `Chart.Histogram`, `Chart.StackedBar`, `Chart.PointDensity`, `Chart.PointPolar`, `Chart.PointGeo`, `Chart.PointMapbox`, `Chart.PointTernary`, `Chart.PointSmith`, `Chart.PointCarpet`, `Chart.Doughnut`). + + - Shared Sankey node/link objects accept encoded positions, source/target/value, and supported numeric metadata. Encoded values replace corresponding plain values when both are supplied in the same init/style call. Labels remain plain strings. + - One-dimensional samples do not need a shape; matrix inputs use an explicitly shaped flat payload. Strings, arbitrary objects, decimal, and 64-bit integer encoding are outside the supported dtype set. Image pixels and helpers that compute from plain inputs (such as Pareto, Residual, and AnnotatedHeatmap) have no direct encoded overload. + - The C# package exposes a selected subset of direct chart conveniences, documented in its release notes and the encoded-array guide. This release does not claim all-chart parity or measured encoding performance gains. + +- **Sankey node alignment** — `StyleParam.SankeyNodeAlign` supports Left, Right, Center, and Justify through `SankeyNodes` and the F# / C# chart conveniences. +- **Virtual-WebGL** — existing `DisplayOptions.AdditionalHeadTags` can load the optional WebGL 1 virtualization script before plotly.js; the encoded-array guide shows the script ordering. - [#500](https://github.com/plotly/Plotly.NET/pull/500): Internal refactor — split the monolithic `Chart.fs` into per-chart-family files (`Chart2D_Scatter.fs`, `Chart2D_Bar.fs`, etc.) for better maintainability. No API changes. @@ -183,4 +190,4 @@ For more insights why we do this, check out the conversation on this [issue](htt Other additions: -- [fix legend xanchor plotly attribute name](https://github.com/plotly/Plotly.NET/commit/0d612f9c847609c8f676ade0acfada11f137d833) ([#289](https://github.com/plotly/Plotly.NET/issues/289)) \ No newline at end of file +- [fix legend xanchor plotly attribute name](https://github.com/plotly/Plotly.NET/commit/0d612f9c847609c8f676ade0acfada11f137d833) ([#289](https://github.com/plotly/Plotly.NET/issues/289)) diff --git a/src/Plotly.NET/Traces/ObjectAbstractions/Sankey.fs b/src/Plotly.NET/Traces/ObjectAbstractions/Sankey.fs index 9ae58ac34..4ee9d7ce8 100644 --- a/src/Plotly.NET/Traces/ObjectAbstractions/Sankey.fs +++ b/src/Plotly.NET/Traces/ObjectAbstractions/Sankey.fs @@ -11,8 +11,11 @@ type SankeyNodes() = static member init ( + ?Align: StyleParam.SankeyNodeAlign, ?Color: Color, + ?ColorEncoded: EncodedTypedArray, ?CustomData: seq<#IConvertible>, + ?CustomDataEncoded: EncodedTypedArray, ?Groups: seq<#seq>, ?HoverInfo: StyleParam.HoverInfo, ?HoverLabel: Hoverlabel, @@ -23,13 +26,18 @@ type SankeyNodes() = ?Pad: int, ?Thickness: int, ?X: seq<#IConvertible>, - ?Y: seq<#IConvertible> + ?XEncoded: EncodedTypedArray, + ?Y: seq<#IConvertible>, + ?YEncoded: EncodedTypedArray ) = SankeyNodes() |> SankeyNodes.style ( + ?Align = Align, ?Color = Color, + ?ColorEncoded = ColorEncoded, ?CustomData = CustomData, + ?CustomDataEncoded = CustomDataEncoded, ?Groups = Groups, ?HoverInfo = HoverInfo, ?HoverLabel = HoverLabel, @@ -40,14 +48,18 @@ type SankeyNodes() = ?Pad = Pad, ?Thickness = Thickness, ?X = X, - ?Y = Y - + ?XEncoded = XEncoded, + ?Y = Y, + ?YEncoded = YEncoded ) static member style ( + ?Align: StyleParam.SankeyNodeAlign, ?Color: Color, + ?ColorEncoded: EncodedTypedArray, ?CustomData: seq<#IConvertible>, + ?CustomDataEncoded: EncodedTypedArray, ?Groups: seq<#seq>, ?HoverInfo: StyleParam.HoverInfo, ?HoverLabel: Hoverlabel, @@ -58,12 +70,17 @@ type SankeyNodes() = ?Pad: int, ?Thickness: int, ?X: seq<#IConvertible>, - ?Y: seq<#IConvertible> + ?XEncoded: EncodedTypedArray, + ?Y: seq<#IConvertible>, + ?YEncoded: EncodedTypedArray ) = fun (sankeyNodes: SankeyNodes) -> sankeyNodes + |> DynObj.withOptionalPropertyBy "align" Align StyleParam.SankeyNodeAlign.convert |> DynObj.withOptionalProperty "color" Color + |> DynObj.withOptionalProperty "color" ColorEncoded |> DynObj.withOptionalProperty "customdata" CustomData + |> DynObj.withOptionalProperty "customdata" CustomDataEncoded |> DynObj.withOptionalProperty "groups" Groups |> DynObj.withOptionalPropertyBy "hoverinfo" HoverInfo StyleParam.HoverInfo.convert |> DynObj.withOptionalProperty "hoverlabel" HoverLabel @@ -73,7 +90,9 @@ type SankeyNodes() = |> DynObj.withOptionalProperty "pad" Pad |> DynObj.withOptionalProperty "thickness" Thickness |> DynObj.withOptionalProperty "x" X + |> DynObj.withOptionalProperty "x" XEncoded |> DynObj.withOptionalProperty "y" Y + |> DynObj.withOptionalProperty "y" YEncoded type SankeyLinkColorscale() = inherit DynamicObj() @@ -125,8 +144,10 @@ type SankeyLinks() = ( ?ArrowLen: int, ?Color: Color, + ?ColorEncoded: EncodedTypedArray, ?ColorScales: seq, ?CustomData: seq<#IConvertible>, + ?CustomDataEncoded: EncodedTypedArray, ?HoverInfo: StyleParam.HoverInfo, ?HoverLabel: Hoverlabel, ?HoverTemplate: string, @@ -134,16 +155,21 @@ type SankeyLinks() = ?Label: seq, ?Line: Line, ?Source: seq, + ?SourceEncoded: EncodedTypedArray, ?Target: seq, - ?Value: seq<#IConvertible> + ?TargetEncoded: EncodedTypedArray, + ?Value: seq<#IConvertible>, + ?ValueEncoded: EncodedTypedArray ) = SankeyLinks() |> SankeyLinks.style ( ?ArrowLen = ArrowLen, ?Color = Color, + ?ColorEncoded = ColorEncoded, ?ColorScales = ColorScales, ?CustomData = CustomData, + ?CustomDataEncoded = CustomDataEncoded, ?HoverInfo = HoverInfo, ?HoverLabel = HoverLabel, ?HoverTemplate = HoverTemplate, @@ -151,17 +177,21 @@ type SankeyLinks() = ?Label = Label, ?Line = Line, ?Source = Source, + ?SourceEncoded = SourceEncoded, ?Target = Target, - ?Value = Value - + ?TargetEncoded = TargetEncoded, + ?Value = Value, + ?ValueEncoded = ValueEncoded ) static member style ( ?ArrowLen: int, ?Color: Color, + ?ColorEncoded: EncodedTypedArray, ?ColorScales: seq, ?CustomData: seq<#IConvertible>, + ?CustomDataEncoded: EncodedTypedArray, ?HoverInfo: StyleParam.HoverInfo, ?HoverLabel: Hoverlabel, ?HoverTemplate: string, @@ -169,22 +199,30 @@ type SankeyLinks() = ?Label: seq, ?Line: Line, ?Source: seq, + ?SourceEncoded: EncodedTypedArray, ?Target: seq, - ?Value: seq<#IConvertible> + ?TargetEncoded: EncodedTypedArray, + ?Value: seq<#IConvertible>, + ?ValueEncoded: EncodedTypedArray ) = fun (sankeyLinks: SankeyLinks) -> sankeyLinks |> DynObj.withOptionalProperty "arrowlen" ArrowLen |> DynObj.withOptionalProperty "color" Color + |> DynObj.withOptionalProperty "color" ColorEncoded |> DynObj.withOptionalProperty "colorscales" ColorScales |> DynObj.withOptionalProperty "customdata" CustomData + |> DynObj.withOptionalProperty "customdata" CustomDataEncoded |> DynObj.withOptionalPropertyBy "hoverinfo" HoverInfo StyleParam.HoverInfo.convert |> DynObj.withOptionalProperty "hoverlabel" HoverLabel |> DynObj.withOptionalSingleOrMultiProperty "hovertemplate" (HoverTemplate, MultiHoverTemplate) |> DynObj.withOptionalProperty "label" Label |> DynObj.withOptionalProperty "line" Line |> DynObj.withOptionalProperty "source" Source + |> DynObj.withOptionalProperty "source" SourceEncoded |> DynObj.withOptionalProperty "target" Target + |> DynObj.withOptionalProperty "target" TargetEncoded |> DynObj.withOptionalProperty "value" Value + |> DynObj.withOptionalProperty "value" ValueEncoded diff --git a/tests/Common/FSharpTestBase/TestCharts/UpstreamFeatures/2.28.fs b/tests/Common/FSharpTestBase/TestCharts/UpstreamFeatures/2.28.fs index d3cc0e96d..f535c1265 100644 --- a/tests/Common/FSharpTestBase/TestCharts/UpstreamFeatures/2.28.fs +++ b/tests/Common/FSharpTestBase/TestCharts/UpstreamFeatures/2.28.fs @@ -1043,3 +1043,153 @@ module ``Encoded typed arrays on carpet and domain traces`` = ) ) |> GenericChart.ofTraceObject true + +module ``Sankey node align`` = + + let ``Sankey with node align right`` = + let nodes = + SankeyNodes.init( + Label = ["A"; "B"; "C"], + Align = StyleParam.SankeyNodeAlign.Right + ) + let links = + SankeyLinks.init( + Source = [0; 1], + Target = [2; 2], + Value = [8; 4] + ) + Chart.Sankey(nodes, links, UseDefaults = false) + + let ``Sankey with node align via Chart overload`` = + Chart.Sankey( + nodeLabels = ["A"; "B"; "C"], + linkedNodeIds = [(0, 2); (1, 2)], + linkValues = [8; 4], + NodeAlign = StyleParam.SankeyNodeAlign.Left, + UseDefaults = false + ) + +module ``Sankey encoded node and link arrays`` = + + let ``Sankey with encoded node arrays`` = + let nodes = + SankeyNodes.init( + Label = ["A"; "B"; "C"], + ColorEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0 |], + CustomDataEncoded = EncodedTypedArray.ofFloat64Array [| 10.0; 20.0; 30.0 |], + XEncoded = EncodedTypedArray.ofFloat64Array [| 0.1; 0.5; 0.9 |], + YEncoded = EncodedTypedArray.ofFloat64Array [| 0.1; 0.5; 0.9 |] + ) + let links = + SankeyLinks.init( + Source = [0; 1], + Target = [2; 2], + Value = [8; 4] + ) + Chart.Sankey(nodes, links, UseDefaults = false) + + let ``Sankey with encoded link arrays`` = + let nodes = + SankeyNodes.init( + Label = ["A"; "B"; "C"] + ) + let links = + SankeyLinks.init( + SourceEncoded = EncodedTypedArray.ofInt32Array [| 0; 1 |], + TargetEncoded = EncodedTypedArray.ofInt32Array [| 2; 2 |], + ValueEncoded = EncodedTypedArray.ofFloat64Array [| 8.0; 4.0 |], + ColorEncoded = EncodedTypedArray.ofFloat64Array [| 1.0; 2.0 |], + CustomDataEncoded = EncodedTypedArray.ofFloat64Array [| 10.0; 20.0 |] + ) + Chart.Sankey(nodes, links, UseDefaults = false) + +module ``Sankey encoded precedence`` = + + // Deliberately different plain inputs prove that encoded values replace them. + let private styleNodes = + SankeyNodes.style( + Align = StyleParam.SankeyNodeAlign.Right, + Label = [ "A"; "B"; "C" ], + Color = Color.fromString "red", + ColorEncoded = EncodedTypedArray.ofFloat32Array [| 1.0f; 2.0f; 3.0f |], + CustomData = [ 99; 99; 99 ], + CustomDataEncoded = EncodedTypedArray.ofInt32Array [| 10; 20; 30 |], + X = [ 0.9; 0.9; 0.9 ], + XEncoded = EncodedTypedArray.ofFloat64Array [| 0.0; 0.0; 1.0 |], + Y = [ 0.9; 0.9; 0.9 ], + YEncoded = EncodedTypedArray.ofFloat64Array [| 0.25; 0.75; 0.5 |] + ) + + let private styleLinks = + SankeyLinks.style( + Label = [ "A to C"; "B to C" ], + Color = Color.fromString "blue", + ColorEncoded = EncodedTypedArray.ofFloat32Array [| 4.0f; 5.0f |], + CustomData = [ 99; 99 ], + CustomDataEncoded = EncodedTypedArray.ofInt32Array [| 40; 50 |], + Source = [ 2; 2 ], + SourceEncoded = EncodedTypedArray.ofInt32Array [| 0; 1 |], + Target = [ 0; 0 ], + TargetEncoded = EncodedTypedArray.ofInt32Array [| 2; 2 |], + Value = [ 99.0; 99.0 ], + ValueEncoded = EncodedTypedArray.ofFloat64Array [| 8.0; 4.0 |] + ) + + let ``Sankey init prefers encoded node and link inputs`` = + let nodes = + SankeyNodes.init( + Align = StyleParam.SankeyNodeAlign.Right, + Label = [ "A"; "B"; "C" ], + Color = Color.fromString "red", + ColorEncoded = EncodedTypedArray.ofFloat32Array [| 1.0f; 2.0f; 3.0f |], + CustomData = [ 99; 99; 99 ], + CustomDataEncoded = EncodedTypedArray.ofInt32Array [| 10; 20; 30 |], + X = [ 0.9; 0.9; 0.9 ], + XEncoded = EncodedTypedArray.ofFloat64Array [| 0.0; 0.0; 1.0 |], + Y = [ 0.9; 0.9; 0.9 ], + YEncoded = EncodedTypedArray.ofFloat64Array [| 0.25; 0.75; 0.5 |] + ) + let links = + SankeyLinks.init( + Label = [ "A to C"; "B to C" ], + Color = Color.fromString "blue", + ColorEncoded = EncodedTypedArray.ofFloat32Array [| 4.0f; 5.0f |], + CustomData = [ 99; 99 ], + CustomDataEncoded = EncodedTypedArray.ofInt32Array [| 40; 50 |], + Source = [ 2; 2 ], + SourceEncoded = EncodedTypedArray.ofInt32Array [| 0; 1 |], + Target = [ 0; 0 ], + TargetEncoded = EncodedTypedArray.ofInt32Array [| 2; 2 |], + Value = [ 99.0; 99.0 ], + ValueEncoded = EncodedTypedArray.ofFloat64Array [| 8.0; 4.0 |] + ) + Chart.Sankey(nodes, links, UseDefaults = false) + + let ``Sankey style prefers encoded node and link inputs`` = + let nodes = + SankeyNodes.init(Label = [ "old" ], X = [ 0.5 ], Y = [ 0.5 ]) + |> styleNodes + let links = + SankeyLinks.init(Source = [ 0 ], Target = [ 1 ], Value = [ 100.0 ]) + |> styleLinks + Chart.Sankey(nodes, links, UseDefaults = false) + +module ``ParallelCoord and ParallelCategories encoded dimensions`` = + + let ``ParallelCoord with encoded dimensions`` = + Chart.ParallelCoord( + keyValuesEncoded = [ + "A", EncodedTypedArray.ofFloat64Array [| 1.0; 2.0; 3.0 |] + "B", EncodedTypedArray.ofFloat64Array [| 4.0; 5.0; 6.0 |] + ], + UseDefaults = false + ) + + let ``ParallelCategories with encoded dimensions`` = + Chart.ParallelCategories( + keyValuesEncoded = [ + "X", EncodedTypedArray.ofInt32Array [| 0; 1; 0 |] + "Y", EncodedTypedArray.ofInt32Array [| 1; 0; 1 |] + ], + UseDefaults = false + ) diff --git a/tests/ConsoleApps/FSharpConsole/Program.fs b/tests/ConsoleApps/FSharpConsole/Program.fs index 486cda48d..203b2690a 100644 --- a/tests/ConsoleApps/FSharpConsole/Program.fs +++ b/tests/ConsoleApps/FSharpConsole/Program.fs @@ -3,6 +3,13 @@ open Plotly.NET [] let main _ = + let encodedHeatmap = + Chart.Heatmap( + zEncoded = EncodedTypedArray.ofFloat64Array([| 1.0; 2.0; 3.0; 4.0; 5.0; 6.0; 7.0; 8.0; 9.0 |], shape = [ 3; 3 ]), + Name = "encoded heatmap", + UseDefaults = false + ) + // sample sets with overlapping members to exercise every venn region let setA = [| "1"; "2"; "3"; "4"; "5"; "6"; "11" |] let setB = [| "1"; "2"; "3"; "7"; "8"; "9"; "10"; "12"; "13" |] @@ -43,6 +50,7 @@ let main _ = UseDefaults = true ) + encodedHeatmap |> Chart.show twoSetVenn |> Chart.show threeSetVenn |> Chart.show upset |> Chart.show diff --git a/tests/CoreTests/CoreTests/UpstreamFeatures/2.28.fs b/tests/CoreTests/CoreTests/UpstreamFeatures/2.28.fs index 40a907ef2..dfd8c2820 100644 --- a/tests/CoreTests/CoreTests/UpstreamFeatures/2.28.fs +++ b/tests/CoreTests/CoreTests/UpstreamFeatures/2.28.fs @@ -5,6 +5,36 @@ open Expecto open TestUtils.HtmlCodegen open PlotlyJS_2_28_TestCharts +module ``Sankey encoded precedence`` = + + // Generated from the shared init fixture through the canonical baseline harness. + let private expectedData = """[{"type":"sankey","node":{"align":"right","color":{"bdata":"AACAPwAAAEAAAEBA","dtype":"f4"},"customdata":{"bdata":"CgAAABQAAAAeAAAA","dtype":"i4"},"label":["A","B","C"],"x":{"bdata":"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAPA/","dtype":"f8"},"y":{"bdata":"AAAAAAAA0D8AAAAAAADoPwAAAAAAAOA/","dtype":"f8"}},"link":{"color":{"bdata":"AACAQAAAoEA=","dtype":"f4"},"customdata":{"bdata":"KAAAADIAAAA=","dtype":"i4"},"label":["A to C","B to C"],"source":{"bdata":"AAAAAAEAAAA=","dtype":"i4"},"target":{"bdata":"AgAAAAIAAAA=","dtype":"i4"},"value":{"bdata":"AAAAAAAAIEAAAAAAAAAQQA==","dtype":"f8"}}}]""" + + [] + let ``Sankey nested encoded precedence tests`` = + testList "UpstreamFeatures.PlotlyJS_2_28.Sankey precedence" [ + for name, chart in [ + "init", ``Sankey encoded precedence``.``Sankey init prefers encoded node and link inputs`` + "style", ``Sankey encoded precedence``.``Sankey style prefers encoded node and link inputs`` + ] do + testCase (name + " replaces plain nested values with encoded values") (fun () -> + for render in [ Plotly.NET.GenericChart.toChartHTML; Plotly.NET.GenericChart.toEmbeddedHTML ] do + let html = render chart + let data = System.Text.RegularExpressions.Regex.Match(html, @"var data = (.*?);") + Expect.isTrue data.Success "Generated HTML contains chart data" + let settings = + Newtonsoft.Json.Linq.JsonLoadSettings( + DuplicatePropertyNameHandling = Newtonsoft.Json.Linq.DuplicatePropertyNameHandling.Error + ) + let actual = Newtonsoft.Json.Linq.JArray.Parse(data.Groups[1].Value, settings) + let expected = Newtonsoft.Json.Linq.JArray.Parse(expectedData) + Expect.isTrue + (Newtonsoft.Json.Linq.JToken.DeepEquals(actual, expected)) + (sprintf "Encoded node/link properties replace plain inputs; labels and alignment survive. Actual: %O" actual) + ) + ] + + module ``Encoded typed arrays`` = [] @@ -905,3 +935,82 @@ module ``Encoded typed arrays on carpet and domain traces`` = ) ] ] + +module ``Sankey node align`` = + + [] + let ``Sankey node align tests`` = + testList "UpstreamFeatures.PlotlyJS_2_28" [ + testList "Sankey node align" [ + testCase "Sankey with node align right serializes align property on node object" (fun () -> + "\"node\":{\"align\":\"right\",\"label\":[\"A\",\"B\",\"C\"]}" + |> chartGeneratedContains ``Sankey node align``.``Sankey with node align right`` + ) + testCase "Sankey via Chart overload serializes align property on node object" (fun () -> + "\"node\":{\"align\":\"left\",\"label\":[\"A\",\"B\",\"C\"],\"line\":{}}" + |> chartGeneratedContains ``Sankey node align``.``Sankey with node align via Chart overload`` + ) + ] + ] + +module ``Sankey encoded node and link arrays`` = + + [] + let ``Sankey encoded node and link array tests`` = + testList "UpstreamFeatures.PlotlyJS_2_28" [ + testList "Sankey encoded node and link arrays" [ + testCase "Sankey node color is serialized as encoded object" (fun () -> + "\"color\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded node arrays`` + ) + testCase "Sankey node customdata is serialized as encoded object" (fun () -> + "\"customdata\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded node arrays`` + ) + testCase "Sankey node x is serialized as encoded object" (fun () -> + "\"x\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded node arrays`` + ) + testCase "Sankey node y is serialized as encoded object" (fun () -> + "\"y\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded node arrays`` + ) + testCase "Sankey link source is serialized as encoded object" (fun () -> + "\"source\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded link arrays`` + ) + testCase "Sankey link target is serialized as encoded object" (fun () -> + "\"target\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded link arrays`` + ) + testCase "Sankey link value is serialized as encoded object" (fun () -> + "\"value\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded link arrays`` + ) + testCase "Sankey link color is serialized as encoded object" (fun () -> + "\"color\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded link arrays`` + ) + testCase "Sankey link customdata is serialized as encoded object" (fun () -> + "\"customdata\":{\"bdata\":" + |> chartGeneratedContains ``Sankey encoded node and link arrays``.``Sankey with encoded link arrays`` + ) + ] + ] + +module ``ParallelCoord and ParallelCategories encoded dimensions`` = + + [] + let ``ParallelCoord and ParallelCategories encoded dimension tests`` = + testList "UpstreamFeatures.PlotlyJS_2_28" [ + testList "ParallelCoord and ParallelCategories encoded dimensions" [ + testCase "ParallelCoord dimension A values are serialized as encoded object" (fun () -> + "\"values\":{\"bdata\":" + |> chartGeneratedContains ``ParallelCoord and ParallelCategories encoded dimensions``.``ParallelCoord with encoded dimensions`` + ) + testCase "ParallelCategories dimension X values are serialized as encoded object" (fun () -> + "\"values\":{\"bdata\":" + |> chartGeneratedContains ``ParallelCoord and ParallelCategories encoded dimensions``.``ParallelCategories with encoded dimensions`` + ) + ] + ] diff --git a/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/ChartDomain/FamilyTests.cs b/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/ChartDomain/FamilyTests.cs index b7896ad78..3b5756c0f 100644 --- a/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/ChartDomain/FamilyTests.cs +++ b/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/ChartDomain/FamilyTests.cs @@ -191,8 +191,11 @@ public class SankeyTests private static Plotly.NET.GenericChart CreateChart() => Chart.Sankey( nodes: SankeyNodes.init( + Align: default, Color: default, + ColorEncoded: default, CustomData: default, + CustomDataEncoded: default, Groups: default, HoverInfo: default, HoverLabel: default, @@ -203,13 +206,17 @@ private static Plotly.NET.GenericChart CreateChart() => Pad: default, Thickness: default, X: default, - Y: default + XEncoded: default, + Y: default, + YEncoded: default ), links: SankeyLinks.init( ArrowLen: default, Color: default, + ColorEncoded: default, ColorScales: default, CustomData: default, + CustomDataEncoded: default, HoverInfo: default, HoverLabel: default, HoverTemplate: default, @@ -217,8 +224,11 @@ private static Plotly.NET.GenericChart CreateChart() => Label: default, Line: default, Source: new[] { 0, 1, 1 }, + SourceEncoded: default, Target: new[] { 2, 2, 3 }, - Value: new[] { 1, 2, 5 } + TargetEncoded: default, + Value: new[] { 1, 2, 5 }, + ValueEncoded: default ), UseDefaults: false ); diff --git a/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/UpstreamFeatures/EncodedArrayExamplesTests.cs b/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/UpstreamFeatures/EncodedArrayExamplesTests.cs new file mode 100644 index 000000000..a18d5f7d9 --- /dev/null +++ b/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/UpstreamFeatures/EncodedArrayExamplesTests.cs @@ -0,0 +1,76 @@ +using System.Collections.Generic; +using Microsoft.FSharp.Core; +using Plotly.NET; +using Plotly.NET.TraceObjects; +using Xunit; +using Chart = Plotly.NET.CSharp.Chart; + +namespace CSharp.Tests.HtmlCodegen.UpstreamFeatures; + +public class EncodedArrayExamplesTests +{ + [Fact] + public void DocumentedScatterExamplePreservesOneDimensionalArrays() + { + // Keep this construction in sync with docs/general/encoded-arrays.fsx. + var x = EncodedTypedArray.ofInt32Array(new[] { 0, 1, 2 }, shape: default); + var y = EncodedTypedArray.ofFloat32Array(new[] { 1.5f, 4.5f, 2.5f }, shape: default); + var scatter = Chart.Scatter( + xEncoded: x, yEncoded: y, mode: StyleParam.Mode.Markers, + Name: "encoded scatter", UseDefaults: false); + + TestUtils.ChartGeneratedSectionEquals(scatter, ChartMarkupSection.Data, + """var data = [{"type":"scatter","name":"encoded scatter","mode":"markers","x":{"bdata":"AAAAAAEAAAACAAAA","dtype":"i4"},"y":{"bdata":"AADAPwAAkEAAACBA","dtype":"f4"},"marker":{},"line":{}}];"""); + } + + [Fact] + public void DocumentedHeatmapExamplePreservesRowsColumnsAndAxes() + { + // Keep this construction in sync with docs/general/encoded-arrays.fsx. + var z = EncodedTypedArray.ofFloat32Array( + new[] { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f }, + shape: new FSharpOption>(new[] { 2, 3 })); + var heatmap = Chart.Heatmap( + zEncoded: z, + xEncoded: EncodedTypedArray.ofInt32Array(new[] { 10, 20, 30 }, shape: default), + yEncoded: EncodedTypedArray.ofInt32Array(new[] { 100, 200 }, shape: default), + ReverseYAxis: true, ShowScale: false, UseDefaults: false); + + TestUtils.ChartGeneratedSectionEquals(heatmap, ChartMarkupSection.Data, + """var data = [{"type":"heatmap","x":{"bdata":"CgAAABQAAAAeAAAA","dtype":"i4"},"y":{"bdata":"ZAAAAMgAAAA=","dtype":"i4"},"z":{"bdata":"AACAPwAAAEAAAEBAAACAQAAAoEAAAMBA","dtype":"f4","shape":"2,3"},"showscale":false}];"""); + TestUtils.ChartGeneratedSectionEquals(heatmap, ChartMarkupSection.Layout, + """var layout = {"yaxis":{"autorange":"reversed"}};"""); + } + + [Fact] + public void ExistingSplomWrapperAcceptsEncodedDimensionsAndPreservesOptions() + { + var chart = Chart.Splom( + dimensions: new[] + { + Dimension.initSplom( + AxisMatches: true, + AxisType: default, + Label: "A", + Name: default, + TemplateItemName: default, + Values: new[] { 99, 99, 99 }, + ValuesEncoded: EncodedTypedArray.ofInt32Array(new[] { 0, 1, 2 }, shape: default), + Visible: default), + Dimension.initSplom( + AxisMatches: default, + AxisType: default, + Label: "B", + Name: default, + TemplateItemName: default, + Values: default, + ValuesEncoded: EncodedTypedArray.ofFloat32Array(new[] { 1.5f, 4.5f, 2.5f }, shape: default), + Visible: default) + }, + Name: "encoded splom", ShowUpperHalf: false, ShowDiagonal: true, + MarkerColor: Color.fromString("blue"), UseDefaults: false); + + TestUtils.ChartGeneratedSectionEquals(chart, ChartMarkupSection.Data, + """var data = [{"type":"splom","name":"encoded splom","dimensions":[{"label":"A","values":{"bdata":"AAAAAAEAAAACAAAA","dtype":"i4"},"axis":{"matches":true}},{"label":"B","values":{"bdata":"AADAPwAAkEAAACBA","dtype":"f4"},"axis":{}}],"marker":{"color":"blue"},"diagonal":{"visible":true},"showupperhalf":false}];"""); + } +} diff --git a/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/UpstreamFeatures/PlotlyJS228Tests.cs b/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/UpstreamFeatures/PlotlyJS228Tests.cs new file mode 100644 index 000000000..386187177 --- /dev/null +++ b/tests/ExtensionLibsTests/CSharpTests/htmlcodegen/UpstreamFeatures/PlotlyJS228Tests.cs @@ -0,0 +1,253 @@ +using System; +using System.Collections.Generic; +using Microsoft.FSharp.Core; +using Plotly.NET; +using Plotly.NET.TraceObjects; +using Xunit; +using Chart = Plotly.NET.CSharp.Chart; + +namespace CSharp.Tests.HtmlCodegen.UpstreamFeatures; + +public class PlotlyJS228Tests +{ + [Theory] + [InlineData("Scatter")] + [InlineData("Bar")] + [InlineData("Column")] + [InlineData("StackedBar")] + [InlineData("StackedColumn")] + [InlineData("BarMinimal")] + [InlineData("ColumnMinimal")] + [InlineData("StackedBarMinimal")] + [InlineData("StackedColumnMinimal")] + [InlineData("Heatmap")] + [InlineData("HeatmapMinimal")] + [InlineData("Histogram2D")] + [InlineData("Histogram2DMinimal")] + [InlineData("Scatter3D")] + [InlineData("ParallelCoord")] + [InlineData("ParallelCategories")] + [InlineData("Sankey")] + [InlineData("SankeyEncoded")] + public void ConstructorsPreserveEncodedPayloadsAndForwardedOptions(string chartName) + { + var (chart, expectedData, expectedLayout) = CreateCase(chartName); + + TestUtils.ChartGeneratedSectionEquals(chart, ChartMarkupSection.Data, expectedData); + TestUtils.ChartGeneratedSectionEquals(chart, ChartMarkupSection.Layout, expectedLayout); + } + + private static EncodedTypedArray X() => + EncodedTypedArray.ofInt32Array(new[] { 0, 2 }, shape: default); + + private static EncodedTypedArray Y() => + EncodedTypedArray.ofFloat32Array(new[] { 1.5f, 4.5f }, shape: default); + + private static EncodedTypedArray Z() => + EncodedTypedArray.ofInt16Array(new short[] { 5, 7 }, shape: default); + + private static EncodedTypedArray Widths() => + EncodedTypedArray.ofFloat32Array(new[] { 0.25f, 0.5f }, shape: default); + + private static EncodedTypedArray Matrix() => + EncodedTypedArray.ofFloat32Array( + new[] { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f, 6.0f }, + shape: new FSharpOption>(new[] { 2, 3 }) + ); + + // Baselines generated through tools/chart-baseline-generation/generate-chart-markup.fsx + // using these C# constructors and GenericChart.toChartHTML. + private static (GenericChart Chart, string Data, string Layout) CreateCase(string chartName) => + chartName switch + { + "Scatter" => ( + Chart.Scatter( + xEncoded: X(), yEncoded: Y(), mode: StyleParam.Mode.Lines_Markers, + Name: "encoded scatter", ShowLegend: false, + MarkerColor: Color.fromString("red"), LineWidth: 2.0, + UseWebGL: true, UseDefaults: false), + """var data = [{"type":"scattergl","name":"encoded scatter","showlegend":false,"mode":"lines+markers","x":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"marker":{"color":"red"},"line":{"width":2.0}}];""", + """var layout = {};""" + ), + + "Bar" => ( + Chart.Bar( + valuesEncoded: Y(), KeysEncoded: X(), Base: 0, + MultiWidthEncoded: Widths(), MarkerColor: Color.fromString("red"), + UseDefaults: false), + """var data = [{"type":"bar","x":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"y":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"base":0,"width":{"bdata":"AACAPgAAAD8=","dtype":"f4"},"orientation":"h","marker":{"color":"red","pattern":{}}}];""", + """var layout = {};""" + ), + + "Column" => ( + Chart.Column( + valuesEncoded: Y(), KeysEncoded: X(), Base: 0, + MultiWidthEncoded: Widths(), MarkerColor: Color.fromString("red"), + UseDefaults: false), + """var data = [{"type":"bar","x":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"base":0,"width":{"bdata":"AACAPgAAAD8=","dtype":"f4"},"orientation":"v","marker":{"color":"red","pattern":{}}}];""", + """var layout = {};""" + ), + + "StackedBar" => ( + Chart.StackedBar( + valuesEncoded: Y(), KeysEncoded: X(), + MultiWidthEncoded: Widths(), MarkerColor: Color.fromString("red"), + UseDefaults: false), + """var data = [{"type":"bar","x":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"y":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"width":{"bdata":"AACAPgAAAD8=","dtype":"f4"},"orientation":"h","marker":{"color":"red","pattern":{}}}];""", + """var layout = {"barmode":"stack"};""" + ), + + "StackedColumn" => ( + Chart.StackedColumn( + valuesEncoded: Y(), KeysEncoded: X(), + MultiWidthEncoded: Widths(), MarkerColor: Color.fromString("red"), + UseDefaults: false), + """var data = [{"type":"bar","x":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"width":{"bdata":"AACAPgAAAD8=","dtype":"f4"},"orientation":"v","marker":{"color":"red","pattern":{}}}];""", + """var layout = {"barmode":"stack"};""" + ), + + "BarMinimal" => ( + Chart.Bar(valuesEncoded: Y(), UseDefaults: false), + """var data = [{"type":"bar","x":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"orientation":"h","marker":{"pattern":{}}}];""", + """var layout = {};""" + ), + + "ColumnMinimal" => ( + Chart.Column(valuesEncoded: Y(), UseDefaults: false), + """var data = [{"type":"bar","y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"orientation":"v","marker":{"pattern":{}}}];""", + """var layout = {};""" + ), + + "StackedBarMinimal" => ( + Chart.StackedBar(valuesEncoded: Y(), UseDefaults: false), + """var data = [{"type":"bar","x":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"orientation":"h","marker":{"pattern":{}}}];""", + """var layout = {"barmode":"stack"};""" + ), + + "StackedColumnMinimal" => ( + Chart.StackedColumn(valuesEncoded: Y(), UseDefaults: false), + """var data = [{"type":"bar","y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"orientation":"v","marker":{"pattern":{}}}];""", + """var layout = {"barmode":"stack"};""" + ), + + "Heatmap" => ( + Chart.Heatmap( + zEncoded: Matrix(), + xEncoded: EncodedTypedArray.ofInt32Array(new[] { 0, 1, 2 }, shape: default), + yEncoded: EncodedTypedArray.ofInt32Array(new[] { 10, 20 }, shape: default), + XGap: 2, ShowScale: false, ReverseYAxis: true, UseDefaults: false), + """var data = [{"type":"heatmap","x":{"bdata":"AAAAAAEAAAACAAAA","dtype":"i4"},"xgap":2,"y":{"bdata":"CgAAABQAAAA=","dtype":"i4"},"z":{"bdata":"AACAPwAAAEAAAEBAAACAQAAAoEAAAMBA","dtype":"f4","shape":"2,3"},"showscale":false}];""", + """var layout = {"yaxis":{"autorange":"reversed"}};""" + ), + + "HeatmapMinimal" => ( + Chart.Heatmap(zEncoded: Matrix(), UseDefaults: false), + """var data = [{"type":"heatmap","z":{"bdata":"AACAPwAAAEAAAEBAAACAQAAAoEAAAMBA","dtype":"f4","shape":"2,3"}}];""", + """var layout = {};""" + ), + + "Histogram2D" => ( + Chart.Histogram2D( + xEncoded: X(), yEncoded: Y(), zEncoded: Z(), + HistFunc: StyleParam.HistFunc.Sum, NBinsX: 3, ShowScale: false, + UseDefaults: false), + """var data = [{"type":"histogram2d","x":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"z":{"bdata":"BQAHAA==","dtype":"i2"},"histfunc":"sum","nbinsx":3,"showscale":false}];""", + """var layout = {};""" + ), + + "Histogram2DMinimal" => ( + Chart.Histogram2D(xEncoded: X(), yEncoded: Y(), UseDefaults: false), + """var data = [{"type":"histogram2d","x":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"y":{"bdata":"AADAPwAAkEA=","dtype":"f4"}}];""", + """var layout = {};""" + ), + + "Scatter3D" => ( + Chart.Scatter3D( + xEncoded: X(), yEncoded: Y(), zEncoded: Z(), mode: StyleParam.Mode.Markers, + MarkerColor: Color.fromString("blue"), + CameraProjectionType: StyleParam.CameraProjectionType.Orthographic, + UseDefaults: false), + """var data = [{"type":"scatter3d","mode":"markers","x":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"y":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"z":{"bdata":"BQAHAA==","dtype":"i2"},"marker":{"color":"blue"},"line":{}}];""", + """var layout = {"scene":{"camera":{"projection":{"type":"orthographic"}}}};""" + ), + + "ParallelCoord" => ( + Chart.ParallelCoord( + keyValuesEncoded: new[] { ("A", X()), ("B", Y()) }, + LabelAngle: 30, LineColor: Color.fromString("blue"), + ShowLineColorScale: false, UseDefaults: false), + """var data = [{"type":"parcoords","dimensions":[{"label":"A","values":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"axis":{}},{"label":"B","values":{"bdata":"AADAPwAAkEA=","dtype":"f4"},"axis":{}}],"line":{"color":"blue","showscale":false},"labelangle":30}];""", + """var layout = {};""" + ), + + "ParallelCategories" => ( + Chart.ParallelCategories( + keyValuesEncoded: new[] { ("A", X()), ("B", Z()) }, + Counts: 2, LineColor: Color.fromString("blue"), + Arrangement: StyleParam.CategoryArrangement.Fixed, BundleColors: false, + UseDefaults: false), + """var data = [{"type":"parcats","counts":2,"dimensions":[{"label":"A","values":{"bdata":"AAAAAAIAAAA=","dtype":"i4"},"axis":{}},{"label":"B","values":{"bdata":"BQAHAA==","dtype":"i2"},"axis":{}}],"line":{"color":"blue"},"arrangement":"fixed","bundlecolors":false}];""", + """var layout = {};""" + ), + + "Sankey" => ( + Chart.Sankey( + nodeLabels: new[] { "A", "B", "C" }, + linkedNodeIds: new[] { (0, 1), (1, 2) }, linkValues: new[] { 2, 3 }, + NodeAlign: StyleParam.SankeyNodeAlign.Left, NodeThickness: 20, + NodeColor: Color.fromString("red"), LinkColor: Color.fromString("blue"), + Arrangement: StyleParam.CategoryArrangement.Fixed, + ValueSuffix: " units", UseDefaults: false), + """var data = [{"type":"sankey","node":{"align":"left","color":"red","label":["A","B","C"],"line":{},"thickness":20},"link":{"color":"blue","line":{},"source":[0,1],"target":[1,2],"value":[2,3]},"arrangement":"fixed","valuesuffix":" units"}];""", + """var layout = {};""" + ), + + "SankeyEncoded" => ( + Chart.Sankey( + nodes: SankeyNodes.init( + Align: StyleParam.SankeyNodeAlign.Right, + Color: default, + ColorEncoded: default, + CustomData: default, + CustomDataEncoded: default, + Groups: default, + HoverInfo: default, + HoverLabel: default, + HoverTemplate: default, + MultiHoverTemplate: default, + Label: new[] { "A", "B", "C" }, + Line: default, + Pad: default, + Thickness: default, + X: default, + XEncoded: EncodedTypedArray.ofFloat32Array(new[] { 0.0f, 0.5f, 1.0f }, shape: default), + Y: default, + YEncoded: EncodedTypedArray.ofFloat32Array(new[] { 0.25f, 0.5f, 0.75f }, shape: default) + ), + links: SankeyLinks.init( + ArrowLen: default, + Color: default, + ColorEncoded: default, + ColorScales: default, + CustomData: default, + CustomDataEncoded: default, + HoverInfo: default, + HoverLabel: default, + HoverTemplate: default, + MultiHoverTemplate: default, + Label: default, + Line: default, + Source: default, + SourceEncoded: EncodedTypedArray.ofInt32Array(new[] { 0, 1 }, shape: default), + Target: default, + TargetEncoded: EncodedTypedArray.ofInt32Array(new[] { 1, 2 }, shape: default), + Value: default, + ValueEncoded: Y() + ), + ValueSuffix: " units", UseDefaults: false), + """var data = [{"type":"sankey","node":{"align":"right","label":["A","B","C"],"x":{"bdata":"AAAAAAAAAD8AAIA/","dtype":"f4"},"y":{"bdata":"AACAPgAAAD8AAEA/","dtype":"f4"}},"link":{"source":{"bdata":"AAAAAAEAAAA=","dtype":"i4"},"target":{"bdata":"AQAAAAIAAAA=","dtype":"i4"},"value":{"bdata":"AADAPwAAkEA=","dtype":"f4"}},"valuesuffix":" units"}];""", + """var layout = {};""" + ), + _ => throw new ArgumentOutOfRangeException(nameof(chartName), chartName, null) + }; +}