Logo Plotly.NET

Display Options

Binder  Notebook

Summary: This example shows how to alter the display options that control the html output that contains plotly charts

You can control the html output that gets created (e.g. documents created with Chart.Show or the output of GenericChart.toChartHTML) with various functions that change a chart's DisplayOptions.

Let's first create some data for the purpose of creating example charts:

open Plotly.NET

let x = [ 1.; 2.; 3.; 4.; 5.; 6.; 7.; 8.; 9.; 10. ]
let y = [ 2.; 1.5; 5.; 1.5; 3.; 2.5; 2.5; 1.5; 3.5; 1. ]

Referencing PlotlyJS

For rendering plotly.js charts in a html document, the document needs to reference plotly.js in some form.

Plotly.NET has two fundamentally different html outputs:

  1. Full html documents, containing <head> tags.

Functions that generate these files are: - Chart.Show - Chart.saveHtml - GenericChart.toEmbeddedHtml

  1. html fragments, containing only some html tags (e.g. a <div> containing a chart generation script). This is usually meant to included into another document that contains a reference to plotly.js.

Functions that generate these fragments are: - GenericChart.toChartHTML


Plotly.NET provides multiple ways to reference plotly.js in generated html via the PlotlyJSReference type. These differ in their effect depending on if the output is a full html document or a fragment:

PlotlyJSReference Option

Description

Document

Fragment

Full

Include the full plotly.js source.

HTML documents created using this option are self-contained and can be used offline.

No effect

CDN

(default) Include a reference to plotly.js from a CDN.

HTML documents created using this option will contain a reference in their <head> tag

No effect

Require

Use requirejs to load plotly.

HTML documents created using this option will programmatically add a reference to require.js in their <head> tag which will then be used to load plotly.js

Fragments created using this option will programmatically add a reference to require.js when embedded into a html document which will then be used to load plotly.js.

NoReference

Don't include any plotly.js reference. Useful if you want to embed the output into another page that already references plotly - the documentation pages you are reading now are generated with this option.

No effect

No effect

You can control this on a per-chart basis via Chart.withDisplayOptionsStyle, for example if you want to include a script tag with the full plotly.js source:

Chart.Point(x = x, y = y)
|> Chart.withDisplayOptionsStyle (PlotlyJSReference = Full)

Writing HTML tags and including Chart descriptions

Plotly.NET uses Giraffe.ViewEngine internally to generate HTML documents, which means you can also use that DSL to add additional content to the output.

For example, use Chart.withDescription to append a list of html tags below the rendered chart:

open Giraffe.ViewEngine

let desc1 =
    Chart.Point(x = x, y = y, Name = "desc1")
    |> Chart.withDescription
        [ h1 [] [ str "Hello" ]
          p [] [ str "F#" ]
          ol [] [ li [] [ str "Item 1" ]; li [] [ str "Item 2" ] ] ]

Hello

F#

  1. Item 1
  2. Item 2

Adding additional head tags

Note: the example here is shown via an image, as the docs themselves are html pages that cannot load additional head tags.

You can add any number of additional html tags to document <head> tag using Chart.WithAdditionalHeadTags.

For example, you can load external css libraries to style the chart description:

//html for description containing bulma classes such as "hero"
let bulmaHero =
    section
        [ _class "hero is-primary is-bold" ]
        [ div
              [ _class "hero-body" ]
              [ p [ _class "title" ] [ str "Hero title" ]
                p [ _class "subtitle" ] [ str "Hero subtitle" ] ] ]
// chart description containing bulma classes
let description3 = [ h1 [ _class "title" ] [ str "I am heading" ]; bulmaHero ]

let desc3 =
    Chart.Point(x = x, y = y, Name = "desc3")
    |> Chart.withAdditionalHeadTags
        [ link
              [ _rel "stylesheet"
                _href "https://cdn.jsdelivr.net/npm/bulma@0.9.2/css/bulma.min.css" ] ]
    |> Chart.withDescription description3

Image

Using MathTeX

Chart.WithMathTex is a prebuilt function to enable MathTeX for your generated plotly chart documents.

It will add a MathJax script reference to your document based on which version (either 2 or 3) you want to use:

let mathtex_chart =
    [ Chart.Point(xy = [ (1., 2.) ], Name = @"$\beta_{1c} = 25 \pm 11 \text{ km s}^{-1}$")
      Chart.Point(xy = [ (2., 4.) ], Name = @"$\beta_{1c} = 25 \pm 11 \text{ km s}^{-1}$") ]
    |> Chart.combine
    |> Chart.withTitle @"$\beta_{1c} = 25 \pm 11 \text{ km s}^{-1}$"
    |> Chart.withMathTex (AppendTags = true, MathJaxVersion = 3)
