250-rmarkdown.qmd

# R Markdown и Quarto {#sec-rmd}

## Что такое R Markdown {#sec-rmd_what}

После подсчета описательных статистик, создания графиков и, в особенности, интерактивных визуализаций, возникает вопрос о том, как представить полученные результаты.

R Markdown представляет такую возможность. С помощью R Markdown в документе можно совмещать код, результаты его исполнения и написанный текст. Кроме того, можно вставлять картинки, ссылки, видео и многое другое. В чем-то R Markdown напоминает Jupyter Notebook знакомый всем питоноводом, но это сходство, скорее, функциональное (и то, и то позволяет превращать сухой текст скрипта в красивый документ), их устройство значительно различается.

R Markdown представляет собой текстовый документ специального формата .Rmd, который можно скомпилировать в самые различные документы:

-   Документы в форматах Word, ODT, RTF, PDF (с использованием LaTeX), HTML, в том числе:

    -   Онлайн-книги (bookdown)
    -   Научные статьи (papaja)

-   Презентации в виде HTML (ioslides, Slidy, revealjs, rmdshower, Beamer)

-   Веб-сайты (blogdown)

-   Дашборды (flexdashboard)

Формат вывода легко настроить и поменять по ходу работы, что позволяет гибко изменять формат документа на выходе.

## Начало работы в R Markdown {#sec-rmd_begin}

Для работы с R Markdown у RStudio есть специальные инструменты, которые позволяют не только удобно писать и компилировать R Markdown документы, но и превращают R Markdown в удобную среду для работы с R вместо обычных R-скриптов.

Чтобы начать работать с R Markdown, нужно создать новый .Rmd файл с помощью `File - New File - R Markdown..`. Перед вами появится меню выбора формата R Markdown документа, названия и имени автора.

![Меню выбора формата R Markdown документа](images/rmd_choose.png){width="400"}

Выбирайте что угодно, все это можно потом изменить вручную.

Если пакет `rmarkdown` у вас еще не установлен, то он будет автоматически установлен. Кроме того, если вы выбрали в качестве формата PDF (презентацию или документ), то вам понадобится еще установить LaTeX на компьютер. Это тоже можно сделать с помощью специального пакета:

```{r, eval = FALSE}
install.packages('tinytex')
tinytex::install_tinytex()  # install TinyTeX
```

.Rmd файл, который вы создадите таким образом, будет создан из шаблона, который демонстрирует основной функционал R Markdown. В отличие от работы с R скриптом, перед вами будет немного другой набор кнопок. Самая важная из новых кнопок --- это кнопка `Knit` (с клубком и спицей рядом), нажав на которую, начнется "вязание" (knitting) финального документа, то есть его компиляция. Если компиляция завершится успешно, то перед вами появится скомпилированный документ в том формате, который вы выбрали.

## Структура R Markdown документа {#sec-rmd_str}

R Markdown документ состоит из трех базовых элементов:

-   YAML-шапки [^250-rmarkdown-1]
-   Текста с использованием разметки Markdown
-   **Чанков (chunks)** с кодом

[^250-rmarkdown-1]: YAML расшифровывается как *"YAML Ain't Markup Language"*, ранее --- как *Yet Another Markup Language*. Связано это с тем, что сначала этот язык позиционировался как язык разметки (например, HTML), затем --- как язык сериализации, т.е. хранения данных (как JSON).

Разберем их по порядку.

1)  **YAML-шапка** находится в самом верху документа и отделена тремя дефисами (`---`) сверху и снизу. В нем содержится, во-первых, мета-информация о документе, которая будет отображена на титульном листе/слайде, во-вторых, информация о формате документа, который будет "связан". Пример YAML-шапки:

<!-- -->

```         
---
title: "Классное название для документа"
author: "Поздняков Иван"
date: "15 11 2020"
output: html_document
---
```

2)  **Текст с использование синтаксиса Markdown** идет сразу после YAML-шапки и составляет основную часть .Rmd документа. Markdown (не путать с R Markdown!) --- это популярный и очень удобный язык разметки. Markdown используется повсюду: в ReadMe страницах на GitHub, как способ ведения записей во многих программах для заметок и даже в Telegram! Например, вот так можно задавать полужирный шрифт и курсив:

