8  Komunikácia

Okrem výpočtového a vizualizačného prostredia pre analýzu údajov Rko poskytuje aj jednotný rámec pre kombináciu generovaných výsledkov a autorského textu¹. Cieľom analytika je totiž najčastejšie

1. komunikovať s ľuďmi (so zákazníkom, s manažérom) o dosiahnutých výsledkoch (bez zachádzania do technických podrobností, kódu),
2. spolupracovať s inými analytikmi (vrátane svojho búdúceho “ja”), ktorých zaujíma aj reprodukovateľnosť výsledkov (teda kód),
3. zaznamenať nielen to, čo urobil, ale aj to, čo si pri tom myslel.

8.1 Úvod

V ranných časoch používania systému R si používatelia zdrojový kód svojich výpočtov ukladali v skriptovom súbore s príponou „.R”. Spočiatku doň pridávali drobné komentáre ku kódu jednoducho za značku #, ale prezentovateľné výstupy vytvárali v špecializovaných programoch ako LaTeX² či MS Word kopírovaním kódu a výstupov. Neskôr – s vyvinutím balíku knitr – sa do skriptového súboru³ začal za značku #' dopĺňať širší textový popis. Ten môže byť štrukturovaný do kapitol a vo výstupe sprevádzaný napr. automaticky generovaným obsahom. Nastavenia ku blokom kódu sa zapisujú za značku #+ a môže sa nimi napr. vypnúť zobrazenie kódu v reporte, nastaviť veľkosť obrázku, či úplne vypnúť vykonanie celého bloku príkazov. Do riadku textu medzi krútené zátvorky {{ a }} sa dá vložiť vykonateľný kód, naopak poznámky medzi dvojicami /* a */ sa v reporte nezobrazia vôbec. Text sa môže doplniť o hlavičku s metainformáciami (medzi znaky ---) či matematické výrazy (medzi znaky $ a $$).

Napríklad skriptový dokument s nasledujúcim obsahom

#' ---
#' title: Môj prvý dokument
#' author: Ferko Mrkvička
#' date: 20.2.2022
#' output: html_document
#' ---
#' 
#' # Prvá kapitola
#' 
#' Začíname _odmocninou_ $\sqrt{4} =$ 
{{ sqrt(4) }}
#' .
#' 
#' # Druhá kapitola
#' 
#' Pokračujeme grafom funkcie $f(x) = \log(x)$
#+ funkcia, out.width = '50%'
curve(log(x), from = 0, to = 2)

/* Čo vymyslieť na záver? */

sa položkou File > Compile Report... v menu RStudio alebo príkazom rmarkdown::render("názov_súboru.R") v interpreteri R skompiluje do HTML dokumentu na Obr. 8.1.

Obrázok 8.1: R Markdown dokument.

Zmysel skriptového súboru však stále spočíva najmä v uchovaní kódu jazyka R, a už menej v jeho prezentovaní (spolu s textovými či grafickými výsledkami výpočtov). Naopak, na tvorbu autorského textu bol zavedený textový formát R Markdown. V skutočnosti sa totiž aj pri kompilácii reportu zo skriptového súboru interne najprv zavolá funkcia knitr::spin, ktorá súbor s príponou .R preloží do súboru vo formáte R Markdown s príponou .Rmd a ten je ďalej spracovaný.

Rovnaký výstupný dokument ako v predošlom príklade (Obr. 8.1) tak dostaneme aj z nasledujúceho R Markdown súboru

---
title: Môj prvý dokument
author: Ferko Mrkvička
date: 20.2.2022
output: html_document
---

# Prvá kapitola

Začíname _odmocninou_ $\sqrt{4} =$ `r sqrt(4)`.

# Druhá kapitola

Pokračujeme grafom funkcie $f(x) = \log(x)$
```{r funkcia, out.width = '50%'}
curve(log(x), from = 0, to = 2)
```

<!-- Čo vymyslieť na záver? --> 

Kompilácia súboru s príponou .Rmd sa spúšťa rovnakou funkciou rmarkdown::render no z prostredia RStudio na to slúži voľba File > Render document alebo klávesová skratka [Ctrl]+[Shift]+[K]. Na pozadí je dokument najprv postúpený balíku knitr, ktorý spustí kód a výsledok uloží do dokumentu vo formáte Markdown s príponou .md, a ten sa následne spracuje konvertorom Pandoc do požadovaného výstupného formátu (pdf, html, doc, odt, epub…).

Zhrnuté a podčiarknuté, R Markdown je jednoduchý značkovací jazyk⁴ ale aj jednotný rámec pre tvorbu reprodukovateľného autorského obsahu v kontexte analýzy údajov pomocou R. Stal sa štandardom pre publikovanie v prostredí R a existuje preň množstvo návodov a doplnkov, zo všetkých relevantných publikácií spomeňme predošlú verziu tejto kapitoly v knihe Bacigál (2022), praktickú kuchársku knihu Xie, Dervieux, a Riederer (2020) alebo podrobnú príručku Xie, Allaire, a Grolemund (2018).

Postupne s prenikaním moderných softvérových nástrojov do Rka (vrátane iných programovacích jazykov) a orientáciou vývojového prostredia RStudio na data science sa však do popredia dostáva nová generácia otvoreného systému pre vedecké a odborné publikovanie, ktorá stavia na vývoji a úspechu R Markdown. Volá sa Quarto a oproti R Markdown zjednocuje syntax značkovacieho jazyka, poskytuje prepracovaný návod a referenčnú príručku pod jednou strechou a tiež otvára brány ďalším programovacím jazykom (Python, Julia), nástrojom interaktívnej vizualizácie (Observable) a vývojovým prostrediam (JupyterLab, VS Code, Neovim, …) používaným v oblasti data science.

