BinderScriptNotebook

Plotly.NET basics

This section is WIP.

Table of contents

GenericChart

Plotly.NET is a .NET wrapper for creation of plotly charts written in F#. This means that, under the hood, all functionality creates JSON objects that can be rendered by plotly.

The central type that gets created by all Chart constructors is GenericChart, which itself represents either a single chart or a multi chart (as a Discriminate Union type). It looks like this:

[<NoComparison>]
type GenericChart =
    | Chart of Trace * Layout * Config * DisplayOptions
    | MultiChart of Trace list * Layout * Config * DisplayOptions

As you can see, a GenericChart consists of four top level objects - Trace (multiple of those in the case of a MultiChart) , Layout, Config, and DisplayOptions.

  • Trace is in principle the representation of a dataset on a chart, including for example the data itself, color and shape of the visualization, etc.
  • Layout is everything of the chart that is not dataset specifivc - e.g. the shape and style of axes, the chart title, etc.
  • Config is an object that configures high level properties of the chart like making all chart elements editable or the tool bar on top
  • DisplayOptions is an object that contains meta information about how the html document that contains the chart.

Working with GenericCharts

Dynamic object style

Plotly.NET has multiple abstraction layers to work with GenericCharts. The prime directive for all functions provided by this library is the construction of valid plotly JSON objects. For this purpose, Trace, Layout, and Config (and many other internal objects) are inheriting from DynamicObj, an extension of DynamicObject which makes it possible to set arbitraryly named and typed properties of these objects via the ? operator.

So if you want to set any kind of property on one of these objects you can do it in a very declarative way like this:

let myTrace = Trace("scatter") // create a scatter trace
myTrace?x <- [0;1;2] // set the x property (the x dimension of the data)
myTrace?y <- [0;1;2] // set the y property (the y dimension of the data)

GenericChart.ofTraceObject myTrace // create a generic chart (layout and config are empty objects)
|> Chart.show

lets have a look at the trace object that will be created. The relevant section of the html generated with Chart.Show is the following:

var data = [{"type":"scatter","x":[0,1,2],"y":[0,1,2]}];
namespace DynamicObj
namespace Plotly
namespace Plotly.NET
Multiple items
type NoComparisonAttribute = inherit Attribute new : unit -> NoComparisonAttribute
<summary>Adding this attribute to a type indicates it is a type where comparison is an abnormal operation. This means that the type does not satisfy the F# 'comparison' constraint. Within the bounds of the F# type system, this helps ensure that the F# generic comparison function is not instantiated directly at this type. The attribute and checking does not constrain the use of comparison with base or child types of this type. </summary>
<category>Attributes</category>


--------------------
new : unit -> NoComparisonAttribute
Multiple items
module GenericChart from Plotly.NET
<summary> Module to represent a GenericChart </summary>

--------------------
type GenericChart = | Chart of Trace * Layout * Config * DisplayOptions | MultiChart of Trace list * Layout * Config * DisplayOptions
Multiple items
union case GenericChart.Chart: Trace * Layout * Config * DisplayOptions -> GenericChart

--------------------
type Chart = static member Area : x:seq<#IConvertible> * y:seq<#IConvertible> * ?Name:string * ?ShowMarkers:bool * ?Showlegend:bool * ?MarkerSymbol:Symbol * ?Color:string * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?Dash:DrawingStyle * ?Width:float -> GenericChart + 1 overload static member Bar : keys:seq<#IConvertible> * values:seq<#IConvertible> * ?Name:string * ?Showlegend:bool * ?Color:string * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?Marker:Marker -> GenericChart + 1 overload static member BarPolar : r:seq<#IConvertible> * theta:seq<#IConvertible> * ?Name:string * ?Showlegend:bool * ?Color:string * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?Dash:DrawingStyle * ?LineWidth:float -> GenericChart static member BoxPlot : ?x:'a0 * ?y:'a1 * ?Name:string * ?Showlegend:bool * ?Color:string * ?Fillcolor:'a2 * ?Opacity:float * ?Whiskerwidth:'a3 * ?Boxpoints:Boxpoints * ?Boxmean:BoxMean * ?Jitter:'a4 * ?Pointpos:'a5 * ?Orientation:Orientation * ?Marker:Marker * ?Line:Line * ?Alignmentgroup:'a6 * ?Offsetgroup:'a7 * ?Notched:bool * ?NotchWidth:float * ?QuartileMethod:QuartileMethod -> GenericChart + 1 overload static member Bubble : x:seq<#IConvertible> * y:seq<#IConvertible> * sizes:seq<#IConvertible> * ?Name:string * ?Showlegend:bool * ?MarkerSymbol:Symbol * ?Color:string * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?StackGroup:string * ?Orientation:Orientation * ?GroupNorm:GroupNorm * ?UseWebGL:bool -> GenericChart + 1 overload static member Bubble3d : x:seq<#IConvertible> * y:seq<#IConvertible> * z:seq<#IConvertible> * sizes:seq<#IConvertible> * ?Name:string * ?Showlegend:bool * ?MarkerSymbol:Symbol * ?Color:string * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font -> GenericChart + 1 overload static member BubblePolar : r:seq<#IConvertible> * theta:seq<#IConvertible> * sizes:seq<#IConvertible> * ?Name:string * ?Showlegend:bool * ?MarkerSymbol:Symbol * ?Color:string * ?Opacity:float * ?Labels:seq<#IConvertible> * ?TextPosition:TextPosition * ?TextFont:Font * ?UseWebGL:bool -> GenericChart + 1 overload static member Candlestick : open:seq<#IConvertible> * high:seq<#IConvertible> * low:seq<#IConvertible> * close:seq<#IConvertible> * x:seq<#IConvertible> * ?Increasing:Line * ?Decreasing:Line * ?WhiskerWidth:float * ?Line:Line * ?XCalendar:Calendar -> GenericChart + 1 overload static member ChoroplethMap : locations:seq<string> * z:seq<#IConvertible> * ?Text:seq<#IConvertible> * ?Locationmode:LocationFormat * ?Autocolorscale:bool * ?Colorscale:Colorscale * ?ColorBar:ColorBar * ?Marker:Marker * ?GeoJson:'a2 * ?FeatureIdKey:string * ?Zmin:float * ?Zmax:float -> GenericChart static member ChoroplethMapbox : locations:seq<#IConvertible> * z:seq<#IConvertible> * geoJson:'a2 * ?FeatureIdKey:string * ?Text:seq<#IConvertible> * ?Below:string * ?Colorscale:Colorscale * ?ColorBar:ColorBar * ?ZAuto:bool * ?ZMin:float * ?ZMid:float * ?ZMax:float -> GenericChart ...
<summary> Provides a set of static methods for creating charts. </summary>
Multiple items
module Trace from Plotly.NET

