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 privde native C# docs as well.
Plotly.NET consists of multiple packages. The two main ones are:
Plotly.NET packages are available on nuget to plug into your favorite package manager.
Or add the package reference directly to your
<PackageReference Include="Plotly.NET" Version="4.0.0" />
You can include the package via an inline package reference:
#r "nuget: Plotly.NET, 4.0.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.0.0"
due to the currently fast development cycles of Dotnet Interactive, there might be increments in their versioning that renders 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 referencning Plotly.NET.Interactive:
# "nuget:https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet5/nuget/v3/index.json" # "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:
GenericChartobject from the data you want to visualize by using the respective
Chart.*function, optionally setting some specific style parameters
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:
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
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 brower:
myFirstStyledChart |> Chart.show
And here is what happened after applying the styles from above:
In a notebook context you usually have (at leat 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")
One of the main design points of Plotly.NET it is to provide support for multiple flavors of chart generation. Here are 2 examples in different styles and languages that create an equivalent chart:
[ (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
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
note that this works only when using the Plotly.NET core API, as the C# bindings only target the high level API.
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.