---
title: "Úvod do R Markdown"
author: "Karel Rečka"
date: "`r format(Sys.time(), '%d. %m. %Y')`"
output:
  html_document:
    toc: yes
    toc_float: yes
    toc_depth: 2
    number_sections: yes
    theme: readable
    highlight: zenburn
bibliography: https://is.muni.cz/el/fss/podzim2022/PSYn5320/um/library.bib
csl: https://is.muni.cz/el/fss/podzim2022/PSYn5320/um/apa.csl
params:
  class: 1
---
```{css, echo=FALSE}
.output-background {
  background-color: #F6F6F6;
}
```
```{r setup, include = FALSE}
options(width = 90)

knitr::opts_chunk$set(
  cache = TRUE,
  fig.path = "figures/",
  comment = "#>",
  collapse = FALSE,
  class.output = "output-background"
)

knitr::opts_template$set(
  fullwidth = list(
      fig.width = 10, fig.height = 6,
      out.width = '100%'
      )
  )

fnum <- function(x, digits = 2) {
  format(round(x, digits), nsmall = digits, big.mark = " ",
                            decimal.mark = ",")
}

```
# Použité balíčky
```{r packages, cache=FALSE, message=FALSE, warning=FALSE}
# Načtení potřebných balíčků
library(haven)
library(tidyverse)
library(DT)

```
# Import a příprava dat
```{r data-import, cache.extra = file.info("https://is.muni.cz/el/fss/podzim2022/PSYn5320/um/datasets/titanic.sav")}
# Import dat o pasažérech titanicu
titanic <- haven::read_spss(
  "https://is.muni.cz/el/fss/podzim2022/PSYn5320/um/datasets/titanic.sav")
```

```{r data-preparation, dependson = "data-import"}
# Tranformace vybraných proměnných na faktory
titanic <- titanic %>% 
  mutate(
    survived = factor(survived, 
                      levels = 0:1, 
                      labels = c("Died", "Survived")),
    class = factor(class),
    sex = factor(sex, 
                 levels = c("male", "female"), 
                 labels = c("Male", "Female"))
  )

# Přehled výsledného datasetu
glimpse(titanic)
head(titanic)
```

<br>

# Formátování textu

## Odstavce a řádky

Ostavce oddělujte prázdnými 
řádky; pouhé "odentrování" nevytvoří nový odstavec, 
ale vše bude ve výsledném dokumentu v jednom odstavci textu.

Odstavec 1

Odstavec 2

Odstavec 3 atd.

Řádek můžete ukončit tím, že na jeho konci použijete dvakrát mezerník 
(pouhé "odentrování" řádek ve výsledném dokumentu neukončí)

Tohle  
bude  
na  
samostatných  
řádcích.

