What is a computational notebook?
Computational notebooks (or "data science notebooks") allow us to do literate programming in an interactive way. This means that we can create a document with paragraphs of text, along with pieces of code and the output of that code, which could be single values, data tables or visualisations. The code can be changed and the outputs can be re-calculated at any time.
Notebooks are often used in data science and so they have been popular in communities using languages like Python, which have a strong focus on that area. However, it is now possible to use them with F#.
Notebooks consist of cells, where each cell either contains some code, the output of the code, or part of a document.
.NET Interactive
.NET Interactive is a new way to create notebooks in .NET, which integrates well with existing .NET tooling. For example, it is possible to create notebooks with C# and F# code from directly within Visual Studio Code.
Warning: At the time of writing, .NET Interactive it is still in an experimental stage and may not yet be ready for production use.
Uses for notebooks
Notebooks are most commonly used to analyse and visualise data along with a text commentary. However, there are other potential uses:
-
Learning F#: F# Interactive is already a great way to experiment with the language, but combining this with a literate style gives even more benefits. You could create notes to explain pieces of code for yourself or to share with others.
-
Creating documentation for a library: You could create a notebook to demonstrate features of your library and how to write code with it. A user could download this and experiment with the code. In addition, this lets you ensure that the documentation code samples still compile and run after your library is updated.
-
Exploring the code in an F# application: Just like you might with F# Interactive, you can load in your own application's DLL from disk and explore the code or reproduce a bug, but in a way that produces a nice document of your findings.
A demonstration
Now I'll show some of the common features used in notebooks. I'm running a notebook locally in Visual Studio Code (currently the Insiders version, because this is still in preview), which uses .NET Interactive.
Installation instructions for VS Code Notebooks.
Markdown
You can create Markdown cells with all of the usual features. Just type the Markdown directly in the cell:
When you're finished editing, the Markdown is rendered:
Basic F# code
Let's add a code cell with some simple F# producing a single value output:
Note that when I evaluate the cell, the output is shown underneath it. The last value returned from the cell is treated as the output.
Sequences
Now let's see what happens if the output is a list of values:
The list is automatically shown as a table column alongside an index column.
Tables
If we want to show a table with more columns, all we need to do is return a sequence of records. They will automatically be displayed with a column for each field. In this example I will use anonymous records:
Using NuGet packages
Since we are still running our F# code on .NET, we can reference NuGet packages and use them as usual. This uses a new feature from the upcoming F# 5 to reference a package directly with the #r directive.
In this example, I'm adding the XPlot.Plotly package. Once we run this cell, the package is available for use in later cells.
Displaying charts
Now we can easily display common chart types. In these examples I'll use some dummy data created in F# code. Firstly, a pie chart.
Now here's a bar chart produced using the sequence of records that we created previously to put in a table. We can just refer to the value that was declared in a previous cell.
Using external data
Again, since we're just running on .NET we can fetch data from the web as we normally would.
Here we have some data from an external weather API as a raw JSON string. Now let's use Newtonsoft.Json to parse it and chart some of the data:
Summary
See here for the raw notebook file containing all of the code pictured above.
As you can see, we don't need to do much work here to produce a nice looking document with runnable code, retrieve and process data and render a visual output. All while using the statically-typed functional-first programming language that we know and love. I would encourage people to use notebooks more as they mature on .NET and discover more uses for them.
