3 Elements of an quarto file

In this chapter, you will

learn the basics of using quarto

3.1 YAML

The YAML is metadata for the document that goes right at the top of the file between two sets of three dashes. The YAML consists of key: values pairs. The colon and space are required. Rstudio will autocomplete the keys.

---
title: "My Manuscript"
format: html
date: 2022-04-03
---

The YAML can set the document author and title, the output format and many other things.

White space

YAML is sensitive to white space. For example, you must have the space after the colon.

Today’s date

With the keyword today, you can make the document report the date it was rendered.

---
title: "My Manuscript"
format: html
date: today
---

Exercise

Add date and author keys to the YAML of your svalbard_traits quarto document so that the rendered document shows today’s date and your name.

3.1.1 Output formats

Quarto documents can be rendered in about 40 formats! The format can be specified when the quarto file is created in RStudio or by editing the YAML.

Producing an html file to view in a browser is the simplest, as no extra software needs installing. The YAML should look something like this.

---
title: "My Manuscript"
format: html
---

Word documents are also easy; just change the format to docx. This can be very useful if you have a supervisor or collaborators who cannot cope with markdown directly.

There are two ways to render a quarto file as a PDF. The easiest is to change the format to typst.

---
title: "My Manuscript"
format: typst
---

Typst comes bundled with quarto. It is very fast and easier to debug than the alternative. However, typst is very new and not yet supported by many journals for manuscript submission.

Quarto, PDF and LaTeX

LaTeX is an alternative way to produce PDF from quarto documents (you don’t need to learn any LaTeX). It requires some external tools to be installed, which can be done with the tinytxt package.

# run this only once
install.packages('tinytex')
tinytex::install_tinytex()

Then the format in the YAML can be changed to pdf.

---
title: "My Manuscript"
format: pdf
---

You don’t need to know any LaTeX, but you can include some if you want to change the formatting etc. For example, you force a new page, you could use the command.

\\newpage

With PDF documents, it can be tricky to control exactly where the figures are positioned, so I recommend working with html as long as possible.

Coauthoring with quarto

Perhaps the best way to collaborate with coauthors on a quarto document is to use version control for example with GitHub.

An alternative is to use the trackdown package to upload markdown files to Google Drive where they can be edited and then downloaded again.

Comments

A comment in an R code block starts with a #, just as in an ordinary R script.

A comment in the text is enclosed an html comment mark

<!-- This is a comment  -->

Select some text and type to make it a comment.

In the source editor, you can select text you want to hide and use this keyboard short-cut to comment it out.

3.2 Text

Type to make text! In the visual editor, you can format the text in much the same way you would work in MS word or LibreOffice. RStudio has a built-in spell checker that will underline words it doesn’t recognise in red.

3.2.1 Source editor

Sometimes it is useful to be able to write in markdown directly, rather than using the visual editor, for example if you are writing a question for stackoverflow.com or an issue on github.com. You can see this mode by clicking on “Source” above the document

Figure 3.1: The Source code and Visual editors

Paragraphs have a blank line between them. It is good practice to write one sentence per line. The extra line breaks will be removed when the document in knitted. If you want to force a line break, put two spaces or a backslash at the end of the line.

Formatting is generated with some special characters. For example:

Markdown Syntax	Output
`# Header 1`	Header 1
`## Header 2`	Header 2
`### Header 3`	Header 3
italics and bold	italics and bold
superscript m^2^	superscript m²
subscript CO~2~	subscript CO₂
`verbatim code`	`verbatim code`

Escaping characters

If you actually want a *_^~ in the text, you need to escape it by putting a backslash \ before it, e.g. \*.

A more complete list of formatting is given in the R markdown cheat sheet, and in the quarto documentation.

Vil du skrive på norsk

Vil du har Dato i stedet for Date, og Figur frem for Figure?

Use the lang tag with nn for nynorsk or nb for bokmål. Other languages are available.

---
title: "My Manuscript"
lang: nn
---

You can change the spell checker language for the current project from the RStudio menu with