Pro zvětšení mezery mezi odstavci použijte buďto `\` nebo `<br>` na samostatném
řádku, který nad sebou i pod sebou prázdný řádek. Můžeme použít např. pro
pro větší oddělení nadpisů na první úrovni.

Pokud používáte jako výstupní formát .doc, .pdf nebo .odt, můžete pomocí
`\newpage` vložit konec stránky (page break). U HTML to nemá moc smysl, protože 
celý dokument je jeden spojitý celek, jedině kdybyste chtěli stránku tisknout.

\newpage

Odsazení textu můžeme zvětšit následovně:

|   Malé odsazení textu
|       Větší odsazení
|           Ještě větší odsazení

## Zdůraznění textu

Když chcete něco napsat kurzivou, ohraničte to hvězdičkami nebo podtržítko 
(underscore)  
*toto bude kurzivou* a _toto bude také kurzivou_

Když chcete něco napsat tučně, použijte dvojité hvězdičky nebo podtržítko 
(underscore)  
**toto bude tučně** a __toto bude také tučně__

Kdybyste něco chtěli napsat kurzivou a zároveň tučně, použitje hvězdičky 
nebo uderscore třikrát  
***toto bude tučně + kurzivou*** a ___toto bude také tučně + kurzivou___

když chcete zdůraznit, že hovoříte o nějakém datovém objektu nebo kódu, 
použijte zpětný apostrof    
`data` `x <- c(0, 1, 2)` 

horní a dolní index vytvoříte pomocí ^ a ~  
SD^2^  H~2~0

## Nadpisy

Nadpisy můžete tvořit hashtagem #

# První úroveň nadpisu{-} 

## Druhá úroveň nadpisu{-}

### Třetí úroveň nadpisu{-}

#### Čtvrtá úroveň nadpisu{-}

##### Pátá úroveň nadpisu{-}

###### Šestá úroveň nadpisu{-}

## Seznamy a odrážky

Nečíslované odrážky vytvoříte pomocí *, - nebo +
(nezapomeňte oddělit seznam prázdnými řákdy z obou stran)

* Položka 1
* Položka 2
  - Položka 2A
    + Položka 2A I 
    + Položka 2A II 
  - Položka 2B
  
Číslované odrážky vytvoříte takto, pokud vám stačí jedna úroveň

1. Položka 1
1. Položka 2
1. Položka 3

Nebo takto pro víceúrovňový číslovaný seznam

1. Položka 1:
    1. Položka 1.1. (je nutné použít tabulátor dvakrát)
        1. Položka 1.1.1. (je nutné použít tabulátor čtyřikrát)
    1. Položka 1.2.
1. Položka 2

<br>

# Vkládání odkazů a obrázků
```{r download.image, include=FALSE}
download.file("https://is.muni.cz/el/fss/podzim2022/PSYn5320/um/rmeme.png",
              "data/rmeme.png", method = "curl")
```


Webové odkazy a obrázky můžete vložit takto

* Vložením holého URL: https://google.com.  
* Vložením URL s labelem [Google](https://www.google.com/).

Obrázky lze vložit podobně – pomocí URL odkazu nebo odkazu na lokální uložiště.
Velikost obrázku lze zmenšit např. přidáním `{width=50%}`

![Programming meme](data/rmeme.png){width=50%}

Větší flexibilitu v úpravě obrázku umožňuje funkce `knitr::include_graphics()`
v rámci bloku s kódem.

```{r datacamp-logo, opts.label='fullwidth'}

knitr::include_graphics("data/rmeme.png")
```


<br>

# Bloky kódu a jejich nastavení

Vložit blok kódu lze pomocí tlačítka v RStudiu (Insert code chunk) nebo pomocí
klávesové zkratky Ctrl + I.

Bloky kódu lze pojmenovat, což má několik výhod:

* Lepší navigaci pomocí osnovy vlevo dole.
* Vytvořené grafy budou mít srozumitelnější pojmenování.
* Lépe se lze odkazovat na jiné bloky kódu, např. v případě cachingu 
(uložení výpočetně náročnějších operací, resp. jejich výstupů, do paměti).

První blok kódu by měl být vždy pojmenován `setup` a obsahovat globální 
nastavení pomocí `knitr::opts_chunk$set()`. Tato nastevení převezmou všechny 
bloky, ale lze jej přepsat, protože prioritu má lokální nastavení konkrétního
bloku.

Bloky kódu mají spoustu nastavení, nejčastěji měníme následující:

* `eval = FALSE` ukáže kód, ale nespustí jej, což se hodí, když chceme ukázat
pouze příklad kódu.
* `include = FALSE` spustí kód, ale skryje kód i jakýkoli výstup ve finálním
dokumentu. Hodí se, pokud obojí není pro analýzu relevantní (`setup`)
* `echo = FALSE` zobrazí pouze výstup, ale nikoli samotný kód. Hodí se,
pokud píšeme zprávu pro někoho, kdo se v R nevyzná, takže by mu R-kód stejně
nic neříkal.
* `message = FALSE` zakáže zobrazování (nevarovných) hlášení a `warning = FALSE` 
zakáže zobrazování hvarovných hlášení ve finálním reportu.
* `results = "hide"` zakáže zobrahení konzolového výstupu a `fig.show = "hide"`
zakáže zobrazení grafického výstupu. `results = "hold"` umístí konzolový výstup
až za všechen R-kód v daném bloku a `fig.show = "hold"` udělá totéž pro graficý
výstup.
* `cached = TRUE` uloží výsledky daného bloku kódu do zvláštního souboru na disk.
Hodí se pro uložení výsledků výpočetně náročných operací. 
Pokud nedojde k žádné změně v daném boku kódu, operace v něm definované se
nemusí spouštět znovu, ale její výsledky se načtou z disku.
* `dependson = "predchozi-blok-kodu"` řeší to, že výsledky bloku kódu mohou záviset
na předchozích blocích, ale kdybychom použili pouze `cached = TRUE`, kontrolují 
se pouze změny v daném bloku kódu. Když použijeme `dependson` s názvem vybraného
předchozího bloku kódu, pak se `cached = TRUE` kontroluje i změny jiném uvedeném
bloku kódu.
* `cache.extra = file.info("externi_dataset.csv")` hlídá změny určeného externího
datového souboru.

Přehled nastavení můžete nalézt [zde](https://yihui.org/knitr/options/#chunk-options).

Zkuste změnit některá z těchto nastavení v následujícím bloku kódu

```{r survival-and-age, }
titanic %>% 
  group_by(class, sex) %>% 
  summarise(
    prop_survived = mean(survived == "Survived")
  )

