05-reports.Rmd

---
title: "Reporting your work"
output: 
  html_document:
    code_download: true
    toc: true
    toc_float: false
    highlight: 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 usefull or expected in some situations?. RMarkdown, and a whole ecosystem of other packages, 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 `output` option on the header.

> Go back to the example report and find the line that starts with `output:`. Change `html_document` to `pdf_document`.

You can also use the "knit" button, clicking on the little arrow on the right to see all the options. 

> Now se the button to generate a word document. What changes do you see on the heather of the file?

## 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 behaviour of an Rmd 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 inside the square brackets. For example:

    `r chunk`{r 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 the `knitr::opts_chunk$set()` function, which sets the global options of the chunks that follow it. You'll find this function on the first "setup" chunk.

    `r chunk`{r setup, include = FALSE}
    knitr::opts_chunk$set(echo = FALSE, 
                      message = FALSE,
                      warning = FALSE)
    `r chunk`
    
> Curious about how the options works? Change them one at a time and knit 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.