You can also change the global options to change the language for all projects.

Exercise

The Results section of the svalbard_traits document should be in Header 1 style, and species names should be in italics. Fix this and render the document to check the formatting has worked.

3.3 Code blocks

Code in an quarto document is contained in code blocks.

This is a code block that loads the tidyverse package.

```{r}
library(tidyverse)
```

It starts with three back-ticks, followed by braces. Inside the braces, the “r” indicates that this block is in the R language. Next, on a new line, is the body of the code block. The block ends with three back-ticks on their own line.

In the visual editor, you won’t see the back-ticks, but the code block will start with {r} and have a grey background.

Figure 3.2: A code block in the visual editor

3.3.1 Making a block

You can type the back-ticks and braces needed to make a block, but, when using the visual editor, it is easier to get RStudio to insert the block with the insert tool.

Type a forwards slash / on a blank line and choose “R code chunk”. You can also use the keyboard short-cut .

3.3.2 Block language

We will just work with R code blocks, but it is possible to run block in other languages, including Python and Julia, which would have {python} and {julia} instead of {r} at the start of the chunk.

3.3.3 Running a code block

Code in blocks will be run when the document is rendered (unless eval: false), but it is also useful to run the code interactively to check that it works. You can do this by clicking on the green play buttons at the top-right of the block (Figure 3.3) or from the Run button above the document. If the code depends on previous block, the grey/green icon will run them all.

Screeshot showing the icons to run the code in a code block. — Figure 3.3: The green run block icon and the grey/green icon to run all previous code blocks

Exercise

Run all the blocks in the document.

Now double click on the object called bistorta in the RStudio Environment tab so you can view it. These are the data we are working with.

Exercise

Make a new code block (or blocks) that make a plot showing the effect of the treatment on Bistorta leaf thickness.

Hint

You can copy and modify some of the existing code rather than writing from scratch. You will need to look at the data. Make sure all your chunk labels are unique.

3.3.4 Block options

Code block options control how the blocks work and how any output is treated. Options are given in special comments at the top of the block.

```{r}
#| label: load-data
#| message: false

# load data
traits <- read_delim("data/PFTC4_Svalbard_2018_ITEX_Traits.csv") 
```

Options format

The white space in the block options is critical.

If you don’t have the space after the #| then the option becomes a regular comment and is ignored.
If you don’t have a space after the colon, you get “ERROR: Render failed due to invalid YAML.”

true and false are written in lower case (in R they are upper case).

The block options must start on the first line of the block after the {r}.

There are lots of block options, but only a few that you will need to use frequently. Here are some and their default.

echo (true) Show the block’s code in the output.
eval (true) Run the block’s code.
include (true) Include the output of the block in the document.
message (true) Include messages from R.
warning (true) Include warnings from R.
output (true) How and whether to include results.
error (false) If true, includes any error message and carries on. If false, stops knitting when there is an error in R code.

I leave message and warning as true while I am writing the document, so I can see any possible problems, and set them to false when I render the final version.

I sometimes find it useful to set error to true as can make it easier to debug any errors in the code.

Some of these block options interact. Use the following widget, which initially shows the defaults, to explore what is shown with the most commonly used options.

Interactive table: Select your block options

eval

include

echo

message

warning

output

Block output

Block options for figures are shown in Section 4.1.1.

For more options see https://quarto.org/docs/computations/execution-options.html

Exercise

Importing packages produces lots of output that we don’t need to see in the final report. Use block options to hide the output of this block.

The code block importing the data is giving a message how the data were imported. Use block options to make this message go away.

3.3.5 Setting global block options

Global code block options can be set for all code blocks by including execute with the option in the YAML at the top of the file.

For example, this YAML would set echo to be false for the entire document (options for individual blocks could override this).

---
title: "My Manuscript"
format: html
execute:
  echo: false
---

Exercise

Use global block options to stop the code from showing in the report.

3.3.6 Block labels