titanic %>% 
  ggplot(aes(age)) +
  geom_histogram()
```


Pokud chcete změnit defaultní (globální) nastavení pro bloky kódu, použijte funkci
`knitr::opts_chunk$set()` v rámci bloku `setup`. Pokud často přepisujete
více globálních nastavení, můžete si pomocí `knitr::opts_template$set` připravit
jejich set a pak jej vložit pomocí argumentu `opts.label='set_nastaveni'`v záhlaví
bloku kódu.

<br>

# Tabulky

Defaultní formát tabulek vypadá tak, jak jsme na něj zvyklí z R konzole. 

Pro pěknější formát tabulek můžeme použít funkci `knitr::kable()`.

Interaktivní tabulky můžeme získat s využitím balíčku `DT` a funkce
`DT::datatable()`

```{r data-table}
# Defaultní tabulka
head(titanic)

# Tabulka s použitím funkce knitr::kable()
knitr::kable(
  head(titanic),
  caption = "Údaje o pasažérech Titaniku (kable)",
  digits = 2
)

# Tabulka s použitím funkce DT::datatable()
DT::datatable(
  titanic %>% select(id:age),
  caption = "Údaje o pasažérech Titaniku (datatable)",
  filter = list(position = 'top'),
  options = list(pageLength = 5),
  rownames = FALSE
)
```

Tabulky lze vytvořit i ručně takto.

 Nadpis 1 | Nadpis 2  | Nadpis 3    
----------|-----------|----------
 a1     | a2          | a3     
 b1     | b2          | b3     

Pravidla jsou tato:
* Tabulka musí mít záhlaví, které je odděleno např. pomocí "--------".
* Buňky musí být odděleny pomocí svislice "|".
* Použití "|" před prvním sloupcem a za posledním sloupcem není nutné.
* Není nutné dodržet vizuální zarovnání buněk.

Zarovnání lze měnit takto:

| nalevo | na střed | napravo |
|:-------|:--------:| -------:|
| 1 | 2 | 3 |

<br>

# Použití kódu přímo v textu

Dalším způsobem, jak vložit R kód, je použití `r `, viz následující příklad.

Máme údaje o `r nrow(titanic)` pasažérech Titanicu, ale pouze u
`r sum(!is.na(titanic$age))` pasažérů známe jejich věk.

Průměrný věk pasažérů Titanicu byl `r mean(titanic$age, na.rm = TRUE)` 
(*SD* = `r sd(titanic$age, na.rm = TRUE)`) let.

Průměrný věk pasažérů Titanicu byl `r mean(titanic$age, na.rm = TRUE) %>% fnum()` 
(*SD* = `r sd(titanic$age, na.rm = TRUE) %>% fnum()`) let.

<br>

# Grafy a parametry

Pomocí parametrů můžeme definovat klíčové vstupní hodnoty pro generování 
výsledků (outputu). Parametry definujeme v záhlavní a pak je můžeme používat
jako argumenty různých funkcí.

```{r counts}
sex_count <- titanic %>% 
  filter(class == params$class) %>%
  count(sex)
