11 R Markdown
11.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)
Формат вывода легко настроить и поменять по ходу работы, что позволяет гибко изменять формат документа на выходе.
11.2 Начало работы в R Markdown
Для работы с R Markdown у RStudio есть специальные инструменты, которые позволяют не только удобно писать и компилировать R Markdown документы, но и превращают R Markdown в удобную среду для работы с R вместо обычных R-скриптов.
Чтобы начать работать с R Markdown, нужно создать новый .Rmd файл с помощью File - New File - R Markdown... Перед вами появится меню выбора формата R Markdown документа, названия и имени автора.
Меню выбора формата R Markdown документа
Выбирайте что угодно, все это можно потом изменить вручную.
Если пакет rmarkdown у вас еще не установлен, то он будет автоматически установлен. Кроме того, если вы выбрали в качестве формата PDF (презентацию или документ), то вам понадобится еще установить LaTeX на компьютер. Это тоже можно сделать с помощью специального пакета:
install.packages('tinytex')
tinytex::install_tinytex() # install TinyTeX.Rmd файл, который вы создадите таким образом, будет создан из шаблона, который демонстрирует основной функционал R Markdown. В отличие от работы с R скриптом, перед вами будет немного другой набор кнопок. Самая важная из новых кнопок — это кнопка Knit (с клубком и спицей рядом), нажав на которую, начнется “вязание” (knitting) финального документа, то есть его компиляция. Если компиляция завершится успешно, то перед вами появится скомпилированный документ в том формате, который вы выбрали.
11.3 Структура R Markdown документа
R Markdown документ состоит из трех базовых элементов:
- YAML-шапки32
- Текста с использованием разметки 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] 411.4 Настройки чанка
У чанка с кодом есть набор настроек. Самый важные из них такие:
echo: будет ли показан сам код
message и warning: будут ли показаны сообщения и предупреждения, всплывающие во время исполнения кода
eval: будет ли испольняться код внутри чанка
11.4.1 Настройка нескольких чанков
Все эти настройки можно настроить как для отдельных чанков, так и для все чанков сразу:
knitr::opts_chunk$set(echo = TRUE, message = FALSE, warning = FALSE)Этот чанк нужно вставлять в начале .Rmd документа, тогда выбранные настройки повлияют на все последующие чанки.
11.4.2 Чанки с Python и другими языками программирования
Можно вставлять чанки с кодом на других языках программирования! Для этого вместо {r} нужно написать {python}.
x = 'hello, python !'
print (x.split(" "))## ['hello,', 'python', '!']Вот полный список поддерживаемых языков:
names(knitr::knit_engines$get())## [1] "awk" "bash" "coffee" "gawk" "groovy"
## [6] "haskell" "lein" "mysql" "node" "octave"
## [11] "perl" "psql" "Rscript" "ruby" "sas"
## [16] "scala" "sed" "sh" "stata" "zsh"
## [21] "highlight" "Rcpp" "tikz" "dot" "c"
## [26] "cc" "fortran" "fortran95" "asy" "cat"
## [31] "asis" "stan" "block" "block2" "js"
## [36] "css" "sql" "go" "python" "julia"
## [41] "sass" "scss" "theorem" "lemma" "corollary"
## [46] "proposition" "conjecture" "definition" "example" "exercise"
## [51] "proof" "remark" "solution"11.4.3 Код вне чанков (inline code)
Иногда хочется вставить результат расчетов прямо в текст. Для этого нужно поставить символ ` с обоих краев команды и написать r перед самой командой. В этом случае результат выполнения этой команды будет в тексте вместо этой конструкции.
Число пи равно ` r pi `:
Число пи равно 3.1415927
11.5 Синтаксис Markdown (без R)
В RStudio есть подсказка по синтаксису Markdown, для ее вызова нужно нажать Help - Markdown Quick Reference
11.5.1 Выделение текста
Выделение текста происходит с помощью обособления текста специальными символами:
*Курсив*
_Тоже курсив_
**Полужирный**
__Тоже полужирный__
~~перечеркнутый~~
индекс^надстрочный^
индекс~подстрочный~Курсив
Тоже курсив
Полужирный
Тоже полужирный
перечеркнутый
индекснадстрочный
индексподстрочный
11.5.2 Заголовки разных уровней
С помощью решенточек (#) выделяются заголовки разных уровней.
# Самый верхний заголовок
## Заголовок второго уровня
### Мне заголовок
#### И моему сыну тоже
##### И моему!
###### Все, дальше опускаться некуда
11.5.3 Списки
Списки можно создавать по-разному, в зависимости от того, является ли список пронумерованным:
* Первый вариант списка выглядит так:
+ Можно и с подсписком
+ Почему бы и нет?
1. Кому нужен порядок
2. Тот списки номерует- Первый вариант списка выглядит так:
- Можно и с подсписком
- Почему бы и нет?
- Кому нужен порядок
- Тот списки номерует
11.5.4 Цитаты
Цитаты выделяются с помощью знака > в начале строки.
> Я устал
> Который год во мне живет нарвалЯ устал
Который год во мне живет нарвал
11.5.5 Таблицы
Табличные данные имеют особое значение в R, в R Markdown им тоже уделяется особое внимание. Функция 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.
11.6 Дополнительные возможности R Markdown
11.6.1 Динамические таблицы
Один из самых интересных HTML-виджетов (??) — пакет DT для создания интерактивных таблиц прямо внутри HTML-документа.
DT::datatable(heroes)11.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-виджетов (??), например, plotly.
library(plotly)
ggplotly(height_weight_gg)Конечно, чтобы эта интерактивность сохранилась, используемый формат итогового документа должен ее поддерживать. Word-документы, так же как и PDF-документы, — статичны, поэтому единственный вариант сохранить интерактивные элементы — это использование HTML-документов или HTML-презентаций.
11.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>YAML расшифровывается как “YAML Ain’t Markup Language”, ранее — как Yet Another Markup Language. Связано это с тем, что сначала этот язык позиционировался как язык разметки (например, HTML), затем — как язык сериализации, т.е. хранения данных (как JSON).↩︎