Používanie nového formátu je v prostredí RStudio jednoduché, Quarto s ním prichádza predinštalované⁵. Na začiatku pri vytvorení nového súboru je potrebné zvoliť položku Quarto document, kompilácia zdrojového súboru do výstupného sa docieli rovnako ako pri R Markodown (tlačítkom Render alebo klávesovou skratkou [Ctrl]+[Shift]+[K]) a výsledok sa zobrazí spravidla v pravom dolnom paneli pod záložkou Viewer. V inom vývojovom prostredí alebo pri práci z príkazového riadku je potrebné Quarto nainštalovať do systému samostatne, prípadne spolu so zásuvným modulom pre dané vývojové prostredie, pričom dokument sa skompiluje a zobrazí príkazom quarto preview dokument.qmd zadaným v termináli operačného systému.

Syntax novej generácie je podobná tej starej, ale hoci sú navzájom do značnej miery kompatibilné, tá nová je konzistentnejšia naprieč platformami a kompatibilnejšia so systémom Pandoc. Pre zbežné porovnanie, náš predošlý príklad bude v textovom formáte Quarto s príponou .qmd vyzerať nasledovne

---
title: Môj prvý dokument
author: Ferko Mrkvička
date-format: "DD.M.YYYY"
format: html
---

# Prvá kapitola

Začíname _odmocninou_ $\sqrt{4} = $ `r sqrt(4)`.

# Druhá kapitola

Pokračujeme grafom funkcie $f(x) = \log(x)$

```{r}
#| label: funkcia
#| out-width: 50%
curve(log(x), from = 0, to = 2)
```

<!-- Čo vymyslieť na záver? --> 

ale výsledný HTML dokument je v novom kabáte (Obr. 8.2).

Obrázok 8.2: Quarto dokument.

V nasledujúcich kapitolách sa zameriame na Quarto. Postupne si preberieme základy formátovania textu, integrovanie kódu a matematických výrazov, formátovanie obrázkov, tvorbu tabuliek a nakoniec špecifiká výstupných formátov.

8.2 Značkovací jazyk Markdown

Text, ktorý má vhodným spôsobom sprostredkovať autorove myšlienky, potrebuje vhodné formátovanie, aby bol ľahko čitateľný – od úpravy vzhľadu písma až po zobrazenie v tabuľke.

Konkrétne, text na zobrazenie kurzívou sa obalí dvojicou hviezdičiek * alebo podčiarkovníkov _ (teda *kurzívou* alebo _kurzívou_), text hrubým fontom štvoricou znakov (**hrubým** __fontom__), ďalej _dolný a ^horný index párom vlnoviek (~dolný~) resp. striešok (^horný^). Text medzi opačnými úvodzovkami sa zachová *bez formátovania* vo fonte kódu (`*bez formátovania*`) a medzi dvoma pármi vlnoviek sa preškrtne (~~preškrtne~~).

Nadpisy kapitol sa začínajú jednou, dvoma alebo viacerými mriežkami # podľa úrovne vnorenia.

Citát sa v štandardnej téme Markdown dokumentu zobrazuje odsadeným odsekom, väčším fontom a zvislou čiarou. Stačí začať znakom >.

> Citát sa v štandardnej téme Markdown dokumentu zobrazuje odsadeným odsekom, väčším 
fontom a zvislou čiarou. Stačí začať znakom `>`.

Číslované aj nečíslované zoznamy predchádza voľný riadok, potom

• každá položka nečíslovaného zoznamu začína ktorýmkoľvek znakom *, -, +
• na novom riadku,
  • každá vnorená položka zoznamu začína na novom riadku odsadením aspoň o dve medzery oproti vyššej úrovni,
    • možné je ešte hlbšie vnorenie
  • aj návrat na ľubovoľnú úroveň.

Číslované aj nečíslované **zoznamy** predchádza voľný riadok, potom

* každá položka nečíslovaného zoznamu začína ktorýmkoľvek znakom `*, -, +` 
* na novom riadku,
  + každá vnorená položka zoznamu začína na novom riadku odsadením aspoň o _dve medzery_ 
  oproti vyššej úrovni,
    - možné je ešte hlbšie vnorenie
  + aj návrat na ľubovoľnú úroveň.

Kvôli prehľadnosti je dobré položky rovnakej úrovne začínať rovnakým znakom. Čo sa týka číslovaného zoznamu,

1. každá položka začína číslicou (0 – 9) a bodkou,
2. číslovanie pokračuje automaticky, takže nevadí, keď sa v ďalšej číslici pomýlime alebo niektorú položku zmažeme,
   2. vnorené položky zoznamu môžu začínať aj písmenom, nemusí byť to prvé v abecede,
   3. musia však byť odsadené aspoň o tri medzery,
      1. čo platí aj pre ďalšiu úroveň (a navyše s dvojitou medzerou po).
3. Hlavné číslovanie pokračuje ďalej automaticky.

1. každá položka začína číslicou (0 -- 9) a bodkou,
3. číslovanie pokračuje automaticky, takže nevadí, keď sa v ďalšej číslici pomýlime alebo 
niektorú položku zmažeme,
   b. vnorené položky zoznamu môžu začínať aj písmenom, nemusí byť to prvé v abecede,
   d. musia však byť odsadené aspoň o _tri medzery_,
      A.  čo platí aj pre ďalšiu úroveň (a navyše s dvojitou medzerou po).
8. Hlavné číslovanie pokračuje ďalej automaticky.

