Úvod do R Markdown
Karel Rečka
24. 10. 2022
1 Použité balíčky
# Načtení potřebných balíčků
library(haven)
library(tidyverse)
library(DT)2 Import a příprava dat
# Import dat o pasažérech titanicu
titanic <- haven::read_spss(
"https://is.muni.cz/el/fss/podzim2022/PSYn5320/um/datasets/titanic.sav")# 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)#> Rows: 891
#> Columns: 12
#> $ id <dbl> 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20…
#> $ survived <fct> Died, Survived, Survived, Survived, Died, Died, Died, Died, Survived,…
#> $ class <fct> 3, 1, 3, 1, 3, 3, 1, 3, 3, 2, 3, 1, 3, 3, 3, 2, 3, 2, 3, 3, 2, 2, 3, …
#> $ name <chr> "Braund, Mr. Owen Harris", "Cumings, Mrs. John Bradley (Florence Brig…
#> $ sex <fct> Male, Female, Female, Female, Male, Male, Male, Male, Female, Female,…
#> $ age <dbl> 22, 38, 26, 35, 35, NA, 54, 2, 27, 14, 4, 58, 20, 39, 14, 55, 2, NA, …
#> $ sib_spouse <dbl> 1, 1, 0, 1, 0, 0, 0, 3, 0, 1, 1, 0, 0, 1, 0, 0, 4, 0, 1, 0, 0, 0, 0, …
#> $ par_child <dbl> 0, 0, 0, 0, 0, 0, 0, 1, 2, 0, 1, 0, 0, 5, 0, 0, 1, 0, 0, 0, 0, 0, 0, …
#> $ ticket <chr> "A/5 21171", "PC 17599", "STON/O2. 3101282", "113803", "373450", "330…
#> $ fare <dbl> 7.2500, 71.2833, 7.9250, 53.1000, 8.0500, 8.4583, 51.8625, 21.0750, 1…
#> $ cabin <chr> "", "C85", "", "C123", "", "", "E46", "", "", "", "G6", "C103", "", "…
#> $ port <chr> "S", "C", "S", "S", "S", "Q", "S", "S", "S", "C", "S", "S", "S", "S",…head(titanic)#> # A tibble: 6 × 12
#> id survived class name sex age sib_s…¹ par_c…² ticket fare cabin port
#> <dbl> <fct> <fct> <chr> <fct> <dbl> <dbl> <dbl> <chr> <dbl> <chr> <chr>
#> 1 1 Died 3 Braund, Mr. O… Male 22 1 0 A/5 2… 7.25 "" S
#> 2 2 Survived 1 Cumings, Mrs.… Fema… 38 1 0 PC 17… 71.3 "C85" C
#> 3 3 Survived 3 Heikkinen, Mi… Fema… 26 0 0 STON/… 7.92 "" S
#> 4 4 Survived 1 Futrelle, Mrs… Fema… 35 1 0 113803 53.1 "C12… S
#> 5 5 Died 3 Allen, Mr. Wi… Male 35 0 0 373450 8.05 "" S
#> 6 6 Died 3 Moran, Mr. Ja… Male NA 0 0 330877 8.46 "" Q
#> # … with abbreviated variable names ¹sib_spouse, ²par_child3 Formátování textu
3.1 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.
Odsazení textu můžeme zvětšit následovně:
Větší odsazení
Ještě větší odsazení
3.2 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 ~
SD2 H20
3.3 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
3.4 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
- Položka 2A
Číslované odrážky vytvoříte takto, pokud vám stačí jedna úroveň
- Položka 1
- Položka 2
- Položka 3
Nebo takto pro víceúrovňový číslovaný seznam
- Položka 1:
- Položka 1.1. (je nutné použít tabulátor dvakrát)
- Položka 1.1.1. (je nutné použít tabulátor čtyřikrát)
- Položka 1.2.
- Položka 1.1. (je nutné použít tabulátor dvakrát)
- Položka 2
4 Vkládání odkazů a obrázků
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.
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
Větší flexibilitu v úpravě obrázku umožňuje funkce
knitr::include_graphics() v rámci bloku s kódem.
knitr::include_graphics("data/rmeme.png")
5 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 = FALSEukáže kód, ale nespustí jej, což se hodí, když chceme ukázat pouze příklad kódu.include = FALSEspustí 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 = FALSEzobrazí 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 = FALSEzakáže zobrazování (nevarovných) hlášení awarning = FALSEzakáže zobrazování hvarovných hlášení ve finálním reportu.results = "hide"zakáže zobrahení konzolového výstupu afig.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 afig.show = "hold"udělá totéž pro graficý výstup.cached = TRUEuloží 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 pouzecached = TRUE, kontrolují se pouze změny v daném bloku kódu. Když použijemedependsons názvem vybraného předchozího bloku kódu, pak secached = TRUEkontroluje 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.
Zkuste změnit některá z těchto nastavení v následujícím bloku kódu
titanic %>%
group_by(class, sex) %>%
summarise(
prop_survived = mean(survived == "Survived")
)#> `summarise()` has grouped output by 'class'. You can override using the `.groups`
#> argument.#> # A tibble: 6 × 3
#> # Groups: class [3]
#> class sex prop_survived
#> <fct> <fct> <dbl>
#> 1 1 Male 0.369
#> 2 1 Female 0.968
#> 3 2 Male 0.157
#> 4 2 Female 0.921
#> 5 3 Male 0.135
#> 6 3 Female 0.5titanic %>%
ggplot(aes(age)) +
geom_histogram()#> `stat_bin()` using `bins = 30`. Pick better value with `binwidth`.#> Warning: Removed 177 rows containing non-finite values (stat_bin).
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.
6 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()
# Defaultní tabulka
head(titanic)#> # A tibble: 6 × 12
#> id survived class name sex age sib_s…¹ par_c…² ticket fare cabin port
#> <dbl> <fct> <fct> <chr> <fct> <dbl> <dbl> <dbl> <chr> <dbl> <chr> <chr>
#> 1 1 Died 3 Braund, Mr. O… Male 22 1 0 A/5 2… 7.25 "" S
#> 2 2 Survived 1 Cumings, Mrs.… Fema… 38 1 0 PC 17… 71.3 "C85" C
#> 3 3 Survived 3 Heikkinen, Mi… Fema… 26 0 0 STON/… 7.92 "" S
#> 4 4 Survived 1 Futrelle, Mrs… Fema… 35 1 0 113803 53.1 "C12… S
#> 5 5 Died 3 Allen, Mr. Wi… Male 35 0 0 373450 8.05 "" S
#> 6 6 Died 3 Moran, Mr. Ja… Male NA 0 0 330877 8.46 "" Q
#> # … with abbreviated variable names ¹sib_spouse, ²par_child# Tabulka s použitím funkce knitr::kable()
knitr::kable(
head(titanic),
caption = "Údaje o pasažérech Titaniku (kable)",
digits = 2
)| id | survived | class | name | sex | age | sib_spouse | par_child | ticket | fare | cabin | port |
|---|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Died | 3 | Braund, Mr. Owen Harris | Male | 22 | 1 | 0 | A/5 21171 | 7.25 | S | |
| 2 | Survived | 1 | Cumings, Mrs. John Bradley (Florence Briggs Thayer) | Female | 38 | 1 | 0 | PC 17599 | 71.28 | C85 | C |
| 3 | Survived | 3 | Heikkinen, Miss. Laina | Female | 26 | 0 | 0 | STON/O2. 3101282 | 7.92 | S | |
| 4 | Survived | 1 | Futrelle, Mrs. Jacques Heath (Lily May Peel) | Female | 35 | 1 | 0 | 113803 | 53.10 | C123 | S |
| 5 | Died | 3 | Allen, Mr. William Henry | Male | 35 | 0 | 0 | 373450 | 8.05 | S | |
| 6 | Died | 3 | Moran, Mr. James | Male | NA | 0 | 0 | 330877 | 8.46 | Q |
# 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 |
7 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 891 pasažérech Titanicu, ale pouze u 714 pasažérů známe jejich věk.
Průměrný věk pasažérů Titanicu byl 29.6991176 (SD = 14.5264973) let.
Průměrný věk pasažérů Titanicu byl 29,70 (SD = 14,53) let.
8 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í.
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 1. třídě cestovalo 122 mužů a 94 žen.
Graf podílu přeživších je zobrazen níže.
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 popisekfig.cap="Podíl přeživších"
p
Podíl přeživších
9 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ř. Wickham & Grolemund (2017) nebo (Wickham & Grolemund, 2017).
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í (Grolemund, 2014; Wickham et al., 2019; Wickham & Grolemund, 2017).
- Do hranatých závorek lze doplnit libovolné komentáře (Grolemund, 2014, kapitola 2; Wickham & Grolemund, 2017, pp. 20–30).
- 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ř. Wickham & Grolemund (2017) i Grolemund (2014) představují dobré učebnice pro začátečníky v R.
- potlačit jméno autor lze pomocí “-”: viz např. Garrett Grolemund (2014) 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.
10 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.
11 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í 24. 10. 2022.
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,
jak vypadají, a vyberte si nějaké, které se vám zdá atraktivní.