markdown your report

class: center, middle

![: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.
-->

# 16 DECEMBER 2021

## INBO coding club

online<br>

---
class: center, middle

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

---
class: left, top

## Introduction: open software

During the coding club about spatial vector data in October, we found that the description of the arguments of `sf::st_contains()` are inverted in the cheat sheet. Issue already open since 2019. Sometimes daring to ask for updates helps :-)

![:scale 80%](/assets/images/20211216/20211216_bug_cheat_sheet_sf_update.png)

---
class: left, top

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

- Markdown: a markup language* for creating formatted text using a plain-text editor. E.g. make text italic by surrounding it with underscores or asterisks, e.g., `__text__` or  `**text**`
- R Markdown: a file type with extension `Rmd` to _knit_ text (in Markdown) and code (in R) together. goal: save and execute code and generate high quality shareable reports.
- [rmarkdown](https://rmarkdown.rstudio.com/lesson-1.html): the R package to write R Markdown documents. **note**: by default installed within RStudio!
- [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): R package containing templates to generate reports, slides or posters with the corporate identity of INBO or the Flemish government.

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

<small>* __Note__:  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).
---
class: left, top

The main reference material for today's coding club:

![:scale 80%](/assets/images/20211216/20211216_reference_material.png)

- [R Markdown cheat sheet](https://github.com/inbo/coding-club/blob/master/cheat_sheets/20211216_cheat_sheet_rmarkdown.pdf)
- book about [bookdown](https://bookdown.org/yihui/bookdown/)
- [Thierry's slides](https://inbo.github.io/inbomd_examples/inbomd_workshop/inbomd_workshop.pdf) about writing a report with INBOmd

---
class: left, top

# R Packages

Load the packages (or install them first):

```r
library(tidyverse)    # to do datascience
library(geepack)      # to do modelling
library(INBOtheme)    # to apply INBO style to graphs
library(sf)           # to work with geospatial vector data
library(leaflet)      # to make dynamic maps
library(htmltools)    # to make nice html labels for dynamic maps
```

---
class: center, middle

### 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

## Coding club play tables

**Like** a card club, we will split us in different tables (aka _breakout rooms_) and we will help each other! We return all together after a fixed amount of time to discuss each challenge apart.

**Unlike** a card club, in our club there is no winner, neither within a table nor among tables!

![:scale 65%](/assets/images/breakout_rooms.png)

---
class: left, top

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

<br> No yellow sticky notes online. We use hackmd (see next slide) but basic principle doesn't change.

---
class: center, middle

### Share your code during the coding session!

Go to https://hackmd.io/DXQK5B3OSjmpbgQK5Ft9KA?edit

---
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 (and say OOOHHH)
- Save it as `test.Rmd`
- **knit** it to create html (= `rmarkdown::render("test.Rmd")` in console)
![:scale 70%](/assets/images/20211216/20211216_knit_does_the_magic.png)

---
class: left, top

# The YAML header: iammol what???

The firs lines between triple dashes (`---`) is our **header**, needed to configurate 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**.

And Why using YAML? Because it is very, very **human readable**.

```r
---
title: "test"
author: "Damiano Oldoni"
date: "14-12-2021"
output: html_document
---
```

---
class: left, top

# Download data and code

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

1. [20211216_challenges.R](https://github.com/inbo/coding-club/blob/master/src/20211216/20211216_challenges.R): R script about geese counts.
2. [20211216_geese_counts.txt](https://github.com/inbo/coding-club/blob/master/data/20211216/20211216_geese_counts.txt): comma separated text file with geese catch data to use in `20211216_challenges.R`.
3. [20211216_flemish_provinces.gpkg,data](https://github.com/inbo/coding-club/blob/master/data/20211216/20211216_flemish_provinces.gpkg): geopackage with the Flemish provinces to use in `20211216_challenges.R`

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

# Challenge 1

Convert the code below to a Rmd document called `1_geese_read_data.Rmd` and _knit_ it as html. Please, take care of:

1. Converting the comments to text
2. Show the library you need to load but avoid to show any **message** (errors or warnings are allowed). Tip: one test output chunk option from [this list](https://yihui.org/knitr/options/#text-output). How to avoid showing **warnings** as well?
3. Do not show the code in lines 83-85 and 89-90. Tip: this is shown in `test.Rmd` (challenge 0) and in the list mentioned in 2.
4. Set date authomatically in YAML header by setting: `date: "`r Sys.Date()`"`
5. Do you want always good looking tables with the smallest effort possible? Set `df_print` argument in header (see screenshot below)
6. Add a table of content (see screenshot below)

![:scale 85%](/assets/images/20211216/20211216_markdown_toc_df_paged.png)

---
class: left, top

# Intermezzo 1

There are plenty chunk options. For example, do you want to restyle your code authomatically? Use chunk option: `tidy='styler'`. It will run `styler::style_text()` behind the screen. Handy!

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

# Challenge 2

Put the code in challenge 2 in a second R Markdown document called `2_visualize_model_data.Rmd` and make an html document out of it. Take care of the following:

1. If you do it "blindly", you will get errors, probably at the very beginning: why? How to solve it?
2. When it goes about plotting and modelling, the chunk codes could be quite long and so potentially distracting to readers. Please, fold them. Readers can then choose to display them by clicking the fold buttons: Tip: check this [fold-show](https://bookdown.org/yihui/rmarkdown-cookbook/fold-show.html) section

---
class: left, top

# Intermezzo 2

Any solution you found for Challenge 2 is far from being an ideal solution! You have two options, depending on the length of your document/report/blogpost/...

1. Put everything in a Rmd document (typical for blogposts, tutorials)
2. Make a Rmd per chapter and bind all chapters together with bookdown!

Let's apply solution 2 to our case! 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 `my_report`. More about it in [this](https://bookdown.org/yihui/bookdown/html.html#gitbook-style) chapter of the bookdown guide. Notice you can _build_ your book via a "Buid book" option in the Build pane of RStudio!

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

# Challenge 3

Try to convert the content of your two Rmd documents in the book we have just created. 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 edit them:

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

---
class: left, top

# Bonus challenge

Now you can become a pro!

1. Add a figure caption. Tip: fig.cap = "your caption" in chunk option
2. Add some cross references, e.g. try to refer to a section within another section and refer to a figure. Tip: change the output in YAML header from `html_document` to `html_document2`, a type of output specific of bookdown, not available in RMarkdown. This allows numbering and cross-referencing figures/tables/equations. Handy!
3. 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

## Did 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/r_gbif_name_matching/).
2. [Data processing pipelines](https://trias-project.github.io/alien-plants-belgium/dwc_mapping.html) published as GitHub pages are R markdown documents?
3. Hackmd pages follow markdown syntax? Yes, you know already!

---
class: left, top

# Resources

### Solutions

You can download the solutions by running: `inborutils::setup_codingclub_session("20211216")`. Here below the links on GitHub if you prefer to download them manually:

1. Solution challenge 1: [Rmd](https://github.com/inbo/coding-club/blob/master/src/20211216/1_geese_read_data.Rmd) and related [html](https://github.com/inbo/coding-club/blob/master/src/20211216/1_geese_read_data.html) document
2. Solution challenge 2: [Rmd](https://github.com/inbo/coding-club/blob/master/src/20211216/2_visualize_data.Rmd) and related [html](https://github.com/inbo/coding-club/blob/master/src/20211216/2_visualize_data.html) document.
3. The solution of challenge 3 and (part of) the bonus challenge is an entire _book_ project placed in a zip file: [`/src/20211216/my_project_20211216.zip`](https://github.com/inbo/coding-club/blob/main/src/20211216/my_report_20211216.zip).

**Note** about challenge 3 and bonus: please unzip `my_project_20211216.zip` in a folder, for example `my_project_20211216`. To see the html book, go to `docs` and open the file `index.html`. Do you want to (re)build the book yourself or just see the R Markdown files (chapters) of the book? Open the RStudio project `my_report_20211216.Rproj`. the three Rmd files are in the root directory.

### Webinar

The video recording is on [vimeo](https://vimeo.com/657889213). Only the first part of the coding club has been recorded. Our apologies.

---
class: left, top

# Resources

## Useful links

1. Article to learn more about [Visual Markdown Editor](https://rstudio.github.io/visual-markdown-editing/) in RStudio
2. [R Markdown cheat sheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)
3. book about [bookdown](https://bookdown.org/yihui/bookdown/)
4. [Thierry's slides](https://inbo.github.io/inbomd_examples/inbomd_workshop/inbomd_workshop.pdf) about writing a report with INBOmd
5. [Examples](https://inbo.github.io/inbomd_examples/) of reports, slides, posters, etc. created with INBO templates from `INBOmd` (with links to source code!)
6. [Article](https://www.educative.io/blog/yaml-tutorial) about YAML

---
class: left, top

# Ideas for 2022

We propose. You decide!

- Coding club of 2.5 hrs: from 10am to **12.30pm**?
- More real data and questions from you: ask for it at each announcement (begin of the month)

![:scale 50%](/assets/images/20211125/20211125_ask_feedback_icon.png)

---
class: left, top

# Ideas for 2022

## Timeline and topics

As for 2021, the coding club would like to reflect the research process: read, process, visualize, report. What do you think about? Which topics do you miss? Would you like to give a special edition on a specific topic?

![:scale 110%](/assets/images/20211125/20211125_timeline_coding_clubs_2022.png)

---
class: center, middle

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

Topic: connect to INBO databases in R (draft)
Room: 01.05 - Isala Van Diest(??) <br>
Date: **25/01/2022**, van **10:00** tot **12:00** <br>
(registration announced via DG_useR@inbo.be)