10:00
Workshop: Quarto for R & RStudio
posit::conf 2023
Take ~2 minutes to introduce yourself to your neighbors.
Please share …
Workshop materials are at:
Everyone leaves with a report and presentation.
Learn from one another.
Build an understanding of the big picture.
Introduction to Quarto
Ask questions at #introduction-to-quarto-with-r-and-rstudio.
During an activity, place a blue sticky on your laptop if you’re good to go and a red sticky if you want help.
Image by Megan Duffy
Sit back and enjoy the tour!
Join me in Posit Cloud!
Open hello-penguins.qmd
in RStudio and…
hello-penguins.qmd
. What do you notice that’s different from what it would look like in an Rmd document? Work with your neighbor to see if you can find the differences (there are at least 3).10:00
Sweave
weaves together S/R and \(\TeX\)pandoc
converts between different document formatsknitr
a next gen Sweave for R and Markdownknitr::pandoc
added to leverage pandoc
flexible outputspandoc
functionality moved into new rmarkdown
. . . throughout, an ecosystem of R packages develops . . . (bookdown
, blogdown
, distill
, etc.)
Quarto is compute-agnostic. R Markdown requires R.
The ecosystem of R packages is replaced by a single framework.
workflowr
, papaja
) that haven’t yet been implemented in Quarto.Heavy users of such tools may want to stick with R Markdown.
Note: You can render existing R Markdown documents with Quarto and/or rename them to .qmd files to turn them into Quarto documents.
Render input file to various document formats.
Input
*.qmd
*.ipynb
*.md
*.Rmd
Format
html
pdf
revealjs
docx
ppt
Quarto is integrated into RStudio
Click in Editor pane of RStudio.
HTML
LATEX
HTML
LATEX
Render 2-formats.qmd
to html
and view the html file in an editor. How is the list expressed in html? (you can click on it in the Files pane)
Render 2-formats.qmd
to latex
and view the latex file in an editor. How is the list expressed in latex?
Change the extension of 2-formats.qmd
to be .md
and .Rmd
and re-render. Does the output differ?
Try rendering the file to a pdf format but this time using the CLI (command line interval) in the Terminal tab.
07:00
A quick way to find out how Pandoc will convert: https://pandoc.org/try/.
“Yet Another Markup Language” or “YAML Ain’t Markup Language” is used to provide document level metadata …
Which of the following are valid ways to include metadata?
Invalid
Lint, or a linter, is a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs.
RStudio + VSCode provide rich tab-completion - start a word and tab to complete, or Ctrl + space
to see all available options.
hello-penguins.qmd
in RStudio.Ctrl + space
to see the available YAML options.05:00
The Elements of Markdown
Markdown is designed to be easy to write and easy to read:
A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
-John Gruber
Whenever I hear “Pandoc”, I picture . . .
Via giphy.
Which of the following forms of text formatting are possible in pandoc markdown?
Markdown allows you to format text with emphasis and strong emphasis. You can also add superscripts2, subscripts2, and display code verbatim
. Little known fact: you can also strikethrough text and present it in small caps.
1
The area of a circle is \(A = \pi r^2\), where \(r\) is the radius and \(\pi\) is the constant \(3.141592\ldots\).
TeX math lives between two
$
. Opening$
must have a non-space character immediately to its right, while the closing$
must have a non-space character immediately to its left, and must not be followed immediately by a digit.– the Pandoc Docs
You can embed [links with names](https://quarto.org/), direct urls
like <https://quarto.org/>, and links to
[other places](#inline-elements-text-formatting) in the document.
The syntax is similar for embedding an inline image:
![render icon](images/render-icon.png).
You can embed links with names, direct urls like https://quarto.org/, and links to other places in the document. The syntax is similar for embedding an inline image: .
Placement of the actual footnote depends on the format: end of page for pdf, end of doc for HTML, bottom of slide for presentations.
One or more lines of text followed by one or more blank lines.
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor.
Markdown Syntax | Output |
---|---|
|
Header 1 |
|
Header 2 |
|
Header 3 |
|
Header 4 |
|
Header 5 |
|
Header 6 |
Can use *
, -
, or +
may be used for unordered list items.
Which of the following will render to the output on the right?
A
C
B
D
I has a sandwich.
It was deliicous.
I had coffee.
It gave me joy.
A list item may contain multiple paragraphs and other block-level content. Subsequent block elements must be preceded by a blank line and indented to line up with the first non-space content after the list marker. – the Pandoc Docs
The first list item with a
@
marker will be numbered 1., the next 2., etc. The numbered examples need not occur in a single list; each new list using@
will take up where the last stopped. – the Pandoc Docs
Explanation of examples.
You can also label your examples:
(@goodname)
.
A larger equation:
\[ f(x)=\sqrt{\frac{\tau}{2\pi}} e^{-\tau (x-\mu )^{2}/2} \]
This breaks it:
$$
{x} = _{i=i}^n x_1 $$
For “display” math, use
$$
delimiters.
Block images use the same syntax as inline images.
Images are a block element…
or are they?
Images behave mostly like inline elements but actually live in a block (e.g. a paragraph). Their behavior depends on output format.
Your goal is to create from scratch the beautiful documents 3-markdown-goal.html
and 3-markdown-goal.pdf
. Add into 3-markdown.qmd
the markdown syntax needed to create the various inline and block elements found in the output documents.
Inline
Block
10:00
Sandwich the code between “fences” of at least three backticks1. An optional language provides syntax highlighting.
What syntax is being used in echo=FALSE
?
How can this be generalized to other languages?
How can this be generalized to other languages?
How can this be generalized to other languages?
#|
{r, and=on, and=on, and=on, and=on, and=on, and=on}
<commentchar>|
.eval=FALSE
)Control how the code is executed with options.
Option | Description |
---|---|
eval |
Evaluate the code chunk (if false , just echos the code into the output). |
echo |
Include the source code in output |
output |
Include the results of executing the code in the output (true , false , or asis to indicate that the output is raw markdown and should not have any of Quarto’s standard enclosing markdown). |
warning |
Include warnings in the output. |
error |
Include errors in the output. |
include |
Catch all for preventing any output (code or results) from being included (e.g. include: false suppresses all output from the code block). |
knitr
optionsThe knitr
syntax for passing options still works since Quarto uses knitr
.
While it’s possible to use R chunks options, hash pipe options are more portable across computational engines.
Don’t forget to use tab-completion to see the available options!
Options can be moved into YAML under the execute
key to apply to all chunks. Exceptions to that option can be set cell-by-cell.
You can also pass options via YAML to knitr through the knitr
key1.
Options can be moved into YAML under the execute
key to apply to all chunks. Exceptions to that option can be set cell-by-cell.
You can also pass options via YAML to knitr through the knitr
key1.
You can use knitr to pass options that control your R session.
Save time/code by moving figure sizing defaults up to the YAML.
3-code-cells.qmd
and render the document.echo: false
to the code cell and re-render.#|
or consult the Quarto Reference.07:00
Any questions / anything you’d like to review before we wrap up this module?
Where does the name “Quarto” come from?
30:00