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) с кодом

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

  1. YAML-шапка находится в самом верху документа и отделена тремя дефисами (---) сверху и снизу. В нем содержится, во-первых, мета-информация о документе, которая будет отображена на титульном листе/слайде, во-вторых, информация о формате документа, который будет “связан.” Пример YAML-шапки:
---
title: "Классное название для документа"
author: "Поздняков Иван"
date: "15 11 2020"
output: html_document
---
  1. Текст с использование синтаксиса Markdown идет сразу после YAML-шапки и составляет основную часть .Rmd документа. Markdown (не путать с R Markdown!) — это популярный и очень удобный язык разметки. Markdown используется повсюду: в ReadMe страницах на GitHub, как способ ведения записей во многих программах для заметок и даже в Telegram! Например, вот так можно задавать полужирный шрифт и курсив:
Вот так мы делаем **полужирный**, а вот так мы делаем *курсив.*

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

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

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

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

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

2+2
## [1] 4

11.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. Тот списки номерует
  • Первый вариант списка выглядит так:
    • Можно и с подсписком
    • Почему бы и нет?
  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>

  1. YAML расшифровывается как “YAML Ain’t Markup Language”, ранее — как Yet Another Markup Language. Связано это с тем, что сначала этот язык позиционировался как язык разметки (например, HTML), затем — как язык сериализации, т.е. хранения данных (как JSON).↩︎