<!-- -->

```         
Вот так мы делаем **полужирный**, а вот так мы делаем *курсив.*
```

В результате мы получим следующую строчку:

Вот так мы делаем **полужирный**, а вот так мы делаем *курсив.*

Далее мы разберем подробнее синтаксис Markdown.

3)  **Чанки с кодом** содержат в себе код на языке R или другом языке программирования, которые будут исполнены, а результат которых будет отображен прямо под чанком с кодом. Чанк с кодом отделяется \`\`\` с обоих сторон и содержит `{r}`. Это означает, что внутри находится код на R, который должен быть выполнен:

```` markdown
`r ''````{r}
2+2
```
````

В итоговом документе чанк будет выглядеть так:

```{r}
2+2
```

## Настройки чанка {#sec-chunk}

У чанка с кодом есть набор настроек. Самый важные из них такие:

-   *echo*: будет ли показан сам код

-   *message* и *warning*: будут ли показаны сообщения и предупреждения, всплывающие во время исполнения кода

-   *eval*: будет ли испольняться код внутри чанка

### Настройка нескольких чанков {#sec-chunks}

Все эти настройки можно настроить как для отдельных чанков, так и для все чанков сразу:

```{r setup2}
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)
```

Этот чанк нужно вставлять в начале .Rmd документа, тогда выбранные настройки повлияют на все последующие чанки.

### Чанки с Python и другими языками программирования {#sec-python}

Можно вставлять чанки с кодом на других языках программирования! Для этого вместо {r} нужно написать {python}.

```{python, eval=FALSE}
x = 'hello, python !'
print (x.split(" "))
```

Вот полный список поддерживаемых языков:

```{r}
names(knitr::knit_engines$get())
```

### Код вне чанков (inline code) {#sec-inline}

Иногда хочется вставить результат расчетов прямо в текст. Для этого нужно поставить символ \` с обоих краев команды и написать r перед самой командой. В этом случае результат выполнения этой команды будет в тексте вместо этой конструкции.

Число пи равно \` r pi \`:

`` Число пи равно `r pi` ``

## Синтаксис Markdown (без R) {#sec-md}

В RStudio есть подсказка по синтаксису Markdown, для ее вызова нужно нажать `Help - Markdown Quick Reference`

### Выделение текста {#sec-md_high}

Выделение текста происходит с помощью обособления текста специальными символами:

```         
*Курсив* 
_Тоже курсив_
**Полужирный**
__Тоже полужирный__
~~перечеркнутый~~
индекс^надстрочный^
индекс~подстрочный~
```

*Курсив* *Тоже курсив* **Полужирный** **Тоже полужирный** ~~перечеркнутый~~ индекс^надстрочный^ индекс~подстрочный~

### Заголовки разных уровней {#sec-headers}

С помощью решенточек (`#`) выделяются заголовки разных уровней.

```         
# Самый верхний заголовок

## Заголовок второго уровня

### Мне заголовок

#### И моему сыну тоже

##### И моему!

###### Все, дальше опускаться некуда
```

### Списки {#sec-md_lists}

Списки можно создавать по-разному, в зависимости от того, является ли список пронумерованным:

```         
* Первый вариант списка выглядит так:  
    + Можно и с подсписком
    + Почему бы и нет?

1. Кому нужен порядок
2. Тот списки номерует
```

-   Первый вариант списка выглядит так:
    -   Можно и с подсписком
    -   Почему бы и нет?

1.  Кому нужен порядок
2.  Тот списки номерует

### Цитаты {#sec-md_cite}

Цитаты выделяются с помощью знака `>` в начале строки.

```         
> Я устал  
> Который год во мне живет нарвал
```

> Я устал\
> Который год во мне живет нарвал

### Таблицы {#sec-rmd_tables}

Табличные данные имеют особое значение в R, в R Markdown им тоже уделяется особое внимание.

Для начала подгрузим данные о супергероях:

```{r}
library("tidyverse")
heroes <- read_csv("https://raw.githubusercontent.com/Pozdniakov/tidy_stats/master/data/heroes_information.csv",
                   na = c("-", "-99"))
```

Функция `knitr::kable()` превращает табличные данные (матрицы, датафреймы) в текст, отформатированный как Markdown-таблицы. Таким образом, вот такая таблица:

