Quarto at Work: Streamline Reports and Share Insights
Quarto is an open-source tool for technical publishing designed to help data scientists share their analytic insights. It speeds up and simplifies the process of creating professional-quality presentations, reports, websites, and blogs in a variety of formats such as PDF, MS Word, HTML, and much more, all within the same environment used to create one’s analysis.
Quarto offers a wealth of features that are particularly useful to professionals, helping them produce engaging, custom-styled content. Quarto automates repetitive tasks, enabling teams to spend less time tweaking the appearance of their output and more time focusing on delivering outstanding work.
While Quarto is developing quickly and constantly adding functionality, this article showcases key ways professionals can incorporate Quarto into their workflows today.
Quarto as a notebook
As a tool for literate computing, millions of people perform data analysis using notebooks like Jupyter Notebooks and R Markdown documents to mix text, code, and rich media. Useful in the initial exploratory phase, practitioners can keep their notes recording what they’ve done in the same document as where they’ve developed their code, as well as where they’ve stored the output of their work, including tables, plots, models, and other results. Notebooks can be a lightweight tool to quickly dive into one’s analysis, preview likely results, and start drafting a narrative.
Quarto is a powerful tool that allows professionals to take advantage of the benefits of literate computing. There is little friction in the process of converting your existing notebook into a Quarto document, and you are able to take advantage of all the publishing and document refinement options available with Quarto. Jupyter documents require only a chunk of raw text at the top of your notebook containing a YAML header characterizing how the document should be rendered. Most R Markdown documents can be converted to Quarto documents with little change.
Quarto eases reporting workflows
Reporting is a necessity of professional life. Many of us have placed our analysis in a report, cycled through multiple iterations, and finally sent it off to stakeholders, only to be asked to make additional changes or refresh the analysis months later. This reporting cycle can be tedious but is all too typical.
Your analytics may end up in an email, on a webpage, as a PDF, in a presentation, or something else. Each publication format requires different packages to render each, and developing a document for one output format can easily make it incompatible with another. You may want to customize the layout, look and feel, and other elements of your report. How do you add citations and automated cross-references? How do you render your document into a specific theme or template for a PowerPoint, Word, or LaTeX document, for example?
How do you do all this efficiently without making your document and codebase unmanageable?
Quarto is your solution for automating reports because it eliminates the need for extensive code to be used in publishing and structuring your report. Instead, it uses code in its proper place to generate output like dynamic tables and charts. Quarto can render reports in PDF, HTML, PowerPoint, Word, or ePub format while effortlessly integrating with Python and other languages. Take advantage of its built-in styling, cross-reference, diagrams, citations and footnotes, refinement capabilities, and numerous extensions and templates. We recently wrote about building reporting infrastructure for Quarto and about Quarto for reporting with Python data science work.
Customize & style your reports
How do you make your reports look like they belong to you and your organization? Though Quarto’s default styling starts you off with a professional look, you’re also able to pull in your logo, official color palette, font, and other elements of a style guide that helps the work stand out.
Quarto Custom formats can provide default document options, style sheets, headers, footers, or logo elements. They can even be bundled with extensions like filters for custom output rendering and shortcodes for markdown shortcuts to generate specific content in your report. They allow you to provide a common baseline for authoring documents or presentations within an organization, for a particular type of project or analysis, or for a specific publication.
How you develop these depends on the output format you want. Check out the custom formatting quick start guide to get started.
Create Word, PowerPoint, & other custom format templates
How do you help new users of your new format understand its options? You’ll find that it is important to create and offer a template along with your custom format extension.
While someone working with your custom format could technically start from scratch to build a new report, it will be quicker and easier to provide them with a template. This reference Quarto file should incorporate all your custom styling and provide example content and demonstrate options. This provides your new users with a sound starting point for taking advantage of the custom report format.
When developing a new custom format, building a starter format template alongside it allows you to test the new report to ensure it renders as expected.
You can build a custom format and starter template for any Quarto output format, including HTML, LaTex, Word, and Powerpoint. Learn about Quarto starter templates here.
Output to multiple formats, e.g., PDF, HTML for a website & email
As data scientists create reports, they often need to generate these in several different output formats. For example, consider a weekly report updating key metrics; it’s deployed to an internal blog and is distributed via email. You might also need to offer leaders slides for PowerPoint presentations or in a format ready to print or any number of other custom output formats.
Common practices often make this a challenge, the effort required to get your report to look good for one format often will not translate to another. Quarto helps here.
As we demonstrated in a recent blog post – Python Made Easy With Posit Part 1: Reporting – without Quarto, rendering a single report to multiple formats requires disparate codebases, leading to complex code that is hard to maintain and scale, and leading to slow iterative improvements.
Automating these kinds of reports should be straightforward and not require much time. Quarto offers a consistent way to write common reporting elements. Adding images, citations, bibliography, code, layout grids, and much else is consistent across output types. In many cases outputting to different formats just requires a tweak to a YAML file or arguments in your command to publish. But also, despite these commonalities across output formats, some output elements still must be tweaked depending on your target output format. For example, with a table element, you may want to offer interactivity when deploying to HTML but then format the table as a traditional LaTeX table when output to PDF. Quarto makes it easy to render content conditional on specific output formats.
Parametrized reports
Do you find yourself producing similar reports repeatedly, with only a small or standard set of changes required between each render? Many data scientists develop standard report templates and apply the analytics to alternative date ranges or to a different subset of the data. For example, there might be a sales analytics report, which needs to be updated and distributed weekly, with options to summarize specific regions and industry verticals or look at the performance of specific teams or individuals.
One of Quarto’s strengths is that you can produce analysis with the click of a button. This makes it easy to update your work by applying it to new data or tweaking parameters within the document. Parametrized reports allow users to specify one or more parameters to customize the analysis. This is useful if you want to create a report template that can be reused across multiple similar scenarios.
Learn more about producing and rendering parameterized Quarto docs.
Use variables for repeated values & incorporating document context
Reports often have repeated information throughout the document, like version numbers or emails. Instead of typing the same information multiple times, we can use a dynamic variable. The benefit of dynamic variables is that you only need to enter the value once, which can be repeatedly referenced. This can ease maintenance and reduce the likelihood of an error with your documents.
You may also want to refer to the title or author of your document or pull into your document an environment variable, like the time the document was rendered.
Quarto variables allow you to refer to these values with shortcode syntax. You may refer to arbitrary variables you’ve defined, document metadata, or system environment variables. Learn more about Quarto variables.
Adding interactivity
A report with static elements can be an excellent way to convey information to stakeholders, but adding interactive elements to an article helps readers explore the concepts and data you are presenting more deeply.
Embedding interactive components can reduce follow-up questions and increase stakeholder engagement, resulting in fewer question-and-answer cycles and greater efficiency. For example, allowing stakeholders to interact with a plot or table to see specific dates, values, etc., can provide your results with much-needed context. Aside from empowering users to answer their own questions as they arise, it can lead to better questions that provide better insights and enhance your work’s value.
Quarto has three core ways to add interactivity to your document.
- Create custom JavaScript visualizations using Observable JS.
- Embed a Shiny application into your document. You can embed Shiny via R or Python via ShinyLive.
- Incorporate Jupyter Widgets or htmlwidgets (for the Jupyter and Knitr engines, respectively) into your document.
Quarto projects
Many analytic projects require numerous scripts and control documents and lead to multiple reports. For example, suppose you ingest data from different sources that need to be cleaned and staged in {pins} pinboard for later use. After that, you may apply a set of modeling methodologies and generate statistics and accompanying visualizations and summary tables. You may have some reports that help you validate this pipeline and allow you to preview the data and results. And finally, you might have a set of reports that are generated and conditionally distribute to your users. There may also be styling and metadata that should be applied to documents across the project.
When your work requires multiple Quarto documents, it likely makes sense to create a Quarto Project. Quarto projects enable a few advantages,
- Rather than rendering multiple documents and scripts individually, all of which may be managed in several different directories – render all in one directory with a single command.
- Share configuration settings across multiple documents, applying styling, YAML settings, variables, meta, and environment data consistently across all.
- Tightly manage how and when these documents are rendered. Render targets help you control which files are run and their execution order. You may further manage execution with caching, conditional freezing (i.e. don’t re-execute documents unless they have changed), and various techniques to minimize the time required to rebuild a site that has expensive computations.
- Project Profiles allow you to introduce different project types (for example, production vs. development, or a book vs. a website) which trigger different behavior given the type selected.
Learn more about Quarto Projects.
Publish and schedule Quarto documents using Posit Connect
Posit Connect makes deploying code-based tasks and distributing insights easy. It supports the publishing of many output types, including web apps, APIs, models, and reports, and it’s a particularly excellent tool for supporting analytics workflows involving Quarto documents.
Static (locally rendered output) and dynamic (updated with new data automatically) Quarto files can be published to Posit Connect in various ways: the command line, Git-backed content, GitHub Actions, and push-button deployment. Once published, Quarto files can be scheduled for refresh and conditionally distribution to stakeholders through either email or the Posit Connect content hub.
For example, build a weekly report, use Posit Connect to refresh it each week, and send it to an email distribution list automatically, while ensuring only those with authorization may access these reports. You can’t get more efficient than that.
Connect offers a large set of tools to streamline the kind of work data science teams commonly encounter, managing scale and security, managing deployment and distribution tasks of data science products in enterprise environments. To learn more about Posit Connect and how it can improve your reporting infrastructure, schedule a demo.
Quarto at posit::conf(2023)
Posit’s conference for all things open source data science is happening in Chicago September September 17-20. We are offering a number of Quarto workshops, including;
- Enhancing Communication & Collaboration with Jupyter Notebooks & Quarto. Watch the trailer, learn more and register.
- Introduction to Quarto with R & RStudio, with instructor Andrew Bray. Watch the course trailer, learn more and register.
- Advanced Quarto with R & RStudio, with instructor Andrew Bray. Watch the course trailer, learn more and register.
