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:

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 Plotly
namespace Plotly.NET
Multiple items
module GenericChart

from Plotly.NET

--------------------
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 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 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
  static member Column : 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 Contour : data:seq<#seq<'a1>> * ?X:seq<#IConvertible> * ?Y:seq<#IConvertible> * ?Name:string * ?Showlegend:bool * ?Opacity:float * ?Colorscale:Colorscale * ?Showscale:'a4 * ?zSmooth:SmoothAlg * ?Colorbar:'a5 -> GenericChart (requires 'a1 :> IConvertible)
  static member DensityMapbox : lon:seq<#IConvertible> * lat:seq<#IConvertible> * ?Z:seq<#IConvertible> * ?Radius:float * ?Opacity:float * ?Text:seq<#IConvertible> * ?Below:string * ?Colorscale:Colorscale * ?Colorbar:Colorbar * ?Showscale:bool * ?ZAuto:bool * ?ZMin:float * ?ZMid:float * ?ZMax:float -> GenericChart + 1 overload
  ...
Multiple items
module Trace

from Plotly.NET

--------------------
type Trace =
  inherit DynamicObj
  new : traceTypeName:string -> Trace
  member type : string

--------------------
new : traceTypeName:string -> Trace
Multiple items
type Layout =
  inherit DynamicObj
  new : unit -> Layout
  static member AddLinearAxis : id:AxisId * axis:LinearAxis -> (Layout -> Layout)
  static member AddMap : id:int * map:Geo -> (Layout -> Layout)
  static member AddScene : name:string * scene:Scene -> (Layout -> Layout)
  static member GetLayoutGrid : grid:LayoutGrid -> (Layout -> Layout)
  static member SetLayoutGrid : grid:LayoutGrid -> (Layout -> Layout)
  static member UpdateLinearAxisById : id:AxisId * axis:LinearAxis -> (Layout -> Layout)
  static member UpdateMapById : id:int * map:Geo -> (Layout -> Layout)
  static member UpdateMapboxById : id:int * mapbox:Mapbox -> (Layout -> Layout)
  ...

--------------------
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)

--------------------
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>
val myTrace : Trace
val ofTraceObject : trace:Trace -> GenericChart.GenericChart
static member Chart.Show : ch:GenericChart.GenericChart -> unit