Еще не прошло и двух лет, как Илья Щуров сказал мне про RMarkdown. С тех пор и не счесть, сколько всего я этим пакетом сделал. Лучше места и повода поблагодарить Илью, наверное, не найти.

0 Установите rmarkdown

install.packages("rmarkdown")

1 Первый R markdown

1.2 Составляющие R markdown

  • yaml шапка (факультативна)
  • обычный текст с markdown форматированием (расширенный при помощи Pandoc)
  • фрагменты кода (не обязательно на языке R)

1.1 Пример R markdown

Создайте файл .Rmd в какой-нибудь папке. Скомпелировать файл можно командой:

rmarkdown::render("ваш_файл.Rmd")

или кнопочкой Knit.

code

---
output: html_document
---

## Данные
В документе можно вставлять R код

```{r}
summary(iris)
```

## График
И строить графики

```{r}
plot(iris$Sepal.Length)
```

result

2 Markdown

Универсальны язык разметки, работает во многих современных он-лайн системах создания текста.

2.1 Заголовки

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

2.2 Форматирование

_италик_ или *другой италик*

__жирный__ или **другой жирный**

~~зачеркивание~~

италик или другой италик

жирный или другой жирный

зачеркивание

2.3 Списки

* кролик
* заяц
    * заяц серый

1. машины
    1. автобус
2. самолеты

+ можно еще ставить плюс
- и минус
  • кролик
  • заяц
    • заяц серый
  1. машины
    1. автобус
  2. самолеты
  • можно еще ставить плюс
  • и минус

2.4 Ссылки и картинки

