Reports in R

class: center, top

![:scale 30%](/assets/images/coding_club_logo_1.png)

<!-- Adjust the presentation to the session. Focus on the challenges,
this is not a coding tutorial.

Note, to include figures, store the image in the `/docs/assets/images`
folder and use the jekyll base.url reference as done in this template
or see https://jekyllrb.com/docs/liquid/tags/#links.
  using the scale attribute ![:scale 30%](...), you can adjust the image size.
-->

# 17 DECEMBER 2024

## INBO coding club

Herman Teirlinck 
01.69 - Paul Janssen 
Holiday edition 🎅

---
class: left, top

## ROOMIE: room reservation

```
> if (isFALSE(roomie)) {
+   warning("Please confirm asap the room reservation on the roomie")
+ }
Warning message:
Please confirm asap the room reservation on the roomie
```

---
class: left, top

## INBO coding club goes to FOSDEM'25

- [**FOSDEM**](https://fosdem.org/2025/) is a free event for software developers to meet, share ideas and collaborate. Every year, thousands of developers of free and open source software from all over the world gather at the event in Brussels. You don't need to register. Just turn up and join in!
- Lightning talk about our club will be given at the dev room "Open Research": see [timetable](https://fosdem.org/2025/schedule/track/research/).

![:scale 80%](/assets/images/20241217/20241217_fossdem_coding_club.png)

---
class: center, middle

![:scale 90%](/assets/images/20241217/20241217_badge.png)

---
class: left, top

## Markdown, R Markdown, bookdown, INBOmd: help!

- Markdown: a markup language \* for creating formatted text using a plain-text editor (= you do NOT t get what you see).
E.g. make text italic by surrounding it with underscores or asterisks, e.g. `__text__`
- R Markdown: a file type with extension `Rmd` to _knit_ text (in Markdown) and code (in R) together. Goal: generate high quality shareable reports.
- [`rmarkdown`](https://rmarkdown.rstudio.com/lesson-1.html): the R package to write R Markdown documents**.
- [bookdown](https://bookdown.org/yihui/bookdown/): R package to make authoring _books_ or technical documents out of a series of R Markdown documents
- [INBOmd](https://github.com/inbo/INBOmd#readme): R package containing templates to generate reports, slides or posters with the corporate identity of INBO or the Flemish government.

![:scale 40%](/assets/images/20241217/20241217_hexlogos.png)

\** A markup language is a language that annotates text so that the computer can manipulate that text. Most markup languages are human-readable. More on [Wikipedia](https://en.wikipedia.org/wiki/Markup_language#Descriptive_markup). 
\** * R Markdown is by default installed within RStudio!

---
class: left, top

The main reference material for today's coding club:

- R Markdown cheat sheet: [web version](https://rstudio.github.io/cheatsheets/html/rmarkdown.html). Download the [pdf version](https://github.com/inbo/coding-club/blob/main/cheat_sheets/20241217_cheat_sheet_rmarkdown.pdf) if you prefer.
- The [R Markdown](https://bookdown.org/yihui/rmarkdown/) reference book
- The [bookdown](https://bookdown.org/yihui/bookdown/) reference book
- [Thierry's slides](https://inbo.github.io/inbomd_examples/inbomd_workshop/inbomd_workshop.pdf) about writing a report with INBOmd

![:scale 80%](/assets/images/20241217/20241217_cheatsheet.png)

---
class: left, top

# R Packages

Load the packages (or install them first):

```r
library(tidyverse)    # to do datascience
library(INBOtheme)    # to apply INBO style to graphs
library(sf)           # to work with geospatial vector data
library(mapview)      # to make dynamic maps
```

---
class: center, top

### How to get started?

Check the [Each session setup](https://inbo.github.io/coding-club/gettingstarted.html#each-session-setup) to get started.

### First time coding club?

Check the [First time setup](https://inbo.github.io/coding-club/gettingstarted.html#first-time-setup) section to setup.

---
class: left, top

![:scale 100%](/assets/images/coding_club_sticky_concept.png)

---
class: center, top

### Share your code during the coding session!

Go to https://hackmd.io/lZNAaZtmQOC6yfBLY5UiTA?both

---
class: left, top

# Challenge 0: R Markdown in a nutshell

- `File` ->  `New File` -> `R Markdown...` -> Title: "test", Author: your name, Output format: HTML (deafult)
- Switch to Visual Markdown Editor (VME) and try to write further: amazing, isn't?
- Save it as `test.Rmd`
- **knit** it to create html (= `rmarkdown::render("test.Rmd")` in console)

![:scale 100%](/assets/images/20241217/20241217_knit_does_the_magic.png)

---
class: left, top

# The YAML header: y a m l what???

The first lines between triple dashes (`---`) is our **header**, needed to configure the output to generate by setting up the title, the author, the output type, etc.

And why is it called a YAML header? Because it is written in YAML :-) YAML is a programming language typically used to write such kind of **configurations**.

Why do people use YAML for writing configurations files? Because YAML is very, very **human readable**.

```r
---
title: "test"
author: "Damiano Oldoni"
date: "17-12-2024"
output: html_document
---
```

---
class: left, top

# Download data and code

- Download everything automatically via `inborutils::setup_codingclub_session()`.
- manually*, from [data/20241217](https://github.com/inbo/coding-club/blob/master/data/20241217/) and [src/20241217](https://github.com/inbo/coding-club/blob/master/src/20241217). Place the R script in `/src/20241217/` and data in `/data/20241217/`.

* __Note__: check the getting started instructions on [how to download a single file](https://inbo.github.io/coding-club/gettingstarted.html#each-session-setup)

---
class: left, top

# Data and scripts description

1. [20241217_challenges.R](https://github.com/inbo/coding-club/blob/master/src/20241217/20241217_challenges.R): R script to start with and containing both code and text.
2. [20241217_occurrence_cube_anemone.tsv](https://github.com/inbo/coding-club/blob/master/data/20241217/20241217_occurrence_cube_anemone.tsv): species occurrence cube* for alien species of genus _Anemone_ from 2010 to 2023 in Belgium. Extracted from https://doi.org/10.15468/dl.2phyja.
3. [20241217_utm1_be.gpkg](https://github.com/inbo/coding-club/blob/master/data/20241217/20241217_utm1_be.gpkg): spatial grid of Belgium at 1km x 1km resolution. Derived from the [Belgium shapefile](https://www.eea.europa.eu/data-and-maps/data/eea-reference-grids-2/gis-files/belgium-shapefile) provided by the European Environment Agency (EEA).

* A species occurrence cube is a new experimental output of GBIF developed in the context of the [B-Cubed](https://b-cubed.eu/) project. An occurrence cube aggregates occurrences per taxon (e.g. species), time (e.g. year) and space (e.g. EEA grid cells). For more info, please check the document ["Specification for species occurrence cubes and their production"](https://docs.b-cubed.eu/occurrence-cube/specification/).

---
background-image: url(/assets/images/background_challenge_1.png)
class: left, top

# Challenge 1

Convert the text and the code in [20241217_challenges.R](https://github.com/inbo/coding-club/blob/master/src/20241217/20241217_challenges.R) to a Rmd document called `20241217_anemone_analysis.Rmd` and _knit_ it as html. Using the cheatsheet and the specific tips provided, please, take care of:

1. Converting the comments to text.

2. Showing the library you need to load but avoiding to show any returned **message** (errors or warnings are allowed). Tip: check the [list](https://yihui.org/knitr/options/#text-output) with all test-output chunk options. How to avoid showing **warnings** as well?

3. adding **inline code** where needed, e.g. min(anemone_cube$year) and max(anemone_cube$year) in the script. [Tip](https://bookdown.org/yihui/rmarkdown/r-code.html).

4. Setting the date automatically in the YAML header. [Tip](https://bookdown.org/yihui/rmarkdown-cookbook/update-date.html). (UPDATE: this is the default behavior now. Maybe try to change it back to use a fix date).

5. Paging the data frames so that they look always nice. [Tip](https://bookdown.org/yihui/rmarkdown/html-document.html#data-frame-printing).

---
background-image: url(/assets/images/background_challenge_2.png)
class: left, top

# Challenge 2

Let's add some text and code from [20241217_challenges.R](https://github.com/inbo/coding-club/blob/master/src/20241217/20241217_challenges.R) to the Rmd to generate visualizations and maps.

1. Add a table of content. Allow the table of contents being always visible, even when the document is scrolled. [Tip](https://bookdown.org/yihui/rmarkdown/html-document.html#table-of-contents).

2. Add section numbers to the table of content. [Tip](https://bookdown.org/yihui/rmarkdown/html-document.html#section-numbering).

3. Use tabbed sections where mentioned (static plots). Tip: check the [tabbed](https://bookdown.org/yihui/rmarkdown/html-document.html#tabbed-sections) section.

4. The chunk codes for the plots and the dynamic map can be quite long and so potentially distracting for the readers. Please, fold them. Readers can then choose to display them by clicking the fold buttons: Tip: check the [fold-show](https://bookdown.org/yihui/rmarkdown-cookbook/fold-show.html) section.

---
class: left, top

# Intermezzo

What happens in a R Markdown stays in that R Markdown! For example: knitting a Rmd containing a variable created in another Rmd will return an error: "variable not found". Three solutions:

1. Put all your workflow in a single Rmd. Good for blogposts and tutorials. Not for complex data analysis, workflows and reports.

2. Save temporary outputs at the end of a Rmd and load them at the beginning of the second Rmd. You have to knit both and be sure to update the second Rmd if you change the first one. Not handy if you work with many Rmds.

3. Create a book with [bookdown](https://bookdown.org/)!

---
class: left, top

# Intermezzo: bookdown

First, make a new book with the RStudio Project Wizard (File > New Project > New Directory > Book project using bookdown) and select gitbook from the dropdown menu. Call the directory, and so, the project, `report_anemone`. Notice you can _build_ your book via a "Buid book" option in the Build pane of RStudio (see screenshot below). More about gitbook style in the [dedicated chapter](https://bookdown.org/yihui/bookdown/html.html#gitbook-style) from the bookdown guide.

![:scale 100%](/assets/images/20241217/20241217_build_book.png)

---
background-image: url(/assets/images/background_challenge_3.png)
class: left, top

# Challenge 3

Try to convert the content of your Rmd document in the book we have just created. Split the Rmd in 2 chapters: the first about reading, exploring and preprocessing the data, the second about visualizing the data (plots and maps). Follow these tips from [Thierry's slides](https://inbo.github.io/inbomd_examples/inbomd_workshop/inbomd_workshop.pdf). Notice that some files are already present, you just need to "slightly" edit them.

![:scale 80%](/assets/images/20241217/20241217_tip_challenge3.png)

---
class: left, top

# Bonus challenge 1

Now you know how to create a _book_, you can understand the phylosophy behind the INBO package `INBOmd` and can fully understand the [slides](https://inbo.github.io/inbomd_examples/inbomd_workshop/inbomd_workshop.pdf) of Thierry! Give `INBOmd` a try by creating the same book as in challenge 3: your report is 100% INBO-styled, yeah! Tip: check `?INBOmd::report()` as well.

---
class: left, top

## Do you know that...

1. Many INBO tutorials are written in R markdown and then _knitted_ as markdown documents? See [example](https://inbo.github.io/tutorials/tutorials/spatial_wfs_services/).
2. Markdown is very popular to easily write webpages. Check the [oscibio](https://oscibio.inbo.be/) team page or the [craywatch](https://craywatch.inbo.be/) website. Both use [Petridish](https://peterdesmet.com/petridish/), a Jekyll* template developed by our colleague Peter Desmet. So, a [Markdown document](https://github.com/inbo/craywatch/blob/main/pages/soorten/faxonius-limosus.md?plain=1) becomes a [webpage](https://craywatch.inbo.be/soorten/faxonius-limosus/).
3. [Data processing pipelines](https://trias-project.github.io/alien-plants-belgium/dwc_mapping.html) published as GitHub pages are actually R markdown documents?
4. The Hackmd pages we use at the INBO coding club follow markdown syntax? Yes, probably you know it!
5. The process of creating an unified checklist of alien species in Belgium (published on GBIF as the [GRIIS checklist of Belgium](https://www.gbif.org/dataset/6d9e952f-948c-4483-9807-575348147c7e)) is a bookdown [document](https://trias-project.github.io/unified-checklist/)? Same for the R reference book of Hadley Wickham, [Advanced R](https://adv-r.hadley.nz/). View the [source](https://github.com/hadley/adv-r/blob/master/index.Rmd): amazing, isn't?

* [Jekyll](https://jekyllrb.com/) is a a static site generator. It takes text written in your favorite markup language (e.g; Markdown) and uses layouts (e.g. Petridsh) to create a static website.

---
class: left, top

## Quarto (.qmd): is it the future?

Do you know about [Quarto](https://quarto.org/) documents? Well, probably we all will write them within a year or two...

Quarto is*:

- A way to combine the (benefits of) R (R Markdown, bookdown, tidyverse packages) and Python (Jupyter Book, Jupyter notebooks, pandas, matplotlib) data science ecocystems.
- A rewrite of RMarkdown with multilanguage as a first-class concern.
- A way to get an accessible webpage AND a publication-ready PDF from the same source.
- A really big wrapper around Pandoc (the document converter used to "knit" Rmd documents).
- Not a prototype anymore: tens of thousands of users already.

Do you know that the [Communicate section](https://r4ds.hadley.nz/communicate) of the R for Data Science book focusses on Quarto and is written using Quarto?

One thing is for sure: all effort you did up to now is not for nothing! Quarto is very similar to Rmd.

\** Credits: Carlos Scheidegger, see his [slides](https://cscheid.net/static/2023-esip-quarto-talk/#/title-slide) and [live presentation](https://youtu.be/uQ3yZjM1bj8)

---
class: left, top

## Quarto (.qmd): is it the future?

The [getting started](https://quarto.org/docs/get-started/hello/rstudio.html) tutorial is the best start to learn Quarto.

Give it a try:

- `File` ->  `New File` -> `Quarto Document...` -> Title: "test", Output format: HTML (deafult)
- Visual Markdown Editor (VME) is used by default, but you can switch to `Source`
- **Render** it to create html (opened automatically in your browser as a Background job)

Check also the talk ["Mixing R, Python, and Quarto: Crafting the Perfect Open Source Cocktail"](https://www.youtube.com/watch?v=8174mk6SGcU&;list=PL9HYL-VRX0oSFkdF4fJeY63eGDvgofcbn&;index=57) by Alenka Frim and Nic Crane.

---
class: left, top

# Bonus challenge 2

Try to create a Quarto document with the same content of the Rmd document you created in challenge 1 and 2. Use, please, the same data and the same code. The goal is to understand the differences between Rmd and Quarto.

---
class: left, top

# The package of the month. Oberon's choice

[Officer](https://davidgohel.github.io/officer/) is a R package to manipulate and format Word documents.
It is a great tool to create reports, certificates, or any other document you need to write in Word format. It is a very powerful package, but it is also very easy to use.

Check the related [officeverse]((https://ardata-fr.github.io/officeverse/)) (it's a bookdown!)  (officer + extensions) and the [package documentation](https://davidgohel.github.io/officer/).

![:scale 90%](/assets/images/20241217/20241217_officer.png)

---
class: left, top

# Solutions and video recordings

1. Solution of challenges 1 and 2 are merged in one single RMarkdown file: [20241217_anemone.Rmd](https://github.com/inbo/coding-club/blob/main/src/20241217/20241217_anemone.Rmd), resulting in a HTML document [20241217_anemone.html](https://github.com/inbo/coding-club/blob/main/src/20241217/20241217_anemone.html). Download it and open it via web browser, e.g. Google Crome or Firefox Mozilla, ...). Notice that some useful information has been added at the end of the document (section "Notes"). Thanks to all participants for the suggestions!
2. Solution of challenge 3 is a zipfile, [20241217_anemone_report.zip](https://github.com/inbo/coding-club/blob/main/src/20241217/20241217_anemone_report.zip) containing the entire bookdown project. Unzip it, please! The built html book can be found in `/docs` folder. Open `index.html` to _open_ the book.
3. Curious about Quarto? Check the Quarto document [20241217_anemone_quarto.qmd](https://github.com/inbo/coding-club/blob/main/src/20241217/20241217_anemone_quarto.qmd), solutions of the Bonus Challenge 2. The rendered HTML version is on RPubs: [INBO_coding_club_20241217_anemone_quarto](https://rpubs.com/damianooldoni/INBO_coding_club_20241217_anemone_quarto).
4. Edited video recording of the session is on [vimeo](https://vimeo.com/1041690812). Do you know that all INBO coding club video recordings are available on our official [INBO coding club vimeo folder](https://vimeo.com/user/8605285/folder/1978815)?

---
class: left, top

# Resources

1. Check out the range of outputs and formats you can create using R Markdown: https://rmarkdown.rstudio.com/gallery
2. Article to learn more about [Visual Markdown Editor](https://rstudio.github.io/visual-markdown-editing/) in RStudio
3. R Markdown cheat sheet: [html](https://rstudio.github.io/cheatsheets/html/rmarkdown.html) and [pdf](https://github.com/inbo/coding-club/blob/main/cheat_sheets/20241217_cheat_sheet_rmarkdown.pdf).
4. Online book about [bookdown](https://bookdown.org/yihui/bookdown/).
5. [Thierry's slides](https://inbo.github.io/inbomd_examples/inbomd_workshop/inbomd_workshop.pdf) about writing a report with INBOmd
6. [Examples](https://inbo.github.io/inbomd_examples/) of reports, slides, posters, etc. created with INBO templates from `INBOmd` (with links to source code!)
7. [Article](https://www.educative.io/blog/yaml-tutorial) about YAML
8. quarto (.qmd) format: a [getting started](https://quarto.org/docs/get-started/hello/rstudio.html)
9. Carlos Scheidegger's [slides](https://cscheid.net/static/2023-esip-quarto-talk/#/title-slide) and [live presentation](https://youtu.be/uQ3yZjM1bj8)
10. Recording of the talk ["Mixing R, Python, and Quarto: Crafting the Perfect Open Source Cocktail"](https://www.youtube.com/watch?v=8174mk6SGcU&;list=PL9HYL-VRX0oSFkdF4fJeY63eGDvgofcbn&;index=57) by Alenka Frim and Nic Crane at the posit::conf(2024)
10. Officeverse: [bookdown](https://ardata-fr.github.io/officeverse/) and officer [package documentation](https://davidgohel.github.io/officer/).

---
class: center, middle

![:scale 30%](/assets/images/coding_club_logo_1.png)

Topic: to be chosen 
Room: HT - 01.70 - Ferdinand Peeters 
Date: **30/12/2025**, from **10:00** to **12:30** 
**Help** needed with technical setup? You are welcome from **9:45am**