namespace Plotly
namespace Plotly.NET
module Defaults from Plotly.NET
<summary> Contains mutable global default values. Changing these values will apply the default values to all consecutive Chart generations. </summary>
val mutable DefaultDisplayOptions: Plotly.NET.DisplayOptions
Multiple items
type DisplayOptions = inherit DynamicObj new: unit -> DisplayOptions static member addAdditionalHeadTags: additionalHeadTags: XmlNode list -> (DisplayOptions -> DisplayOptions) static member addChartDescription: description: XmlNode list -> (DisplayOptions -> DisplayOptions) static member combine: first: DisplayOptions -> second: DisplayOptions -> DisplayOptions static member getAdditionalHeadTags: displayOpts: DisplayOptions -> XmlNode list static member getChartDescription: displayOpts: DisplayOptions -> XmlNode list static member getDocumentCharset: displayOpts: DisplayOptions -> string static member getDocumentDescription: displayOpts: DisplayOptions -> string static member getDocumentFavicon: displayOpts: DisplayOptions -> XmlNode ...

--------------------
new: unit -> Plotly.NET.DisplayOptions
static member Plotly.NET.DisplayOptions.init: ?DocumentTitle: string * ?DocumentCharset: string * ?DocumentDescription: string * ?DocumentFavicon: Giraffe.ViewEngine.HtmlElements.XmlNode * ?AdditionalHeadTags: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?ChartDescription: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?PlotlyJSReference: Plotly.NET.PlotlyJSReference -> Plotly.NET.DisplayOptions
type PlotlyJSReference = | CDN of string | Full | Require of string | NoReference
<summary> Sets how plotly is referenced in the head of html docs. </summary>
union case Plotly.NET.PlotlyJSReference.NoReference: Plotly.NET.PlotlyJSReference
val x: float list
val y: float list
type Chart = static member Bubble: x: #IConvertible seq * y: #IConvertible seq * sizes: int seq * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads static member Line: x: #IConvertible seq * y: #IConvertible seq * ?ShowMarkers: bool * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?Fill: Fill * ?FillColor: Color * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads static member Point: x: #IConvertible seq * y: #IConvertible seq * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads static member Range: x: #IConvertible seq * y: #IConvertible seq * upper: #IConvertible seq * lower: #IConvertible seq * mode: Mode * ?Name: string * ?GroupName: string * ?ShowMarkers: bool * ?ShowLegend: bool * ?Text: 'e * ?MultiText: 'e seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?UpperMarker: Marker * ?LowerMarker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?UpperLine: Line * ?LowerLine: Line * ?RangeColor: Color * ?RangePattern: Pattern * ?UpperText: 'f * ?MultiUpperText: 'f seq * ?LowerText: 'g * ?MultiLowerText: 'g seq * ?TextFont: Font * ?LowerName: string * ?UpperName: string * ?UseDefaults: bool -> GenericChart (requires 'e :> IConvertible and 'f :> IConvertible and 'g :> IConvertible) + 2 overloads static member Scatter: ?X: 'a seq * ?XEncoded: EncodedTypedArray * ?MultiX: 'a seq seq * ?Y: 'b seq * ?YEncoded: EncodedTypedArray * ?MultiY: 'b seq seq * ?Mode: Mode * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?Fill: Fill * ?FillColor: Color * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'a :> IConvertible and 'b :> IConvertible and 'c :> IConvertible) + 3 overloads static member Spline: x: #IConvertible seq * y: #IConvertible seq * ?ShowMarkers: bool * ?Smoothing: float * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: TextPosition * ?MultiTextPosition: TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: MarkerSymbol * ?MultiMarkerSymbol: MarkerSymbol seq * ?Marker: Marker * ?LineColor: Color * ?LineColorScale: Colorscale * ?LineWidth: float * ?LineDash: DrawingStyle * ?Line: Line * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: Orientation * ?GroupNorm: GroupNorm * ?Fill: Fill * ?FillColor: Color * ?FillPattern: Pattern * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> IConvertible) + 2 overloads
static member Chart.Point: xy: (#System.IConvertible * #System.IConvertible) seq * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: StyleParam.TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: StyleParam.MarkerSymbol seq * ?Marker: TraceObjects.Marker * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: StyleParam.Orientation * ?GroupNorm: StyleParam.GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> System.IConvertible)
static member Chart.Point: xEncoded: EncodedTypedArray * yEncoded: EncodedTypedArray * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'a * ?MultiText: 'a seq * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: StyleParam.TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: StyleParam.MarkerSymbol seq * ?Marker: TraceObjects.Marker * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: StyleParam.Orientation * ?GroupNorm: StyleParam.GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'a :> System.IConvertible)
static member Chart.Point: x: #System.IConvertible seq * y: #System.IConvertible seq * ?Name: string * ?ShowLegend: bool * ?Opacity: float * ?MultiOpacity: float seq * ?Text: 'c * ?MultiText: 'c seq * ?TextPosition: StyleParam.TextPosition * ?MultiTextPosition: StyleParam.TextPosition seq * ?MarkerColor: Color * ?MarkerColorScale: StyleParam.Colorscale * ?MarkerOutline: Line * ?MarkerSymbol: StyleParam.MarkerSymbol * ?MultiMarkerSymbol: StyleParam.MarkerSymbol seq * ?Marker: TraceObjects.Marker * ?AlignmentGroup: string * ?OffsetGroup: string * ?StackGroup: string * ?Orientation: StyleParam.Orientation * ?GroupNorm: StyleParam.GroupNorm * ?UseWebGL: bool * ?UseDefaults: bool -> GenericChart (requires 'c :> System.IConvertible)
argument x: float seq
<summary> Creates a Point chart, which uses Points in a 2D space to visualize data. </summary>
<param name="x">Sets the x coordinates of the plotted data.</param>
<param name="y">Sets the y coordinates of the plotted data.</param>
<param name="Name">Sets the trace name. The trace name appear as the legend item and on hover</param>
<param name="ShowLegend">Determines whether or not an item corresponding to this trace is shown in the legend.</param>
<param name="Opacity">Sets the opactity of the trace</param>
<param name="MultiOpacity">Sets the opactity of individual datum markers</param>
<param name="Text">Sets a text associated with each datum</param>
<param name="MultiText">Sets individual text for each datum</param>
<param name="TextPosition">Sets the position of text associated with each datum</param>
<param name="MultiTextPosition">Sets the position of text associated with individual datum</param>
<param name="MarkerColor">Sets the color of the marker</param>
<param name="MarkerColorScale">Sets the colorscale of the marker</param>
<param name="MarkerOutline">Sets the outline of the marker</param>
<param name="MarkerSymbol">Sets the marker symbol for each datum</param>
<param name="MultiMarkerSymbol">Sets the marker symbol for each individual datum</param>
<param name="Marker">Sets the marker (use this for more finegrained control than the other marker-associated arguments)</param>
<param name="AlignmentGroup">Set several traces linked to the same position axis or matching axes to the same alignmentgroup. This controls whether bars compute their positional range dependently or independently.</param>
<param name="OffsetGroup">Set several traces linked to the same position axis or matching axes to the same offsetgroup where bars of the same position coordinate will line up.</param>
<param name="StackGroup">Set several traces (on the same subplot) to the same stackgroup in order to add their y values (or their x values if `Orientation` is Horizontal). Stacking also turns `fill` on by default and sets the default `mode` to "lines" irrespective of point count. ou can only stack on a numeric (linear or log) axis. Traces in a `stackgroup` will only fill to (or be filled to) other traces in the same group. With multiple `stackgroup`s or some traces stacked and some not, if fill-linked traces are not already consecutive, the later ones will be pushed down in the drawing order</param>
<param name="Orientation">Sets the stacking direction. Only relevant when `stackgroup` is used, and only the first `orientation` found in the `stackgroup` will be used.</param>
<param name="GroupNorm">Sets the normalization for the sum of this `stackgroup. Only relevant when `stackgroup` is used, and only the first `groupnorm` found in the `stackgroup` will be used</param>
<param name="UseWebGL">If true, plotly.js will use the WebGL engine to render this chart. use this when you want to render many objects at once.</param>
<param name="UseDefaults">If set to false, ignore the global default settings set in `Defaults`</param>
argument y: float seq
<summary> Creates a Point chart, which uses Points in a 2D space to visualize data. </summary>
<param name="x">Sets the x coordinates of the plotted data.</param>
<param name="y">Sets the y coordinates of the plotted data.</param>
<param name="Name">Sets the trace name. The trace name appear as the legend item and on hover</param>
<param name="ShowLegend">Determines whether or not an item corresponding to this trace is shown in the legend.</param>
<param name="Opacity">Sets the opactity of the trace</param>
<param name="MultiOpacity">Sets the opactity of individual datum markers</param>
<param name="Text">Sets a text associated with each datum</param>
<param name="MultiText">Sets individual text for each datum</param>
<param name="TextPosition">Sets the position of text associated with each datum</param>
<param name="MultiTextPosition">Sets the position of text associated with individual datum</param>
<param name="MarkerColor">Sets the color of the marker</param>
<param name="MarkerColorScale">Sets the colorscale of the marker</param>
<param name="MarkerOutline">Sets the outline of the marker</param>
<param name="MarkerSymbol">Sets the marker symbol for each datum</param>
<param name="MultiMarkerSymbol">Sets the marker symbol for each individual datum</param>
<param name="Marker">Sets the marker (use this for more finegrained control than the other marker-associated arguments)</param>
<param name="AlignmentGroup">Set several traces linked to the same position axis or matching axes to the same alignmentgroup. This controls whether bars compute their positional range dependently or independently.</param>
<param name="OffsetGroup">Set several traces linked to the same position axis or matching axes to the same offsetgroup where bars of the same position coordinate will line up.</param>
<param name="StackGroup">Set several traces (on the same subplot) to the same stackgroup in order to add their y values (or their x values if `Orientation` is Horizontal). Stacking also turns `fill` on by default and sets the default `mode` to "lines" irrespective of point count. ou can only stack on a numeric (linear or log) axis. Traces in a `stackgroup` will only fill to (or be filled to) other traces in the same group. With multiple `stackgroup`s or some traces stacked and some not, if fill-linked traces are not already consecutive, the later ones will be pushed down in the drawing order</param>
<param name="Orientation">Sets the stacking direction. Only relevant when `stackgroup` is used, and only the first `orientation` found in the `stackgroup` will be used.</param>
<param name="GroupNorm">Sets the normalization for the sum of this `stackgroup. Only relevant when `stackgroup` is used, and only the first `groupnorm` found in the `stackgroup` will be used</param>
<param name="UseWebGL">If true, plotly.js will use the WebGL engine to render this chart. use this when you want to render many objects at once.</param>
<param name="UseDefaults">If set to false, ignore the global default settings set in `Defaults`</param>
static member Chart.withDisplayOptionsStyle: ?DocumentTitle: string * ?DocumentCharset: string * ?DocumentDescription: string * ?DocumentFavicon: Giraffe.ViewEngine.HtmlElements.XmlNode * ?AdditionalHeadTags: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?ChartDescription: Giraffe.ViewEngine.HtmlElements.XmlNode list * ?PlotlyJSReference: PlotlyJSReference -> (GenericChart -> GenericChart)
union case PlotlyJSReference.Full: PlotlyJSReference
<summary> Full plotly.js source code (~3MB) is included in the output. HTML files generated with this option are fully self-contained and can be used offline </summary>
namespace Giraffe
namespace Giraffe.ViewEngine
val desc1: GenericChart
static member Chart.withDescription: chartDescription: XmlNode list -> ch: GenericChart -> GenericChart
val h1: (XmlAttribute list -> XmlNode list -> XmlNode)
val str: (string -> XmlNode)
<summary> An alias for the `encodedText` function. </summary>
val p: (XmlAttribute list -> XmlNode list -> XmlNode)
val ol: (XmlAttribute list -> XmlNode list -> XmlNode)
val li: (XmlAttribute list -> XmlNode list -> XmlNode)
type GenericChart = | Chart of data: Trace * layout: Layout * config: Config * displayOpts: DisplayOptions | MultiChart of data: Trace list * layout: Layout * config: Config * displayOpts: DisplayOptions static member addConfig: config: Config -> gChart: GenericChart -> GenericChart static member addDisplayOptions: displayOpts: DisplayOptions -> gChart: GenericChart -> GenericChart static member addLayout: layout: Layout -> gChart: GenericChart -> GenericChart static member combine: gCharts: GenericChart seq -> GenericChart static member countTrace: gChart: GenericChart -> int static member existsTrace: predicate: (Trace -> bool) -> gChart: GenericChart -> bool static member fromChartDTO: dto: ChartDTO -> GenericChart static member fromFigure: fig: Figure -> GenericChart static member getConfig: gChart: GenericChart -> Config static member getDisplayOptions: gChart: GenericChart -> DisplayOptions ...
<summary> 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). 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 specific - 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. </summary>
static member GenericChart.toChartHTML: gChart: GenericChart -> string
val bulmaHero: XmlNode
val section: (XmlAttribute list -> XmlNode list -> XmlNode)
val _class: (string -> XmlAttribute)
val div: (XmlAttribute list -> XmlNode list -> XmlNode)
val description3: XmlNode list
val desc3: GenericChart
static member Chart.withAdditionalHeadTags: additionalHeadTags: XmlNode list -> ch: GenericChart -> GenericChart
val link: attr: XmlAttribute list -> XmlNode
val _rel: (string -> XmlAttribute)
val _href: (string -> XmlAttribute)
val mathtex_chart: GenericChart
static member Chart.combine: gCharts: GenericChart seq -> GenericChart
static member Chart.withTitle: title: Title -> (GenericChart -> GenericChart)
static member Chart.withTitle: title: string * ?TitleFont: Font -> (GenericChart -> GenericChart)
static member Chart.withMathTex: ?AppendTags: bool * ?MathJaxVersion: int -> (GenericChart -> GenericChart)

Type something to start searching.