males <- sex_count %>% filter(sex == "Male") %>% pull(n)
females <- sex_count %>% filter(sex == "Female") %>% pull(n)
```
V `r params$class`. třídě cestovalo `r males` mužů a `r females` žen. 

Graf podílu přeživších je zobrazen níže.

```{r survival-plot1}
p <- titanic %>% 
  filter(class == params$class) %>% 
  group_by(sex) %>% 
  summarise(prop_survived = mean(survived == "Survived")) %>% 
  ggplot(aes(sex, prop_survived)) +
  geom_col() +
  expand_limits(y = 1)

p
```

Rozměry grafů lze měnit pomocí argumentů `fig.width`, `fig.height`, 
`fig.asp`, `out.width` a `out.height`.

Argumenty začínající na `fig.` mění velikost grafu vytvořeného v R,
zatímco argumenty začínající na `out.` mění velikost místa, do kterého
bude graf vložen.

Aby měly grafy konzistentní šířku, stačí nastavit pro všechny 
stejnou `fig.width` (šířka grafu) a měnit podle potřeby `fig.asp` (poměr stran);
`fig.height` se tak nastaví automaticky jako `fig.width * fig.asp`.

Často je rozumné nastavení `fig.width = 6` (tj. 6 palců) a `fig.asp = 0.618` 
(zlatý řez) společně s `out.width = "70%"` (tj. 70 % šířky odstavců) a 
`fig.align = "center"` (zarovnání na střed). 

Pro umístění více grafů na jeden řádek můžete např. nastavit `out.width = "50%"`,
pokud se jedná o dva grafy; pokud máte tři grafy, můžete nastavit `out.width = "33%"`;
pokud máte čtyři `out.width = "25%"`, ale nechat `fig.align = "default"`.

Mezi další důležitá nastavení patří:

* `fig.show = "hold"`: ukáže graf(y) až nakonec za celým blokem kódu.
* `fig.cap = "Popisek grafu"`: přidá ke grafu popisek 
`fig.cap="Podíl přeživších"`



``` {r plot2, fig.width=2, fig.asp= 1, out.width="100%", fig.align='center', fig.cap="Podíl přeživších"}
p
```

<br>

# Citace

R Markdown umí používat různé formáty k tvorbě bibliografie, včetně
BiBLatex, BibTeX, endnote nebo medline.

Pokud chcete generovat citace balíčků v BibTeXu, můžete použít funkci
`knitr::write_bib(c("vektor", "s", "názvy", "balíčků), width = 60)`. 
Zkuste takto vytvořit BibTex soubor pro balíčky, které jsme doposud používali,
např. ggplot2, dlyr nebo skimr.

Soubor se seznamem literatury v BibTexu se uvádí v záhlaví, 
např. `bibliography: library.bib`. Stejně tak je nutné v se v záhlavní odkázat
na soubor `.csl` (citation style language), který definuje citační styl, např.
`csl: apa.csl`, defaultní je totiž styl *Chicago*.

Pro vložení citace použijte "@" společně s identifikátorem citace, např.
@r4ds nebo [@r4ds].

Citace lze upravovat např. takto:

* Pro vložení více citací za sebou použijte středník, např. takto: Lidé
začínající programovat v R mohou využít několik publikací [@r4ds; @hopr; @tidyverse].
* Do hranatých závorek lze doplnit libovolné komentáře 
[@r4ds, pp. 20–30; @hopr, kapitola 2].
* Bez použití hranatých závorek se vytvoří citace přímo v textu, tj. jméno autora
nebo autorů bude před závorkouk a závorce bude uveden rok publikace, viz např.
@r4ds i @hopr představují dobré učebnice pro začátečníky v R.
* potlačit jméno autor lze pomocí "-": viz např. Garrett Grolemund [-@hopr] je 
autorem knihy *Hands-On Programming with R*.

Seznam literatury se automaticky vloží na konec dokumentu, můžete ho vložit i na
jiné místo, pokud např. máte několik příloh, které chcete uvést až za seznamem
literatury. Stačí použít tento tag `<div id="refs"></div>` a dát jej na místo,
kam seznam literatury chcete vložit.

<br>

# R Notebook

Další možností, jak pracovat s R Markdownem, je použít R Notebook. R Notebook
je specifický způsob kompilace R Markdown souborů. Vytvoříte jej pomocí 
`File -> New File -> Notebook` nebo volbou `output: html_notebook` v záhlaví.

Hlavní rozdíly oproti standardnímu R Markdownu jsou následující: 

* R Notebook funguje v rámci téže R session, zatímco při kompilaci R Markdown 
souboru se automaticky spustí vždy nová, "čistá" R session.
* R Notebook spouští kód postupně, po částech, takže i když 
nějaký řádek kódu ústí v error, nevede to k tomu, že nedostanete žádný výstup.
* Místo tlačítka **Knit** se objeví tlačítko **Preview**. Když na něj kliknete,
vytvoří se HTML dokument, ale ten bude obsahovat output pouze těch bloků kódu, 
které jste sami předtím spustili. To znamená, že **Preview** žádný blok kódu 
nespouští.  Oproti tomu tlačítko **Knit** vytvoří novou R session a kompiluje 
najednou celý dokument včetně všech bloků kódu, což obvykle trvá déle. Jinými 
slovy **Preview** tedy vlastně nic nového nevytváří, pouze zobrazí text, který 
jste napsali v R Notebooku, a output těch bloků kódu, který jste již spustili
* R Notebook umožňuje jen jeden typ outputu `output: html_notebook`, zatímco
R Markdown může kompilovat html, .doc, .pdf a další typy dokumentů.

Protože lze snadno změnti R Notebook v R Markdown (stačí  místo 
`output: html_notebook` v záhlavní uvést např. `output: html_document`)
a protože práce s R Notebook je obvykle o něco rychlejší, můžete klidně 
nejprve pracovat s R Notebookem a až poté, ve konečné fázi psaní reportu,
s R Markdownem.

<br>

# Nastavení v záhlaví

Většina výstupních formátů podporuje číslování nadpisů/sekcí. Stačí do záhlaví 
dolnit `number_sections: true`. Pokud nechcete vypnout číslování u některých nadpisů,
doplňte za ně `{-}`.

Součástí záhlaví může být i r kód, můžete například nechat generovat datum
automaticky na základě systémového času pomocí 
`r format(Sys.time(), '%d. %m. %Y')`.

Pomocí `toc: true` zapnete zobrazení obsahu (table of content); u HTML dokumentů
funguje `toc_float: true`, pokud chcete interaktní (plovoucí) obsah. Pomocí
`toc_depth: ` pak lze nastavit, kolik úrovní nadpisů se má v obsahu zobrazovat.

Pomocí `code_folding: hide` můžete defaultně skýr R kód; pro jeho zobrazení je 
pak nutné si jej "rozkliknout"; a pomocí `code_folding: show` naopka umožníte
skrýt (defaultně viditelný) R kód.

R Markdown nabízí mnoho předdefinovaných themes, např. `theme: readable`. 
Podívejte se [zde](https://www.datadreaming.org/post/r-markdown-theme-gallery/), 
jak vypadají, a vyberte si nějaké, které se vám zdá atraktivní.

# Zdroje