2. comp
  3. RMarkdown: справочник и "маленькие хитрости"

RMarkdown: справочник и "маленькие хитрости"

Date Редакция Категория comp Теги R / Markdown

Краткое руководство по R Markdown

R Markdown как диалект довольно незначительно отличается от базового Markdown, описание которого легко найти в Сети. Для понимания особенностей R Markdown удобно воспользоваться кратким руководством или шпаргалкой, предлагаемыми разработчиками пакета.

Предварительно отформатированный текст

Текстовый блок, в форматирование которого RMarkdown не вмешивается, отображается моноширинным шрифтом:

```
This text is displayed verbatim / preformatted
```

Получим:

This text is displayed verbatim / preformatted

Аналогичный текст, расположенный внутри строки, задаётся как

Определим функцию `add` следующим образом...

Код

Вставка в документ Markdown фрагмента кода

```{r}
dim(iris)
```

позволяет отобразить в готовом документе сам этот код и результат его выполнения:

dim(iris)

## [1] 150   5

Если исходный код не должен отображаться и выдаются только результаты его исполнения:

```{r echo=FALSE}
dim(iris)
```

## [1] 150   5

Если напротив, код должен только отображаться, но не исполняться:

```{r eval=FALSE}
dim(iris)
```

dim(iris)

Выполнение кода внутри строки текста

Two plus two equals `r 2+2`.

даёт

Two plus two equals 4.

Исполняемый код может содержать ошибки, из-за чего прерывается обработка документа. Например, следующий код:

```{r}
sum(a)
```

при том, что переменная a еще не инициализирована, приводит к появлению сообщения об ошибке

error.png

Исправить ситуацию помогает установка параметра error=TRUE для данного фрагмента кода

```{r error=TRUE}
sum(a)
```

Сообщение об ошибке препятствующей трансляции теперь появится в готовом документе.

Любопытно, что установка параметра results='hide', которая предотвращает вывод результатов выполнения кода, в данном случае не помогает и сообщение об ошибке всё равно попадает в документ. Поэтому, в случае, когда нужен неисполняемый код проще использовать eval=FALSE.

Вставка в документ исходного кода из файла test.R осуществляется с помощью:

```{r code=readLines('test.R')}
```

При этом код test.R выполняется и результаты его работы также помещаются в документ. Если нужно просто отобразить код в документе, то, как обычно, добавляется опция eval=FALSE 

```{r, code=readLines('test.R', encoding='UTF-8'), eval=FALSE}
```

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

Ссылки между фрагментами кода

Рассмотрим следующий документ:

---
output:  pdf_document
---

```{r ref.label="chunk3", echo=FALSE}
```

```{r chunk2}
printSqr(7)
```

```{r chunk3}
printSqr <- function(x) {
  print(x ^ 2)
}
```

В втором фрагменте кода (с именем chunk2) используется функция printSqr. Однако сама функция будет задана ниже, в chunk3. Попытка вызова неизвестной функции, естественно, приведёт к ошибке. Чтобы этого не случилось, выше chunk2 мы поставим ссылку на копию printSqr при помощи параметра ref.label. В результате функция будет определена, но не будет отображаться в документе благодаря echo=FALSE.

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

Комментарии

в Markdown делаются также, как и в HTML:

<!--
текст, который вы хотите
закомментировать
-->

В YAML-заголовке документа возможны только строчные комментарии. Они начинаются с "решётки" (#):

---  
title: "Отчёт"
output: 
  pdf_document:
    highlight: haddoc # стиль подсветки синтаксиса
    toc: yes 
---

Markdown внутри Markdown

Если нужно показать Markdown-разметку внутри Markdown-документа, то ее приходится экранировать. Например, каждая из строк фрагмента кода

```r
x <- c(1,2,3)
```

начинается с отступа в 4 пробела. Это делается для того чтобы отобразить обратные косые черточки (backticks), обрамляющие код.

Неразрывный пробел

делается также, как в HTML:

&nbsp;

Сноски

Непосредственно после текста, к которому нужно сделать сноску, помещаем^[Текст сноски.]

footnote.png

Другой вариант:

Ссылки появляются в нижнем левом углу документа и могут задаваться кратко[^1] или 
длинно.[^longnote]. Сам текст сноски указывается после абзаца, где она вводится

[^1]: Это текст сноски.

[^longnote]: Это текст еще одной сноски.

Включение в текст файлов HTML

```{r child="path/to/file.html"}
```

Вместо данного chunk'а подгрузится файл file.html и его содержимое отобразится в том же стиле, что и текущий документ.

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

Составной документ

Файл отчёта report.Rmd состоит из двух глав, каждая из которых помещается в отдельном файле:

report.Rmd

---  
title: "Отчёт"
output: 
  pdf_document:
    toc: yes 
---

```{r child='chapter1.Rmd'}
```

```{r child='chapter2.Rmd'}
```

chapter1.Rmd

# Глава 1

Это глава 1.

```{r}
1
```

chapter2.Rmd

# Глава 2

Это глава 2.

```{r}
2
```

Для удобства навигации по документу удобно использовать меню Code/Jump To... или комбинацию клавиш Alt+Shift+J в RStudio

Подготовка документов в формате MS Word

RMarkdown умеет и это. Особенно интересно, как будет выглядеть текст, содержащий формулы и рисунки:

word.Rmd

---
title: "Проба пера"
output:
  word_document:
    fig_caption: yes
---

Тест, который должен быть отформатирован. $x$ -- переменная.

$$\int x^2 dx = \frac{x^3}{3} + C.$$

Тест, который должен быть отформатирован.

![Пример рисунка](heart.gif)

Тест, который должен быть отформатирован.

Вот что получится в результате:

word.png

Ещё одним пакетом, который можно использовать в R для подготовки документов MS Word является ReporteRs.

Скачать docx-файл

Дата создания документа

задаётся полем data в заголовке документа:

---
title: "My Document"
date:  "Today"
---

Чтобы задать текущую дату в качестве даты создания документа, вставим строку кода на R прямо в заголовок:

---
date: "`r format(Sys.time(), '%d.%m.%Y')`"
---

Другой вариант: воспользоваться LaTeX'овской командой \today:

---
date: \today
---

Автора, кстати, тоже можно задать не просто так, а со ссылкой на сайт:

---
author: "[Дмитрий Храмов](http://dkhramov.dp.ua)"
---

Название документа

помещённое в раздел заголовка title не должно начинаться с цифры, иначе pandoc выдаёт сообщение об ошибке.

Центрирование рисунков

Markdown не предназначен для красивой разметки и многого в этом смысле не умеет. Но он позволяет использовать способы разметки, использующиеся в целевом формате документа. Например, если Markdown-документ предполагается транслировать в формат HTML, то для центрирования изображений можно использовать элемент HTML-разметки center:

<center>![](image.png)</center>

Цвет шрифта

В случае, когда выходным форматом является HTML, цвет шрифта можно задать с помощью CSS:

Roses are <span style="color:red">red</span>, 
violets are <span style="color:blue">blue</span>.

Если на выходе предполагается получить PDF, то для задания цвета используется синтаксис LaTeX:

Roses are \textcolor{red}{red}, violets are \textcolor{blue}{blue}.

Комментарии

comments powered by Disqus