It is a good idea to give code blocks labels which you can do with the label option. If you don’t, they will automatically be called “unnamed-chunk-n” where “n” is a incrementing number. This is inconvenient for debugging (you need to work out which block is “unnamed-chunk-38”) and for working with any image files generated by the document. In section Chapter 6 you will see how to use block names to cross-reference figures and tables in your document.

3.3.6.1 Rules for block labels

Block labels should be informative and can contain letters and numbers. Words should be separated by hyphens (“-”).

Special characters in labels

Avoid spaces, underscores, periods and other special characters in code block labels. They will cause all sorts of strange problems.

3.3.7 Hiding a block

If a block has a lot of code, it can be useful to hide it to make it easier to navigate the document. It will still be rendered. The grey arrow next to the line numbers will do this. Sections of text can also be hidden.

3.3.8 Environments and working directory

R renders quarto documents in a new R session. Initially, no packages are loaded and the environment is empty: the quarto document does not have access to any objects in your current environment (this is a good thing for reproducible analyses). This means that any data or packages you want to use in the document needs to be imported by the code in the document.

The working directory for the new R session used when rendering the quarto file is the directory where the quarto file is. If the file is in the root directory of an RStudio project, relative paths will work the same way in the quarto document as from the console. If the quarto file is in a sub-directory, use here::here() to form paths relative to the project root.

3.4 Inline code

In addition to the output from code blocks, you can insert code directly into text. This lets you avoid copying and pasting numbers from the output. Inline code is enclosed by back-ticks and starts with an r.

Seven times six is `r 7 * 6`

Seven times six is 42

In the visual editor, you can make inline code by clicking on the </> icon.

Numbers in words

If you want numbers written as words, for example at the start of a sentence, use the package english.

`r english::Words(7 * 6)` is the answer to seven times six.

Forty-two is the answer to seven times six.

It is best to keep inline code short to keep the text readable.

Making a list to shorten inline code

One trick to shorten inline code is to do all necessary calculations in a previous code block, so only the name of the object with the result needs to be in the inline code. If there are many results to report, consider storing them in a list as in the following example.

# filter out height data
trait_height <- traits |> 
  filter(Trait == "Plant_Height_cm") |> 
  drop_na(Treatment)

# make list summarising height data
height_info <- list(
  n = nrow(trait_height),
  min = min(trait_height$Value),
  max = max(trait_height$Value)
)

We measured `r height_info$n` plants. 
The minimum height was `r height_info$min` cm and the maximum `r height_info$max` cm.

We measured 422 plants. The minimum height was 0.1 cm and the maximum 30 cm.

glue chunks inline code.

You can also use a glue chunk with the glue package. This might be useful when there is a lot of inline R, or if you want to test it before you render the document.

First we need to load the glue package

library(glue)

The we can use a glue chunk with the chunk option output: asis to format the output as raw markdown. R code is put inside braces {}.

```{glue}
#| label: glue-example
#| output: asis
We measured {height_info$n} plants. The minimum height was {height_info$min} cm and the maximum {height_info$max} cm.
```

We measured 422 plants. The minimum height was 0.1 cm and the maximum 30 cm.

Only one line of text per glue chunk.

Exercise

Use some inline R code to report the number of leaf thickness measurements for Bistorta vivipara.

Rounding numbers

Numbers should be rounded to an appropriate number of decimal places when reported in the text or a table to avoid spurious precision.

Here are some functions that can help

# use round() to round number to the required number of digits after the decimal point.
round(151.98646, digits = 2)

[1] 151.99

round(151.98646, digits = -1) # negative values round to the left of the decimal point.

[1] 150

# Use signif() to set the required number of significant figures
signif(c(0.15198646, 151.98646), digits = 4)

[1]   0.152 152.000

# format.pval() is a special function for formatting p-values. 
# Use the eps argument to set the minimum exact values to display.
format.pval(c(0.194342, 0.00000194342), digits = 3, eps = 0.001)

[1] "0.194"  "<0.001"

# format() when you need more control over how the number is displayed
format(1504703.232, big.mark = ".", decimal.mark = ",",  nsmall = 1) # Norwegian format

