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 <code>ipynb</code> 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.</span> Table of contents: <ul><li><a href="#jupyternotebook">What is Jupyter Notebook</a></li><li><a href="#whyquarto">Why should I consider Quarto?</a></li><li><a href="#example">Example of Jupyter Notebook and Quarto</a></li><li><a href="#benefits">Benefits of using Quarto with Jupyter Notebook</a></li><li><a href="#closing">Summary of Matplotlib vs. ggplot</a></li></ul> <hr /> <h2 id="jupyternotebook">What is Jupyter Notebook</h2> 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 <code>.qmd</code>/<code>.Rmd</code> files, all outputs, like plots and tables, are saved inside the report file in a <code>.ipynb</code> 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; <a href="https://code.visualstudio.com/docs/datascience/jupyter-notebooks#_custom-notebook-diffing" target="_blank" rel="noopener">VS Code supports notebooks differences</a>! Additionally, Jupyter Notebooks are rendered on GitHub so you can easily share your report and make them readable for everyone. <h2 id="whyquarto">If Jupyter Notebook is so great, why should I consider Quarto?</h2> 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. <a href="https://quarto.org/docs/get-started/hello/jupyter.html"><img class="size-full wp-image-13111" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b7d39e85b6bd7053b5f971_d70a3cad_1-4.webp" alt="Image 1 - Getting started with R Quarto" width="3398" height="2668" /></a> Image 1 - Getting started with Quarto With Quarto, you can easily export your <code>.ipynb</code> file into an interactive HTML with plotly plots, interactive cross-references, and a table of contents! <blockquote>Is R your preferred language? Get started with Quarto in R with our <a href="https://appsilon.com/r-quarto-tutorial/" target="_blank" rel="noopener">Quarto tutorial for interactive Markdown documents</a>.</blockquote> If you work closely with R developers that are used to <code>.Rmd</code> files you’ll find an additional benefit. You can create a single custom theme in <code>.css</code> file for all reports, from <code>.qmd</code> files, and from <code>.ipynb</code>! 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 <code>HTML</code> reports are not accepted everywhere. But worry not, you can just as easily export as pdf or another format as needed. <h2 id="example">Example of Jupyter Notebook and Quarto</h2> 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 <code>.qmd</code> file from the previous post. <img class="alignnone size-full wp-image-15077" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b01d9b6bdc8f59ff85b5fb_quarto-and-jupyter-notebook-code.gif" alt="Quarto and Jupyter Notebook code example" width="948" height="514" /> And here is the generated report by running <code>quarto render report.ipynb</code>. <img class="alignnone size-full wp-image-15021" src="https://webflow-prod-assets.s3.amazonaws.com/6525256482c9e9a06c7a9d3c%2F65b01d9cc1b48d7cae121a20_quarto_jupyter-reduced.gif" alt="Quarto report from Jupyter Notebook" width="1006" height="622" /> The only important thing is the first cell, the one with yaml configuration, that has to be of type <code>raw</code>. 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 <a href="https://quarto.org/docs/output-formats/html-basics.html#self-contained">the <code>self-contained: true</code> Quarto option</a>. It bundles all required <code>css</code>, <code>js</code> files into the <code>HTML</code> file, thus making the report easy to distribute, working without the Internet. <h2 id="benefits">The benefits of using Quarto with Jupyter Notebook</h2> You could ask, <i>OK, so the results are exactly the same as with the </i><i><code>qmd</code></i><i> file, what’s the deal</i>? With <code>quarto preview</code>, 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! <blockquote>RStudio (Posit) 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 <a href="https://appsilon.com/rstudio-certified-partner/" target="_blank" rel="noopener">RStudio Certified Partner</a>.</blockquote> 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! <h2 id="closing">Summing up Quarto and Jupyter Notebook</h2> 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! <blockquote>Ready to level up your reporting with Posit (RStudio) Connect? See <a href="https://appsilon.com/how-to-pull-shiny-usage-data-from-rstudio-connect-api-setup-guide/" target="_blank" rel="noopener">how to pull Shiny usage data from Connect</a>!</blockquote> 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.
Contact us!