Hypertextové odkazy je možné vkladať priamo – https://www.math.sk/mpm/ (<https://www.math.sk/mpm/>) – alebo skryté za kľúčovými frázami ako fakultná stránka ([fakultná stránka](https://www.svf.stuba.sk "Stavebná fakulta")).

Obrázky sa vkladajú veľmi podobne – – s (dobrovoľným) alternatívnym textom v hranatých zátvorkách (![logo MPM](https://.....png)). Okrem toho sa dajú ľubovoľne kombinovať, napríklad kompozícia

Fakulta

Študijný program

je výsledkom zápisu

::: {layout-ncol=2}
![Fakulta](pic/logo-svf.png)

![Študijný program](pic/logo-mpm.png)
:::

pomocou prostredia div.

Do rovnakej skupiny značiek ako odkazy a obrázky patrí aj poznámka pod čiarou⁶ (čiarou^[Poznámka pod čiarou.]). Hranaté zátvorky však majú ešte širší význam, ohraničujú inline prostredie span pomocou ktorého môžeme formátovať ľubovoľnú časť textu, napr. pomocou CSS štýlu ho zafarbiť ([zafarbiť]{style="color: red;"}). ⁷

Aby odkazy (na webstránku, obrázok či poznámku) nemuseli zneprehľadňovať zdrojový text, Markdown umožňuje vsunúť iba identifikátor a potom celú adresu uviesť inde, povedzme na konci dokumentu. Napríklad text [fakultná stránka][svf] bude vo vete a [svf]: https://www.svf.stuba.sk/ "Stavebná fakulta" upratané na inom, vhodnejšom mieste, pričom zjavne svf je jedinečný identifikátor a text v úvodzovkách je zobrazovaný ako bublinová nápoveda (tooltip). Podobne sa umiestnia obrázky pomocou ![alternatívny text][id] v texte, a mimo neho bude uvedený zvyšok [id]: odkaz/na/obrázok "tooltip", resp. poznámka s identifikátorom [^id] v texte a telom [^id]: ... mimo neho.

Nasledujúca tabuľka s nadpismi a zarovnaním stĺpcov

Vľavo	Vpravo	Preddefinovane	Na stred
12	12	12	12
123	123	123	123

je výsledkom jednoduchého zápisu:

| Vľavo | Vpravo | Preddefinovane | Na stred |
|:------|-------:|----------------|:--------:|
| 12    | 12     | 12             | 12       |
| 123   | 123    | 123            | 123      |

Samozrejme tabuľky či obrázky sa dajú vytvoriť alebo pripojiť aj pomocou príkazov R, o tom si bližšie povieme v ďalšej kapitole.

8.3 Výpočty

Kód jazyka R (podobne ako ďalších podporovaných programovacích jazykov) sa v Quarto dokumente vkladá po blokoch medzi značky ```{r} a ```, ktorých vloženie v prostredí RStudio zabezpečí aj klávesová skratka [Ctrl]+[Alt]+[I]. Spustenie kódu po riadkoch alebo vyznačených častiach funguje rovnako ako sme boli doteraz zvyknutí – klávesovou skratkou [Ctrl]+[Enter] – no často je výhodnejšie spustiť celý blok naraz pomocou [Ctrl]+[Shift]+[Enter].

Bloky by sme mali chápať ako relatívne samostatné jednotky – podobne ako funkcie – zamerané na jednu úlohu. Každý blok môže mať svoj názov (label), čo má niekoľko výhod: a) dá sa ľahšie nájsť pomocou rozbaľovacej ponuky vľavo pod oknom skriptového editoru RStudio, b) pri zlyhaní kompilácie dokumentu sa rýchlejšie nájde chyba, c) pomôže pri zostavení súboru súvisiacich blokov, ktoré majú byť pre náročnosť výpočtu po prvom spustení uložené do cache pamäte a obnovené len pri zmene (tzv. caching), d) pomenujú sa po nich súbory obrázkov exportovaných pri konverzii (t. j. ľahšie sa potom manipuluje s vygenerovanými obrázkami), e) slúži ako identifikátor pre krížové referencie. V názve sa odporúča použiť iba alfanumerické znaky a pomlčku.

Okrem názvu sa do metaúdajov za znaky #| zapisujú lokálne nastavenia blokov, každé do nového riadku. Napríklad nasledujúci blok R kódu sa volá súčet a pri kompilácii sa vďaka nastaveniu ani nespustí, ani v dokumente nezobrazí.

```{r}
#| label: súčet 
#| eval: false 
#| echo: false
a <- 2
a + 3
```

Ak chceme blok iba zobraziť, ale nie nechať vykonať, stačí vynechať krútené zátvorky. Vďaka špecifikácii jazyka sa zvolí správne zvýraznenie syntaxe.

```r
2 + 2
```

2 + 2

Nastavenie môže byť dané pre celý blok jednou logickou hodnotou, ale aj selektívne pre konkrétne riadky (s predsadením !expr)

```{r}
#| eval: !expr c(1,3)
#| echo: false
a <- 2
a <- 10
a
```

[1] 2

alebo môže byť zadané dynamicky. Napríklad nasledujúci blok určí hodnotu jednoduchého časového prepínača

```{r}
# časový prepínač  
podmienka <- Sys.Date() < '2020-05-15'  
```

a ďalší blok sa vykoná len pred 15. májom 2020.

```{r}
#| eval: !expr podmienka
2 + 3
```

Balík knitr poskytuje asi 80 nastavení, kompletný zoznam sa nachádza v referenčnej príručke, najdôležitejšie sú tieto (s prednastavenou hodnotou v zátvorke):

