{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [] } , { "cell_type": "code", "metadata": {}, "execution_count": null, "outputs": [], "source": ["#r \"nuget: Plotly.NET, 2.0.0\"\n", "#r \"nuget: Plotly.NET.Interactive, 2.0.0\"\n", "\n", "open Plotly.NET\n"] } , { "cell_type": "markdown", "metadata": {}, "source": ["[![Binder](https://plotly.net/img/badge-binder.svg)](https://mybinder.org/v2/gh/plotly/Plotly.NET/gh-pages?filepath=00_0_basics.ipynb)\u0026emsp;\n", "[![Script](https://plotly.net/img/badge-script.svg)](https://plotly.net/00_0_basics.fsx)\u0026emsp;\n", "[![Notebook](https://plotly.net/img/badge-notebook.svg)](https://plotly.net/00_0_basics.ipynb)\n", "\n", "# Plotly.NET basics\n", "\n", "**This section is WIP.**\n", "\n", "### Table of contents\n", "\n", "* Library design(#Library-design)\n", "\n", "* [GenericChart](#GenericChart)\n", "\n", "* [Working with GenericCharts](#Working-with-GenericCharts)\n", "\n", " * [Dynamic object style](#Dynamic-object-style)\n", " \n", "\n", "## Library design\n", "\n", "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.\n", "\n", "A plotly.js chart consists of 3 objects:\n", "\n", "* `data`, which is a collection of `traces` which represent the data and chart type used to visualize the data\n", "\n", "* `layout`, which controls the general chart layout such as axis positions and styles\n", "\n", "* `config` high level properties of the chart like making all chart elements editable or the tool bar on top\n", "\n", "These are mirrored in Plotly.NET\u0027s central type, `GenericChart`:\n", "\n", "## GenericChart\n", "\n", "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:\n", "\n", "```fsharp\n", "type GenericChart =\n", " | Chart of Trace * Layout * Config * DisplayOptions\n", " | MultiChart of Trace list * Layout * Config * DisplayOptions\n", "\n", "```\n", "\n", "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`.\n", "\n", "* `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.\n", "\n", "* `Layout` is everything of the chart that is not dataset specifivc - e.g. the shape and style of axes, the chart title, etc.\n", "\n", "* `Config` is an object that configures high level properties of the chart like making all chart elements editable or the tool bar on top\n", "\n", "* `DisplayOptions` is an object that contains meta information about how the html document that contains the chart.\n", "\n", "### Layers of abstraction\n", "\n", "Plotly.NET uses multiple layers of abstractions to generate valid plotly.js JSON objects with different levels of control and complexity:\n", "\n", "#### The Chart module\n", "\n", "The `Chart` module provides the highest layer of abstraction. Here, plotly.js trace types are broken down to the most common and useful styling options, and combined with common layout settings.\n", "It also provides composite charts which consist of multiple traces such as `Chart.Range`, which really is a combination of 3 scatter traces.\n", "\n", "Here is an example on how to create a simple 2D point chart:\n", "\n"] } , { "cell_type": "code", "metadata": {}, "execution_count": 3, "outputs": [], "source": ["let pointChart =\n", " Chart.Point([1,2; 3,4])\n"] } , { "cell_type": "code", "metadata": {}, "execution_count": null, "outputs": [ { "data": { "text/plain": ["No value returned by any evaluator"] }, "execution_count": null, "metadata": {}, "output_type": "execute_result" }], "source": ["pointChart\n"] } , { "cell_type": "markdown", "metadata": {}, "source": ["#### The TraceStyle modules\n", "\n", "The TraceStyle modules offer access to all parameters supported by plotly.js for the respective trace type. If you want to create a `scatter` trace, you can use the function\n", "`Trace2D.initScatter`, which will initialize an empty trace of type `scatter` and apply a styling function to it. This function would be `Trace2DStyle.Scatter`, which can apply all scatter related parameters to a trace.\n", "In contrast to the `Chart` module, the parameters are named exactly the same as in plotly.js (but in PascalCase).\n", "\n", "To create a GenericChart from a `Trace` object, you can use `GenericChart.ofTraceObject`.\n", "Compare how many more styling options you have compared to `Chart.Point` above, but also take a look at how more verbose you have to be.\n", "You can clearly see the advantages and disadvantages of both approaches.\n", "\n"] } , { "cell_type": "code", "metadata": {}, "execution_count": 5, "outputs": [], "source": ["let withTraceStyle =\n", " Trace2D.initScatter( \n", " Trace2DStyle.Scatter(\n", " X = [1; 3],\n", " Y = [2; 4]\n", " )\n", " )\n", " |\u003e GenericChart.ofTraceObject true\n"] } , { "cell_type": "code", "metadata": {}, "execution_count": null, "outputs": [ { "data": { "text/plain": ["No value returned by any evaluator"] }, "execution_count": null, "metadata": {}, "output_type": "execute_result" }], "source": ["withTraceStyle\n"] } , { "cell_type": "markdown", "metadata": {}, "source": ["#### Dynamic object\n", "\n", "The prime directive for all functions provided by Plotly.NET is the construction of valid plotly JSON objects.\n", "For this purpose, `Trace`, `Layout`, and `Config` (and many other internal objects) are inheriting from [`DynamicObj`](https://github.com/plotly/Plotly.NET/blob/dev/src/Plotly.NET/DynamicObj.fs),\n", "an extension of `DynamicObject` which makes it possible to set arbitraryly named and typed properties of these objects via the `?` operator.\n", "\n", "If you want to exactly mirror a plotly.js tutorial, or want to set properties that for any reason are not abstracted in Plotly.NET,\n", "it can be useful to use the power of DynamicObj to set the parameters directly. Just make sure that the property name is exactly the same as in plotly.js (all lowercase)\n", "\n", "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:\n", "\n"] } , { "cell_type": "code", "metadata": {}, "execution_count": 7, "outputs": [], "source": ["let myTrace = Trace(\"scatter\") // create a scatter trace\n", "myTrace?x \u003c- [0;3] // set the x property (the x dimension of the data)\n", "myTrace?y \u003c- [2;4] // set the y property (the y dimension of the data)\n", "\n", "let withDynObj = GenericChart.ofTraceObject true myTrace\n"] } , { "cell_type": "code", "metadata": {}, "execution_count": null, "outputs": [ { "data": { "text/plain": ["No value returned by any evaluator"] }, "execution_count": null, "metadata": {}, "output_type": "execute_result" }], "source": ["withDynObj\n"] } , { "cell_type": "markdown", "metadata": {}, "source": ["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:\n", "\n", "```javascript\n", "var data = [{\"type\":\"scatter\",\"x\":[0,1,2],\"y\":[0,1,2]}];\n", "```\n", "\n"] }], "metadata": { "kernelspec": {"display_name": ".NET (F#)", "language": "F#", "name": ".net-fsharp"}, "langauge_info": { "file_extension": ".fs", "mimetype": "text/x-fsharp", "name": "C#", "pygments_lexer": "fsharp", "version": "4.5" } }, "nbformat": 4, "nbformat_minor": 1 }