Jupyter Notebook as a Product. How to Format, Prepare, and Export... | by Kurt Klingensmith | Towards Data Science

Once a data scientist’s analysis is complete, the most critical aspect of the job begins: delivery of results to the customer. At this step, even the greatest work can fail due to poor presentation or an untimely delivery. This conundrum is perhaps best summarized by Akin’s 20th Law of Spacecraft Design, which states [1]:
A bad design with a good presentation is doomed eventually. A good design with a bad presentation is doomed immediately.
— Akin’s Laws of Spacecraft Design
Traditionally, product delivery means transferring coded outputs to other mediums such as PowerPoint. But what if there was a way to deliver the Python Jupyter Notebook, complete with interactive charts, directly to the customer? Enter the HTML-based Jupyter Notebook as a Product (JNaaP).
The concept of the JNaaP is simple: structure a typical, python Jupyter notebook [2] so it is HTML-exportable in a clean, understandable manner for customers of varying levels of technical proficiency.
JNaaPs are highly distributable. Almost everyone in the modern workforce has access to an internet browser capable of opening HTML files, enabling broad distribution and minimal compatibility issues.
This article will walkthrough a demonstration on how to build the author-created JNaaP available in HTML format, with the full repository and data available here: https://github.com/kurtklingensmith/JNaaP. Click “Code” and “Download Zip” to access the files.
The provided JNaaP at the above GitHub repository uses anonymized data courtesy of a local autocross club. Autocross is a timed, amateur motorsports event where drivers navigate a course constructed from cones and it generates a wealth of data. The JNaaP and notebook will work best when downloaded and viewed locally versus viewing within GitHub.
Before building a JNaaP, data scientists must address two key considerations:
Customer Requirements: What are the high-level requirements or questions the customer needs addressed via data science capabilities? This drives the structure of the JNaaP. The various sections should address each question or requirement, and the notebook should provide a summary.Customer Technical Considerations: Will the customer want access to code? Is the customer technically proficient? This drives the final presentation techniques. Creating a JNaaP necessitates clean code; customers who are more technical in nature may want visible code in the final product. For most customers, hiding the code on HTML-export is the best approach, but this is not an absolute.
Customer Requirements: What are the high-level requirements or questions the customer needs addressed via data science capabilities? This drives the structure of the JNaaP. The various sections should address each question or requirement, and the notebook should provide a summary.
Customer Technical Considerations: Will the customer want access to code? Is the customer technically proficient? This drives the final presentation techniques. Creating a JNaaP necessitates clean code; customers who are more technical in nature may want visible code in the final product. For most customers, hiding the code on HTML-export is the best approach, but this is not an absolute.
Effective JNaaP construction demands extensive use of nbextensions. An article to get started with nbextensions is available here: Jupyter Notebook Extensions by Will Koehrsen [3]. The provided sample JNaaP uses the following nbextensions capabilities:
Table of Contents (2)
Codefolding
Hide input
Hide input all
plotlywidget/extension
The sample JNaaP will also require:
nbconvert: Used for exporting [4].
Plotly Express: For interactive visualizations [5].
Structurally, the JNaaP should stand alone. Download the provided example here as a reference while reading the following list of typical JNaaP elements:
Title: The title should succinctly summarize what the notebook is about. Consider adding a date stamp, authorship, and contact information. Use markdown and maximize use of markdown formatting features. A rundown of various markdown features can be found here [6]. An example of markdown for a title is below:
**<center><font size = "6">The JNaaP Title<center>*****<center><font size = "2">Prepared by: Data Scientist<center>
Background: This should set the stage by addressing the JNaaP’s purpose, the key analytical objectives, and any pertinent background information or story necessary to understand the JNaaP. This should also include key findings and results up front that are supported by analysis later in the notebook. If limited for time, the customer should only need to read this section, with the trust that the analysis further down in the notebook backs the findings. Use markdown to format and display this section.
Table of Contents: Using nbextensions, the Table of Contents (2) [7] extension allows readers to rapidly jump to different parts of the notebook.
Data Loading and Setup: This is where the notebook loads in the data and libraries. Generally, this is of little use to the customer, but displaying the dataframe head and some summary dimensions using print statements can add value by showing a visual depiction of the data.
The Analysis Portion: This is where the data science work, to include visualizations, resides. Structure the analysis so it addresses analytical objectives from the background and customer requirements. A sound way to approach this is by using headers that are the customer’s analytical questions. Note that clean code and cleanly displayed tables, results, and code outputs are necessary for an effective JNaaP. Use print statements, markdown, and visualization techniques wisely to give a clean, professional appearance.
Plotly Express offers simple and efficient interactive charts that have a clean, professional look. The interactive aspect allows users to zoom in or out on the chart and even generate screenshots. Critical to ensuring those charts export and remain interactive in HTML files is the below code beneath the hashtag:
import plotly.express as pximport plotly.graph_objects as goimport plotly.io as pio# The below line ensures charts export to HTMLpio.renderers.default='notebook'
With this code, interactive charts are exportable. An example from the provided JNaaP is visible below. Note all axes are labeled, a legend is provided, and the viewer can hover over data points for additional information. Clean and clear presentation is critical for a successful JNaaP. Further documentation on customizing Plotly charts is available here [8].
Python’s print() function offers a powerful alternative to markdown. Notably, repeatable analysis is possible via print functions. Consider the following from the example JNaaP:
mode = df['Car Make'].mode()print("\u2022 Most common manufacturer:", mode.to_string(index=False))
The above code will take the dataframe and print a statement identifying the most common car manufacturer in the dataset. Because it is not markdown, but instead a print() function using python to identify the most commonly occurring entry, the code is repeatable with future datasets from other events.
Note the “\u2022” text, which generates a unicode bullet. Similar to markdown, there are many formatting possibilities with the Python print() function that will improve the professional appearance of the JNaaP. The sample JNaaP provides an example of setting classes to print bold text.
Once the JNaaP is complete, there are several ways to export it to HTML. There are two considerations before export:
Code or No Code: Some customers may want to see the code. Others may not. Keep all code clean and well documented in the event the customer wants it. This will enhance interpretability and decrease clutter on the HTML file.
Previewing the JNaaP: Typically, most customers will not want to see code. Extensive use of nbextension’s codefolding [9] and Hide Input allow previewing what the JNaaP will look like before export [10]. This can save time by avoiding repeat exports.
Once the determination on code inclusion is complete, there are several ways to export the JNaaP to an HTML:
Jupyter Notebook’s Built-In Capability: If including code, this is the easiest way to create the JNaaP. This method is as simple as clicking File, Download as, HTML (.html). Jupyter will then download the notebook as an HTML file to wherever the browser defaults for downloaded files.
Use nbconvert to Export: Nbconvert provides more options. The below code block does several things:
%%capture!jupyter nbconvert --to html --no-input --no-prompt Notebook.ipynb
The top line (%%capture) ensures the output of the nbconvert HTML export line will not display.
The bottom line exports the notebook to HTML. To html specifies the format, and no input, no prompt hide the code. The end of the line should be the file name for the notebook being converted.
The HTML file exports to the directory in which the Jupyter Notebook ipynb file is located. Dark themes are available as well by adding the following code to the nbconvert line:
--HTMLExporter.theme=dark
This will require reformatting Plotly chart color schemes, though; running the following code can adjust the plotly themes to dark:
pio.templates.default = "plotly_dark"
Delivering Jupyter Notebooks as an HTML-based product streamlines data science work by making the analytical, code-based effort part of the final product production. It also reduces error and rework by eliminating the need to translate efforts from one tool (Jupyter) to others such as PowerPoint or Word. Finally, HTML files are broadly compatible and easily transferred, making the product easy to deliver to customers. Ultimately, well-structured JNaaPs can provide a means for reproducible, all-in-one analysis and report generation. In such cases, non-data scientists can take a prepared JNaaP notebook, execute it, and generate a deliverable product.
Feel free to reference the linked example and create JNaaPs of your own.
[1] D. Akin, Akin’s Laws of Spacecraft Design (2021), Dave Akin’s Web Site.
[2] Project Jupyter, Project Jupyter (2021), https://jupyter.org/.
[3] W. Koehrsen, Jupyter Notebook Exensions (2018), Towards Data Science.
[4] Nbconvert, nbconvert: Convert Notebooks to other formats (2021), nbconvert.
[5] Plotly Express, Plotly Express | Python | Plotly (2021), Plotly | Graphing Libraries.
[6] M. Zaman, The Ultimate Markdown Cheat Sheet (2021), Towards Data Science.
[7] jupyter_contrib_nbextensions, Table of Contents (2) (2021), Unofficial Jupyter Notebook Extensions.
[8] Plotly Express, Plotly Express | Python | Plotly (2021), Plotly | Graphing Libraries.
[9] jupyter_contrib_nbextensions, Codefolding (2021), Unofficial Jupyter Notebook Extensions.
[10] jupyter_contrib_nbextensions, Hide Input (2021), Unofficial Jupyter Notebook Extensions.