17  Tvorba článků, reportů a prezentací v jazyce R

Jak už jsme zmínili v oddíle 16.5, s pomocí R je možné vytvářet i články, dokumenty, knihy, prezentace a weby, které smíchají živý R skript s textem. Tyto dokumenty je pak možné renderovat do velkého množství formátů jako je HTML, LaTeX, PDF (přes LaTeX), MS Word, OpenOffice, ConTeXt a další. (Tímto způsobem byla vytvořena i tato kniha.) V této kapitole se podíváme na to, jak takové dokumenty vytvářet.

17.1 Základy

Od roku 2022 doporučuje tvůrce RStudia, firma posit, používat k tvorbě dokumentů systém Quarto (https://quarto.org/).1 Dnes je Quarto součástí instalace RStudia. Pokud je chcete používat i mimo RStudio, můžete si je nainstalovat ze stránky https://quarto.org/docs/get-started/.

Quarto dokument je čistý textový soubor s koncovkou .qmd, který obsahuje hlavičku YAML, markdownové značky a R kód. Quarto na požádání dokument renderuje do požadovaného formátu. Při tom v R postupuje následujícím způsobem (viz obrázek 17.1): Nejprve se soubor .qmd prožene prográmkem knitr, což jsou funkce z R balíku knitr, které postupně spustí veškerý vložený R kód a výsledek vloží zpět ve formě Markdownu, TeXu, HTML apod. do čistě markdownového souboru. Ten se následně prožene prográmkem pandoc (https://pandoc.org/), který umí převádět dokumenty z různých textových formátů do jiných textových formátů. Výsledkem tohoto procesu je dokument v požadovaném formátu, např. PDF, HTML apod.

Obrázek 17.1: Mechanismus překladu Quarto dokumentu. Zdroj: https://quarto.org/docs/get-started/hello/rstudio.html#how-it-works.

Dokument .qmd můžete vytvořit v jakémkoli čistě textovém editoru. V RStudiu jej vytvoříte v menu File \(\rightarrow\) New File \(\rightarrow\) Quarto Document... nebo Quarto Presentation.... RStudio se dále zeptá na některé informace, viz obrázek 17.2:

  • název dokumentu,
  • jméno autora,
  • výstupní formát,
  • nástroj pro kompilaci R kódu (použijte knitr) a
  • zda chcete editovat dokument vizuálně nebo přímo v Markdownu.

Tyto volby se projeví pouze v hlavičce dokumentu a můžete je kdykoli změnit.

(a) dokument

(b) prezentace

Obrázek 17.2: Menu pro vytvoření Quarto dokumentu a prezentace v RStudiu.

Pokud zvolíte vizuální editaci, pak vám RStudio zobrazí jednoduchý textový editor, ve kterém můžete editovat text pomocí menu a klávesových zkratek (např. Ctrl-b pro tučné písmo). Editor je WYSIWYM (What You See Is What You Mean). To znamená, že neurčujete detailní vzhled výsledku, ale pouze označujete logické části textu: co je nadpis, co hlavička první úrovně, co bude tučně apod. Detailní vzhled pak určí použité styly (v HTML CSS styly, v PDF LaTeXová třída apod.).

Alternativou je psát přímo Markdownové značky. Pokud se je naučíte, můžete pracovat rychleji a přesněji. (Dají se využít i ve vizuálním módu, kde je RStudio zobrazí vizuálně.)

Po vytvoření dokumentu se v editoru objeví ukázkový dokument. Ten můžete prozkoumat, editovat a renderovat do výstupního formátu. K renderování slouží klávesová zkratka Ctrl-Shift-K nebo v RStudiu ikona šipky složené z kostiček s textem “Render” nebo ve VSCode tlačítko Preview. V RStudiu můžete také zakliknout volbu “Render on Save” – pak se dokument přerenderuje pokaždé, když jej uložíte. Z příkazového řádku svého operačního systému můžete Quarto dokument renderovat i pomocí příkazu quarto render.

V RStudiu můžete několik nastavení změnit pomocí ikony ozubeného kolečka. Tlačítka “Source” a “Visual”, která jsou pod nimi, vám umožní přepnout dokument z vizuálního módu do Markdownu nebo opačně. K tomu slouží i klávesová zkratka Ctrl+Shift+F4, která funguje i ve VSCode.

Quarto dokument doporučuji uložit v kódování UTF-8. V Linuxu a na macOs je to implicitní volba. Ve Windows můžete v RStudiu nastavit kódování tak, že při prvním uložení v menu zvolíte File \(\rightarrow\) Save with Encoding... a vyberete UTF-8.

17.2 Základy Markdownu

Jak bylo řečeno, Markdown je systém jednoduchých značek, které v dokumentu označují jeho strukturu. Výhodou Markdownu je jeho jednoduchost, univerzálnost a čitelnost prostým okem. V tomto oddíle se podíváme na naprosté základy tohoto jazyka. Více najdete na stránkách Quarto (zejména https://quarto.org/docs/authoring/markdown-basics.html) a pandoc (https://pandoc.org/).

Základem textu jsou odstavce. V Markdownu odstavec ukončíte jedním nebo více prázdnými řádky:

Toto je jeden odstavec. Zde odstavec nekončí.
Zato zde ano.

Toto je druhý odstavec.

Nadpisy kapitol, oddílů apod. je v Markdownu možné zadat pomocí křížků (jde to i jinak, ale práce s křížky je jednodušší):

# Nadpis první úrovně

## Nadpis druhé úrovně

### Nadpis třetí úrovně

#### Podivíny potěší, že úrovní může být i více

V rámci odstavců je někdy potřeba některá slova zdůraznit. K tomu slouží uzavření textu do hvězdiček:

*toto je psané italikou* a **toto je psané tučně**

Pokud chcete do odstavce vložit jméno proměnné nebo ukázku kódu, můžete je vložit mezi dva zpětné apostrofy:

... proměnná `speed` obsahuje hodnotu ...

Často je třeba vkládat seznamy. Číslovaný seznam se vytvoří tak, že řádek začne číslem 1., druhý řádek 2. apod. (ve skutečnosti mohou všechny řádky začít vždy 1.). Nečíslovaný seznam je podobně uvozený pomlčkou nebo hvězdičkou. Další úroveň seznamu vznikne tak, že příslušnou značku posuneme o čtyři mezery:

1. první položka číslovaného seznamu
1. druhá položka
1. třetí položka
    1. druhá úroveň a
    1. druhá úroveň b
        1. třetí úroveň i
        1. třetí úroveň ii
    1. druhá úroveň c
1. čtvrtá položka

- první položka nečíslovaného seznamu
- druhá položka
    - druhá úroveň
- třetí položka

Pokud potřebujete do odstavce vložit matematický výraz, stačí jej uzavřít mezi dva znaky dolaru. Podobně rovnice, které nejsou součástí odstavce, uzavřete mezi dvě dvojice dolarů. Uvnitř dolarů zapisujete matematické výrazy pomocí běžných LaTeXových značek (základy LaTeXové matematické notace můžete najít např. na stránce https://en.wikibooks.org/wiki/LaTeX/Mathematics):

V\ rámci tohoto odstavce napíšeme slavný Einsteinův vzorec
$E = m \cdot c^2$. Ovšem následující rovnice je mnohem hezčí:

$$\Delta y_k = \left(\int_0^k \sin x^{x^{x^x}}d x\right) \times
  \left|\matrix{1&0\\0&1}\right|.$$

A\ to je vlastně vše, co potřebujete vědět o\ matematice.

Hypertextový odkaz, který vložíte do páru značek větší a menší, bude automaticky klikací, musí však začínat znaky “http”, “https” apod.:

<https://quarto.org/>

Alternativně můžete vložit slovo (zde Quarto), které bude obsahovat link na webovou stránku:

[Quarto](https://quarto.org)

Podobně se vkládají i externí obrázky:

![Popisek obrázku](elephant.png)

Alternativně můžete vložit R kód (viz dále) s funkcí include_graphics z balíku knitr. Typičtěji však budeme obrázky vytvářet přímo v R.

Markdown obsahuje i způsob, jak vytvářet tabulky. Nejjednodušší způsob je následující:

hlavička 1      | hlavička 2      | hlavička 3     
--------------- | --------------- | ---------------
obsah buňky 1.1 | obsah buňky 1.2 | obsah buňky 1.3
obsah buňky 2.1 | obsah buňky 2.2 | obsah buňky 2.3

Tabulky je možné různě formátovat. Pro složitější formátování tabulek se podívejte do dokumentace pandoc Markdownu. Častěji však budeme tabulky tvořit přímo v R.

Poznámky pod čarou je možné vložit dvěma způsoby:

[^pozn]: Toto je má poznámka.

V\ tomto textu je poznámka.[^pozn]

V\ tomto odstavci je také poznámka.^[Zde je text poznámky.]

Estéti jistě uvítají, že obyčejné uvozovky " se změní na pravo- a levo-stranné uvozovky (bohužel jen anglické), že tři tečky se změní na znak elipsy a že pomlčky se píší stejně jako v LaTeXu, tj. -- se změní na en-dash (“–”) a --- na m-dash (“—”). Nezlomitelnou mezeru je možné zapsat tak, že před mezeru napíšeme zpětné lomítko, jako např. ve výrazu proměnná\ $k$.

Zalomit stránku je možné takto:

jedna strana

{{< pagebreak >}}

druhá strana

Část textu je možné “zakomentovat” pomocí HTML komentářů:

<!-- Toto je komentář. -->

Markdown v Quartu toho umí mnohem více. Detaily použití najdete zejména na stránkách pandocu (https://pandoc.org/) a Quarta (https://quarto.org/), které obsahuje různá rozšíření Markdownu oproti pandocu.

17.3 Vložení kusů R kódu

Hlavní krása Quarta spočívá v tom, že do dokumentu můžeme vložit kus R kódu. Ten se vyhodnotí a jeho výsledek se (případně s pěkně formátovaných vlastním kódem) vloží do dokumentu.

R kód se vkládá do tzv. chunků. V RStudiu můžete chunk vložit pomocí klávesové zkratky Ctrl-Alt-I; můžete jej však vložit i ručně. Chunk oddělují od běžného textu nahoře i dole tři zpětné apostrofy. Malé r ve složených závorkách ({r}) určuje typ kódu (podobně např. {python} by spustil kód v Pythonu). Chunk s kusem R kódu tedy v Markdownu vypadá takto:

```{r}
x <- seq(from = 0, to = 5 * pi, by = 0.01) |> sin()
plot(x)
```

Při jeho vložení Quarto vypíše vlastní kód (a pěkně jej naformátuje), pak kód provede (a v našem případě vloží do dokumentu obrázek).

Vlastnosti každého chunku může nastavit pomocí zvláštního typu komentářů, které začínají v prvním sloupci a za křížkem mají svislou čáru (trubku) a klíčové jméno parametru oddělené od jeho hodnoty dvojtečkou:

```{r}
#| label: fig-sin
#| fig-cap: "Krásný graf sinusovky."
#| fig-dpi: 100
#| echo: false
x <- seq(from = 0, to = 5 * pi, by = 0.01) |> sin()
plot(x)
```

Výše uvedený chunk obsahuje čtyři volby:

  1. nastavení jména chunku (pomocí volby label); toto jméno se v RStudiu ukáže v seznamu chunků vlevo dole pod editorem a můžete jej použít i v křížovém odkazu na obrázek, tabulku apod.,
  2. popisek obrázku (fig-cap),
  3. rozlišení obrázku (fig-dpi), pokud se bude kompilovat do bitmapovaného formátu (to je implicitní volba při výstupu do HTML a MS Wordu; při výstupu od PDF a LaTeXu se použije vektorový formát PDF) a
  4. zákaz zobrazení zdrojového kódu chunku v dokumentu (echo).

Podobných voleb existuje velmi mnoho. Najdete je vysvětlené na stránkách Quarta (https://quarto.org/).

R kód uvedený výše se provede mezi odstavci. To se hodí pro běžné výpočty, tvorbu obrázků, tabulek apod. Někdy se však hodí vložit vypočtenou hodnotu i přímo do textu. To je možné udělat následujícím způsobem. Řekněme, že jste výše spočítali nějakou hodnotu a vložili ji do proměnné velocity. Nyní chcete přímo v textu vypsat její zaokrouhlenou hodnotu:

... rychlost oběhu peněz je `r round(velocity, 1)`; oproti loňsku ...

Veškerý text mezi dvěma zpětnými apostrofy, kde za prvním apostrofem následuje r se vyhodnotí v R a výsledek vloží na místo nahrazeného textu.

Některé výpočty trvají dlouho a není rozumné muset je provést pokaždé, když chcete renderovat svůj dokument. Zde nabízejí dvě možnosti: Zaprvé, můžete si všechna data, obrázky a tabulky, které chcete do dokumentu vložit, nachystat pomocí v nějakém R skriptu a do dokumentu .qmd je jen vložit. Druhou možností je své mezivýsledky kešovat.

K tomu slouží volba cache. Buď můžete kešovat jen individuální výpočetně náročné chunky, nebo celý dokument. V prvním případě vložíte do chunku volbu cache: true. Ve druhém případě vložíte tuto volbu do hlavičky YAML (viz oddíl 17.5):

---
title: "My Document"
format: html
execute: 
  cache: true
---

17.4 Křížové odkazy a citace

Quarto umí (na rozdíl od čistého Markdownu) pracovat i s křížovými odkazy a citacemi. Oba typy odkazů jsou uvozeny znakem zavináč (@).

Abyste se mohli odkázat na obrázek, tabulku, rovnici nebo oddíl pomocí křížového odkazu, musíte do nich nejdříve umístit “nálepku” (label). V případě obrázků a tabulek k tomu slouží volba label v chunku, kde je vytváříte. “Nálepka” obrázku musí začínat písmeny fig- (např. fig-sin, viz výše), “nálepka” tabulky tbl-. Křížový odkaz na ně má pak podobu @fig-sin.

V případě rovnic musí nálepka začínat písmeny eq- a musíte ji vložit za definici rovnice:

$$\Delta y_k = \left(\int_0^k \sin x^{x^{x^x}}d x\right) \times
  \left|\matrix{1&0\\0&1}\right|.$$ {#eq-mat}

Quarto v takovém případě rovnici očísluje. Křížový odkaz na rovnici má pak podobu @eq-mat.

V případě oddílů je třeba vložit křížový odkaz za název oddílu takto:

## Oddíl druhé úrovně {#sec-odd-dva}

“Nálepka” oddílů musí začínat písmeny sec-. Odkaz má pak podobu @sec-odd-dva.

Quarto k odkazům implicitně přidává slova jako “Figure”, “Table” apod. Tomu je možné zabránit tak, že odkaz umístíte do hranatých závorek a před zavináč napíšete znak minus:

... viz obrázek\ [-@fig-sin].

Do hranatých závorek můžete umístit i text; ten je pak součástí hypertextového odkazu.

Pro tvorbu citací používá Quarto prográmek bibtex. Nejdříve potřebujete databázi odkazovaných zdrojů (článků, knih apod.). Vytvořit ji můžete buď ručně (jednotlivé položky např. stáhnete ze stránky https://scholar.google.cz/, kde u zvoleného článku kliknete na “Cite”, a pak na “BibTeX”) nebo vám ji může vygenerovat software pro správu citací. Zde doporučuji Zotero, protože RStudio má vyřešenou integraci Zotera. Zadruhé potřebujete do hlavičky YAML (viz oddíl 17.5) umístit odkaz na bibtexovou databázi.

---
bibliography: book.bib
---

Vlastní odkaz na literaturu má pak podobný formát jako křížové odkazy. Řekněme, že chcete citovat knihu Wickham a Grolemund (2017) a ve své bibtexové databázi ji máte označenou nálepkou WickhamRfDS. Pak se na ni můžete odkázat takto:

více viz @WickhamRfDS.

Citaci opět můžete různě formátovat tak, že ji uzavřete do hranatých závorek.

Více o křížových odkazech a citacích najdete na webu Quarta, zejména na stránkách https://quarto.org/docs/authoring/footnotes-and-citations.html#citations a https://quarto.org/docs/authoring/cross-references.html.

17.5 Hlavička YAML

Quarto dokumenty začínají hlavičkou, ve které je možné nastavit různé proměnné a volby platné pro celý dokument. Hlavička má formát YAML (https://yaml.org/), což je prostým okem čitelný způsob ukládání strukturovaných dat (“a human-friendly data serialization language for all programming languages”).

Nejjednodušší hlavička má následující podobu:

---
title: "Můj skvělý dokument"
author: "Já Sám"
format: html
editor: visual
---

Hlavička od zbytku dokumentu oddělená nahoře i dole třemi pomlčkami. Struktura hlavičky je zde jednoduchá: klíčové slovo (název proměnné) je oddělené od své hodnoty odděleno dvojtečkou. Tato hlavička určuje název dokumentu, který ze zobrazí v jeho titulku a jméno autora. Dále určuje, že se dokument bude renderovat do HTML a že se bude používat vizuální editor.

Všechny položky v hlavičce se skládají z čistého textu je možné je snadno přepsat. Např. renderování do PDF zajistíme změnou “html” na “pdf”.

Některé proměnné mohou v YAML obsahovat více položek. V takovém případě se píší na nové řádky a jsou odsazeny (standardně o 2 znaky, je však možné použít i odsazení o 4 znaky apod.). Následující příklad ukazuje hlavičku, která zajistí, že ten stejný dokument bude renderován jak do HTML (ve stylu cosmo), tak do PDF (kde se použije rodina písem Libertinus):

---
title: "Můj dokument"
format:
  html:
    theme: cosmo
  pdf:
    fontfamily: libertinus
---

Pokud jeden dokument obsahuje v hlavičce pokyny pro více výstupních formátů, pak se v RStudiu vedle tlačítka Render objeví malý trojúhelníček, který označuje pull-down menu, ve kterém si můžete vybrat, do kterého formátu se bude dokument renderovat.

V hlavičce YAML můžete nastavit i jazyk dokumentu (např. lang: cs). V takovém případě se v dokumentu automaticky přeloží některé texty, např. “Figure” se změní na “Obrázek”, “Table” na “Tabulka” apod.

Do hlavičky můžete umístit veškerá obecná nastavení dokumentu, včetně obecného nastavení chunků. Pokud např. chcete, aby se v dokumentu neobjevil zdrojový kód chunků, přidáte do hlavičky:

echo: false

Quarto podporuje mnoho různých nastavení hlavičky. Jejich dokumentaci najdete na stránce https://quarto.org/.

17.6 Specialitky

Parametrizovaný report

Někdy potřebujete vytvořit celou sadu dokumentů, které se budou lišit jen několika parametry. Například mustíe zpracovat stejnou analýzu pro různé země, různé sklady apod. V takovém případě je vhodné vytvořit parametrizovaný report. Toho lze docílit tak, že v hlavičce YAML vytvoříte proměnné, které budou obsahovat implicitní hodnoty těchto parametrů:

---
params:
  country: "cz"
  vat: 0.21
---

Ve vlastním kódu pak můžete tyto parametry použít takto:

... v\ zemi `r params$country` ...

(V reálném případě spíš použijete daný parametr k načítání nebo filtrování dat apod.)

Výhodou tohoto přístupu je to, že pak můžete vytvořit stejný report pro různé země tak, že stejný dokument renderujete s různými parametry. V příkazovém řádku svého operačního systému spustíte

quarto render my-report.qmd -P country:de -P vat:0.19

Alternativně můžete vytvořit pro každou zemi konfigurační soubor s parametry ve formátu YAML. Výsledný dokument pak renderujete takto:

quarto render my-report.qmd --execute-params params-de.yml

Tvorba větších dokumentů

V předchozím oddíle jsme uvažovali typickou situaci, kdy výstupem Quarto dokumentu je jeden dokument (např. článek) nebo jedna prezentace. Quarto však umí stejným způsobem vytvářet knihy, weby, blogy a mnoho dalších výstupních formátů. Jediné, co se změní, je fakt, že hlavička YAML bude poněkud komplexnější a bude umístěna v separátním souboru _quarto.yml. Dokumentaci najdete opět na stránce https://quarto.org/docs/guide/.

Renderování R skriptu

Někdy můžete potřebovat renderovat do výstupního formátu normální R skript. To můžete udělat tak, že v RStudiu kliknete na ikonu knihy (Compile Report) nebo pomocí klávesové zkratky Ctrl-Shift-K.

Standardně se skript provede a kód i výsledky se vloží do zvoleného formátu (HTML, PDF nebo MS Word). I do takového skriptu můžete vložit hlavičku YAML a běžný text. Postup je však mírně odlišný. Dokumentaci najdete na stránce https://rmarkdown.rstudio.com/articles_report_from_r_script.html.

  1. Kromě R umí Quarto podobně pracovat i s Pythonem, Julií a Observable.↩︎