install.packages('tinytex')
tinytex::install_tinytex() # install TinyTeX16 R Markdown и Quarto
И.С. Поздняков 
16.1 Что такое R Markdown
После подсчета описательных статистик, создания графиков и, в особенности, интерактивных визуализаций, возникает вопрос о том, как представить полученные результаты.
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)
Формат вывода легко настроить и поменять по ходу работы, что позволяет гибко изменять формат документа на выходе.
16.2 Начало работы в R Markdown
Для работы с R Markdown у RStudio есть специальные инструменты, которые позволяют не только удобно писать и компилировать R Markdown документы, но и превращают R Markdown в удобную среду для работы с R вместо обычных R-скриптов.
Чтобы начать работать с R Markdown, нужно создать новый .Rmd файл с помощью File - New File - R Markdown... Перед вами появится меню выбора формата R Markdown документа, названия и имени автора.
Выбирайте что угодно, все это можно потом изменить вручную.
Если пакет rmarkdown у вас еще не установлен, то он будет автоматически установлен. Кроме того, если вы выбрали в качестве формата PDF (презентацию или документ), то вам понадобится еще установить LaTeX на компьютер. Это тоже можно сделать с помощью специального пакета:
.Rmd файл, который вы создадите таким образом, будет создан из шаблона, который демонстрирует основной функционал R Markdown. В отличие от работы с R скриптом, перед вами будет немного другой набор кнопок. Самая важная из новых кнопок — это кнопка Knit (с клубком и спицей рядом), нажав на которую, начнется “вязание” (knitting) финального документа, то есть его компиляция. Если компиляция завершится успешно, то перед вами появится скомпилированный документ в том формате, который вы выбрали.
16.3 Структура R Markdown документа
R Markdown документ состоит из трех базовых элементов:
- YAML-шапки 1
- Текста с использованием разметки Markdown
- Чанков (chunks) с кодом
Разберем их по порядку.
- YAML-шапка находится в самом верху документа и отделена тремя дефисами (
---) сверху и снизу. В нем содержится, во-первых, мета-информация о документе, которая будет отображена на титульном листе/слайде, во-вторых, информация о формате документа, который будет “связан”. Пример YAML-шапки:
---
title: "Классное название для документа"
author: "Поздняков Иван"
date: "15 11 2020"
output: html_document
---- Текст с использование синтаксиса Markdown идет сразу после YAML-шапки и составляет основную часть .Rmd документа. Markdown (не путать с R Markdown!) — это популярный и очень удобный язык разметки. Markdown используется повсюду: в ReadMe страницах на GitHub, как способ ведения записей во многих программах для заметок и даже в Telegram! Например, вот так можно задавать полужирный шрифт и курсив:
Вот так мы делаем **полужирный**, а вот так мы делаем *курсив.*В результате мы получим следующую строчку:
Вот так мы делаем полужирный, а вот так мы делаем курсив.
Далее мы разберем подробнее синтаксис Markdown.
- Чанки с кодом содержат в себе код на языке R или другом языке программирования, которые будут исполнены, а результат которых будет отображен прямо под чанком с кодом. Чанк с кодом отделяется ``` с обоих сторон и содержит
{r}. Это означает, что внутри находится код на R, который должен быть выполнен:
```{r}
2+2
```В итоговом документе чанк будет выглядеть так:
2+2[1] 416.4 Настройки чанка
У чанка с кодом есть набор настроек. Самый важные из них такие:
echo: будет ли показан сам код
message и warning: будут ли показаны сообщения и предупреждения, всплывающие во время исполнения кода
eval: будет ли испольняться код внутри чанка
16.4.1 Настройка нескольких чанков
Все эти настройки можно настроить как для отдельных чанков, так и для все чанков сразу:
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)Этот чанк нужно вставлять в начале .Rmd документа, тогда выбранные настройки повлияют на все последующие чанки.
16.4.2 Чанки с Python и другими языками программирования
Можно вставлять чанки с кодом на других языках программирования! Для этого вместо {r} нужно написать {python}.
x = 'hello, python !'
print (x.split(" "))Вот полный список поддерживаемых языков:
names(knitr::knit_engines$get()) [1] "awk" "bash" "coffee" "gawk" "groovy" "haskell"
[7] "lein" "mysql" "node" "octave" "perl" "php"
[13] "psql" "Rscript" "ruby" "sas" "scala" "sed"
[19] "sh" "stata" "zsh" "asis" "asy" "block"
[25] "block2" "bslib" "c" "cat" "cc" "comment"
[31] "css" "ditaa" "dot" "embed" "eviews" "exec"
[37] "fortran" "fortran95" "go" "highlight" "js" "julia"
[43] "python" "R" "Rcpp" "sass" "scss" "sql"
[49] "stan" "targets" "tikz" "verbatim" "ojs" "mermaid"
[55] "include" 16.4.3 Код вне чанков (inline code)
Иногда хочется вставить результат расчетов прямо в текст. Для этого нужно поставить символ ` с обоих краев команды и написать r перед самой командой. В этом случае результат выполнения этой команды будет в тексте вместо этой конструкции.
Число пи равно ` r pi `:
Число пи равно 3.1415927
16.5 Синтаксис Markdown (без R)
В RStudio есть подсказка по синтаксису Markdown, для ее вызова нужно нажать Help - Markdown Quick Reference
16.5.1 Выделение текста
Выделение текста происходит с помощью обособления текста специальными символами:
*Курсив*
_Тоже курсив_
**Полужирный**
__Тоже полужирный__
~~перечеркнутый~~
индекс^надстрочный^
индекс~подстрочный~Курсив Тоже курсив Полужирный Тоже полужирный перечеркнутый индекснадстрочный индексподстрочный
16.5.2 Заголовки разных уровней
С помощью решенточек (#) выделяются заголовки разных уровней.
# Самый верхний заголовок
## Заголовок второго уровня
### Мне заголовок
#### И моему сыну тоже
##### И моему!
###### Все, дальше опускаться некуда16.5.3 Списки
Списки можно создавать по-разному, в зависимости от того, является ли список пронумерованным:
* Первый вариант списка выглядит так:
+ Можно и с подсписком
+ Почему бы и нет?
1. Кому нужен порядок
2. Тот списки номерует- Первый вариант списка выглядит так:
- Можно и с подсписком
- Почему бы и нет?
- Кому нужен порядок
- Тот списки номерует
16.5.4 Цитаты
Цитаты выделяются с помощью знака > в начале строки.
> Я устал
> Который год во мне живет нарвалЯ устал
Который год во мне живет нарвал
16.5.5 Таблицы
Табличные данные имеют особое значение в R, в R Markdown им тоже уделяется особое внимание.
Для начала подгрузим данные о супергероях:
library("tidyverse")
heroes <- read_csv("https://raw.githubusercontent.com/Pozdniakov/tidy_stats/master/data/heroes_information.csv",
na = c("-", "-99"))Функция knitr::kable() превращает табличные данные (матрицы, датафреймы) в текст, отформатированный как Markdown-таблицы. Таким образом, вот такая таблица:
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, то для этого есть специальный ресурс.
Пакет knitr является ключевым для R Markdown, поэтому он устанавливается вместе с rmarkdown. А вот для дополнительной настройки вывода таблиц рекомендуется пакет kableExtra.
16.6 Дополнительные возможности R Markdown
16.6.1 Динамические таблицы
Один из самых интересных HTML-виджетов (@ref(htmlwidgets)) — пакет DT для создания интерактивных таблиц прямо внутри HTML-документа.
library(tidyverse)
heroes <- read_csv("https://raw.githubusercontent.com/Pozdniakov/tidy_stats/master/data/heroes_information.csv",
na = c("-", "-99"))
DT::datatable(heroes)16.6.2 Графики в R Markdown
Все создаваемые графики будут появляться под чанком с кодом.
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.
library(plotly)
ggplotly(height_weight_gg)Конечно, чтобы эта интерактивность сохранилась, используемый формат итогового документа должен ее поддерживать. Word-документы, так же как и PDF-документы, — статичны, поэтому единственный вариант сохранить интерактивные элементы — это использование HTML-документов или HTML-презентаций.
16.6.3 HTML-код
Если вы выбрали HTML форматом итогового документа, то можете использовать все его фишки, включая форматирование с помощью HTML-тегов (в дополнение к обычному Markdown). Еще вы можете вставлять куски HTML-кода, например, вставить видео с YouTube или отдельный пост из Twitter.
<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>16.7 Quarto
Quarto – это следующая итерация развития R Markdown, которая пытается выйти за пределы его ограничений и стать более универсальным инструментом, не привязанным к R. Quarto позволяет использовать как {knitr}, который лежит в основе R Markdown, так и Jupyter Notebooks, Julia и Observable JS. Quarto имеет свой дополнительный синтаксис, но так же будет работать со всеми фишками R Markdown, которые были описаны выше. В частности, данная книга была изначально написана с помощью R Markdown и была переведена в Quarto почти без каких-либо дополнительных усилий кроме переименования файлов.
YAML расшифровывается как “YAML Ain’t Markup Language”, ранее — как Yet Another Markup Language. Связано это с тем, что сначала этот язык позиционировался как язык разметки (например, HTML), затем — как язык сериализации, т.е. хранения данных (как JSON).↩︎