• eval (true): či sa má blok príkazov vykonať (vyhodnotiť, angl. evaluate),

• echo (true): či sa má vo výstupnom dokumente zobraziť zdrojový kód,

• warning, message (true): či sa má varovná hláška alebo diagnostická správa zobraziť vo výstupnom dokumente,

• error (false): či pokračovať s kompiláciou aj napriek chybe,

• include (true): či zaradiť blok do dokumentu (vykoná sa tak či tak),

• fig-width (7), fig-height (5): veľkosť grafického výstupu v palcoch (prednastavené hodnoty sa líšia podľa výstupného formátu),

• fig-asp: pomer výšky ku šírke (výška alebo šírka je následne dopočítaná),

• out-width, out-height: veľkosť grafického výstupu vo finálnom dokumente (môže byť v jednotkách podporovaných LaTeX-om či HTML-kom), stačí určiť relatívne, napr. out-width: 80%,

• fig-align (default): horizontálne zarovnanie obrázku ('left', 'center', 'right'),

• layout: rozmiestnenie a relatívna šírka plávajúcich objektov, napr. layout: [[2,1],[1]] umiestni prvé dva obrázky hore v pomere 2:1 a druhý dole na celú šírku.

• layout-ncol (1): počet stĺpcov, do ktorých sa obrázky majú umiestniť,

• cache (false): či zapnúť caching (toto môže byť veľmi zradné, používať opatrne a len v nevyhnutných prípadoch).

Často sa opakujúce nastavenie môže byť výhodné vykonať globálne v YAML hlavičke alebo funkciou

```{r}
#| include: false
knitr::opts_chunk$set(fig.width = 8, collapse = TRUE)
```

Kódom sa dajú vkladať aj obrázky, či už hotové alebo čerstvo vygenerované.

```{r}
#| fig-subcap:
#|   - GGplot
#|   - Logo R
#| layout: [[4,3]]
library(ggplot2)
ggplot(mtcars) + aes(x = hp, y = mpg) + geom_point(color = 4) + theme_bw()
knitr::include_graphics("pic/logo-R.png")
```

GGplot

Logo R

Na zobrazenie tabuľky dobre poslúži funkcia knitr::kable

knitr::kable(mtcars[1:4, ], caption = "Hlavička mtcars pomocou *kable*")

Hlavička mtcars pomocou kable

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1

(s podrobnejším doladením pomocou balíka kableExtra), ale aj nástroje balíkov gt, flextable a ďalších.

8.4 Matematické výrazy

Vďaka vygenerovanému dokumentu môžeme korektnosť výsledkov svojho výpočtu podložiť zverejneným kódom. V pozadí výpočtu však stojí aj nejaká teória – tá (nielen vo vedeckých článkoch či diplomových prácach) zvyčajne zaujíma miesto na začiatku dokumentu hneď po motivačnom úvode. Súčasťou teoretickej rozpravy sú aj matematické vzorce (keďže je často efektívnejšie vyjadriť vzťahy nimi než slovným opisom).

