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.
dotnet CLI
|
paket CLI
|
package manager
|
Or add the package reference directly to your .*proj
file:
<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"
Note:
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:
GenericChart
object from the data you want to visualize by using the respective Chart.*
function, optionally setting some specific style parametersThe 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:
Chart.withTitle
Chart.withXAxisStyle
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 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 Plotly.NET.CSharp
package.
|
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.
|
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.