--------------------
type Trace = inherit DynamicObj new : traceTypeName:string -> Trace member type : string
<summary> Trace type inherits from dynamic object </summary>

--------------------
new : traceTypeName:string -> Trace
Multiple items
type Layout = inherit DynamicObj new : unit -> Layout static member AddGeo : id:SubPlotId * geo:Geo -> (Layout -> Layout) static member AddLinearAxis : id:SubPlotId * axis:LinearAxis -> (Layout -> Layout) static member AddMapbox : id:SubPlotId * mapbox:Mapbox -> (Layout -> Layout) static member GetLayoutGrid : grid:LayoutGrid -> (Layout -> Layout) static member SetLayoutGrid : grid:LayoutGrid -> (Layout -> Layout) static member UpdateGeoById : id:SubPlotId * geo:Geo -> (Layout -> Layout) static member UpdateLinearAxisById : id:SubPlotId * axis:LinearAxis -> (Layout -> Layout) static member UpdateMapboxById : id:SubPlotId * mapbox:Mapbox -> (Layout -> Layout) ...
<summary> Layout </summary>

--------------------
new : unit -> Layout
Multiple items
type Config = inherit DynamicObj new : unit -> Config static member init : ?StaticPlot:bool * ?Autosizable:bool * ?Responsive:bool * ?ShowEditInChartStudio:bool * ?ToImageButtonOptions:ToImageButtonOptions * ?Editable:bool * ?EditableAnnotations:seq<AnnotationEditOptions> -> Config static member style : ?StaticPlot:bool * ?Autosizable:bool * ?Responsive:bool * ?ToImageButtonOptions:ToImageButtonOptions * ?ShowEditInChartStudio:bool * ?Editable:bool * ?EditableAnnotations:seq<AnnotationEditOptions> -> (Config -> Config)
<summary> Config </summary>

--------------------
new : unit -> Config
Multiple items
type DisplayOptions = inherit DynamicObj new : unit -> DisplayOptions static member getReplacements : displayOptions:DisplayOptions -> (string * string) list static member init : ?AdditionalHeadTags:seq<string> * ?Description:ChartDescription -> DisplayOptions static member replaceHtmlPlaceholders : displayOptions:DisplayOptions -> html:string -> string static member style : ?AdditionalHeadTags:seq<string> * ?Description:ChartDescription -> (DisplayOptions -> DisplayOptions)

--------------------
new : unit -> DisplayOptions
union case GenericChart.MultiChart: Trace list * Layout * Config * DisplayOptions -> GenericChart
type 'T list = List<'T>
<summary>The type of immutable singly-linked lists. </summary>
<remarks>See the <see cref="T:Microsoft.FSharp.Collections.ListModule" /> module for further operations related to lists. Use the constructors <c>[]</c> and <c>::</c> (infix) to create values of this type, or the notation <c>[1; 2; 3]</c>. Use the values in the <c>List</c> module to manipulate values of this type, or pattern match against the values directly. See also <a href="https://docs.microsoft.com/dotnet/fsharp/language-reference/lists">F# Language Guide - Lists</a>. </remarks>
val myTrace : Trace
val ofTraceObject : trace:Trace -> GenericChart.GenericChart
<summary> Converts from a trace object and a layout object into GenericChart </summary>
static member Chart.show : ch:GenericChart.GenericChart -> unit