Data Rich Reports

Session 1–Basic Authoring in Quarto

Overview

Quarto


  • Quarto is an open-source scientific publishing platform
  • Allows you to integrate text with code
  • Kind of like a word processor for data science
  • Can use it to create reports, books, websites, etc.
  • Can make HTML, PDF, Word, and other formats
  • Can use R, Python, Julia, and other languages

Quick Discussion


  • Have a look at the Quarto gallery
  • What project(s) do you like?
  • What would you like to do for a final project?
  • Discuss with a neighbor
03:00

Setup

Install R and RStudio


  • If you haven’t already…
  • Go to the RStudio download page
  • Download R and then RStudio

Set up RStudio


  • Go to Tools>Global Options
  • Under Code, enable native pipe operator (|>)
  • Under Appearance, choose a theme
  • Configure panes
    • Go to Pane Layout
    • Move Source, Console, etc. to preferred positions

Illustration

03:00

Using Quarto

Project Oriented Workflow


  • Always start a document in a project folder
    • That way you don’t have to do setwd
    • Also can share easily with other people
  • Go to File>New Project
  • Create a Quarto project folder

Visual Editor

  • There are two ways to edit Quarto docs
    • Source (markdown)
    • Visual editor
  • Visual editor
    • WYSIWYM
    • Approximates appearance
  • Try both and see what you like

Rendering Documents

  • Rendering = converting to another format
    • Default format is HTML
    • Can also render to PDF, Word, etc.
  • To render a Quarto document
    • Click on the Render button
      • Or keyboard shortcut (Cmd/Ctrl + Shift + K)
  • By default, Quarto will preview the document in your browser
  • But you can also preview in Viewer pane
    • Click on the gear icon next to the Render button
    • Select “Preview in Viewer Pane”

Illustration

Let’s Try Quarto!

  • Create a new Quarto document
    • File>New File>Quarto Document
  • Save the document in your project folder
  • Render it
    • Click on the Render button
    • Or keyboard shortcut (Cmd/Ctr + Shift + K)
  • Try out the visual editor
02:00

Quarto Docs

Document Elements


  • YAML Header
  • Markdown content
  • Code chunks

YAML Header


  • Metadata about the document
    • Title, author, date, etc.
  • Output format
  • Execution options

YAML Header

---
title: "My Documnet"
author: "Your Name"
date: today
date-format: long
format: html
execute:
  echo: false
  message: false
---
  • Try changing some of these options in your document
  • Then render it again
  • Look in the Quarto guide for other options to try
02:00

Markdown


  • Markdown is a simple markup language
  • You can use it to format text
  • You can also use it to embed images, tables, etc.
  • And to embed code chunks…

Markdown Syntax - Basic Authoring

  • For basic text you can just start typing
  • For line breaks use two spaces and return (enter)
  • Headings (use #, ##, ###, etc.)
    • # is the largest heading (level 1)
    • ## is the next largest (level 2)
    • ### is the next largest (level 3)
    • Etc.

Markdown Syntax - Styling

  • Emphasis = Italics (use *)
    • Bold (use **)
  • Lists
    • Bullet points (use -)
    • Numbered lists (use 1.)

Markdown Syntax - Content

  • Links (use [text](url))
  • Images (use ![](file path or url))
  • Code chunks
    • R code chunks (```{r}…```)
    • Python code chunks (```{python}…```)
    • Etc.

Try Some Markdown


  • Check out the Markdown Cheatsheet
  • Try editing the markdown in your document
  • Try incorporating an figure (image), link, table, etc.
  • Try some of the other things you find in the guide
  • Then render it again
10:00

Code Chunks

  • Incorporate R code (could also be Python, Julia, etc.)
  • Add a code chunk with the ‘+’ button
  • Run the code chunk by clicking the play button
    • Or use keyboard shortcut (Cmd/Ctrl + Shift + Enter)
  • Run all chunks up that point by clicking the down arrow
    • Or use keyboard shortcut (Cmd/Ctrl + Shift + K)
  • Run a single line with shortcut (Cmd/Ctrl + Enter)

Code Chunk Options

  • Use #| (hash-pipe) to add options
  • label is a unique identifier for the chunk
  • Options to control what happens when you render
    • echo controls whether the code is shown
    • eval controls whether the code is run
    • message controls whether messages are shown
    • warning controls whether warnings are shown

Code Chunk Options


  • Code-chunk options override global options set in YAML header
  • See documentation for more options
  • You can also use write chunk options inline with chunk name,
    • e.g., {r, echo = FALSE} ...

Illustration

Your Turn!


  • Try running a code chunk in your document
  • Change the chunk options
  • Run the code again

DRR Website