Quarto and Jupyter Notebooks


In a recent post, we discussed how to use Quarto with Python and VS Code. However, as a Python user, I’m not that familiar with .Rmd/.qmd files; I use ipynb notebooks most often. And in this post, I’ll show why you might consider using Jupyter Notebooks and how to convert them into beautiful reports with minimal effort – using Quarto.

Table of contents:


What is Jupyter Notebook

If you’re an R purist, you may not be familiar with Jupyter Notebooks. I’ll briefly introduce it and then we can jump into Quarto. 

Jupyter Notebook is a web application that provides a streamlined, interactive way to work with code mixed with plots and markdown text. And although it’s popular for Python users, it also supports other languages like R. There are some limitations in creating and sharing computational documentation, but that’s where Quarto comes into play.

Contrary to .qmd/.Rmd files, all outputs, like plots and tables, are saved inside the report file in a .ipynb format. 

This has its pros and cons. On one hand, it’s convenient to be able to embed images into the same file where executable code is. On the other, embedding images into code files makes it hard to version control notebooks. Fortunately, in recent years this has changed; VS Code supports notebooks differences!

Additionally, Jupyter Notebooks are rendered on GitHub so you can easily share your report and make them readable for everyone.

If Jupyter Notebook is so great, why should I consider Quarto?

While the Jupyter Notebook format is very convenient to experiment in, there’s no easy way to convert a notebook into a beautiful report. That is until Quarto entered the picture.

Image 1 – Getting started with Quarto

With Quarto, you can easily export your .ipynb file into an interactive HTML with plotly plots, interactive cross-references, and a table of contents!

Is R your preferred language? Get started with Quarto in R with our Quarto tutorial for interactive Markdown documents.

If you work closely with R developers that are used to .Rmd files you’ll find an additional benefit. You can create a single custom theme in .css file for all reports, from .qmd files, and from .ipynb! This way you’ll have consistency across reports created using different technologies. Creating a uniform, professional look in front of your clients! 

It’s always good to remember that Quarto, by leveraging on top of Pandoc, allows exporting to over 50 different formats! This is important as HTML reports are not accepted everywhere. But worry not, you can just as easily export as pdf or another format as needed.

Example of Jupyter Notebook and Quarto

I believe that the best way to learn is through examples. So let’s start by looking at a simple notebook, full of Quarto features compatible with any notebook editor. Actually, this notebook contains the same code as the .qmd file from the previous post.

 

And here is the generated report by running quarto render report.ipynb.

The only important thing is the first cell, the one with yaml configuration, that has to be of type raw. As we can see, all features that we’ve used earlier, work here as well!

Once you’re done with report creation, you might want to check out the self-contained: true Quarto option. It bundles all required css, js files into the HTML file, thus making the report easy to distribute, working without the Internet.

The benefits of using Quarto with Jupyter Notebook

You could ask, OK, so the results are exactly the same as with the qmd file, what’s the deal? With quarto preview, every time you change the notebook and save, the preview gets updated. But what’s important is that the cells’ outputs are taken directly from the notebook, with no need for re-running all cells! 

Posit (RStudio) Connect and Workbench give you the power to create and publish data products at a push of a button! See how Appsilon can help as an RStudio Certified Partner.

This can save you a lot of time. And makes working in Jupyter my favorite way of creating reports. That being said, remember that apart from Python, you can just as well use R or Julia as kernels in Jupyter!

Summing up Quarto and Jupyter Notebook

Jupyter Notebooks provide a fantastic way for iterative experimenting. What they were lacking was the possibility to export the created report to a visually appealing, business-friendly format. And that’s exactly what Quarto does! 

Ready to level up your reporting with Posit (RStudio) Connect? See how to pull Shiny usage data from Connect!

On top of that, you can create a custom theme for your team and have constant branding no matter the underlying technology (R/Python) being used.