Введение в `rmarkdown` и `lingglosses`

данный мастер-класс посвящается моим коллегам из лаборатории, которые сейчас уехали из России: М. Даниэлю, Н. Добрушиной, А. Закировой, С. Ферхеес¹, И. Щурову

Г. Мороз

Международная лаборатория языковой конвергенции (НИУ ВШЭ)

«3-ий выезд Оплинга», 12-13 марта 2022

1 Введение в `rmarkdown`

rmarkdown — это пакет, который конвертирует документы написанные в markdown разметке в HTML, MS Word, PDF, и Beamer. Я делаю в Rmarkdown:

единичные страницы курсов (как эта);
презентации на конференциях;
“книгу” со всеми материалами какого-то курса;
сайт базы данных;
делаю Supplementary Materials;
пишу лингвистические статьи (в частности в наш журнал);
веду дневник;
…

1.1 Установка

Как и все пакеты rmarkdown можно установить из CRAN:

install.packages("rmarkdown")

1.2 Составляющие `rmarkdown`-документа

yaml шапка (факультативна)
обычный текст с markdown форматированием (расширенный при помощи Pandoc)
блоки кода (не обязательно на языке R), оформленные с двух сторон тройным бэктиком ``` (у меня на клавиатуре этот знак на букве ё).

1.3 Пример `rmarkdown`-документа

Создайте файл .Rmd в какой-нибудь папке (в RStudio, это можно сделать File > New file > R Markdown). Скомпелировать файл можно командой:

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

или кнопкой . Вот пример кода:

---
output: html_document
---

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

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

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

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

Результат.

1.4 `Markdown`

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

1.4.1 Заголовки

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

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

*курсив*

**жирный**

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

курсив

жирный

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

1.4.3 Списки

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

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

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

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

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

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

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

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

Ссылка 1

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

1.4.5 Код

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

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

```{r}
seq(0, 1, by = 0.01)
```

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

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

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

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

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

1.4.7 Сноски

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

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

Вот и сноска²

1.5 YAML шапка

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

---
title: "Мой RMarkdown"
author: Славный Автор
date: 20 ноября 2019
---

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

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

и др.

1.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)…

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

2 Введение в `lingglosses`

lingglosses — это пакет на R (смотрите подробную инструкцию здесь), который я написал для того, чтобы оформлять глоссированные примеры в нашем типологическом атласе языков Дагестана. Но так как это плохой повод, я так же провел короткое исследование и нашел вот такой список глосс:

NOM = nominative, GEN = nominative, DAT = nominative, ACC = accusative, VOC = accusative, LOC = accusative, INS = accusative, PL = plural, SG = singular

Кроме очевидных проблем, в этом списке глосс есть еще некоторые:

отсутсвие алфавитного порядка;
в нем отсутствуют две глоссы, которые есть в тексте статьи (sbjv, imp).

Так что основная цели lingglosses:

сделать глоссированные примеры для .html варианта rmarkdown;
полу-автоматически собирать список глосс.

2.1 Установка

Как и все пакеты lingglosses можно установить из CRAN:

install.packages("lingglosses")

2.2 Глоссированные примеры с `gloss_example()`

Во-первых, библиотеку нужно включить:

library(lingglosses)

Основная функция это gloss_example()

gloss_example(transliteration = "bur-e-**ri** c'in-ne-sːu",
              glosses = "fly-NPST-**INF** know-HAB-NEG",
              free_translation = "I cannot fly. (Zilo Andi, East Caucasian)",
              comment = "(lit. do not know how to)",
              annotation = "Бурери цIиннессу.")

Бурери	цIиннессу.
bur-e-ri	c’in-ne-sːu
fly-npst-inf	know-hab-neg
(lit. do not know how to)
‘I cannot fly. (Zilo Andi, East Caucasian)’

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

gloss_example("bur-e-**ri** c'in-ne-sːu",
              "fly-NPST-**INF** know-HAB-NEG",
              "I cannot fly. (Zilo Andi, East Caucasian)",
              "(lit. do not know how to)",
              "Бурери цIиннессу.")

Бурери	цIиннессу.
bur-e-ri	c’in-ne-sːu
fly-npst-inf	know-hab-neg
(lit. do not know how to)
‘I cannot fly. (Zilo Andi, East Caucasian)’

Иногда некоторые люди глоссируют полисинтетические морфемы как отдельные слова:

Абазинский, абхазо-адыгские (Arkadiev and Lander 2020: example 5.2)

gloss_example("s- z- á- la- nəq'wa -wa -dzə -j -ɕa -t'",
              "1SG.ABS POT 3SG.N.IO LOC pass IPF LOC 3SG.M.IO seem(AOR) DCL",
              "It seemed to him that I would be able to pass there.")

s-	z-	á-	la-	nəq’wa	-wa	-dzə	-j	-ɕa	-t’
1sg.abs	pot	3sg.n.io	loc	pass	ipf	loc	3sg.m.io	seem(aor)	dcl
‘It seemed to him that I would be able to pass there.’

Алгоритм извлечения глосс в пакете lingglosses чувствителен к регистру, так что если вы считаете, что что-то не должно восприниматься как глосса, оберните это в квадратные скобки:

Kvankhidatli Andi, (Verhees 2019: 203)

gloss_example("den=no he.ʃː-qi hartʃ'on-k'o w-uʁi w-uk'o.",
              "{I}=ADD DEM.M-INS watch-CVB M-stand.AOR M-be.AOR",
              "And I stood there, watching him.")

den=no	he.ʃː-qi	hartʃ’on-k’o	w-uʁi	w-uk’o.
I=add	dem.m-ins	watch-cvb	m-stand.aor	m-be.aor
‘And I stood there, watching him.’

Иногда примеры слишком длинные, и не влезают на страницу. В таком случае следует использовать аргуемнт {r, results='asis'} в чанке кода, тогда все разобьется на кусочки

Мишлешский диалект цахурского, нахско-дагестанские (Maisak and Tatevosov 2007: 386)

gloss_example('za-s jaːluʁ **wo-b** **qa-b-ɨ**; turs-ubɨ qal-es-di ǯiqj-eː jaːluʁ-**o-b** **qa-b-ɨ**', 
               '1SG.OBL-DAT shawl.3 AUX-3 PRF-3-bring.PFV woolen_sock-PL NPL.bring-PL-A.OBL place-IN shawl.3-AUX-3 PRF-3-bring.PFV',
               '(they) **brought** me a shawl; instead of (lit. in place of bringing) woolen socks, (they) **brought** a shawl.',
               '(Woolen socks are considered to be more valuable than a shawl.)')

za-s	jaːluʁ	*wo-b*	qa-b-ɨ;	turs-ubɨ	qal-es-di
1sg.obl-dat	shawl.3	aux-3	prf-3-bring.pfv	woolen_sock-pl	npl.bring-pl-a.obl

ǯiqj-eː	jaːluʁ-o-b	*qa-b-ɨ*
place-in	shawl.3-aux-3	prf-3-bring.pfv
(Woolen socks are considered to be more valuable than a shawl.)
‘(they) brought me a shawl; instead of (lit. in place of bringing) woolen socks, (they) brought a shawl.’

В функции прописан аргумент по умолчанию line_length, который равен 70, так что если вы не удовлетворены результатом, поменяйте это число.

2.3 Список глосс с `make_gloss_list()`

Когда вы закончили текст, можно вызвать функцию make_gloss_list() и она сделает список глосс:

make_gloss_list()

1sg — first person singular; 3 — third person; 3sg — third person singular; a — agent-like argument of canonical transitive verb; abs — absolutive; add — additive; aor — aorist; aux — auxiliary; cvb — converb; dat — dative; dcl — declarative; dem — demonstrative; hab — habitual; imp — imperative; in — in a container; ins — instrumental; io — indirect object; ipf — imperfective; loc — locative; m — masculine; n — neuter; neg — negation; npl — neutral plural; npst — non-past; obl — oblique; pfv — perfective; pl — plural; pot — potential; prf — perfect; sbjv — subjunctive

Эта функция основана на датасете glosses_df, который я составил на основе лейпцигских глосс, страницы в Википедии и откытого журнала Glossa. Все могут скачать и что-нибудь изменить в моем датасете. Вот его кусочек:

set.seed(42)
glosses_df[sample(1:nrow(glosses_df), 5),]

      gloss    definition    source weight
561  IMPERF  imperfective Wikipedia      1
321    DFLT       default Wikipedia      1
1177     ST       stative Wikipedia      1
1098    RSN        reason Wikipedia      1
1252 TRANSL translocative Wikipedia      0

Вообще, алгоритм написан таким образом, что он подсвечивает проблемные глоссы. Давайте добавим в список глоссу fake и вызовем функцию make_gloss_list() (сами не пытайтесь несколько раз вызывать эту функцию в одном документе — для этого нужна одна хитрость).

make_gloss_list()

1sg — first person singular; 3 — third person; 3sg — third person singular; a — agent-like argument of canonical transitive verb; abs — absolutive; add — additive; aor — aorist; aux — auxiliary; cvb — converb; dat — dative; dcl — declarative; dem — demonstrative; fake — ; hab — habitual; imp — imperative; in — in a container; ins — instrumental; io — indirect object; ipf — imperfective; loc — locative; m — masculine; n — neuter; neg — negation; npl — neutral plural; npst — non-past; obl — oblique; pfv — perfective; pl — plural; pot — potential; prf — perfect; sbjv — subjunctive

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

make_gloss_list(all_possible_variants = TRUE)

1sg — first person singular; 3 — third person; 3sg — third person singular; a — agent-like argument of canonical transitive verb; abs — absolutive; add — additive; aor — aorist; aux — auxiliary; cvb — converb; dat — dative; dcl — declarative; dem — demonstrative; fake — ; hab — habitual; imp — imperative; imp — imperfect; imp — imperfective; imp — impersonal; in — in a container; in — inclusive; in — inessive; ins — instantiated; ins — instrumental; io — indirect object; ipf — imperfective; loc — locative; m — masculine; n — neuter; neg — negation; npl — neutral plural; npst — non-past; obl — oblique; pfv — perfective; pl — plural; pot — potential; prf — perfect; prf — perfective; sbjv — subjunctive

Ссылки на литературу

Arkadiev, P., and Y. Lander. 2020. “The Northwest Caucasian Languages.” In The Oxford Handbook of the Languages of the Caucasus, 369–446.

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

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

Maisak, T., and S. Tatevosov. 2007. “Beyond Evidentiality and Mirativity: Evidence from Tsakhur.” In L’Énonciation médiatisée II, 377–406.

Verhees, S. 2019. “General Converbs in Andi.” Studies in Language. International Journal Sponsored by the Foundation “Foundations of Language” 43 (1): 195–230.

🌺 С днем рождения, родная! Я страшно скучаю!↩︎
Сноска, сноска, сноска.↩︎

Введение в rmarkdown и lingglosses

данный мастер-класс посвящается моим коллегам из лаборатории, которые сейчас уехали из России: М. Даниэлю, Н. Добрушиной, А. Закировой, С. Ферхеес1, И. Щурову

Г. Мороз Международная лаборатория языковой конвергенции (НИУ ВШЭ) «3-ий выезд Оплинга», 12-13 марта 2022

1 Введение в rmarkdown