What is Quarto?
Quarto is a powerful tool for data science that helps you create professional documents that combine your code, its results (like plots or tables), and your written explanations all in one place.
Think of it as a modern-day digital lab notebook where you can capture exactly what you did and why you did it.
It’s not an R package, but a command-line interface (CLI) tool.
RStudio, a popular environment for R, automatically handles Quarto for you when needed, so you don’t typically have to install it separately.
Why is Quarto useful?
Quarto is designed for several key purpose:
• Communication: It helps you create reports for decision-makers who want to see your conclusions without getting bogged down in the code.
• Collaboration: It’s great for working with other data scientists (including your future self!) because it shows both your findings and the code that led to them.
• Reproducibility: Quarto documents are fully reproducible, meaning anyone can run your code and get the exact same results.
• Analysis Notebook: It acts as an analysis notebook, helping you record your thoughts and processes, which supports rigorous thinking and makes your work understandable to others.
Quarto also builds upon and unifies the functionality of many tools from the R Markdown ecosystem (like
rmarkdown, bookdown, distill, xaringan) and extends it to support multiple programming languages like Python and Julia, in addition to R.What does a Quarto file look like?
A Quarto file is a plain text file with the extension .qmd. It typically contains three main types of content:
1. YAML Header: An optional section at the top, surrounded by
--- (three hyphens), that provides metadata and settings for your document, like the title, date, and output format.2. Code Chunks: Blocks of code (like R code) enclosed by three backticks (“`). These chunks are where you write your analysis code.
3. Text: Your written explanations, mixed with simple text formatting (like
# heading for headings or _italics_ for italics).How do you create and work with Quarto documents?
You can start a new Quarto document in RStudio by selecting File > New File > Quarto Document…. RStudio offers two main ways to edit these files:
• Visual Editor: This is a “What You See Is What You Mean” (WYSIWYM) interface that feels similar to writing in tools like Google Docs or Microsoft Word. You can use buttons on a menu bar or shortcuts to easily insert things like images, tables, and code chunks, and you’ll see your formatting applied directly.
• Source Editor: This is a plain text editor, familiar if you’ve written R scripts or R Markdown documents. Here, you directly type Pandoc Markdown syntax for formatting (e.g.,
*italic* for italic text, ## Heading for a second-level heading). It can be helpful for debugging. You can switch between the visual and source editors.Running Code and Rendering Documents
• Code Chunks: You can run code chunks individually by clicking a “Run” icon (a play button) or using the keyboard shortcut Cmd/Ctrl + Shift + Enter. RStudio displays the results right there with your code.
• Rendering: To produce a complete report, you click “Render” or press Cmd/Ctrl + Shift + K. This process transforms your
.qmd file into your desired output format (like HTML, PDF, or Word).The rendering process involves two main steps:
1. knitr: Your
.qmd file is sent to knitr, which executes all the code chunks and creates a new Markdown (.md) document containing your code and its output.2. pandoc: This Markdown file is then processed by
pandoc, which creates the final output file (e.g., HTML, PDF, Word).Important Features and Options
Here are some key things you can control in Quarto documents:
• Code Chunk Options: You can customise how your code and its results appear in the final document using options in the chunk header (e.g., ““{r} #| label: setup #| include: false` ).
◦ eval: false: Prevents code from running and showing any results.
◦ include: false: Runs the code but hides both the code and its results from the final document. Useful for setup code.
◦ echo: false: Hides the code, but shows the results in the final document. Good for reports where the audience doesn’t need to see the R code.
◦ message: false or warning: false: Stops messages or warnings from appearing.
◦ error: true: Allows the document to render even if an error occurs in a chunk (useful for debugging).
• Global Options: You can set these chunk options for your entire document in the YAML header, under
execute or knitr::opts_chunk, so you don’t have to repeat them for every chunk.• Inline Code: You can embed results of R code directly into your text using
`r code` (e.g., r nrow(diamonds) will display the number of rows in the diamonds dataset).• Figures:
◦ Figures generated by your code will be automatically included.
◦ You can control their size and placement using options like
fig-width, fig-height, out-width, and fig-align. ◦ Add captions with
fig-cap. ◦ It’s a good idea to name code chunks that produce figures so their filenames are useful.
• Tables:
◦ You can create markdown tables directly or generate them from code.
◦ The
knitr::kable() function helps you format tables nicely from R data frames.• Caching: If you have parts of your code that take a long time to run, you can cache their results with
cache: true. This means Quarto will only re-run that code if it detects changes, saving you time. You can also specify dependencies between chunks using dependson and track changes to external files with cache.extra.• Self-Contained Documents: For HTML output, you can embed all external dependencies (like images, CSS, JavaScript) directly into the HTML file by setting
embed-resources: true in your YAML, making it easier to share via email.• Parameters: You can define parameters in the YAML header (
params field) whose values can be changed when you render the report. This is useful for generating similar reports with different inputs (e.g., sales reports for different regions).• Citations and Bibliographies: Quarto can automatically generate citations and a bibliography. You can insert citations using the visual editor or by typing a specific markdown format (
[@citation]) in the source editor. It works with DOIs, Zotero, and .bib files, and you can customise the style with CSL files.Workflow Tips for Quarto
• Organise your work: Give each notebook a descriptive title, evocative file name, and a first paragraph outlining its aims.
• Date your work: Use the
date field in the YAML header in ISO8601 YYYY-MM-DD format.• Document everything: Even if an analysis idea fails, don’t delete it; write a note explaining why it failed.
• Data integrity: Never modify raw data files directly. Instead, write code to correct any errors and explain why you made the fix.
• Render frequently: Try to render your document daily, and clear caches if you’re using them, to catch problems early.
• Reproducibility over time: Consider using tools like
renv to track package versions, or include sessionInfo() in a chunk.• Project management: Store your notebooks in individual projects with a clear naming scheme.
This should give you a good foundation for understanding and using Quarto! For more in-depth information and the latest updates, the official Quarto website is the best resource