[Ссылка 1](https://agricolamz.github.io/2018_ANDAN_course_winter/2_ex.html)

<https://agricolamz.github.io/2018_ANDAN_course_winter/2_ex.html>

[Можно вставить ссылку потом, а пока отсавить метку][1]

Или даже просто голую [метку].

![](https://raw.githubusercontent.com/agricolamz/2018_ANDAN_course_winter/master/rmarkdown.png)

Опять же можно вставить только метку ![][2]

[1]: https://agricolamz.github.io/2018_ANDAN_course_winter/2_ex.html
[метку]: https://agricolamz.github.io/2018_ANDAN_course_winter/2_ex.html
[2]: https://raw.githubusercontent.com/agricolamz/2018_ANDAN_course_winter/master/rmarkdown.png

Ссылка 1

https://agricolamz.github.io/2018_ANDAN_course_winter/2_ex.html

Можно вставить ссылку потом, а пока отсавить метку

Или даже просто голую метку.

Опять же можно вставить только метку

2.5 Код

Код нужно оформалять вот так `rmarkdown::render()`

Код нужно оформалять вот так rmarkdown::render()

```{python}
friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
    print "iteration {iteration} is {name}".format(iteration=i, name=name)
```
friends = ['john', 'pat', 'gary', 'michael']
for i, name in enumerate(friends):
    print "iteration {iteration} is {name}".format(iteration=i, name=name)
iteration 0 is john
iteration 1 is pat
iteration 2 is gary
iteration 3 is michael

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

2.6 Цитаты

> Цитаты нужно офрмлять так.
> Это попадет в тот же фрагмент.

> А вот тут произошел разрыв. Кстати, здесь тоже можно использовать *markdown*.

Цитаты нужно офрмлять так. Это попадет в тот же фрагмент.

А вот тут произошел разрыв. Кстати, здесь тоже можно использовать markdown.

2.7 Разрыв страницы

***

2.8 HTML

<dl>
  <dt>Чистый HTML</dt>
  <dd>Еще можно писать в HTML.</dd>

  <dt>и Markdown в  HTML </dt>
  <dd> даже работает **правильно**. Но можно использовать и <em>теги</em>.</dd>
</dl>
Чистый HTML
Еще можно писать в HTML.
и Markdown в HTML
даже работает правильно. Но можно использовать и теги.

2.9 Таблицы

Еще есть целая наука как делать таблицы в Markdown, но я предпочитаю использовать он-лайн генератор.

3 Pandoc

Pandoc это программа, созданная Дж. МакФарлэйном (J. MacFarlane), которая позволяет переходить из разных текстовых форматов в другие, а также смешивать их. Я покожу лишь несколько полезных расширений.

3.1 Верхние и нижние индексы

2^10^ C~n~^k^

210 Cnk

3.2 Нумерованные примеры

(@) Славный пример номер раз.
(@) Славный пример номер два.
(@three) Славный пример номер три, у которого есть *имя*.

Я могу сослаться на пример (@three)!
  1. Славный пример номер раз.
  2. Славный пример номер два.
  3. Славный пример номер три, у которого есть имя.

Я могу сослаться на пример (3)!

3.3 Сноски

Вот и сноска[^1]

[^1]: Сноска, сноска, сноска.

Вот и сноска1

3.4 Математика: \(\LaTeX\)

$\LaTeX$  код может быть в тексте $\frac{\pi}{\sum{n+1}}$ или отдельной строчкой:

$$\frac{\pi}{\sum{n+1}}$$

\(\LaTeX\) код может быть в тексте \(\frac{\pi}{\sum{n+1}}\) или отдельной строчкой:

\[\frac{\pi}{\sum{n+1}}\]

4 Code chunks

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

4.1 Язык программирования

code

```{r}
summary(cars)
```

```{bash}
mkdir my_new_folder
ls
rm -d my_new_folder
```

```{python}
x = "my string"
print(x.split(" "))
```

result

4.2 Появление и исполнение кода

code

И код, и результат
```{r}
plot(mtcars$mpg)
```

Только результат
```{r, echo = FALSE}
plot(mtcars$mpg)
```

Только код
```{r, eval = FALSE}
plot(mtcars$mpg)
```

Исполняется, но не показывается ни код, ни результат
```{r, include = FALSE}
a <- mtcars$mpg
```

Обратимся к переменной, созданной в фрагменте с аргументом `include = FALSE`
```{r}
a
```

result

4.3 Другие полезные аргументы

Существует достаточно много аргументов, которые можно перечислить в фигурных скобках в фрагменте кода, вот некоторые из них:

  • error: показывать ли ошибки.
  • warning: показывать ли предупреждения.
  • message: показывать ли сообщения (например, при подключении пакетов).
  • comment: по умолчанию, результат работы кода предваряется знаком ##, используйте NA, чтобы их не было, или любую другую строку.
  • cache: сохранить ли результат работы фрагмента кода. Очень полезно, если происходят какие-то операции, занимающая много времени. Сохранив результат, не нужно будет тратить время, на пересчет, при каждой новой компиляции.
  • fig.width, fig.height (по умолчанию, 7)

Все эти аргументы можно перечислить в функции knitr::opts_chunk$set(...):

code

```{r, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, message = FALSE, fig.height = 3)
```

Первый фрагмент

```{r}
library(tidyverse)
diamonds %>% 
  count(carat, color) %>%
  ggplot(aes(carat, n, color = color))+
  geom_point()
```

Второй фрагмент

```{r}
diamonds %>% 
  count(cut, color) %>%
  ggplot(aes(cut, n, color = color))+
  geom_point()
```

result

4.4 Pets or livestock?

В RMarkdown каждому фрагменту кода можно дать имя (но избегайте пробелов и точек):

```{r my_beautiful_graph, eval = FALSE}
library(tidyverse)
diamonds %>% 
  count(carat, color) %>%
  ggplot(aes(carat, n, color = color))+
  geom_point()
```

Maëlle Salmon написал отличный пост, почему полезно именовать фрагменты кода:

  • проще ориентироваться
  • код более читаемый
  • ошибки при компеляции показывают имя, а не номер
  • если фрагмент кэшировался, то добавление одного фрагменты перед ним, не заставит все пересчитываться
  • в blogdown можно ссылаться

5 YAML шапка

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

---
title: "Мой RMarkdown"
author: Айс Дан
date: 5 января 2018
---

5.1 Тип получившегося файла

  • output: html_document (по умолчанию)
  • output: word_document
  • output: pdf_document (но нужно договориться с \(\LaTeX\)ом на вашем компьютере)
  • output: ioslides_presentation
  • output: slidy_presentation
  • output: slidy_presentation
  • output: beamer_presentation

и др.

5.2 Библиография

Существует несколько сопособов вставлять библиографию в RMarkdown. Я раскажу, как использовать пакет Bibtex (как видно из названия, сделанный для \(\LaTeX\)). Для начала нужно создать файл с раширением .bib, в который записать все источники, которые будут использоваться (библиографию в формате BibTeX выдает, например, GoogleScholar):

@book{ladefoged96,
  title={The sounds of the world's languages},
  author={Ladefoged, P. and Maddieson, I.},
  year={1996},
  publisher={Oxford Publishers}
}

@article{gordon02,
  title={A cross-linguistic acoustic study of voiceless fricatives},
  author={Gordon, M. and Barthmaier, P. and Sands, K.},
  journal={Journal of the International Phonetic Association},
  volume={32},
  number={2},
  pages={141--174},
  year={2002},
  publisher={Cambridge University Press}
}

На следующем шаге нужно добавить название файла с раширением .bib в YAML шапку:

---
bibliography: bibliography.bib
---

После этого, можно использовать сслыки в тексте

В своей работе @gordon02 раскрыл...

В своей работе Gordon, Barthmaier, and Sands (2002) раскрыл…

Об этом можно узнать из [@ladefoged96; @gordon02], но ...

Об этом можно узнать из (Ladefoged and Maddieson 1996; Gordon, Barthmaier, and Sands 2002), но …

В своей работе [@gordon02] раскрыл...

В своей работе (Gordon, Barthmaier, and Sands 2002) раскрыл…

Об этом можно узнать из [см. @gordon02, с. 33--35; а также @ladefoged96, гл. 1]...

Об этом можно узнать из (см. Gordon, Barthmaier, and Sands 2002, с. 33–35; а также Ladefoged and Maddieson 1996, гл. 1)…

Список литературы автоматически появляется в конце.

5.3 Оглавление и пр.

Существует сразу несколько аргументов, отвечающих за оглавление.

  • toc вставлять ли оглавление
  • toc_depth глубина иерархии, которую отражать в огловлении
  • toc_float должно ли оглавление все время следовать за текстом
  • collapsed должно ли оглавление быть все время полностью раскрыто
  • collapsed должно ли оглавление быть все время полностью раскрыто
  • number_sections автоматическая нумерация секций
  • code_folding (hide) — делать ли кнопочку, показывающую/скрывающую весь код
  • theme одна из Bootstrap тем
  • highlight: “default”, “tango”, “pygments”, “kate”, “monochrome”, “espresso”, “zenburn”, “haddock” или “textmate”
---
html_document:
    theme: spacelab
    highlight: pygments
    toc: yes
    toc_position: right
    toc_depth: 3
    toc_float: yes
    smooth_scroll: false
---

5.4 Отображение датафреймов

  • df_print: default
  • df_print: kable
  • df_print: tibble
  • df_print: paged
---
output:
  html_document:
    df_print: paged
---

5.5 CSS

---
output:
  html_document:
    css: styles.css
---

Если хочется совсем все взять из .css файла, то нужно добавить в YAML шапку аргументы theme: null и highlight: null.

6 JavaScript библиотеки

Существует много разных пакетов, которые интегрируют возможности уже написанных java-script библиотек в R. Все это возможно благодоря пакету htmlwidgets, который соединяет R и JavaScript. Здесь приведены лишь несколько примеров, больше примеров можно найти здесь.

6.1 DT

library(DT)
datatable(mtcars)

У меня была вот такая проблема. Устанавливайте версию с гитхаба:

devtools::install_github("rstudio/DT")

6.2 leaflet

library(leaflet)
leaflet() %>%
  addTiles() %>% 
  addPopups(37.168254, 55.408408,
            'Мы возможно <b>здесь</b>')

6.3 plotly

library(ggplot2)
library(plotly)

mtcars %>% 
  ggplot(aes(mpg, hp)) + 
  geom_point()+
  geom_smooth(method = "lm")+
  theme_bw()->
  my_plot
ggplotly(my_plot)

6.4 visNetwork

library(visNetwork)
nodes <- data.frame(id = 1:3)
edges <- data.frame(from = c(1,2), to = c(1,3))

visNetwork(nodes, edges)

Gordon, M., P. Barthmaier, and K. Sands. 2002. “A Cross-Linguistic Acoustic Study of Voiceless Fricatives.” Journal of the International Phonetic Association 32 (2). Cambridge University Press: 141–74.

Ladefoged, P., and I. Maddieson. 1996. The Sounds of the World’s Languages. Oxford Publishers.

  1. Сноска, сноска, сноска.↩

© Гарик Мороз 2018 с помощью RMarkdown. Исходный код на GitHub