#r "nuget: Plotly.NET, 4.2.0"
#r "nuget: Plotly.NET.Interactive, 4.2.0"
Plotly.NET provides functions for generating and rendering plotly.js charts in .NET programming languages 📈🚀.
This documentation page is almost exclusively for the core F# API of Plotly.NET.
It should be easy to translate them into C#. However, as work on the idiomatic C# API progresses, we will provide native C# docs as well.
Plotly.NET consists of multiple packages. The two main ones are:
Plotly.NET.CSharp , native C# bindings that make the usage of Plotly.NET more idiomatic from C#. This is work in progress. Missing charts and/or styling must be done via the core API.
Plotly.NET packages are available on NuGet to plug into your favorite package manager.
dotnet CLI
dotnet add package Plotly.NET --version 4.2.0
paket CLI
paket add Plotly.NET --version 4.2.0
package manager
Install-Package Plotly.NET -Version 4.2.0
Or add the package reference directly to your .*proj
file:
<PackageReference Include="Plotly.NET" Version="4.2.0" />
You can include the package via an inline package reference:
#r "nuget: Plotly.NET, 4.2.0"
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:
#r "nuget: Plotly.NET.Interactive, 4.2.0"
Note:
Due to the currently fast development cycles of .NET Interactive, there might be increments in their versioning that render the current version of Plotly.NET.Interactive incompatible (example here).
If the interactive extension does not work, please file an issue and we will try to get it running again as soon as possible.
A possible fix for this is the inclusion of Dotnet.Interactive preview package sources. To use these, add the following lines before referencing Plotly.NET.Interactive:
no-hl
#i "nuget:https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet5/nuget/v3/index.json"
#i "nuget:https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json"
The general, high-level API of Plotly.NET implements the following visualization flow:
initialize a GenericChart
object from the data you want to visualize by using the respective Chart.*
function, optionally setting some specific style parameters
further style the chart with fine-grained control, e.g. by setting axis titles, tick intervals, etc.
display (in the browser or as cell result in a notebook) or save the chart
The Chart
module contains a lot of functions named after the type of chart they will create, e.g.
Chart.Point
will create a point chart, Chart.Scatter3d
wil create a 3D scatter chart, and so on.
The respective functions all contain specific arguments, but they all have in common that the first mandatory arguments are the data to visualize.
Example: The first two arguments of the Chart.Point
function are the x and y data. You can therefore initialize a point chart like this:
open Plotly.NET
let xData = [ 0. .. 10. ]
let yData = [ 0. .. 10. ]
let myFirstChart = Chart.Point(xData, yData)
Styling functions are generally the Chart.with*
naming convention. The following styling example does:
set the chart title via Chart.withTitle
set the x axis title and removes the gridline from the axis via Chart.withXAxisStyle
set the y axis title and removes the gridline from the axis via Chart.withYAxisStyle
let myFirstStyledChart =
Chart.Point(xData, yData)
|> Chart.withTitle "Hello world!"
|> Chart.withXAxisStyle ("xAxis")
|> Chart.withYAxisStyle ("yAxis")
Attention: Styling functions mutate 😈 the input chart, therefore possibly affecting bindings to intermediary results. We recommend creating a single chart for each workflow to prevent unexpected results.
The Chart.Show
function will open a browser window and render the input chart there. When working in a notebook context, after
referencing Plotly.NET.Interactive, the function is not necessary, just end the cell with the value of the chart.
myFirstChart |> Chart.show
Should render this chart in your browser:
myFirstStyledChart |> Chart.show
And here is what happened after applying the styles from above:
In a notebook context, you usually have (at least when running on a Jupyter server like Binder) no access to the browser on the machine where plotly runs on. That's why you can render charts directly in the cell output. Just end the cell with the chart value:
let xData' = [ 0. .. 10. ]
let yData' = [ 0. .. 10. ]
Chart.Point(xData', yData')
Here is the styled chart:
Chart.Point(xData, yData)
|> Chart.withTitle "Hello world!"
|> Chart.withXAxisStyle ("xAxis")
|> Chart.withYAxisStyle ("yAxis")
[ (1, 5); (2, 10) ]
|> Chart.Point
|> Chart.withTraceInfo (Name = "Hello from F#")
|> Chart.withYAxisStyle (TitleText = "xAxis")
|> Chart.withXAxisStyle (TitleText = "yAxis")
This example uses the high-level native C# bindings for Plotly.NET that are provided by the Plotly.NET.CSharp
package.
using System;
using Plotly.NET.CSharp;
Chart.Point<double, double, string>(
x: new double[] { 1, 2 },
y: new double[] { 5, 10 }
)
.WithTraceInfo("Hello from C#", ShowLegend: true)
.WithXAxisStyle<double, double, string>(Title: Plotly.NET.Title.init("xAxis"))
.WithYAxisStyle<double, double, string>(Title: Plotly.NET.Title.init("yAxis"))
.Show();
DynamicObj
:¶This API is the most low-level and closest to the original plotly.js syntax. Make sure to spell dynamic members exactly as they are used in the plotly.js json schema.
open Plotly.NET.LayoutObjects
let xAxis =
let tmp = LinearAxis()
tmp?title <- "xAxis"
tmp?showgrid <- false
tmp?showline <- true
tmp
let yAxis =
let tmp = LinearAxis()
tmp?title <- "yAxis"
tmp?showgrid <- false
tmp?showline <- true
tmp
let layout =
let tmp = Layout()
tmp?xaxis <- xAxis
tmp?yaxis <- yAxis
tmp?showlegend <- true
tmp
let trace =
let tmp = Trace("scatter")
tmp?x <- [ 1; 2 ]
tmp?y <- [ 5; 10 ]
tmp?mode <- "markers"
tmp?name <- "Hello from F#"
tmp
GenericChart.ofTraceObject true trace |> GenericChart.setLayout layout
DynamicObj
:¶Note that this works only when using the Plotly.NET core API, as the C# bindings only target the high level API.
using System;
using Plotly.NET;
using Plotly.NET.LayoutObjects;
double[] x = new double[] { 1, 2 };
double[] y = new double[] { 5, 10 };
LinearAxis xAxis = new LinearAxis();
xAxis.SetValue("title", "xAxis");
xAxis.SetValue("showgrid", false);
xAxis.SetValue("showline", true);
LinearAxis yAxis = new LinearAxis();
yAxis.SetValue("title", "yAxis");
yAxis.SetValue("showgrid", false);
yAxis.SetValue("showline", true);
Layout layout = new Layout();
layout.SetValue("xaxis", xAxis);
layout.SetValue("yaxis", yAxis);
layout.SetValue("showlegend", true);
Trace trace = new Trace("scatter");
trace.SetValue("x", x);
trace.SetValue("y", y);
trace.SetValue("mode", "markers");
trace.SetValue("name", "Hello from C#");
GenericChart
.ofTraceObject(true, trace)
.WithLayout(layout)
.Show();
The project is hosted on GitHub where you can report issues, fork the project and submit pull requests. If you're adding a new public API, please also consider adding samples that can be turned into a documentation. You might also want to read the library design notes to understand how it works.
The library is available under the OSI-approved MIT license which allows modification and redistribution for both commercial and non-commercial purposes. For more information, see the License file in the GitHub repository.