Kto raz začal práce s matematickým obsahom písať v typografickom systéme LaTeX, ten sa už sotva dobrovoľne vráti ku WYSIWYG procesoru akým je MS Word, kde sa vzorce vkladajú z palety ako grafické elementy. Už voľne šíriteľná alternatíva – textový procesor LibreOffice Writer – vkladanie vzorcov rieši textovým vstupom pomocou svojho jednoduchého značkovacieho jazyka, čo po osvojení syntaxe prácu výrazne zrýchli. Systém LaTeX má bohatšie možnosti vytvárania (nielen) matematického obsahu, nevýhodou je strmšia krivka učenia sa (learning curve) na úplnom začiatku. Dobrá správa je, že R Markdown používa rovnakú syntax ako LaTeX, takže skúsenejší čitateľ môže túto kapitolu pokojne preskočiť (užitočný prehľad poskytuje aj wiki stránka alebo slovenský preklad známeho manuálu (Oetiker 1999, najmä Kapitola 3).

Podobne ako kód, aj vzorce sa dajú písať v texte – ohraničené párom dolárov (napríklad $S=\pi r^2$ sa zobrazí do \(S=\pi r^2\)) – alebo v samostatnom riadku (riadkoch) medzi dvojicami dolárov:

$$
S = \pi r^2
$$

\[ S = \pi r^2. \] Viacriadkové vzorce prostredníctvom znaku zarovnania & a zalomenia riadku \\ zabezpečuje prostredie⁸ split.

$$
\begin{split}
S & = \pi r^2 \\
\sqrt{\frac{S}{\pi}} & = r
\end{split}
$$

\[ \begin{split} S & = \pi r^2 \\ \sqrt{\frac{S}{\pi}} & = r \end{split} \]

Premenné značené písmenami latinskej abecedy sú v matematickom móde štandardne sádzané kurzívou, potom napr. zhrubnutie sa vykoná pomocou \mathbf. Grécke písmená sa značia svojim názvom za lomítkom, napr. \omega \(\omega\) a \Omega \(\Omega\). Zátvorky sa prispôsobia svojmu obsahu, ak ich doplníme dvojicou \left a \right.

$$
\left( \sum_{i=1}^n v_i^2 \right) = \mathbf{v}\cdot\mathbf{v} = \alpha \in \mathbb{R}
$$

\[ \left( \sum_{i=1}^n v_i^2 \right)= \mathbf{v}\cdot\mathbf{v} = \alpha \in \mathbb{R} \] Podobne ako R – aj systém LaTeX má množstvo rozširujúcich balíčkov. Pre písanie matematických výrazov je najznámejším amsmath, v ktorom sú definované okrem iného aj rôzne prostredia pre viacriadkové zarovnanie ako napr. align alebo cases. Tento balík je automaticky systémom načítaný, no iné balíky by bolo potrebné v YAML hlavičke inicializovať. Rovnako by to bolo aj s LaTeX príkazmi, ktoré patria do preambuly (teda pred telo) LaTeX dokumentu. Treba však upozorniť, že nie všetky slová jazyka LaTeX budú fungovať mimo PDF formátu výstupného dokumentu bez problémov.

8.5 YAML hlavička

Globálne nastavenia dokumentu sa zapisujú do hlavičky vo formáte YAML⁹ medzi párovú sekvenciu znakov --- napr. v nasledovnej hierarchickej štruktúre:

---
položka1: hodnota
položka2:
  položka2.1: hodnota 1
  položka2.2: 
    položka2.2.1:
      - položka2.2.1.1: hodnota 2
      - položka2.2.1.2: hodnota 3
    položka2.2.1: hodnota 4
---

Najčastejšie obsahuje

• metaúdaje za položkami title, subtitle, author, affiliation, abstract,
• dátum
  • date zadaný v tvare “mesiac/deň/rok” alebo jednoducho hodnotou today, now či last-modified a
  • zobrazený podľa špecifikácie date-format, napr. full, long, short, iso alebo manuálne “DD.MM.YYYY”
• výstupný formát položkou format
  • a hodnotami napr. (dokumenty) html, pdf, docx, odt, epub, (prezentácie) revealjs, pptx, beamer
  • alebo položkou druhej úrovne v tvare hodnota_formátu: a jeho špecifikáciou ako položky tretej úrovne
• ďalšie nastavenia, napr. pre
  • zobrazenie obsahu toc, toc-depth a číslovanie kapitol number-section, number-depth, number-offset
  • layout classoption, cap-location, margin-*
  • zobrazenie a vykonanie kódu (podobne ako pre jednotlivé bloky)
  • obrázky fig-align, fig-width, fig-height, fig-asp a tabuľky tbl-colwidths, df-print
  • bibliografiu a citácie
  • lokalizáciu buď skratkou jazyka lang, napr. cs alebo manuálne v položke language.

Uvedené nastavenia sa dajú použiť globálne pre všetky bežné formáty, ale aj selektívne, takže napr. nasledujúcou hlavičkou sa zakáže vykonanie kódu vo všetkých výstupoch a zobrazí sa iba v HTML.

---
format:
  pdf: 
    echo: false
  html:
    echo: true

eval: false
---

Niektoré nastavenia sú špecifické pre daný formát a v rôznych výstupných formátoch fungujú rozdielne, prípadne vôbec, ako napr. code-fold, ktoré umožní rozbaliť nezobrazený kód v HTML.

Pristavme sa ešte pri položke lang, ktorá je mimo anglicky hovoriacich krajín veľmi dôležitá. Vo verzii Quarto 1.3 ešte nebol dostupný preklad názvov do slovenského jazyka, takže sa dal pridať iba manuálne pre všetky premenné obsiahnuté v jazykovom súbore _language.yml pomocou položky language. Či už jednotlivo, napr.

language: 
  toc-title-document: Obsah

alebo spolu v jednom .yml súbore (musí byť pripravený vopred).

language: _language-sk.yml

Od verzie Quarto 1.4 je použitie slovenskej lokalizácie jednoduchšie.

lang: sk

8.6 Krížové odkazy a citácie

Krížové odkazy prepájajú jednotlivé prvky toho istého dokumentu, najčastejšie objekt (ako napr. obrázok) s jeho zmienkou v texte. Každý taký objekt musí mať pridelený jedinečný identifikátor v tvare typ-názov, aby sa naň v texte dalo odkázať pomocou odkazu @typ-názov. Typ takého objektu môže byť

• obrázok fig (figure),
• tabuľka tbl (table),
• matematická rovnica eq (equation),
• veta thm (theorem), lem (lemma), prp (proposition), dôsledok cor (corrolary), definícia def (definition), príklad exm (example), cvičenie exr (exercise),
• kapitola sec (section),
• upozornenia (callout blocks) nte (note), tip, wrn (warning), imp (important), cau (caution)

Umiestnenie identifikátorov závisí od objektu, vo všeobecnosti

• v prostredí Markdown je v tvare {#typ-názov},
• v blokoch kódu ako súčasť metaúdajov: #| label: typ-názov,

teda napríklad Obr. 8.3 (@fig-logoMPM) odkazuje na obrázok, ktorý mohol byť generovaný nasledujúcim zápisom (všimnime si, že v krútených zátvorkách sa nastavujú aj atribúty objektu)

![Logo MPM](pic/logo-mpm.png){#fig-logoMPM width=50%}

ale ekvivalentne aj nasledujúcim kódom.

```{r}
#| label: fig-logoMPM
#| fig-cap: Logo MPM
#| out-width: 50%
knitr::include_graphics("pic/logo-mpm.png")
```

Obrázok 8.3: Logo MPM

Obrázky sa dajú kombinovať s odkazom na ich popis, a to spoločne Obr. 8.4 (@fig-logo) aj jednotlivo Obr. 8.4 (a) (@fig-logo-1), jednak pomocou prostredia div,

::: {#fig-logo layout-ncol=2}
![Fakulta](pic/logo-svf.png){#fig-logo-1}

![Študijný program](pic/logo-mpm.png){#fig-logo-2}

Logá používané v súčasnosti
:::

jednak pomocou kódu.

#| label: fig-logo
#| fig-cap: Logá používané v súčasnosti
#| fig-subcap:
#|   - Fakulta
#|   - Študijný program
#| layout-ncol: 2
knitr::include_graphics("pic/logo-svf.png")
knitr::include_graphics("pic/logo-mpm.png")

(a) Fakulta

(b) Študijný program

Obrázok 8.4: Logá používané v súčasnosti

Podrobný textový popis jednotlivých obrázkov nie je nutný, stačí uviesť fig-subcap: true.

Pri tabuľkách sa popis umiestňuje za dvojbodku, ako napr. v zápise tabuľky Tabuľka 8.1

| Col1 | Col2 | Col3 |
|------|------|------|
| A    | B    | 1    |
| E    | F    | 2    |
| X    | Y    | 3    |

: Moja tabuľka {#tbl-alfanum}

Tabuľka 8.1: Moja tabuľka

Col1	Col2	Col3
A	B	1
E	F	2
X	Y	3

Identifikátor matematickej rovnice je potrebné odsunúť až za uzatvárajúcu dvojicu dolárov, ako vo vzťahu (8.1).

$$
y = ax + b
$$ {#eq-line}

\[ y = ax + b \tag{8.1}\]

Matematické vety sa vytvárajú pomocou prostredia div, napríklad Teorém 8.1 je výsledkom zápisu

::: {#thm-phytagoras}

## Pytagoras

Štvorec prepony $c$ pravouhlého trojuholníka je rovný súčtu štvorcov odvesien $a,b$, teda

$$
c^2 = a^2 + b^2.
$$
:::

Teorém 8.1 (Pytagoras) Štvorec prepony \(c\) pravouhlého trojuholníka je rovný súčtu štvorcov odvesien \(a,b\):

\[ c^2 = a^2 + b^2 \]

A nakoniec, identifikátor kapitoly sa umiestňuje za jej názov (## Značkovací jazyk Markdown {#sec-crossref}), presmerovanie je potom možné pomocou klasického hypertextového odkazu Krížové odkazy a citácie ([Značkovací jazyk Markdown](#sec-crossref)) alebo krížovým odkazom Sekcia 8.6 (@sec-crossref).

Správanie a zobrazovanie odkazov sa dá nastaviť v YAML hlavičke. Tu sme napríklad zrušili zobrazenie prednastaveného slova ‘Rovnica’ (alebo ‘Equation’) pred číslom rovnice.

---
crossref: 
  eq-prefix: ""
---

Zatiaľčo krížové odkazy pomáhajú čitateľnosti a orientácii vo vlastnom autorskom texte, citácie bibliografických zdrojov plnia ďalšie úlohy:

• podložiť autorove tvrdenia a doplniť ďalšie informácie,
• uznať prácu iných autorov (a vyhnúť sa plagiátorstvu),
• pridať dielu na dôveryhodnosti.

Citácia sa dá považovať za špeciálny druh krížového odkazu, pretože sa používa podobným spôsobom (@názov). Pomenovanie identifikátora nie je striktne určené, ale je výhodné mať ustálený systém, napr. v tvare autorROK alebo autorROKdielo. V texte sa citácia umiestňuje rôznymi spôsobmi:

• @bacigal2022uvod: Bacigál (2022) ukázal, že R sa dá použiť ako kalkulačka.
• [@bacigal2022uvod]: R sa dá použiť ako kalkulačka (Bacigál 2022).
• [pozri @bacigal2022uvod, str. 7]: R sa dá použiť ako kalkulačka (pozri Bacigál 2022, str. 7).
• [-@bacigal2022uvod]: Bacigál povedal, že R sa dá použiť ako kalkulačka (2022).

Aby sme mohli v texte citovať, potrebujeme k dokumentu pripojiť citačnú databázu (bibliografický zoznam). To sa dá tromi spôsobmi:

• uvedením zoznamu v hlavičke vo formáte CSL YAML, napr.¹⁰

  ---
  references:
  - id: bacigal2022uvod
    title: Úvod do analýzy údajov pomocou R
    author:
    - family: Bacigál
      given: Tomáš
    issued:
    - year: 2022
    publisher: Spektrum STU
    type: book
    url: https://www.svf.stuba.sk/buxus/docs/dokumenty/skripta/2022/Bacigal_T._-_UVOD_DO_ANALYZY_UDAJOV_POMOCOU_R.pdf
  ---

• odkázaním na bibliografický súbor vo formáte BibTeX s príponou .bib/.bibtex (alebo v inom podporovanom formáte: .json, .yaml, .ris). V hlavičke YAML pribudne riadok

  bibliography: literatura.bib

  a súbor literatura.bib obsahuje (okrem iných aj) záznam

  @book{bacigal2022uvod,
  author = "Tomáš Bacigál",
  title = "Úvod do analýzy údajov pomocou R",
  year = "2022",
  publisher = "Spektrum STU",
  url = "https://www.svf.stuba.sk/buxus/docs/dokumenty/skripta/2022/Bacigal_T._-_UVOD_DO_ANALYZY_UDAJOV_POMOCOU_R.pdf"
  }

• so systémom pre správu bibliografických zdrojov (reference manager), napríklad Zotero, CiteDrive a JabRef.

Bibliografické metaúdaje o konkrétnych publikáciách sa dajú jednoducho vyhľadať a exportovať pomocou služby Google Scholar.

Citovaný dokument sa zobrazí (v prednastavenom štýle Chicago) na konci dokumentu v samostatnej kapitole ako položka zoznamu:

Bacigál, Tomáš. 2022. Úvod do analýzy údajov pomocou R. Spektrum STU. https://www.svf.stuba.sk/buxus/docs/dokumenty/skripta/2022/Bacigal_T._-_UVOD_DO_ANALYZY_UDAJOV_POMOCOU_R.pdf.

Štýl citácií a zoznamu literatúry sa dá zmeniť v hlavičke YAML voľbou súboru .csl (Citation Style Language) z množstva dostupných.

csl: iso690-author-date-sk.csl

8.7 Výstupné formáty

Quarto zatiaľ neponúka toľko výstupných formátov ako R Markdown, avšak tie, ktoré ponúka, dokážu pokryť väčšinu potrieb svojich užívateľov. Zdrojový súbor môže byť skompilovaný do viacerých formátov, z príkazového riadku OS sa zadáva prepínačom --to, napríklad

quarto render súbor.qmd --to html

nastavenie konkrétneho formátu sa špecifikuje v YAML hlavičke za položkou format. Dajú sa rozdeliť do nasledujúcich skupín:

• dokument HTML (html), PDF (pdf), MS Word (docx), Open Office (odt), ePub (epub), Markdown …,
• prezentácia reveal.js (revealjs, HTML), PowerPoint (pptx, PPTX), Beamer (beamer, PDF),
• webstránka, blog a kniha, ktoré už tvoria komplexnejšie, viacstránkové a viacsúborové projekty.
• “prístrojová doska” (dashboard, HTML)

Všetko, čo sme doteraz preberali, by pri týchto formátoch malo fungovať. V nasledujúcom sa zameriame iba na ich osobitosti.

8.7.1 HTML dokument

Formát HTML je v súčasnosti najpoužívanejší publikačný kontajner. Oproti ostatným má HTML dokument (najmä vďaka javaScript-u) mnoho výhod, napr. nasledujúce (s relevantným nastavením v YAML hlavičke)

• interaktívne prvky ako napr. generované obrázky a tabuľky, alebo citácie a poznámky pod čiarou v tvarte tooltip-u,

• plávajúcu tabuľku obsahu (toc-location),

• CSS štýly (css),

• rôzne systémy na sadzbu matematických výrazov (html-math-method)

• tabsets, čiže niečo ako záložkové sekcie, napr.

  Tab1

  Nejaký text a kód.

  Tab2

  Iný obsah.

• zdielané komentáre cez widget Utterances, Giscus alebo službu Hypothesis.is (comments),

• skrývanie a rozbaľovanie blokov kódu (code-fold), zalamovanie riadkov kódu (code-overflow),

• tématické štýly (pre HTML, CSS a JS knižnicu Bootstrap).

Dokument je štandardne generovaný s externými závislosťami (v adresári s rovnakým názvom), takže ak chceme jediný súbor, ktorý obsahuje všetky prvky HTML vrátane obrázkov, je potrebné to v YAML hlavičke indikovať.

format:
  html:
    embed-resources: true

8.7.2 PDF dokument

Nespornou a najväčšou výhodou PDF (portable document format) je jeho zapuzdrenosť a široká softvérová podpora, čiže je vhodný na jednoduché zdielanie či tlač formátovaného textu a obrázkov. Jeho nevýhodou je komplikovaná editácia a absencia interaktívnych prvkov (ak nepočítame anotácie a formuláre).

Pandoc štandardne na vytvorenie PDF používa typografický systém LaTeX, ktorý je treba vopred nainštalovať. Namiesto komplexných distribúcií ako TeX Live a MikTeX bežnému používateľovi stačí odľahčená verzia TinyTeX, ktorá sa nainštaluje príkazom

quarto install tinytex

v termináli alebo príkazom

tinytex::install_tinytex()    

v konzole prostredia R.

V zdrojovom súbore Quarto funguje väčšina značiek/makier používaných v jazyku LaTeX. Niektoré z tých, čo patria do preambuly majú svoj ekvivalent v YAML špecifikácii formátu, napr.

• documentclass (article, book, report …)
• classoptions (twocolumn, landscape…)
• geometry (top, left, bottom, right, heightrounded)
• papersize (letter, a4 …)
• colorlinks (true, false)

ostatné sa dajú umiestniť ako text za položku include-in-header a podobné.

8.7.3 Prezentácia

Syntax je rovnaká pre všetky výstupné súborové formáty,

• # delí prezentáciu do sekcií,
• ## začína nový slajd s nadpisom
• --- nový slajd bez nadpisu,
• ### nadpis tretej úrovne na tom istom slajde,

pričom toto správanie platí pre prednastavenú úroveň nadpisov slajdov slide-level: 2 (a dá sa zmeniť v YAML).

Položky zoznamu môžu byť odkrývané postupne, čo sa dá zapnúť v YAML položkou tretej úrovne incremental: true globálne alebo zabaliť do prostredia div triedy {.incremental} lokálne (prípadne naopak, označiť zoznam ako neinkrementálny triedou {.nonincremental}). Aj ostatný obsah slajdov sa dá odkrývať postupne, a to pomocou trojice bodiek s medzerami . . . a voľným riadkom pred aj po.

Takisto dvojstĺpcový layout sa (lokálne) dá dosiahnuť prostredím div, ale triedy {.column}.

Nasledujúci príklad dokumentuje tento jednoduchý koncept.

---
title: Moja prvá prezentácia
autor: Ferko Mrkvička
format: revealjs
embed-resources: true
---

## Ráno

::: {.incremental}

- Zazvoní budík
- Vstanem
- Umyjem sa
- Raňajkujem

:::

## Večer

:::: {.columns}

::: {.column width="40%"}
- Umyjem si zuby
- Idem do postele
- Počítam ovečky
:::

::: {.column width="60%"}
![](https://upload.wikimedia.org/wikipedia/commons/thumb/5/58/Sunset_2007-1.jpg/320px-Sunset_2007-1.jpg)
:::

::::

---

Ak nemôžem zaspať, idem sa unaviť čítaním.

. . .

### Beletria

- Pán prsteňov
- Stopárov sprievodca po galaxii

### Odborná literatúra

- Úvod do analýzy údajov v R

```{r}
#| echo: true
Sys.time()
```

Jednotlivé formáty prezentácie potom pridávajú ďalšie funkcie, napríklad Reveal.js ponúka

• zmenšenie písma slajdu globálne smaller: true alebo lokálne {.smaller},
• skrolovateľnosť slajdov s presahujúcim obsahom, globálne scrollable: true alebo lokálne {.scrollable},
• poznámky, ktoré sa zobrazia iba rečníkovi, cez div {.notes},
• poznámky menšieho významu cez div ::: aside
• selektívne zvýraznenie kódu cez nastavenie bloku, napr. #| code-line-numbers: "2-5"
• pozadie slajdu ako farba, obrázok, video alebo externá stránka
• navigačná ponuka a klávesové skratky,
• zmenšený prehľad prezentácie a zoom,
• oddelenie prezentácie od poznámok,
• formátovateľné čísla slajdov,
• export do PDF,
• náhľad externých odkazov,
• automatické prechody, časovanie,
• interaktívna anotácia slajdov,
• multiplex umožňujúci publiku sledovať prezentáciu na vlastnom zariadení,
• a ďalšie

8.7.4 Webstránka a kniha

Webstránka je viacdokumentový formát Quarto, ktorý sa v RStudio zakladá ako projekt. Výsledok obsahuje dynamické prvky moderných webových stránok ako je navigačný panel a vyhľadávacie pole a dá sa jednoducho publikovať v službách ako GitHub Pages, Netlify, Posit Connect a pod.

Kniha je špeciálny typ webstránky a okrem HTML môže byť vytvorená v súborových formátoch PDF, DOCX a ďalších. Je ideálna pre tvorbu zložitejších dokumentov, napr. záverečnej práce bakalárskeho či inžinierskeho štúdia, študijných materiálov a monografií.

8.8 Publikovanie

Najjednoduchší spôsob, ako zverejniť svoje dokumenty a knihy vo formáte HTML na internete, je použit voľne dostupné služby ako GitHub Pages či Quarto Pub. Podrobne je postup popísaný v oficiálnom návode Quarto.

Bacigál, Tomáš. 2022. Úvod do analýzy údajov pomocou R. Spektrum STU. https://www.svf.stuba.sk/buxus/docs/dokumenty/skripta/2022/Bacigal_T._-_UVOD_DO_ANALYZY_UDAJOV_POMOCOU_R.pdf.

Oetiker, Tobias. 1999. Nie príliš stručný úvod do systému LATEX2ε. Preložil Ján ml. a st. Buša. https://www.ptep-online.com/ctan/lshort_slovak.pdf.

Xie, Yihui, Joseph J Allaire, a Garrett Grolemund. 2018. R Markdown: The definitive guide. CRC Press. https://bookdown.org/yihui/rmarkdown/.

Xie, Yihui, Christophe Dervieux, a Emily Riederer. 2020. R Markdown Cookbook. Chapman; Hall/CRC. https://bookdown.org/yihui/rmarkdown-cookbook/.

---

1. Myšlienku dokumentovaného programovania (literate programming) medzi prvými systematicky rozpracoval D.E. Knuth v rovnomennej publikácii. Vystihuje ju autorov citát: “Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.”

2. Slovo LaTeX sa číta [latech].

3. Spôsobom, ktorý zaviedol balík roxygen2. Pomocou neho sa vďaka špeciálne formátovaným komentárom dá ľahko generovať dokumentácia ku vlastným balíkom – v zhode s oficiálnou špecifikáciou systému R.

4. Prečo vlastne by sme mali používať nejaký značkovací jazyk, keď sme už roky zvyknutí na MS Word, v ktorom všetko napísané má už napohľad finálne formátovanie (tzv. WYSIWYG, “what you see is what you get”)? Pretože písanie textu vo Worde je vhodné predovšetkým pre počítačovo menej zdatných používateľov, a pre komplexnejšie úlohy je nevýhodné. Transparentnejšou cestou je značkovanie textu, t.j. doplnenie obyčajného textu o značky, ktoré určujú, ako bude text vyzerať. Niektoré značkovacie jazyky ako HTML sú dosť “krikľavé”, iné ako napr. Markdown sú subtílnejšie. Výhod značkovacích jazykov je veľa: sú ľahšie prenosné medzi počítačmi, menej viazané na konkrétne softvérové spoločnosti, a v čase stabilnejšie než WYSIWYG textové procesory.

5. Avšak odporúča sa aktualizovať na najnovšiu stabilnú verziu dostupnú na oficiálnej stránke.

6. Poznámka pod čiarou.

7. Prostredia div a span sú objekty, ktorým sa dá definovať hierarchický systém tried, takže ich vlastnosti je potom možné definovať na jednom mieste, napr. v YAML hlavičke alebo v CSS súbore.

8. Prostredím „názov” sa tu rozumie obalujúca dvojica \begin{názov} a \end{názov}.

9. Rekurzívny akronym “YAML Ain’t Markup Language”, teda v preklade “YAML nie je značkovací jazyk”.

10. Okrem príkladov môže pri vytváraní bibliografického záznamu z populárneho formátu BibTeX pomôcť konverter pandoc alebo funkcia ymlthis::bib2yml.