---
title: "R Markdown"
author: "Karel Rečka"
date: "`r format(Sys.time(), '%d. %m. %Y')`"
knit: (function(inputFile, encoding) { 
      out_dir <- 'tutorials';
      rmarkdown::render(inputFile,
                        encoding=encoding, 
                        output_file=file.path(dirname(inputFile), out_dir, '07_rmarkdown.html')) })
output:
  html_document:
    toc: yes
    toc_float: yes
    toc_depth: 2
    number_sections: yes
    theme: readable
    highlight: zenburn
bibliography: library.bib
csl: 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 = TRUE,
  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>

# Úvod ke kapitole, která je tak trochu jiná
Rmarkdown je způsob, jak zkombinovat analýzu a zprávu o analýze do jednoho dokumentu. 
Jde vlastně o obyčejný textový soubor, který obsahuje formátovací značky (podobně jako třeba obyčejné html),
a vedle toho obsahuje také kousky Rkového kódu. Když v RStudiu takový soubor "spustíme" (knit),
text se podle formátovacích značek zformátuje, Rkový kód se vykoná a jeho výsledky 
se zakomponují do textu. Výsledek může mít podobu webové stránky nebo třeba pdf dokumentu.
Tímto způsobem vznikla celá cvičebnice, se kterou právě pracujete. 

Nyní čtete výslednou pdf podobu. Zdrojový Rmarkdownový kód, který ji vytvořil, 
najdete na adrese https://is.muni.cz/el/fss/podzim2023/PSYb5320/um/6_RMarkdown2.Rmd .
Stáhněte si ji, zkuste číst přímo kód a sem se dívejte jen, když si nebudete umět představit, 
co je výsledkem kódu. Rmarkdown je v základu velmi jednoduchý a intuitivní; pokročilejší
prvky můžete do svého repertoáru zařazovat postupně.


# 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í
```{r }

```

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í.

<br>

# Zdroje