[1] "1.504.703,2"

Make sure to do all calculations, analyses and figures on the full precision number and only round to display it as text.

Exercise

The mean Bistorta vivipara height is currently given to the nearest nanometre. This precision is spurious. Edit the inline code in the document so that the mean height and its standard error are shown to two decimal places.

--- editor_options: markdown: wrap: sentence --- ```{r setup, include=FALSE} library(tidyverse) source("../Templates/biostats_theme.R") ``` # Elements of an quarto file {#sec-elements-of-a-quarto-file} ::: callout-note ## In this chapter, you will - learn the basics of using quarto ::: ## YAML The YAML is metadata for the document that goes right at the top of the file between two sets of three dashes. The YAML consists of `key: values` pairs. The colon and space are required. Rstudio will autocomplete the keys. ``` yaml --- title: "My Manuscript" format: html date: 2022-04-03 --- ``` The YAML can set the document author and title, the output format and many other things. ::: callout-warning ## White space YAML is sensitive to white space. For example, you must have the space after the colon. ::: ::: callout-tip ## Today's date With the keyword `today`, you can make the document report the date it was rendered. ``` yaml --- title: "My Manuscript" format: html date: today --- ``` ::: ::: callout-note ## Exercise Add date and author keys to the YAML of your svalbard_traits quarto document so that the rendered document shows today's date and your name. ::: ### Output formats Quarto documents can be rendered in about 40 formats! The format can be specified when the quarto file is created in RStudio or by editing the YAML. Producing an html file to view in a browser is the simplest, as no extra software needs installing. The YAML should look something like this. ``` yaml --- title: "My Manuscript" format: html --- ``` Word documents are also easy; just change the format to `docx`. This can be very useful if you have a supervisor or collaborators who cannot cope with markdown directly. There are two ways to render a quarto file as a PDF. The easiest is to change the format to `typst`. ``` yaml --- title: "My Manuscript" format: typst --- ``` Typst comes bundled with quarto. It is very fast and easier to debug than the alternative. However, typst is very new and not yet supported by many journals for manuscript submission. ::: callout-tip ## Quarto, PDF and LaTeX LaTeX is an alternative way to produce PDF from quarto documents (you don't need to learn any LaTeX). It requires some external tools to be installed, which can be done with the `tinytxt` package. ```{r} #| label: tinytxt #| eval: false #| echo: true # run this only once install.packages('tinytex') tinytex::install_tinytex() ``` Then the format in the YAML can be changed to `pdf`. ``` yaml --- title: "My Manuscript" format: pdf --- ``` You don't need to know any LaTeX, but you can include some if you want to change the formatting etc. For example, you force a new page, you could use the command. ``` latex \\newpage ``` ::: With PDF documents, it can be tricky to control exactly where the figures are positioned, so I recommend working with html as long as possible. ::: callout-tip ## Coauthoring with quarto Perhaps the best way to collaborate with coauthors on a quarto document is to use version control for example with [GitHub](https://biostats-r.github.io/biostats/github/index.html "Git and GitHub book"). An alternative is to use the `trackdown` package to upload markdown files to Google Drive where they can be edited and then downloaded again. ::: ::: callout-tip ## Comments A comment in an R code block starts with a `#`, just as in an ordinary R script. A comment in the text is enclosed an html comment mark ``` markdown  ``` Select some text and type {{< kbd mac=Shift-Command-C win=Control-Shift-C linux=Ctrl-Shift-C >}} to make it a comment. In the source editor, you can select text you want to hide and use this keyboard short-cut to comment it out. ::: ## Text Type to make text! In the visual editor, you can format the text in much the same way you would work in MS word or LibreOffice. RStudio has a built-in spell checker that will underline words it doesn't recognise in red. ### Source editor Sometimes it is useful to be able to write in markdown directly, rather than using the visual editor, for example if you are writing a question for [stackoverflow.com](stackoverflow.com) or an issue on [github.com](github.com). You can see this mode by clicking on "Source" above the document ```{r} #| echo: false fs::dir_create(here::here("docs/quarto/Pics")) fs::file_copy( here::here("quarto/Pics/source-editor.png"), here::here("docs/quarto/Pics/source-editor.png"), overwrite = TRUE) fs::file_copy( here::here("quarto/Pics/visual-editor.png"), here::here("docs/quarto/Pics/visual-editor.png"), overwrite = TRUE) ``` ```{r} #| echo: false #| label: fig-editors #| fig-cap: "The Source code and Visual editors" #| fig-alt: Screenshots of the source code and visual editors #| out-height: "797px" #remotes::install_github("xvrdm/ricv") ricv::ricv(img1 = "Pics/source-editor.png", img2 = "Pics/visual-editor.png", options = list(addCircle = TRUE, hoverStart = TRUE)) ``` Paragraphs have a blank line between them. It is good practice to write one sentence per line. The extra line breaks will be removed when the document in knitted. If you want to force a line break, put two spaces or a backslash at the end of the line. Formatting is generated with some special characters. For example: ```{=html} <style type="text/css"> .heading-output { border-bottom: none; margin-top: 0; margin-bottom: 0; } </style> ``` +------------------------------+--------------------------------------------+ | Markdown Syntax | Output | +==============================+============================================+ | # Header 1 | # Header 1 {.unnumbered .heading-output} | +------------------------------+--------------------------------------------+ | ## Header 2 | ## Header 2 {.unnumbered .heading-output} | +------------------------------+--------------------------------------------+ | ### Header 3 | ### Header 3 {.unnumbered .heading-output} | +------------------------------+--------------------------------------------+ | \*italics\* and \*\*bold\*\* | *italics* and **bold** | +------------------------------+--------------------------------------------+ | superscript m\^2\^ | superscript m^2^ | +------------------------------+--------------------------------------------+ | subscript CO\~2\~ | subscript CO~2~ | +------------------------------+--------------------------------------------+ | \`verbatim code\` | `verbatim code` | +------------------------------+--------------------------------------------+ ::: callout-tip ## Escaping characters If you actually want a \*\_\^\~ in the text, you need to escape it by putting a backslash \\ before it, e.g. \\\*. ::: A more complete list of formatting is given in the [R markdown cheat sheet](https://github.com/rstudio/cheatsheets/blob/master/rmarkdown-2.0.pdf), and in the [quarto documentation](https://quarto.org/docs/authoring/markdown-basics.html). ::: callout-tip ## Vil du skrive på norsk Vil du har Dato i stedet for Date, og Figur frem for Figure? Use the `lang` tag with `nn` for nynorsk or `nb` for bokmål. Other languages are available. ``` yaml --- title: "My Manuscript" lang: nn --- ``` You can change the spell checker language for the current project from the RStudio menu with <ol class="breadcrumb"> <li class="breadcrumb-item">Tools</li> <li class="breadcrumb-item">Project options...</li> <li class="breadcrumb-item">Spelling</li> </ol> You can also change the global options to change the language for all projects. ::: ::: callout-note ## Exercise The Results section of the svalbard_traits document should be in Header 1 style, and species names should be in italics. Fix this and render the document to check the formatting has worked. ::: ## Code blocks Code in an quarto document is contained in code blocks. This is a code block that loads the `tidyverse` package. ```{r} #| echo: fenced library(tidyverse) ``` It starts with three back-ticks, followed by braces. Inside the braces, the "r" indicates that this block is in the R language. Next, on a new line, is the body of the code block. The block ends with three back-ticks on their own line. In the visual editor, you won't see the back-ticks, but the code block will start with `{r}` and have a grey background. ```{r} #| echo: false #| label: fig-visual-code #| fig-cap: A code block in the visual editor #| out-width: 70% knitr::include_graphics("Pics/r-code-block.png") ``` ### Making a block You can type the back-ticks and braces needed to make a block, but, when using the visual editor, it is easier to get RStudio to insert the block with the insert tool. Type a forwards slash {{< kbd / >}} on a blank line and choose "R code chunk". You can also use the keyboard short-cut {{< kbd mac=Option-Command-i win=Control-Alt-i linux=Ctrl-Alt-i >}}. ### Block language We will just work with R code blocks, but it is possible to run block in other languages, including Python and Julia, which would have `{python}` and `{julia}` instead of `{r}` at the start of the chunk. ### Running a code block Code in blocks will be run when the document is rendered (unless `eval: false`), but it is also useful to run the code interactively to check that it works. You can do this by clicking on the green play buttons at the top-right of the block (@fig-run-pic) or from the Run button above the document. If the code depends on previous block, the grey/green icon will run them all. ```{r} #| label: fig-run-pic #| fig-cap: "The green run block icon and the grey/green icon to run all previous code blocks" #| fig-alt: Screeshot showing the icons to run the code in a code block. #| out.width: "220px" #| echo: false knitr::include_graphics("Pics/run-chunk.png") ``` ::: callout-note ## Exercise Run all the blocks in the document. Now double click on the object called `bistorta` in the RStudio Environment tab so you can view it. These are the data we are working with. ::: ::: callout-note ## Exercise Make a new code block (or blocks) that make a plot showing the effect of the treatment on *Bistorta* leaf thickness. <details> <summary>Hint</summary> You can copy and modify some of the existing code rather than writing from scratch. You will need to look at the data. Make sure all your chunk labels are unique. </details> ::: ### Block options Code block options control how the blocks work and how any output is treated. Options are given in special comments at the top of the block. ```{r} #| echo: fenced #| label: load-data #| message: false # load data traits <- read_delim("data/PFTC4_Svalbard_2018_ITEX_Traits.csv") ``` ::: callout-important ## Options format The white space in the block options is critical. - If you don't have the space after the `#|` then the option becomes a regular comment and is ignored. - If you don't have a space after the colon, you get "[ERROR: Render failed due to invalid YAML]{style="color: red"}." `true` and `false` are written in lower case (in R they are upper case). The block options must start on the first line of the block after the `{r}`. ::: There are lots of block options, but only a few that you will need to use frequently. Here are some and their default. - `echo` (`true`) Show the block's code in the output. - `eval` (`true`) Run the block's code. - `include` (`true`) Include the output of the block in the document. - `message` (`true`) Include messages from R. - `warning` (`true`) Include warnings from R. - `output` (`true`) How and whether to include results. - `error` (`false`) If `true`, includes any error message and carries on. If `false`, stops knitting when there is an error in R code. I leave `message` and `warning` as `true` while I am writing the document, so I can see any possible problems, and set them to `false` when I render the final version. I sometimes find it useful to set `error` to `true` as can make it easier to debug any errors in the code. Some of these block options interact. Use the following widget, which initially shows the defaults, to explore what is shown with the most commonly used options. ::: {style="background-color: gainsboro; padding:5px; border: 2px solid darkgrey;"} **Interactive table: Select your block options** ```{r} #| label: chunk-option-setup #| echo: false #| layout-ncol: 2 library(reactable) library(crosstalk) # remotes::install_github("richardjtelford/crosstalk@no-all) block_options <- crossing(eval = c(TRUE, FALSE), echo = c(TRUE, FALSE), message = c(TRUE, FALSE), warning = c(TRUE, FALSE), include = c(TRUE, FALSE), output = c("true", "asis", "false")) |> mutate( Code = if_else(echo & include, "shown", "hidden"), Messages = case_when( !eval ~ "none", !include ~ "hidden", !message ~ "hidden", TRUE ~ "shown" ), Warnings = case_when( !eval ~ "none", !include ~ "hidden", !warning ~ "hidden", TRUE ~ "shown" ), `Text, figures & tables` = case_when( !eval ~ "none", !include ~ "hidden", output == "false" ~ "hidden", output == "asis" ~ "raw markdown", TRUE ~ "shown" ) ) |> mutate(across(eval:include, tolower), across(eval:include, \(x)factor(x, levels = c("true", "false"))), output = factor(output, levels = c("true", "asis", "false"))) # make crosstalk shared data data <- SharedData$new(block_options) # make select input filter_select("eval", "eval", data, ~eval, multiple = FALSE) filter_select("include", "include", data, ~include, multiple = FALSE) ``` ```{r} #| label: chunk-option-selects #| echo: false #| layout-ncol: 4 filter_select("echo", "echo", data, ~echo, multiple = FALSE) filter_select("message", "message", data, ~message, multiple = FALSE) filter_select("warning", "warning", data, ~warning, multiple = FALSE) filter_select("output", "output", data, ~output, multiple = FALSE) ``` **Block output** ```{r} #| echo: false reactable(data, minRows = 1, pagination = FALSE, showPageInfo = FALSE, outlined = TRUE, defaultColDef = colDef( style = function(value) { cols <- c("hidden" = "#bce2f7", "shown" = "#bdf7bc", "none" = "#f7c0bc", "raw markdown" = "#bdf7bc") colour <- as.vector(cols[value]) list(background = colour) } ), columns = list( eval = colDef(show = FALSE), echo = colDef(show = FALSE), message = colDef(show = FALSE), warning = colDef(show = FALSE), include = colDef(show = FALSE), output = colDef(show = FALSE), Code = colDef(show = TRUE), Messages = colDef(show = TRUE), Warnings = colDef(show = TRUE), `Text, figures & tables` = colDef(show = TRUE) ), theme = reactableTheme( backgroundColor = "lightgrey" )) ``` ```{js echo = FALSE} function filter_default() { document.getElementById("eval").getElementsByClassName("selectized")[0].selectize.setValue("true", false); document.getElementById("echo").getElementsByClassName("selectized")[0].selectize.setValue("true", false); document.getElementById("message").getElementsByClassName("selectized")[0].selectize.setValue("true", false); document.getElementById("warning").getElementsByClassName("selectized")[0].selectize.setValue("true", false); document.getElementById("include").getElementsByClassName("selectized")[0].selectize.setValue("true", false); document.getElementById("output").getElementsByClassName("selectized")[0].selectize.setValue("true", false); } $(document).ready(filter_default); //document.addEventListener("load", filter_default); ``` ::: Block options for figures are shown in @sec-figure-chunk-options. For more options see <https://quarto.org/docs/computations/execution-options.html> ::: callout-note ## Exercise Importing packages produces lots of output that we don't need to see in the final report. Use block options to hide the output of this block. The code block importing the data is giving a message how the data were imported. Use block options to make this message go away. ::: ### Setting global block options Global code block options can be set for all code blocks by including `execute` with the option in the YAML at the top of the file. For example, this YAML would set echo to be false for the entire document (options for individual blocks could override this). ``` yaml --- title: "My Manuscript" format: html execute: echo: false --- ``` ::: callout-note ## Exercise Use global block options to stop the code from showing in the report. ::: ### Block labels It is a good idea to give code blocks labels which you can do with the `label` option. If you don't, they will automatically be called "unnamed-chunk-n" where "n" is a incrementing number. This is inconvenient for debugging (you need to work out which block is "unnamed-chunk-38") and for working with any image files generated by the document. In section @sec-cross-referencing you will see how to use block names to cross-reference figures and tables in your document. #### Rules for block labels Block labels should be informative and can contain letters and numbers. Words should be separated by hyphens ("-"). ::: callout-warning ## Special characters in labels Avoid spaces, underscores, periods and other special characters in code block labels. They will cause all sorts of strange problems. ::: ### Hiding a block If a block has a lot of code, it can be useful to hide it to make it easier to navigate the document. It will still be rendered. The grey arrow next to the line numbers will do this. Sections of text can also be hidden. ### Environments and working directory R renders quarto documents in a new R session. Initially, no packages are loaded and the environment is empty: the quarto document does not have access to any objects in your current environment (this is a good thing for reproducible analyses). This means that any data or packages you want to use in the document needs to be imported by the code in the document. The working directory for the new R session used when rendering the quarto file is the directory where the quarto file is. If the file is in the root directory of an RStudio project, relative paths will work the same way in the quarto document as from the console. If the quarto file is in a sub-directory, use `here::here()` to form paths relative to the project root. ## Inline code In addition to the output from code blocks, you can insert code directly into text. This lets you avoid copying and pasting numbers from the output. Inline code is enclosed by back-ticks and starts with an `r`. ```{r} #| echo: false #| results: asis cat("``` markdown\n") cat("Seven times six is `r 7 * 6`") cat("\n```") ``` ::: bg-success Seven times six is `r 7 * 6` ::: In the visual editor, you can make inline code by clicking on the `</>` icon. ::: callout-tip ## Numbers in words If you want numbers written as words, for example at the start of a sentence, use the package `english`. ```{r} #| echo: false #| results: asis cat("``` markdown\n") cat("`r english::Words(7 * 6)` is the answer to seven times six.") cat("\n```") ``` ::: bg-success `r english::Words(7 * 6)` is the answer to seven times six. ::: ::: It is best to keep inline code short to keep the text readable. ::: callout-tip ## Making a list to shorten inline code One trick to shorten inline code is to do all necessary calculations in a previous code block, so only the name of the object with the result needs to be in the inline code. If there are many results to report, consider storing them in a list as in the following example. ```{r trait-stats} #| label: height-info # filter out height data trait_height <- traits |> filter(Trait == "Plant_Height_cm") |> drop_na(Treatment) # make list summarising height data height_info <- list( n = nrow(trait_height), min = min(trait_height$Value), max = max(trait_height$Value) ) ``` ```{r} #| echo: false #| results: asis cat("``` markdown\n") cat("We measured `r height_info$n` plants. The minimum height was `r height_info$min` cm and the maximum `r height_info$max` cm.") cat("\n```") ``` ::: bg-success We measured `r height_info$n` plants. The minimum height was `r height_info$min` cm and the maximum `r height_info$max` cm. ::: ::: ::: callout-tip ## glue chunks inline code. You can also use a `glue` chunk with the `glue` package. This might be useful when there is a lot of inline R, or if you want to test it before you render the document. First we need to load the `glue` package ```{r} #| label: glue library(glue) ``` The we can use a `glue` chunk with the chunk option `output: asis` to format the output as raw markdown. R code is put inside braces `{}`. ```{glue} #| label: glue-example #| output: asis We measured {height_info$n} plants. The minimum height was {height_info$min} cm and the maximum {height_info$max} cm. ``` ```{glue} #| label: glue-example-active #| echo: false #| class-output: bg-success We measured {height_info$n} plants. The minimum height was {height_info$min} cm and the maximum {height_info$max} cm. ``` Only one line of text per `glue` chunk. ::: ::: callout-note ## Exercise Use some inline R code to report the number of leaf thickness measurements for *Bistorta vivipara*. ::: ::: callout-tip ## Rounding numbers Numbers should be rounded to an appropriate number of decimal places when reported in the text or a table to avoid spurious precision. Here are some functions that can help ```{r} #| label: round # use round() to round number to the required number of digits after the decimal point. round(151.98646, digits = 2) round(151.98646, digits = -1) # negative values round to the left of the decimal point. # Use signif() to set the required number of significant figures signif(c(0.15198646, 151.98646), digits = 4) # format.pval() is a special function for formatting p-values. # Use the eps argument to set the minimum exact values to display. format.pval(c(0.194342, 0.00000194342), digits = 3, eps = 0.001) # format() when you need more control over how the number is displayed format(1504703.232, big.mark = ".", decimal.mark = ",", nsmall = 1) # Norwegian format ``` Make sure to do all calculations, analyses and figures on the full precision number and only round to display it as text. ::: ::: callout-note ## Exercise The mean *Bistorta vivipara* height is currently given to the nearest nanometre. This precision is spurious. Edit the inline code in the document so that the mean height and its standard error are shown to two decimal places. :::