```{r, eval = FALSE}
knitr::kable(heroes[1:3, 1:4])
```

Превращается вот в такую, отформатированную с помощью символов `-`, `|` и т.п.:

```         
| X1|name       |Gender |Eye color |
|--:|:----------|:------|:---------|
|  0|A-Bomb     |Male   |yellow    |
|  1|Abe Sapien |Male   |blue      |
|  2|Abin Sur   |Male   |blue      |
```

А эта таблица, в свою очередь, превращается в такую в финальном документе:

|  X1 | name       | Gender | Eye color |
|----:|:-----------|:-------|:----------|
|   0 | A-Bomb     | Male   | yellow    |
|   1 | Abe Sapien | Male   | blue      |
|   2 | Abin Sur   | Male   | blue      |

Если вам нужно самостоятельно отформатировать таблицу в Markdown, то для этого есть [специальный ресурс](https://www.tablesgenerator.com/markdown_tables).

Пакет `knitr` является ключевым для R Markdown, поэтому он устанавливается вместе с `rmarkdown`. А вот для дополнительной настройки вывода таблиц рекомендуется пакет `kableExtra`.

## Дополнительные возможности R Markdown {#sec-extra_rmd}

### Динамические таблицы {#sec-dynamic_tables}

Один из самых интересных HTML-виджетов (\@ref(htmlwidgets)) --- пакет `DT` для создания интерактивных таблиц прямо внутри HTML-документа.

```{r}
library(tidyverse)
heroes <- read_csv("https://raw.githubusercontent.com/Pozdniakov/tidy_stats/master/data/heroes_information.csv",
                   na = c("-", "-99"))
DT::datatable(heroes)
```

### Графики в R Markdown {#sec-vis}

Все создаваемые графики будут появляться под чанком с кодом.

```{r}
height_weight_gg <- heroes %>%
  mutate(Publisher = ifelse(Publisher %in% c("Marvel Comics", "DC Comics"), 
                            Publisher,
                            "Other publishers")) %>%
  filter(Weight < 700 & Height < 400) %>%
  ggplot(aes(x = Height, y = Weight)) +
  geom_point(aes(colour = Gender), alpha = 0.5) +
  coord_fixed() +
  facet_wrap(~Publisher)+
  theme_minimal()
height_weight_gg
```

Это так же относится и к динамическим визуализациям с помощью HTML-виджетов (\@ref(htmlwidgets)), например, `plotly`.

```{r}
library(plotly)
ggplotly(height_weight_gg)
```

Конечно, чтобы эта интерактивность сохранилась, используемый формат итогового документа должен ее поддерживать. Word-документы, так же как и PDF-документы, --- статичны, поэтому единственный вариант сохранить интерактивные элементы --- это использование HTML-документов или HTML-презентаций.

### HTML-код {#sec-html_inside}

Если вы выбрали HTML форматом итогового документа, то можете использовать все его фишки, включая форматирование с помощью HTML-тегов (в дополнение к обычному Markdown). Еще вы можете вставлять куски HTML-кода, например, вставить видео с YouTube или отдельный пост из Twitter.

```{r, echo = FALSE, results = 'asis'}
if (knitr:::is_latex_output()) {
  cat("\n\nК сожалению, в PDF нельзя вставить никакой интерактивности, смотрите онлайн-версию книги)")
} else {
  cat('\n\n     <iframe width="560" height="315" src="https://www.youtube.com/embed/5qap5aO4i9A" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

    <iframe width="560" height="315" src="https://www.youtube.com/embed/5qap5aO4i9A" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>') 
}
```

## Quarto {#sec-quarto}

*Quarto* -- это следующая итерация развития *R Markdown*, которая пытается выйти за пределы его ограничений и стать более универсальным инструментом, не привязанным к R. *Quarto* позволяет использовать как `{knitr}`, который лежит в основе *R Markdown*, так и Jupyter Notebooks, Julia и Observable JS. Quarto имеет свой дополнительный синтаксис, но так же будет работать со всеми фишками R Markdown, которые были описаны выше. В частности, данная книга была изначально написана с помощью R Markdown и была переведена в Quarto почти без каких-либо дополнительных усилий кроме переименования файлов.