Reporting your work

The first example report we saw was rendered into an html file. But what about Word or PDF files, which can be more useful or expected in some situations?. Quarto allows you to generate documents in multiple formats using the same plain text file.

The way you generate the output file format is by changing the format option on the header.

Go back to the example report and find the line that starts with format:. Change html to pdf.

Now try to Render the file into a word document. Use docx.

Code control

Our example looks quite tidy. We’ve hidden all the code and R messages so you can concentrate your attention on the table and figures. But this is not the default behavior of an qmd file. Usually the output will have both code and output, which is fine when you or the person that will read the report wants to see the code that generates those results, but it might not be what the final audience of the report might need. It’s up to you to decide if you want to show the code or not.

To change the options of a chunk code, all you have to do is list the options using #| at the beginning of the line. For example:

```{r}
 #| label: nombre-del-chunk
 #| echo: false
 #| message: false
```

A particularly important set of options are the ones that control whether the code is executed and whether the result of the code will remain in the report or not:

eval: false prevents the chunk code from being run, so it will not display results either. It is useful for displaying example code if you are writing, for example, a document to teach R.
echo: false runs the chunk code and displays the results, but hides the code in the report. This is useful for writing reports for people who do not need to see the R code that generated the graph or table.
include: false runs the code but hides both the code and the results. It is useful to use in general configuration chunks where you load libraries.

If you are writing a report where you don’t want any code to be shown, adding echo: false to each new chunk becomes tedious. The solution is to change the option globally so that it applies to all chunks. This is done by adding the same options in the header under execute.

execute:
  echo: false
  warning: false
  message: false

Curious about how the options works? Change them one at a time and render the file each time to see what changes.

Automatisation

At the beginning of this workshop we asked you to change the penguin species in the example report. The task was not easy because “Gentoo” appears several times and it is easy to make a mistake. Parameterising a report allows us to define those kind of parameters in just one place and get different analyses from the same file.

To generate a parameterised report you have to add an element called params to the header with the list of parameters and their default values.

params:
  species: gentoo

From now on, you’ll have access to a variable called params which is a list containing the parameters and their value. To access the value of each parameter you use the $ operator as follows:

params$species

[1] "Gentoo"

In this way, the original code can be modified to use the value of the specie stored in params$species.

penguins %>% 
  filter(species == params$species) %>% 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm)) +
  geom_point(color = "darkorange",
             size = 3,
             alpha = 0.8) +
  geom_smooth(method = "lm", se = FALSE, color = "darkorange") +
  theme_minimal() +
  labs(title = "Penguin bill dimensions",
       subtitle = paste("Bill length and depth for", params$specie, "Penguins at Palmer Station LTER"),
       x = "Bill length (mm)",
       y = "Bill depth (mm)",
       color = "Penguin species")

Here we changed the subtitle to concatenate words with the value stored in params$species, this way we can construct the subtitle pragmatically.

Now the report is ready to function as a parameterised report!

Finally, change “Gentoo” on the yaml to generate a new report for one of the other species.

--- title: "Reporting your work" format: html: toc: true toc-location: left code-tools: source: true highlight-style: tango --- ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE) chunk <- "```" ``` The first example report we saw was rendered into an html file. But what about Word or PDF files, which can be more useful or expected in some situations?. Quarto allows you to generate documents in multiple formats using the same plain text file. The way you generate the output file format is by changing the `format` option on the header. > Go back to the example report and find the line that starts with `format:`. Change `html` to `pdf`. > > Now try to Render the file into a word document. Use `docx`. ## Code control Our example looks quite tidy. We've hidden all the code and R messages so you can concentrate your attention on the table and figures. But this is not the default behavior of an qmd file. Usually the output will have both code and output, which is fine when you or the person that will read the report wants to see the code that generates those results, but it might not be what the final audience of the report might need. It's up to you to decide if you want to show the code or not. To change the options of a chunk code, all you have to do is list the options using `#|` at the beginning of the line. For example: `r chunk`{r} #| label: nombre-del-chunk #| echo: false #| message: false `r chunk` A particularly important set of options are the ones that control whether the code is executed and whether the result of the code will remain in the report or not: * `eval: false` prevents the chunk code from being run, so it will not display results either. It is useful for displaying example code if you are writing, for example, a document to teach R. * `echo: false` runs the chunk code and displays the results, but hides the code in the report. This is useful for writing reports for people who do not need to see the R code that generated the graph or table. * `include: false` runs the code but hides both the code and the results. It is useful to use in general configuration chunks where you load libraries. If you are writing a report where you don't want any code to be shown, adding `echo: false` to each new chunk becomes tedious. The solution is to change the option globally so that it applies to all chunks. This is done by adding the same options in the header under `execute`. ```yaml execute: echo: false warning: false message: false ``` > Curious about how the options works? Change them one at a time and render the file each time to see what changes. ## Automatisation At the beginning of this workshop we asked you to change the penguin species in the example report. The task was not easy because "Gentoo" appears several times and it is easy to make a mistake. Parameterising a report allows us to define those kind of parameters in just one place and get different analyses from the same file. To generate a parameterised report you have to add an element called `params` to the header with the list of parameters and their default values. ```yaml params: species: gentoo ``` ```{r, include=FALSE} params <- list(species = "Gentoo") ``` From now on, you'll have access to a variable called `params` which is a list containing the parameters and their value. To access the value of each parameter you use the `$` operator as follows: ```{r} params$species ``` In this way, the original code can be modified to use the value of the specie stored in `params$species`. ```{r eval=FALSE} penguins %>% filter(species == params$species) %>% ggplot(aes(x = bill_length_mm, y = bill_depth_mm)) + geom_point(color = "darkorange", size = 3, alpha = 0.8) + geom_smooth(method = "lm", se = FALSE, color = "darkorange") + theme_minimal() + labs(title = "Penguin bill dimensions", subtitle = paste("Bill length and depth for", params$specie, "Penguins at Palmer Station LTER"), x = "Bill length (mm)", y = "Bill depth (mm)", color = "Penguin species") ``` Here we changed the subtitle to concatenate words with the value stored in `params$species`, this way we can construct the subtitle pragmatically. Now the report is ready to function as a parameterised report! > Finally, change "Gentoo" on the yaml to generate a new report for one of the other species.